Apostila de Clipper

Introdução

Existem muitas opções no mundo altamente competitivo dos produtos de bancos de dados para PCs. Com o lançamento da versão 5.3, o primeiro upgrade do Clipper num espaço de mais de três anos, a Computer Associates aperfeiçoou bastante o seu pacote de desenvolvimento de banco de dados em termos de desempenho, capacidade e facilidade de uso. E, com a versão 5.3, melhorou tanto a estabilidade quanto a funcionalidade do Clipper. Mas as perguntas que logo surgem são: Por que se fala tanto no Clipper? O que ele faz?

O Que é o Clipper?

Em linhas gerais, o Clipper é uma linguagem de programação de banco de dados completa, com todas as ferramentas necessárias para desenvolver aplicações de banco de dados independentes. Como o Clipper originariamente baseou-se na série dBASE da Ashton-Tate, muitos programas do dBASE são compatíveis com o Clipper, com poucas modificações. Você pode pensar no Clipper como um superconjunto da "linguagem" dBASE.

O Clipper é tão fácil que até mesmo um programador inexperiente pode usá-lo para desenvolver aplicações rápidas e poderosas. Quem estiver familiarizado com o dBASE III estará apto a criar aplicações do Clipper em apenas um dia. Os programadores com experiência em outras linguagens o acharão incrivelmente atual (em muitos aspectos ele se parece bastante com as atuais implementações da linguagem C) e o ambiente ideal para a criação rápida de aplicações de banco de dados. Caso precise de interfaces planejadas cuidadosamente, ficará satisfeito com o utilitário de criação de banco de dados (DBU) e com o depurador de códigos-fonte (CLD) do Clipper.

Compilando Programas do Clipper

O compilador do Clipper converte arquivos-fonte (.PRG) que contêm um número qualquer de procedures e funções escritas pelo usuário em arquivos-objeto (.OBJ). Esses últimos podem então ser linkados com outros arquivos-objeto do Clipper para formar um arquivo executável (.EXE). Os arquivos-fonte contendo códigos a serem compilados pelo Clipper precisão de extensões .PRG. Alguns exemplos de nomes de arquivos são MENU.PRG ou REPORT.PRG. Atribuir nomes aos arquivos-fonte com extensões consistentes tornará fácil encontrá-los no disco rígido, e as ferramentas do Clipper como o PE e o compilador fornecerão automaticamente a extensão .PRG nos arquivos de entrada, evitando assim o problema de ter que digitar extensões cada vez que se usar um desses programas.

Chamando o Compilador do Clipper

Para compilar um arquivo fonte do Clipper com a extensão .PRG, basta indicar no prompt do DOS.

CLIPPER <nome do arquivo>

O CLIPPER.EXE assumirá .PRG. Então, para compilar o arquivo SAMPLE.PRG, você digitaria:

Clipper Sample

CLIPPER – Apostila de Linguagem de Programação I 1999

Criando Arquivos Executáveis com o EXOSPACE

Agora que já discutimos como compilar arquivos, apenas mais uma ferramenta do Clipper é necessária para criar aplicações executáveis independentes. Esta ferramenta é o linker do Clipper, EXOSPACEK, que é um programa complexo, tanto pelo que faz quando pelo modo como pode ser entender e usar o EXOSPACE de modo competente, mas de qualquer modo esteja preparado para alguns jargões.

Chamando o EXOSPACE

O EXOSPACE é inicializado digitando-se seu nome no prompt do DOS. No modo Linha de Comandos, todas as informações de que o EXOSPACE precisa para criar um arquivo executável também são digitadas nesse prompt. Os únicos parâmetros obrigatórios na linha de comandos são o parâmetro FILE e a lista de arquivos-objeto a serem linkados. Portanto, o formato deste comando é o seguinte:

EXOSPACE FILE < lista de arquivos-objeto>

onde <lista de arquivos-objetos> é a lista de arquivos-objeto a serem linkados, separados por vírgulas. No caso de arquivos listados sem extensões, o programa assume .OBJ. A menos que um nome de arquivo de saída seja especificado o arquivo executável (.EXE) criado pelo EXOSPACE usará o nome do primeiro arquivo da <lista de arquivos-objeto>. Além do parâmetro FILE, existem bem poucas opções de link. Anteriormente você criou e compilou um arquivo denominado SAMPLE.PRG. Agora, vamos tentar fazer um link deste arquivo. Digite no prompt do DOS:

EXOSPACE FILE Sample

Você verá algumas linhas na tela dizendo que o linker está trabalhando, e informando qualquer erro que o EXOSPACE possa encontrar durante o processo. Se o processo ocorreu corretamente aparecerá a mensagem:

SUCCESSFULLY LINKED

Obs: Tamanho de uma aplicação simples do Clipper: aproximadamente 500 Kb

O tamanho aparentemente excessivo desta aplicação deve-se ao espaço extra requerido para os overlays dinâmicos, o gerenciamento de memória virtual e as funções de biblioteca do Clipper. No caso de aplicações grandes, quanto mais memória ( incluindo a estendida e expandida ) estiver disponível, mais rapidamente serão executadas.

Como o EXOSPACE encontra Arquivos da Biblioteca

As procedures e funções do Clipper estão contidas num conjunto de bibliotecas que foram carregadas no diretório \CLIP53\LIB do disco rígido durante a instalação. Quando chegar a hora do link, o EXOSPACE tentará encontrar essas bibliotecas para que possa fazer o link dos comandos e das funções da biblioteca necessários à sua aplicação. Ele sabe onde procurar as bibliotecas por causa do SET LIB=C:\CLIP53\LIB (ou equivalente da estrutura do seu diretório) que você incluiu no comando

Colégio Catanduvas Prof. Hélio Lemes Costa Jr. 2


AUTOEXEC.BAT. Se o EXOSPACE lhe pediu a localização do diretório que contém os arquivos CLIPPER.LIB, EXTEND.LIB e TERMINAL.LIB enquanto estava fazendo o link do arquivo SAMPLE, é porque você deve ter omitido esta linha do AUTOEXEC.BAT. Para evitar uma espera cansativa durante links futuros, sugerimos que você volte e inclua os comandos SET agora no AUTOEXEC.BAT ( e reinicialize o computador ).

Comandos do Clipper

Comandos de manipulação de variáveis

CLEAR MEMORY

Libera todas variáveis públicas e privadas

Sintaxe

CLEAR MEMORY

Descrição

CLEAR MEMORY elimina as variáveis públicas e privadas da tabela de variáveis. Ele opera contrastando com RELEASE ALL, o qual não libera realmente as variáveis públicas e privadas, mas coloca NIL em todas que tenham por abrangência a rotina corrente.CLEAR MEMORY é a única forma de excluir todas as variáveis públicas da memória corrente. Variáveis locais e estáticas não são afetadas por CLEAR MEMORY.

DECLARE*

Cria e inicializa variáveis e vetores PRIVATE

Sintaxe

DECLARE <identificador> [[:= <inicializador>], ... ]

Argumentos

<identificador> é o nome da variável ou vetor a ser criado PRIVATE. Se o <identificador> é seguido por colchêtes ([ ]), ele é criado como um vetor. Se o <identificador> é um vetor, a sintaxe para especificar o número de elementos para cada dimensão pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>][<nElementos2>]... O máximo de elementos por dimensão é 4096.

<inicializador> é a atribuição opcional de um valor a nova variável. Um <inicializador> para uma variável PRIVATE consiste do operador in-line (:=) seguido de qualquer expressão Clipper, incluindo um vetor. Se nenhum <inicializador> implícito for especificado, a variável terá o valor de NIL. Em caso de vetor, cada elemento é NIL.



Uma lista de variáveis ou vetores pode ser criada e opcionalmente inicializada com uma declaração DECLARE se cada definição for separada por uma vírgula.

Descrição

DECLARE é uma declaração de compatibilidade que é exatamente igual a PRIVATE. Seu uso não é recomendado. PRIVATE deve ser usado em seu lugar. Veja PRIVATE para maiores detalhes.

LOCAL

Declara e inicializa variáveis e vetores local

Sintaxe

LOCAL <identificador> [[:= <inicializador>], ... ]

Argumentos

<identificador> é o nome de uma variável ou vetor a ser declarado LOCAL. Se o <identificador> é seguido de colchêtes ([ ]), ele é criado como vetor. Se o <identificador> é um vetor, a sintaxe para especificar o número de elementos para cada dimensão pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>][<nElementos2>]... O máximo de elementos por dimensão é 4096. O número de dimensões é limitado somente pela memória disponível.

<inicializador> é a atribuição opcional de um valor para uma nova variável local. Identificadores vetor, entretanto, não podem receber valores com um <inicializador>. Um <inicializador> para uma variável local consiste do operador in-line (:=) seguido de qualquer expressão válida em Clipper incluindo um vetor. Se não for fornecido explicitamente um <inicializador>, a variável terá o valor NIL. No caso de um vetor, cada um dos elementos será NIL.

Nota

O operador macro (&) não pode ser usado numa declaração de variável local.

Descrição

LOCAL é uma declaração de uma ou mais variáveis ou vetores para a rotina corrente e deve ocorrer antes de qualquer instrução executável incluindo PRIVATE, PUBLIC, e PARAMETERS. Declarações de variáveis locais ocultam todas as variáveis private e as variáveis public com o <inicializador> é a atribuição opcional de um valor para uma nova variável local. Identificadores vetor, entretanto, não podem receber valores com um <inicializador>. Um <inicializador> para uma variável local consiste do operador in-line (:=) seguido de qualquer expressão válida em Clipper incluindo um vetor. Se não for fornecido explicitamente um <inicializador>, a variável terá o valor NIL. No caso de um vetor, cada um dos elementos será NIL.

Nota

O operador macro (&) não pode ser usado numa declaração de variável local.



Descrição

LOCAL é uma declaração de uma ou mais variáveis ou vetores para a rotina corrente e deve ocorrer antes de qualquer instrução executável incluindo PRIVATE, PUBLIC, e PARAMETERS. Declarações de variáveis locais ocultam todas as variáveis private e as variáveis public com o mesmo nome. Uma declaração LOCAL, entretanto, que declare um nome de variável que já esteja declarado causa um erro fatal de compilador e não será gerado um arquivo (.obj). Este erro pode ocorrer como resultado de duas declarações para a mesma variável na mesma rotina, ou como resultado de declarar uma variável que possua abrangência para todo o arquivo (.prg). Declarações incluem FIELD, MEMVAR, STATIC.

Variáveis locais são visíveis somente dentro da rotina corrente, e de forma diferente de variáveis private, não são visíveis para as rotinas invocadas a partir da rotina corrente. Variáveis locais são automaticamente criadas cada vez que a rotina onde elas estao é executada. Elas continuam a existir e retém seu valor até que a rotina devolva o controle para quem a invocou.Se a rotina é invocada recursivamente, cada chamada irá criar um novo conjunto de variáveis locais.

O valor inicial para variáveis locais ou elementos de vetor não especificamente inicializados é NIL, seja na lista de inicializador ou por atribuição. A expressão inicializadora pode ser qualquer expressão válida Clipper, incluindo chamadas de função. Note que uma declaração de vetor não pode ter um inicializador.

O número máximo de variáveis em um programa é limitado apenas pela memória disponível. Vetores, entretanto, quando atribuídos para uma variável local são ainda limitados a 4096 elementos por dimensão.

Notas

Inspecionando variáveis locais dentro do Debugger: Para acessar nomes de variáveis locais dentro do Clipper Debugger, você primeiro deve compilar o programa com a opção /B para que a informação sobre locais seja inclusa no arquivo objeto.

Parâmetros locais: Uma lista de parâmetros locais pode ser declarada especificando a lista entre parênteses seguindo <idFunção> desta forma:

FUNCTION <idFunção>(<idLista Param>)

Declarar parâmetros locais supera a criação de parâmetros privados com a declaração PARAMETERS.

Macro expressões: Variáveis locais não podem ser referenciadas dentro de macro variáveis ou expressões. Se uma variável é referenciada dentro de uma macro variável, uma variável public ou private com o mesmo nome será referenciada. Se tal variável não existir, um erro em tempo de execução será gerado.

Arquivos de memória: Variáveis locais não podem ser gravadas ou recuperadas de arquivos (.mem).

Tipo de uma variável local: Desde que TYPE() usa o operador macro (&) para avaliar seu argumento, ele não pode ser usado para determinar o tipo de variável local ou estática ou uma expressão contendo uma referência a uma variável local ou estática. Para permitir isso, use VALTYPE().



Exemplos

O exemplo a seguir declara dois vetores locais e duas variáveis locais:

LOCAL aArray1[20, 10], aArray2[20][10], var1, var2

Este exemplo declara duas variáveis locais com inicializadores. O primeiro é inicializado com uma data e o segundo com um vetor literal:

LOCAL dWhen := DATE()LOCAL aVegies := {"Mandioca", "Pepino", "Cenoura"}

PRIVATE

Cria e inicializa variáveis de memória e vetores private.

Sintaxe

PRIVATE <identificador> [[:= <inicializador>], ... ]

Argumentos

<identificador> é o nome da variável ou vetor private a ser criado. Se <identificador> é seguido de colchêtes ([ ]), um vetor é criado e atribuído a <identificador>. Quando o <identificador> indica um vetor, a sintaxe para especificar o número de elementos em cada dimensão pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>][<nElementos2>]... O número máximo de elementos por dimensão é 4096. O número máximo de dimensões é limitado pela memória disponível.

<inicializador> é a atribuição opcional de um valor para a nova variável private. Para um vetor não se pode dar valores usando

<inicializador>. Um <inicializador> para uma variável private consiste do operador in-line (:=) seguido de qualquer expressão Clipper incluindo um vetor. Se nenhum <inicializador> for especificado, a variável é inicializada com NIL. No caso de um vetor, cada elemento é inicializado com NIL.

Uma lista de variáveis e vetores pode ser criada e opcionalmente inicializada com uma única declaração PRIVATE se cada definição for separada por vírgula.

Descrição

A declaração PRIVATE cria variáveis visíveis dentro da rotina corrente e aquelas que forem por esta invocadas. A classe de variável é dita como tendo abrangência dinâmica. Variáveis private existem durante a duração da rotina ativa ou até que explícitamente liberadas com CLEAR ALL, CLEAR MEMORY, ou RELEASE. Quando uma variável ou vetor private é criado, variáveis e vetores public ou private existentes de mesmo nome são ocultos até que a rotina corrente se encerre.

Tentativas de especificar uma variável private que conflite com declarações FIELD, LOCAL, ou STATIC prévias de mesmo nome irão resultar num erro fatal de compilador. Isto ocorre não importando as abrangência da declaração.



Declarações PRIVATE são executáveis e portanto devem ser especificadas dentro do corpo da rotina e devem seguir todas as declarações de variáveis como FIELD, LOCAL, MEMVAR, e STATIC.

Adicionalmente a declaração PRIVATE, variáveis PRIVATE podem ser criadas de duas maneiras:

Atribuição a uma variável que não exista ou não seja visível irá criar uma variável private

Parâmetros recebidos com a declaração PARAMETERS são criados como variáveis private com a mesma vida útil e visibilidade

O número máximo de variáveis e vetores private que podem existir simultâneamente num programa é de 2048.

Notas

Compatibilidade: As cláusulas ALL, LIKE, e EXCEPT da declaração PRIVATE suportadas por outros dialetos dBASE não o são em Clipper.

Exemplos

O exemplo a seguir cria dois vetores private e outras tres variáveis também private:

PRIVATE aArray1[10], aArray2[20], var1, var2, var3

Este exemplo cria um vetor multi dimensional private usando as convenções de endereçamento de cada elemento:

PRIVATE aArray[10][10][10], aArray2[10, 10, 10]

Este exemplo demonstra várias declarações PRIVATE para declarar e inicializar vetores e variáveis:

PRIVATE aArray := { 1, 2, 3, 4 }, aArray2 := ARRAY(12, 24)PRIVATE cChar := SPACE(10), cColor := SETCOLOR()

PUBLIC

Cria e inicializa variáveis e vetores públicos.

Sintaxe

PUBLIC <identificador> [[:= <inicializador>], ... ]

Argumentos

<identificador> é o nome da variável ou vetor a ser criado. Se <identificador> é seguido de colchetes ([ ]), ele é criado como vetor.Se <identificador> é um vetor, a sintaxe para especificar o número de elementos em cada dimensão pode ser vetor [<nElementos>, <nElementos2>, ...]ou vetor[<nElementos>][<nElementos2>]... O



número máximo de elementos por dimensão é 4096. O número máximo de dimensões por vetor é limitado pela memória disponível.

<inicializador> é a atribuição opcional de um valor para uma nova variável pública. Identificadores de vetor, não podem ser inicializados com <inicializador>. Um <inicializador> para uma variável pública contitui-se do operador in-line (:=) seguido de qualquer expressão Clipper incluindo um vetor. Se nenhum <inicializador> for especificado, o valor inicial para estas variáveis será falso (.F.). Esta é uma exceção já que todas as variáveis não inicializadas assumem valor NIL. Contudo, para o caso de vetores, o valor de cada elemento não inicializado continua sendo NIL.

Uma lista de variáveis e vetores pode ser criada e opcionalmente inicializada com uma declaração PUBLIC se cada definição for separada por uma vírgula.

Descrição

A declaração PUBLIC cria variáveis e vetores visíveis para todas as rotinas no programa. Variáveis public existem durante toda a duração do programa ou até que sejam explicitamente liberadas com CLEAR ALL, CLEAR MEMORY, ou RELEASE. Declarar nomes de variáveis private, local ou static com o mesmo nome de uma public, temporariamente esconde estas public até que as outras sejam liberadas ou não estejam mais visíveis.Uma tentativa de criar uma variável public com o mesmo nome de uma private visível e existente é simplesmente ignorado (veja Notas abaixo para uma excessão).

Tentativas de especificar uma variável PUBLIC que conflite com uma declaração anterior FIELD, LOCAL, ou STATIC com o mesmo nome, irá causar um erro fatal de compilador. Isto é sempre verdade não importando a abrangência da declaração.

Declarações PUBLIC são executáveis e portanto devem ser especificadas no corpo da rotina. Elas devem também seguir as declarações em tempo de compilador, ou seja: FIELD, LOCAL, MEMVAR, e STATIC.

O máximo número de variáveis public e private que podem existir simultaneamente é de 2048.

Notas

PUBLIC Clipper: Para incluir extensões Clipper num programa e ainda permitir que o mesmo seja executado debaixo de dBASE III PLUS, uma variável public especial, Clipper, é inicializada como verdadeira (.T.) quando criada PUBLIC.

Vetores public e conflitos de nome com variáveis private: A declaração PUBLIC x[10], não irá criar um vetor public x se já existir uma variável public ou private x. Ela irá, entretanto, destruir o conteúdo de x existente, trocando-o por uma referência a um vetor de 10 elementos.

Exemplos

Este exemplo cria dois vetores e uma variável PUBLIC:

PUBLIC aArray1[10, 10], var2PUBLIC aArray2[20][10]

Aqui criamos várias variáveis e as inicializamos:



PUBLIC cString := SPACE(10), cColor := SETCOLOR()PUBLIC aArray := {1, 2, 3}, aArray2 := ARRAY(12, 24)

RELEASE

Libera variáveis de memória dos tipos pública e privada

Sintaxe

RELEASE <idLista Varmem>RELEASE ALL [LIKE | EXCEPT <esqueleto>]

Argumentos

<idLista Varmem> é uma lista de variáveis de memória ou vetores do tipo pública ou privada a serem liberados.

ALL [LIKE|EXCEPT <esqueleto>] define o conjunto de variáveis de memória do tipo privada visíveis a serem atribuídas ou serem excluídas da atribuição de um NIL. <esqueleto> é a máscara do tipo coringa que especifica um grupo de variáveis de memória a serem eliminadas. Os caracteres do tipo coringa aceitos são "*" e "?."

Descrição

O comando RELEASE executa uma de duas ações, dependendo da forma do comando. Se RELEASE é especificado com <idLista Varmem>, as variáveis de memória dos tipos pública e privada e/ou vetores especificados são liberados da memória. No caso de variáveis escondidas previamente (variáveis dos tipos pública e privada definidas em rotinas de nível mais elevado) tornam-se acessíveis ao término da rotina na qual a variável foi inicialmente criada.

Caso RELEASE seja especificado com qualquer forma da cláusula ALL, às variáveis de memória do tipo privada criadas no nível da rotina corrente é atribuído um NIL, e elas não são eliminadas até que a rotina corrente termine. Variáveis do tipo pública não são afetadas por esta forma do comando RELEASE. Para eliminar o conteúdo deste tipo de variáveis, você deve usar o comando RELEASE explicitamente ou usar CLEAR MEMORY.

Variáveis dos tipos local ou estática não são afetadas pelo comando RELEASE. As do primeiro tipo são liberadas automaticamente quando a rotina na qual elas foram declaradas termina. As do último tipo não podem ser liberadas, pois a existência das mesmas extende-se até o final do programa.

Comandos para apresentação de dados

@...BOX

Desenha uma caixa na tela

Sintaxe



@ <nLinTopo>, <nColTopo>, <nLinBase>, <nColBase>BOX <cStringCaixa>

Argumentos

<nLinTopo>, <nColTopo>, <nLinBase>, e <nColBase> definem as coordenadas da caixa. @...BOX desenha uma caixa usando valores de linha de zero até MAXROW(), e coluna de zero até MAXCOL(). Se <nLinBase> e <nColBase> são maiores que MAXROW() e MAXCOL(), o canto inferior direito é desenhado fora da tela.

<cStringCaixa> é um string de oito caracteres de borda e um de preenchimento. Se <cStringCaixa> é especificado como um único caractere, este é usado para desenhar a caixa inteira.

Descrição

@...BOX desenha uma caixa na tela usando bordas configuráveis e caractere de preenchimento. @...BOX desenha a caixa usando <cStringCaixa>a partir do canto superior esquerdo, continuando no sentido horário e preenchendo a regiao de tela com o nono caractere.Se o nono caractere não for especificado, a regiao de tela dentro da caixa não é preenchida. Textos e cores pré-existentes não são alterados.

Após @...BOX ter sido executado, o cursor é colocado no canto superior esquerdo em <nLinTopo> + 1 e <nColTopo> + 1. ROW() e COL() têm seus valores atualizados para refletir a nova posição do cursor.

Exemplos

Os seguintes exemplos desenham duas caixas usando constantes manifestas contidas no arquivo header, Box.ch. O primeiro exemplo desenha uma caixa usando os caracteres especificados para a borda, mas deixa todas as outras áreas da tela intactas. O segundo exemplo desenha a mesma caixa preenchendo a regiao com espaços:

#include "Box.ch"

// Desenha uma caixa com topo em linha dupla e lateral em linha simples@ 1, 1, 22, 79 BOX DOUBLE_SINGLE

// Desenha a mesma caixa preenchendo com espaços@ 1, 1, 22, 79 BOX DOUBLE_SINGLE + SPACE(1)

@...PROMPT

Exibe um item de menu e define uma mensagem

Sintaxe

@ <nLin>, <nCol> PROMPT <cItemMenu>[MESSAGE <cItemMensagem>]



Argumentos

<nLin> e <nCol> são as coordenadas de linha e coluna para exibir o item de menu. Valores de linha estão na faixa de zero até MAXCOL()>

<cItemMenu> é o string com o item de menu a ser exibido.

<cItemMenssagem> define a mensagem a ser exibida cada vez que o item corrente é iluminado.

Descrição

@...PROMPT é a porção exibidora de sistema de menu de barra luminosa do Clipper. Cada @...PROMPT exibe um item de menu e define uma mensagem associada a ser exibida na linha definida em SET MESSAGE. O menu de barra luminosa é invocado com MENU TO. Os itens de menu podem ser exibidos na tela em qualquer ordem e configuração de linha e coluna. MENU TO, entretanto, navega na lista de itens de menu corrente na ordem em que estes foram definidos.

Podem existir até 32 itens para cada menu e o @...PROMPT irá exibi-los em tela utilizando a cor padrão. Quando MENU TO é ativado, o item corrente é iluminado utilizando a cor destaque.

Após cada comando @...PROMPT, o cursor é posicionado uma coluna à direita do item no qual você está. ROW() e COL() são atualizados de modo a refletir a posição do cursor. Isto lhe permite utilizar ROW() e COL() de modo a especificar posições de itens consecutivas ao primeiro item colocado na tela. Veja o exemplo abaixo.

Exemplos

Este exemplo exibe um menu de barra luminosa na linha 1 da tela com as mensagens associadas exibidas na próxima linha. Quando o usuário apertar Return, a posição do item de menu é atribuída a nChoice:

LOCAL nChoice := 1CLS ; SET WRAP ONSET MESSAGE TO 2@ 1, 3 PROMPT "Arquivo" MESSAGE "Acesso a arquivo de dados"@ ROW(), COL() + 2 PROMPT "Edita" MESSAGE "Edita registro corrente"@ ROW(), COL() + 2 PROMPT "Busca" MESSAGE "Acha outro registro"MENU TO nChoice

@...SAY

Exibe dados em uma linha e coluna especificadas

Sintaxe

@ <nLin>, <nCol>[SAY <exp> [PICTURE <cSayPicture>]]

Argumentos



<nLin> e <nCol> são as coordenadas de linha e coluna da saída. Os valores de linha podem variar entre zero e MAXROW() para o dispositivo corrente (DEVICE) se este for a tela ou entre zero e 32.776 caso o dispositivo (DEVICE) seja PRINTER. O mesmo vale para as colunas.

SAY <exp> exibe o resultado de uma expressão de qualquer tipo--inclusive um campo memo--ao DEVICE corrente.

PICTURE <cSayPicture> define a máscara para a saída de exp. O Clipper fornece dois mecanismos de controle de formatação: funções e templates. Funções aplicam-se ao SAY inteiro, enquanto que templates mascaram caracteres posição por posição.

Descrição

@...SAY é um comando de tela que exibe os resultados de <exp> para tela ou impressora nas coordenadas de linha e coluna especificadas. Ele pode opcionalmente formatar a saída usando a cláusula PICTURE. @...SAY é usado para criar telas de entrada de dados ou relatórios que podem ser enviados para a tela ou impressora.

Quando um @...SAY é executado, a saída de <exp> é enviada ao dispositivo corrente definido por SET DEVICE. O DEVICE corrente pode ser SCREEN (tela) ou PRINTER (impressora). De forma diferente de outros comandos de console, @...SAY não é ecoado em tela quando está sendo enviado para a impressora e SET CONSOLE não tem efeito na saída de @...SAY em tela.

Se o DEVICE corrente é SCREEN (o padrão do sistema), @...SAY exibe a saída em tela deixando o cursor uma coluna à direita do último caractere mostrado. ROW() e COL() são atualizados. Exibição que saia fora da tela definida por MAXROW() e MAXCOL() faz com que o cursor seja posicionado fora da tela visível. Todas as saídas de @...SAY são exibidas na cor padrão.

Se o dispositivo corrente (DEVICE) for impressora (PRINTER), a saída é direcionada para esta em <nLin> adicionando ao valor de SET MARGIN e nCol>. A cabeça de impressão sofre avanço para uma coluna à direita do último caractere impresso. PROW() e PCOL() são atualizados conforme esta posição. Comandos @...SAY para a impressora comportam-se de uma forma levemente diferente que na tela quando a saída é endereçada para a impressora numa linha e coluna menor que a corente em PROW() e PCOL().

Caso <nLin> seja menor que PROW(), um EJECT automático (CHR(12)) é enviado à impressora seguido pelo número de caracteres line-feed (CHR(10)) necessários para posicionar a cabeça de impressão em <nLin>.

Caso <nCol> inclua o valor SET MARGIN menor que PCOL(), um caractere carriage return (CHR(13)) e o número de espaços necessários para posicionar <exp> em <nCol> são enviados à impressora.

Para evitar este comportamento de forma a enviar códigos de controle para a impressora, ou por qualquer outra razão, você pode usar SETPRC() para reconfigurar PROW() e PCOL() para novos valores.

Se DEVICE corrente for PRINTER, a saída de comandos @...SAY pode ser redirecionada para um arquivo usando SET PRINTER TO <xcArquivo>.

Como citado acima, @...SAY pode ter sua saída formatada usando a cláusula PICTURE com <cSayPicture>. Isto executa a mesma ação que TRANSFORM(). Uma <cSayPicture> pode consistir



em uma função e/ou template. Uma função PICTURE impoe uma regra de como @...SAY deve ser exibido como um todo. Um template PICTURE define o tamanho da saída de @...SAY, e a regra de formatação dentro da saída.

Funções: Uma função PICTURE é um símbolo precedido do símbolo @. Um símbolo de template segue a função, e deve ser precedido de um espaço. Note que mais de uma função pode ser aplicada dentro da mesma PICTURE. A tabela seguinte resume as opções disponíveis para as funções PICTURE:

Tabela 4-3: PICTURES para SAY e TRANSFORM()

Função AçãoB Exibe números alinhados à esquerdaC Exibe CR após números positivosD Exibe datas no formato SET DATEE Exibe datas e números no formato BritishR Caracteres não template serão inseridosX Exibe DB após números negativosZ Exibe zeros como brancos( Coloca números negativos entre parênteses! Converte caracteres alfabéticos para maiúsculas

Templates: Símbolos de template seguem as funções no string de PICTURE se forem especificados. Cada posição no fluxo de entrada ou saída é mapeada para o símbolo na mesma posição no string template. Clipper fornece vários símbolos os quais estão discriminados na tabela da página seguinte:

Tabela 4-4: Símbolos Template para SAY e TRANSFORM()

Template AçãoA,N,X,9,# Exibe dígitos em qualquer tipo de dadosL Exibe lógicos como "T" ou "F"Y Exibe lógicos como "Y" ou "N"! Converte um caractere alfabético para maiúscula$ Exibe o sinal de dolar em lugar de espaços à esquerda de um numérico* Exibe asteriscos em lugar de espaços à esquerda de um numérico. Especifica a posição do ponto decimal, Especifica a posição da vírgula

Outros caracteres especificados no template sobreescrevem o caractere na mesma posição no stream fonte e saída. Se, entretanto, você usar a função R, símbolos não-template especificados serão inseridos para exibição.

Exemplos

O exemplo seguinte demonstra o uso de @...SAY com uma cláusula PICTURE para exibir saída formatada:

nNetIncome = 7125.50nNetLoss = -125.50



cPhone = "2134567890"cName = "Kate Mystic"//@ 1, 1 SAY nNetIncome PICTURE "@E 9,999.99" //Resulta: 7,125.50@ 2, 1 SAY nNetLoss PICTURE "@)" //Resulta: (125.50)@ 3, 1 SAY cPhone PICTURE "@R (999)999-9999" //Resulta: (213)456-7890@ 4, 1 SAY cName PICTURE "@!" //Resulta: KATE MYSTIC

Este exemplo é uma pequena impressão de etiquetas que utiliza SET DEVICE para direcionar para impressora e SETPRC() para suprimir EJECTs automáticos:

USE Salesman INDEX Salesman NEWSET DEVICE TO PRINTERDO WHILE !EOF() // Imprime todos registros

@ 2, 5 SAY RTRIM(FirstName) + " " + LastName@ 3, 5 SAY Street@ 4, 5 SAY RTRIM(City) + ", " + State + " " + PostalCode@ 6, 0 SAY SPACE(1) // Para a base da etiquetaSETPRC(0, 0) // Suprime ejeção de páginaSKIP // Próximo registro

ENDDOSET DEVICE TO SCREENCLOSE Salesman

@...TO

Desenha uma caixa em linha simples ou dupla

Sintaxe

@ <nLinTopo>, <nColTopo> TO <nLinBase>, <nColBase> [DOUBLE]

Argumentos

<nLinTopo>, <nColTopo>, <nLinBase>, e <nColBase> definem as coordenadas da caixa. @...TO irá desenhar usando valores de linha de zero até MAXROW(). <nLinBase> e <nColBase> podem ser maiores que o tamanho da tela.

DOUBLE desenha a caixa em linha dupla. Se não for especificado, a caixa é desenhada em linha simples.

Descrição

@...TO desenha uma caixa em linha simples ou dupla na tela. Caso <nLinTopo> e <nLInBase> sejam o mesmo, uma linha horizontal é desenhada. Se <nColTopo> e <nColBase> forem o mesmo valor, uma linha vertical é desenhada.

Após @...TO finalizar o desenho, o cursor é posicionado no canto superior da região em <nLinTopo> + 1 e <nColTopo> + 1. ROW() e COL() são também atualizadas de forma a refletir a posição do cursor.



@...TO é similar a @...BOX com duas exceções: primeiro, @...BOX permite-lhe definir os caracteres para moldura e, segundo, ele permite um caractere para preeenchimento.

Exemplos

O exemplo seguinte apaga uma região da tela e desenha em seguida uma caixa do mesmo tamanho:

@ 10, 10 CLEAR TO 20, 40@ 10, 10 TO 20, 40 DOUBLE

CLEAR SCREEN

Apaga a tela e coloca o cursor na posição inicial

Sintaxe

CLEAR [SCREEN] | CLS

Argumentos

SCREEN suprime a limpeza automática de GETs quando a tela é apagada com CLEAR.

Descrição

CLEAR apaga a tela, libera GETs pendentes, e posiciona o curosr em 0,0. Caso seja usado SCREEN, os GETs não são liberados.

CLS é o mesmo que CLEAR SCREEN.

Notas

SET KEY e VALID: Caso você esteja editando GETs, executar um CLEAR dentro de uma rotina de SET KEY ou a partir de uma função definida pelo usuário invocada por VALID irá encerrar o READ quando o controle retornar. Para limpar a tela sem liberar os GETs, use CLS ou CLEAR SCREEN.

RESTORE SCREEN*

Exibe uma tela guardada

Sintaxe

RESTORE SCREEN [FROM <cTela>]

ArgumentosFROM <cTela> especifica a expressão caractere a ser exibida na tela.



Descrição

RESTORE SCREEN é um comando sinônimo da função RESTSCREEN() que re-exibe uma tela previamente gravada, e é utilizada juntamente com o comando SAVE SCREEN para evitar qua a tela original escrita com os comandos @...SAY, @...GET seja re-escrita.

Este comando opera de duas formas, dependendo se a cláusula FROM for especificada ou não. Caso ela seja especificada, a tela será recuperada de <cTela>. <cTela> é uma expressão caractere, geralmente uma variável à qual foi atribuída uma imagem de tela pelo comando SAVE SCREEN. Caso a cláusula FROM não seja especificada, a tela é recuperada do buffer de telas gravadas padrão que foi criado pelo comando SAVE SCREEN especificado sem a cláusula TO.

Para gravar e recuperar o conteúdo parcial das telas, ao invés de seu conteúdo completo, use as funções SAVESCREEN() e RESTSCREEN().

RESTORE SCREEN é um comando de compatibilidade e, portanto, desaconselhado. Ele está superado pela função RESTSCREEN(), a qual pode recuperar telas parciais, bem como telas completas.

Aviso

Os comandos e funções SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), e RESTSCREEN() não são aceitos quando ANSI.OBJ ou IBMANSI.OBJ estiverem linkados ao programa corrente.

Exemplos

O exemplo abaixo exibe uma pequena caixa de mensagem usando os comandos SAVE e RESTORE SCREEN:

IF FileAlert()COPY FILE Them.txt TO My.txtELSEBREAK

ENDIF

FUNCTION FileAlertLOCAL lAnswer = .F., cScreenSAVE SCREEN TO cScreen@ 10, 10 CLEAR TO 12, 54@ 10, 10 TO 12, 54 DOUBLE@ 11, 12 SAY "Arquivo existe, sobreescreve? (s/n)? ";GET lAnswer PICTURE "@!" VALID lAnswer $ "SN"READRESTORE SCREEN FROM cScreenRETURN lAnswer == "S"

SAVE SCREEN*

Grava a tela corrente num buffer ou variável



Sintaxe

SAVE SCREEN [TO <idVar>]

Argumentos

TO <idVar> especifica a variável à qual serão atribuídos os conteúdos da tela corrente como um valor de caractere. Se <idVar> não for visível ou não existir, uma variável de memória do tipo privada é criada e a ela atribuída a tela.

Descrição

SAVE SCREEN é um comando sinônimo à função SAVESCREEN() que grava a tela de 0, 0 a MAXROW(), MAXCOL() no buffer de tela padrão, ou em uma variável opcional. Se a tela for gravada em uma variável, esta pode ser de qualquer classe de armazenamento, inclusive campo, local, estática, ou elemento de vetor. Observe, porém, que você não pode gravar variáveis tipo vetor, local ou estática em arquivos (.mem) com a finalidade de gravar telas mútiplas no disco.

O comando SAVE SCREEN é utilizado juntamente com o comando RESTORE SCREEN para impossibilitar que uma tela original que tenha sido temporariamente substituída seja re-escrita. Telas múltiplas podem ser gravadas através da atribuição de cada tela a uma variável diferente.

SAVE SCREEN é um comando de compatibilidade e, portanto, desaconselhado. Ele está superado pela função SAVESCREEN(), a qual pode gravar telas parciais ou completas.

Aviso

Os comandos e funções SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), e RESTSCREEN() não são aceitos quando ANSI.OBJ ou IBMANSI.OBJ estao linkados ao programa corrente.

Exemplos

Este fragmento de código demonstra o uso de um vetor estático para armazenar telas gravadas:

STATIC aScreens[10]SAVE SCREEN TO aScreens[1]//<declaraçooes>...//RESTORE SCREEN FROM aScreens[1]

Este exemplo demonstra como gravar e recuperar telas utilizando um arquivo de dados:

USE Screens INDEX Name NEWAPPEND BLANKScreens->Name := "Screen001" // Guarda o nome da telaSAVE SCREEN TO Screens->Image // Guarda uma tela//<declarações>...//



SEEK "Screen001" // Acha a telaRESTORE SCREEN FROM Screens->Image // Restaura

Comandos para entrada e edição de dados

@...GET

Cria um novo objeto GET e o coloca em exibição na tela

Sintaxe

@ <nLin>, <nCol> [SAY <exp>[PICTURE <cSayPicture>]]GET <idVar> [PICTURE <cGetPicture>][WHEN <lPreCondição>][RANGE <dnMínimo>, <dnMáximo>] | [VALID <lPosCondição>]

Argumentos

<nLin> e <nCol> são as coordenadas de linha e coluna para a operação. Se a claúsula SAY está presente, especificam as coordenadas para o SAY, e o GET é exibido a direita deste. Caso a saída esteja além da extensão visível ela não aparecerá.

SAY exibe o valor de <exp> nas coordenadas especificadas. Caso a PICTURE <cSayPicture> seja especificada, <exp> é formatada de acordo com as regras das máscaras do SAY.

GET <idVar> define o nome da variável de qualquer tipo de dados a ser editada. Ela pode ser caractere, data, numérica ou lógica (Se o tipo for ambíguo, FIELD é assumido). Vetores, NIL, e blocos de código não podem ser editados.

PICTURE <cGetPicture> especifica uma máscara para exibição e as regras para edição do GET.

WHEN <lPreCondição> especifica uma expressão que deve ser satisfeita antes do cursor entrar na região de edição de GET. Se <lCondição> é avaliada como verdadeira (.T.), é permitido ao cursor entrar; de outra forma, o GET corrente é saltado e o cursor move-se para o próximo GET no vetor GetList.

RANGE <dnMínimo>, <dnMáximo> limita a edição de datas ou variáveis numéricas especificando os limites mínimos e máximos aceitáveis (o mínimo deve preceder o máximo). Se o valor entrado não está dentro do RANGE especificado, uma mensagem indicativa aparece no SCOREBOARD e o controle retorna ao objeto GET. A verificação de RANGE (faixa) é executada a menos que o usuário aperte Esc para terminar a edição do GET corrente. Quando isto ocorre, a verificação de RANGE não é executada e é reatribuído seu valor original.

VALID <lPosCondição> especifica uma expressão que deve ser satisfeita antes que o cursor possa deixar a região de edição do GET corrente. De forma semelhante às expressões RANGE, o VALID<lPosCondição> é avaliado sempre que o usuário tenta deixar a região de edição do GET, a menos que a tecla Esc seja pressionada e ESCAPE esteja ON. Se <lPosCondição> retorna falso (.F.), o controle retorna ao GET e o usuário não pode deixá-lo até que <lPosCondição> retorne verdadeiro



(.T.) ou o usuário aperte Esc. Um VALID <lPosCondição> pode conter ou ser uma função definida pelo usuário ,permitindo-lhe executar buscas e outros tipos de operações de validação.

Descrição

O comando @...GET cria um novo objeto GET, adiciona-o ao vetor GetList, e exibe-o na tela. Um comando READ subsequente permite a edição dos conteúdos de todos os objetos GET contidos no vetor GetList corrente.

Quando um comando READ é especificado, um GET executa uma edição do conteúdo de <idVar> de qualquer tipo de dado, incluindo campo de arquivo, elemento de vetor, variável de memória local ou estática.

Quando um objeto GET é criado, o nome e valor corrente de <idVar> são guardados no objeto GET. O valor de <idVar> fica armazenado no que é chamado de buffer do GET. O buffer de GET é o que é realmente mostrado na tela e editado.

Formatação automática e validação: Quando o usuário estiver editando o buffer do objeto GET, existe uma formatação implícita e validação da edição para cada tipo de dado. Isto significa que enquanto o usuário digita, um teste automático de tipo é executado para cada tecla pressionada de forma a evitar que o usuário digite um caractere impróprio para aquele tipo de dado contido em <idVar>. Este comportamento assumido aplica-se a datas, numéricos, e lógicos. Tipo caractere não é automáticamente verificado.

PICTURE: Cada objeto GET pode opcionalmente conter uma PICTURE e string template para explicitamente impor formatação e validação da entrada. Um função PICTURE impoe uma regra de como o GET pode ser editado pelo usuário. Por exemplo, se a função de PICTURE @! é especificada para um GET, todos os caracteres alfabéticos serão convertidos para maiúsculas antes de tomarem lugar no buffer. Um template PICTURE define o tamanho do buffer de GET, e a regra de validação para cada posição dentro do buffer. Por exemplo, o template "999" define o tamanho do buffer de GET em três dígitos, com cada dígito devendo ser um número entre 0 e 9.

Funções: Uma função PICTURE é um símbolo precedido do símbolo @. Um símbolo de template segue a função, e deve ser precedido de um espaço. Note que mais de uma função pode ser aplicada dentro da mesma PICTURE. A tabela na página seguinte mostra as opções disponíveis para as funções PICTURE:

Tabela 4-1: Formatos de PICTURE para um GET

Função Tipo AçãoA C Permite somente caracteres alfabéticosB N Exibe números alinhados à esquerdaC N Exibe CR após números positivosD D,N Exibe datas segundo o formato SET DATEE D,N Exibe datas com o mês e dia invertidos independente do SET DATE

corrente, númericos com pontos e vírgulas period reverse invertidosK TODOS Elimina texto assumido caso a primeira tecla não seja cursorR C Caracteres não-template são inseridos na tela mas não são guardados na

variávelS<n> C Permite rolagem horizontal dentro de um GET. <n> é um inteiro que

especifica a largura da região



X N Exibe DB após números negativosZ N Exibe zeros como brancos( N Exibe números negativos entre parênteses com espaços à esquerda) N Exibe números negativos entre parênteses sem espaços à esquerda! C Converte caracteres alfabéticos para maiúsculas

Templates: Símbolos de template seguem as funções no string de PICTURE se forem especificados. Cada posição no fluxo de entrada ou saída é mapeada para o símbolo na mesma posição no string template. O Clipper fornece vários símbolos os quais estão discriminados na tabela da página seguinte:

Tabela 4-2: Símbolos Template para PICTURES de GETs

Template AçãoA Permite somente caracteres alfabéticosN Permite somente caracteres alfabéticos e alfanuméricosX Permite qualquer caractere9 Permite dígitos para qualquer tipo de dados incluindo sinal para numéricos# Permite dígitos, sinais, e espaços para qualquer tipo de dadosL Permite somente T, F, Y ou NY Permite somente Y ou N! Converte um caractere alfabético para maiúsculo$ Exibe o sinal de dolar em lugar de um espaço à esquerda de um numérico* Exibe um asterisco em lugar de um espaço à esquerda de um numérico. Exibe um ponto decimal, Exibe uma vírgula

Outros caracteres especificados no template sobreescrevem o caractere localizado na mesma posição no fluxo fonte e saída. Se, entretanto, você usar a função R, símbolos não-template especificados são inseridos na tela mas não são gravados no buffer de GET.

WHEN e VALID: Um objeto GET também possui expressões de pré condição e pós condição usando WHEN e VALID respectivamente. A expressão WHEN é executada sempre que o usuário tenta entrar com o cursor na região de GET. A expressão VALID é executada sempre que o usuário tentar sair do GET exceto se o usuário apertar uma tecla com SET KEY ou Esc.

SET KEY: Quando existe uma rotina definida para SET KEY, o usuário pode apertar a tecla designada de forma a desviar o controle para a rotina definida. Após tal rotina ter sido executada, o controle retorna ao GET com o cursor restaurado à sua posição prévia.

Vida útil de um objeto GET: Objetos GET existem enquanto existirem referências ativas a eles em algum local do programa corrente. Caso você não tenha atribuído um objeto GET a outra variável ou GetList, ele terá uma duração enquanto o vetor GetList corrente existir, ou até que o vetor GetList seja reatribuído. O vetor GetList corrente é atribuído a um vetor vazio sempre que for emitido CLEAR GETS, CLEAR, ou um comando READ sem a cláusula SAVE.

Variável associada: Cada objeto GET é criado associado a uma variável que você especifica como <idVar>. Quando o objeto GET é ativado durante um READ, <idVar> é atribuído, em vários pontos, com o valor corrente do buffer do objeto GET. Isto ocorre nas seguintes situações:

O usuário aperta uma tecla de saída e antes a expressão de validação é executada.



O usuário aperta um SET KEYDa mesma forma, o buffer do GET corrente sofre refresh e é reexibido após vários intervalos, incluindo:

Quando do término de uma rotina SET KEY

Após uma expressão WHEN

Após uma expressão VALID

Isto permite a você explicitamente atribuir <idVar> dentro destas operações. Em Clipper 5.0, entretanto, não é mais necessário utilizar KEYBOARD para atualizar o buffer do GET corrente. Veja a nota abaixo para maiores informações.

Exibição do objeto GET: Quando o comando @...GET é executado, o novo objeto GET é exibido em <nLin> e <nCol>, a menos que a cláusula SAY seja especificada. Se isto acontece, o objeto GET é exibido em ROW() e COL() + 1. Caso SET DELIMITERS esteja ON quando o comando @...GET for executado, o objeto GET é inicialmente exibido delimitado pelo caractere escolhido correntemente como delimitador e seu atributo de coluna é <nCol> +1. Note que os delimitadores não são atributos do objeto GET, mas simplesmente são exibidos como na cláusula SAY.

Se INTENSITY está ON, um objeto GET é exibido na cor destaque ou vídeo reverso dependendo do adaptador utilizado pelo seu monitor. Se a cor não selecionado é definida, o objeto GET é exibido na cor destaque, enquanto os GET remanescentes serão exibidos na cor não selecionado. Com INTENSITY OFF, um objeto GET é exibido na cor corrente para a cor padrão.

Quando um objeto GET é exibido, o tamanho da área é determinado pelo tamanho de <idVar>, ou pelo número de dígitos especificado por <cGetPicture> se a cláusula PICTURE foi especificada. Caso a função @S for especificada como parte de <cGetPicture>, o tamanho da área a ser exibida é o argumento da função @S.

Notas

Atribuindo <idVar>: Devido às propriedades de refresh automático e exibição de um objeto GET quando sofre um READ, você pode fazer uma atribuição explícita de <idVar> ao objeto GET dentro de um WHEN ou VALID. Existem duas formas de fazê-lo. Para aplicações onde as expressões de validação estão acopladas ao objeto GET, você pode atribuir a variável por nome na expressão de validação ou numa função definida pelo usuário.

Para aplicações onde a rotina de validação é genérica e <idVar> não é uma variável campo ou elemento de vetor, você pode passar <idVar> por referência e atribuir seu parâmetro formal. Help em GET: Você exibe texto de help (auxílio) usando uma rotina de SET KEY. Dentro da rotina de SET KEY, use a função READVAR() para determinar a variável <idVar> associada ao objeto GET corrente. Então use esta informação para exibir o texto apropriado. Lembre-se de que num programa compilado em Clipper, a tecla F1 é automaticamente configurada para uma rotina de nome Help.

SET DEVICE TO PRINTER: A exibição de um objeto GET com o comando @...GET não é direcionada para a impressora ou arquivo caso SET DEVICE seja TO PRINTER.

Exemplos

O exemplo seguinte demonstra o uso da cláusula VALID para validar entradas num GET:



nNumber = 0@ 10, 10 SAY "Digite um número maior que zero:";GET nNumber;VALID nNumber > 0

Este exemplo mostra como a cláusula WHEN pode ser usada para proibir a entrada em GETs baseada no valor de outro GET. Neste exemplo, entrando com Y no campo Insured indica que o cliente tem seguro e ao usuário é permitido entrar com a informação. Se o cliente não tem seguro, o cursor move-se para o campo Accident:

@ 10, 10 GET Insured PICTURE "Y"@ 11, 10 GET InsNumber WHEN Insured@ 12, 10 GET InsCompany WHEN Insured@ 13, 10 GET Accident PICTURE "Y"READ

Um exemplo de GET em uma área secundária:

USE Invoice NEWAPPEND BLANKUSE Inventory NEW@ 1, 1 GET Invoice->CustNoREAD

Este exemplo demonstra o uso da função @K para sugerir um valor padrão de entrada, mas elimina-o caso a primeira tecla pressionada não seja uma tecla de movimentação de cursor ou Return:

file = "Accounts"@ 1, 1 SAY "Arquivo" GET file PICTURE "@K"READ

MENU TO

Executa um menu de barra luminosa para PROMPTs definidos

Sintaxe

MENU TO <idVar>

Argumentos

<idVar> é o nome da variável à qual será atribuída o resultado da seleção de menu. Caso a variável especificada não seja visível ou não exista, uma do tipo privada é criada e a ela atribuído o resultado.

Descrição

O comando MENU TO é o mecanismo de seleção para o sistema de menus de barra luminosa do Clipper. Antes de chamar o comando MENU TO, defina primeiro os PROMPTS do menu e mensagens associadas com uma série de comandos @...PROMPT. Depois, ative o menu com MENU



TO <idVar>. Se <idVar> não existir ou não for visível, o comando MENU TO irá criá-la como uma variável do tipo privada e coloca a barra luminosa sobre o primeiro PROMPT. Se ele não existir, seu valor inicial determina o primeiro PROMPT sobre o qual ficará a barra luminosa.

Notas

Cor: Os PROMPTs são escritos na tela na cor padrão corrente. O PROMPT sobre o qual aparece a barra luminosa aparece na cor corrente destaque.

Navegação e seleção: As teclas de navegação movem a barra luminosa para o PROMPT anterior ou posterior. A cada PROMPT que é evidenciado pela barra luminosa, a sua respectiva mensagem (MESSAGE) aparece na linha, especificada com SET MESSAGE. Se o comando WRAP está em ON, e caso a barra luminosa esteja posicionada no primeiro PROMPT, teclando Cursor para cima moverá a barra luminosa para o último PROMPT. Da mesma forma, teclando Cursor para baixo do último PROMPT move a barra luminosa para o primeiro prompt.

Para fazer uma seleção, tecle Return ou o primeiro caractere de um PROMPT. O comando MENU TO então retorna a posição do PROMPT selecionado como um valor numérico para a variável de memória especificada. A tecla Esc interrompe a seleção de menu e retorna zero. A tabela na página seguinte resume as teclas ativas dentro do comando MENU TO.

Rotinas SET KEY: Um comando MENU TO pode ser aninhado num procedimento SET KEY chamado dentro de um menu sem que os PROMPTs pendentes sejam apagados, o que não acontece com os comandos GET/READ.

Tabela 4-8: Teclas Ativas em MENU TO

Tecla AçãoCursor para cima Move para o item anteriorCursor para baixo Move para o próximo itemHome Move para o primeiro itemEnd Move para o último item Cursor para esquerda Move para o item

anterior Cursor para direita Move para o próximo itemPgUp Seleciona item de menu, retorna posiçãoPgDn Seleciona item de menu, retorna posiçãoReturn Seleciona item de menu, retorna posiçãoEsc Aborta seleção, retorna zeroPrimeira letra Seleciona primeiro item iniciando com a letra,retorna posição

Exemplos

Este exemplo cria um menu de barra luminosa vertical simples com as mensagens aparecendo centradas na linha 23. Quando este comando é usado, a barra luminosa sempre aparece sobre o segundo PROMPT baseado no valor inicial definido em nChoice:

LOCAL nChoice := 2SET WRAP ONSET MESSAGE TO 23 CENTER@ 6, 10 PROMPT "Inclui" MESSAGE "Nova conta"@ 7, 10 PROMPT "Edita " MESSAGE "Muda conta"@ 9, 10 PROMPT "Fim " MESSAGE "Retorna ao DOS"



MENU TO nChoice//IF nChoice == 1

NewAccount()ELSEIF nChoice == 2

ChangeAcoount()ELSE

QUITENDIFRETURN

READ

Ativa edição em tela usando objetos GET.

Sintaxe

READ [SAVE]

Argumentos

SAVE retém o conteúdo do vetor GetList corrente após o fim da operação do comando READ. Depois, você pode editar os mesmos objetos GET através de outro comando READ. Caso não esteja especificada, à GetList corrente é atribuído um vetor vazio eliminando todos os objetos GET anteriores quando o comando READ tiver terminado.

Descrição

O comando READ executa um módulo de edição em tela usando todos os objetos GET criados e adicionados à GetList corrente a partir dos comandos CLEAR, CLEAR GETS, CLEAR ALL ou READ mais recentes. Se há uma rotina de formatação ativa, o comando READ executa essa rotina antes de entrar no módulo de edição em tela.

Dentro de um READ, o usuário pode editar o buffer de cada objeto GET bem como mover-se de um objeto GET para outro. Antes que o usuário possa entrar com um objeto GET, o controle passa para o respectivo WHEN <lPreCondição> caso alguma tenha sido atribuída àquele objeto GET. Se <lPreCondição> retornar valor verdadeiro (.T.), é permitido ao usuário editar o buffer do objeto GET. Caso contrário, o controle passa para o próximo objeto GET na GetList. Dentro de um buffer GET, o usuário pode editar, utilizando-se do conjunto completo de teclas de navegação e edição. Veja as tabelas abaixo.

Quando o usuário pressiona uma tecla de saída de GET, o controle passa à pós-condição RANGE ou VALID respectiva, caso tenha sido especificada. Se alguma das condições retornar valor verdadeiro (.T.), a edição do objeto GET é encerrada e o controle passa para o próximo objeto GET. Caso contrário, o controle permanece dentro do objeto GET corrente até que um valor válido for entrado ou até que o usuário tecle Esc.

Quando o usuário consegue entrar com um valor num objeto GET, é atribuído à respectiva variável o valor do buffer do objeto GET.



As seguintes tabelas listam teclas ativas num comando READ:

Tabela 4-9: Teclas de Navegação em um READ

Tecla AçãoCursor para esquerda, Ctrl-S Caractere à esquerda. Não move cursor para o GET

anteriorCursor para direita, Ctrl-D Caractere à direita. Não move cursor para o próximo GETCtrl-Cursor para esquerda, Ctrl-A Palavra à esquerdaCtrl-Cursor para direita, Ctrl-F Palavra à direitaCursor para cima, Ctrl-E GET anteriorCursor para baixo, Ctrl-X, Return, Ctrl-M Próximo GETHome Primeiro caractere do GETEnd último caractere do GETCtrl-Home Início do primeiro GETCtrl-End Início do último GET

Tabela 4-10: Teclas de Edição de READs

Tecla AçãoDel, Ctrl-G Elimina caractere onde está o cursorBackspace, Ctrl-H BackspaceCtrl-T Elimina palavra à direitaCtrl-Y Elimina do cursor até o final do GETCtrl-U Retorna o GET ao seu valor original

Tabela 4-11: Teclas Comutativas em um READ

Tecla AçãoIns, Ctrl-V Comuta modo de inserção

WAIT*

Suspende a execução de um programa até que seja pressionada uma tecla

Sintaxe

WAIT [<expPrompt>] [TO <idVar>]

Argumentos

<expPrompt> é uma expressão de qualquer tipo. O assumido é "Aperte qualquer tecla para continuar..."

TO <idVar> é a variável de qualquer categoria à qual será atribuída a tecla pressionada seu valor caractere. Se <idVar> não existe ou não está visivel, ela é criada como privada e então lhe é atribuído o valor caractere.



Descrição

WAIT é um estado de espera que exibe um prompt após enviar um carriage return/line feed para a tela. Então aguarda até que o usuário aperte um tecla. Se a cláusula TO for especificada, <idVar> recebe o valor da tecla pressionada como caractere. Se um Alt ou Ctrl é pressionado, WAIT atribui CHR(0) a <idVar>. Valores não alfanuméricos entrados por Alt-númericos atribuem o caractere especificado. Se o caractere for do tipo que pode ser exibido, ele é ecoado em tela. Teclas de função são ignoradas a menos que atribuídas com SET FUNCTION E SET KEY.

WAIT é um comando de compatibilidade e portanto não recomendado. Ele é superado por @...GET/READ e INKEY().

Notas

WAIT sem prompt: Para interromper a execução de um programa, especifique WAIT "" ou INKEY(0), o segundo é recomendado pois não perturba a posição do cursor na tela.

Exemplos

WAIT "Aperte uma tecla..." TO key

Comandos para manutenção de arquivos de dados

APPEND BLANK

Adiciona um registro vazio ao arquivo de dados corrente

Sintaxe

APPEND BLANK

Descrição

APPEND BLANK adiciona um registro vazio no fim do arquivo corrente e o torna o registro corrente. Os novos valores de campos são inicializados em valores vazios para cada tipo de dado. A campos caractere são atribuídos espaços, campos numéricos são inicializados com zero, campos lógicos são inicializados com falso (.F.), a campos data são atribuídos CTOD(""), e campos memo são deixados vazios.

Quando estiver operando em ambiente de rede e o arquivo corrente estiver compartilhado, APPEND BLANK tenta adicionar e então travar o registro novo. Se outro usuário tiver travado o arquivo com FLOCK() ou travado LASTREC() + 1 com RLOCK(), NETERR() retorna verdadeiro (.T.). Note que um registro recém APPENDado permanece travado até que você trave outro registro ou execute UNLOCK. Note também que APPEND BLANK não libera um FLOCK() imposto pelo usuário corrente.

Exemplos



Este exemplo tenta adicionar um registro a um arquivo de dados compartilhado e usa NETERR() para testar o sucesso da operação:

USE Vendas SHARED NEW

APPEND BLANKIF !NETERR()

<atualiza registro vazio>...ELSE

? "Append não realizado"BREAK

ENDIFAPPEND RECORD 5 FROM Temp

CLEAR ALL

Fecha arquivos e libera as variáveis públicas e privadas

Sintaxe

CLEAR ALL

Descrição

CLEAR ALL libera todas as variáveis públicas e privadas, fecha todos os arquivos abertos e os que a eles estejam relacionados em todas as áreas, e seleciona (SELECT) a área 1.

Arquivos relacionados são índices, alternate, e memo. Note que CLEAR ALL não libera variáveis estáticas ou locais.

CLEAR ALL é um comando de compatibilidade e portanto não recomendado.Seu uso em Clipper é superado por comandos ou funções que executam a ação que você necessita. Arquivos associados a áreas de trabalho podem ser fechados de várias formas com o comando CLOSE. Liberação explícita de variáveis não é recomendada na maioria dos casos.

CLOSE

Fecha um conjunto específico de arquivos

Sintaxe

CLOSE [<idAlias> | ALL | ALTERNATE | DATABASES | FORMAT | INDEXES]

Argumentos

<idAlias> especifica a área de trabalho onde os arquivos serão fechados.

ALL Fecha arquivos de dados, alternate, e de indíces em todas as áreas. Além disso, libera todos os filtros, relações e formatos ativos.



ALTERNATE Fecha o arquivo alternate corrente, executa o mesmo que SET ALTERNATE TO sem argumento.

DATABASES Fecha todos os arquivos de dados abertos, memos e índices See also: QUIT RETURN SET ALTERNATE SET INDEX USE

DATABASES Fecha todos os arquivos de dados abertos, memos e índices em todas as áreas, e libera filtros e relações ativas. Entretanto, ele não causa efeito no formato ativo.

FORMAT libera o formato corrente, executando a mesma ação que SET FORMAT TO sem argumento.

INDEXES Fecha todos arquivos de índice na área corrente.

Descrição

CLOSE é um comando de propósito geral que fecha vários tipos de arquivos Clipper dependendo da cláusula opcional especificada. CLOSE sem opção fecha o arquivo de dados corrente e seus índices, o mesmo que USE sem argumentos.

Em Clipper, vários outros comandos fecham arquivos, incluindo:

QUIT CANCEL* RETURN a partir da rotina principal CLEAR ALL* USE sem argumentos

COMMIT

Executa uma gravação em disco para todas as áreas ativas

Sintaxe

COMMIT

Descrição

COMMIT dirige os buffers do Clipper para disco e executa sua gravação para todas as áreas de trabalho com arquivos de dados ou índices abertos. Tal característica está disponível apenas em DOS 3.3 ou superior. Sob DOS 3.2 ou inferior, o COMMIT dirige os buffers do Clipper para os do DOS.

No ambiente de rede, COMMIT faz todos os tipos de atualização para um arquivo de dados e seus índices visiveis a outros processos.

Exemplos

Neste exemplo, COMMIT é utilizado para forçar a escrita em disco, após atribuir o conteúdo de variáveis de memória a variáveis campo:



USE Sales EXCLUSIVE NEWMEMVAR->Name := Sales->NameMEMVAR->Amount := Sales->Amount//@ 10, 10 GET MEMVAR->Name@ 11, 10 GET MEMVAR->AmountREAD//IF UPDATED()

APPEND BLANKSales->Name := MEMVAR->NameSales->Amount := MEMVAR->AmountCOMMIT

ENDIF

CREATE

Cria um arquivo de estrutura (.dbf) vazio

Sintaxe

CREATE <xcArquivoEstrutura>

Argumentos

<xcArquivoEstrutura> é o nome do arquivo de estrutura vazio. Este argumento pode ser especificado literalmente ou como expressão caractere entre parênteses. Se não for colocada extensão, o assumido será (.dbf).

Descrição

O comando CREATE produz um arquivo de estrutura vazio que tem o seguinte formato:

Tabela 4-6: Formato de Um Arquivo de Estruturas

Campo Nome Tipo Tamanho Decimais1 Field_name Caractere 102 Field_type Caractere 13 Field_len Numérico 3 04 Field_dec Numérico 4 0

Tal como o comando COPY STRUCTURE EXTENDED, CREATE pode ser usado juntamente com CREATE FROM para formar um novo arquivo de dados. Ao contrário do comando COPY STRUCTURE EXTENDED, CREATE produz um arquivo de dados vazio, e não necessita da presença de um outro arquivo de dados para isso.

<xcArquivoEstrutura> é automaticamente aberto na área de trabalho corrente após ser criado.



Exemplos

Este exemplo cria um novo arquivo de estrutura, coloca a definição de um campo dentro do mesmo, e então cria um novo arquivo de dados a partir da estrutura:

CREATE TempStruAPPEND BLANKREPLACE;Field_name WITH "Name";Field_type WITH "C";Field_len WITH 25;Field_dec WITH 0CLOSECREATE NewFile FROM TempStru

DELETE

Marca registros para eliminação

Sintaxe

DELETE [<abrangência> [WHILE <lCondição>] [FOR <lCondição>]

Argumentos

<abrangência> é a porção do arquivo de dados corrente a ser eliminada. Se abrangência não for especificada, o comando DELETE agirá somente no registro corrente. Se uma <abrangência> ou cláusula condicional for especificada, o padrão torna-se todos (ALL) os registros.

WHILE <lCondição> especifica o conjunto dos registros que atendem a condição do registro corrente até que a condição seja falsa.

FOR <lCondição> especifica o conjunto de registros condicional a ser eliminado dentro da abrangência.

Descrição

O comando DELETE marca os registros para que eles possam ser filtrados com o comando SET DELETED ON, identificados com a função DELETED(), ou fisicamente removidos do arquivo de dados com o comando PACK. Além disso, comandos de visualização de registros como, por exemplo, LIST e DISPLAY identificam os registros marcados para eliminação com um asterisco (*). Uma vez marcados os registros, você pode recuperá-los usando o comando RECALL. Se você desejar remover todos os registros de um arquivo de dados, use o comando ZAP ao invés dos comandos DELETE ALL e PACK.Num ambiente de rede, o comando DELETE pede que o registro corrente seja travado através da função RLOCK(), caso você esteja marcando um único registro. Se você estiver marcando vários registros, o arquivo de dados corrente deve ser travado com a função FLOCK() ou aberto EXCLUSIVE.



Notas

Marcação com o comando SET DELETED ON: Se o registro corrente for eliminado com o comando SET DELETED ON, ele permanecerá visível até que o ponteiro de registro seja movido.

Exemplos

Este exemplo demonstra como deve ser especificada a cláusula FOR para marcar um conjunto de registros a ser eliminado:

USE Sales INDEX Salesman NEWDELETE ALL FOR Inactive

GO

Move o ponteiro de registro para um registro específico

Sintaxe

GO[TO] <nRegistro> | BOTTOM | TOP

Argumentos

<nRegistro> especifica o número do registro destino.

BOTTOM especifica o último registro na área de trabalho corrente.TOP especifica o primeiro registro na área de trabalho corrente.

Descrição

O comando GO posiciona o ponteiro num registro especificado na área de trabalho corrente. O registro pode ser especificado através de seu número ou como registro início ou fim do arquivo. Se a nova posição é início (TOP) e há um índice ativo, o ponteiro de registros vai até o primeiro registro do índice, ou então para o registro 1. Caso a nova posição seja fim (BOTTOM) e haja um índice ativo, o ponteiro de registros vai para o último registro do índice, ou então para a função LASTREC().

A forma GO <nRegistro> do comando é a mesma da cláusula RECORD de qualquer comando de arquivo de dados que aceite uma abrangência.

Acessando registros filtrados: Os registros filtrados pelos comandos SET DELETED ON ou SET FILTER TO podem ser acessados por GO <nRegistro>. Se o comando DELETED estiver em ON ou se houver um FILTER ativo, o comando GO BOTTOM vai para o último registro lógico que não tiver sido marcado e/ou atenda a condição do filtro.Caso o comando DELETED estiver em ON ou haja um FILTER ativo, o comando GO TOP vai para o primeiro registro lógico que não tiver sido marcado e/ou atenda a condição do filtro.

Indices de chave única: Registros não presentes em um índice criado com SET UNIQUE ON ou INDEX...UNIQUE podem ser acessados pelo comando GO <nRegistro>.



Registro fora da faixa: Em Clipper, um comando GO que posiciona o ponteiro num registro fora do alcance do arquivo de dados não gera um erro em tempo de execução. Pelo contrário, as funções EOF() e BOF() retornam verdadeiras (.T.) e o ponteiro de registros é ajustado para LASTREC() + 1.

Refresh dos buffers de arquivos de dados e de índices:

Num ambiente de rede, você pode fazer refresh dos buffers de arquivos de dados e de índices sem mover o ponteiro de registros, usando a função GO RECNO

Exemplos

Estes exemplos mostram resultados do comando GO simples:

USE Sales NEW? LASTREC() // Resulta: 84GO TOP? RECNO() // Resulta: 1

GO BOTTOM? RECNO() // Resulta: 84

GO 5? RECNO() // Resulta: 5

GO 5 + 15? RECNO() // Resulta: 20

INDEX

Cria um arquivo de índices.

Sintaxe

INDEX ON <expChave> TO <xcIndice> [UNIQUE]

Argumentos

<expChave> é uma expressão que retorna o valor chave a ser colocado no índice para cada registro na área de trabalho corrente. <expChave> pode ser do tipo caractere, data, lógico, ou numérico. O tamanho máximo da expressão da chave de indexação é de 250 caracteres.

TO <xcIndice> especifica o nome do arquivo de índices a ser criado. O nome do arquivo pode ser especificado literalmente ou por expressão caractere entre parênteses. Normalmente, a extensão de arquivo padrão é (.ntx). Se, contudo, você linkou NDX.OBJ a fim de usar arquivos de índice compatíveis com dBASE III PLUS, a extensão padrão passa a ser (.ndx).UNIQUE especifica que <xcIndice> inclui somente valores de chave únicos.

Descrição



O comando INDEX ON cria um arquivo que contém um índice dos registros do arquivo de dados corrente baseado em <expChave>. Quando o arquivo de índices é usado, os registros do arquivo de dados aparecem na ordem da expressão chave, embora o índice não altere a ordem física dos registros dentro do arquivo de dados. O comando INDEX ordenas as chaves de caractere de acordo com o valor ASCII de cada caractere dentro da cadeia, valores numéricos em ordem numérica, ordem cronológica dos valores de datas, considerando datas em branco como valores baixos, e valores lógicos classificados com valor verdadeiro (.T.) considerados como valores altos. Campos memo não podem ser indexados.

Quando o comando INDEX ON é usado, todos os arquivos de índice abertos na área de trabalho corrente são fechados e o novo arquivo de índices é criado. Quando a operação de indexação termina, o novo índice permanece aberto, tornando-se o índice de controle, e o ponteiro de registro é posicionado no primeiro registro do índice.

O comando INDEX assemelha-se ao comando SORT, porém não faz uma cópia física do arquivo de dados, e é atualizado a cada vez que um novo valor chave é entrado no arquivo de dados corrente. O comando SORT é usado primordialmente para copiar um subconjunto ordenado de registros para outro arquivo de dados.

Em ambiente de rede, o comando INDEX abre um <xcIndice> exclusivo. Caso haja falha, ocorre um erro em tempo de execução e a função de erro respectiva é chamada. Consulte o capítulo Programando em Rede no livro Programando e Utilitários para mais informações.

Notas

Indices de Datas: O Clipper aceita índices de data para os dois tipos de índice,(.ntx) e (.ndx). Para uma expressão chave que possui uma data como subconjunto da chave, transforme a expressão numa de tipo caractere e use a função DTOS() para converter a data em caractere. Por exemplo:

USE InvoicesINDEX ON Customer + DTOS(InvDate) TO Invoice

Variáveis declaradas: Variáveis locais e estáticas não podem ser usadas em expressões de chave de indexação. Isto acontece porque tais expressões são gravadas como texto nos arquivos de índice e são mais tarde expandidas para produzir valores chave. Uma vez que variáveis locais e as estáticas são invisíveis dentro das variáveis macro, referências a elas dentro de expressões de chave de indexação não serão reconhecidas devidamente.

Pela mesma razão, uma variável declarada com qualquer uma das outras declarações em tempo de compilação como, por exemplo, MEMVAR ou FIELD, não são válidas dentro de uma expressão de chave de indexação. Se for necessária qualificação de nome (alias) ou de variável numa expressão de chave de indexação, deve-se fazê-lo claramente na expressão e não através de declarações ao compilador.

Registros marcados e filtrados: Registros que estão filtrados ou marcados para eliminação não são incluídos no índice.

Indices de ordem descendente: Para criar índices de ordem ou sub-ordens descendentes, use a função DESCEND(). Esta função aceita qualquer tipo de dados como argumento e retorna o valor na forma complementar. Depois, ao executar um SEEK dentro do índice,use a função DESCEND() como parte do argumento de SEEK.



Indices de ordem tipo dicionário: Para criar um índice de ordem tipo dicionário de chaves de caractere, use UPPER(<expChave>) como expressão de índice. Ordens do tipo dicionário são aquelas onde a diferenciação entre letras maiúsculas e minúsculas não é feita.

Arquivos de índice compatíveis: O Clipper aceita arquivos de índice dBASE III PLUS compatíveis através da conexão de um driver de arquivo de dados.

Cuidado

O driver de arquivo de dados não aceita os mecanismos de segurança do dBASE III PLUS. Isto significa que você não pode ter programas Clipper e dBASE III PLUS acessando ao mesmo tempo os mesmos arquivos de índice numa rede sem comprometer a integridade dos mesmos. Com dois programas Clipper, porém, o driver dBASE III PLUS funciona da mesma forma que o driver padrão.

Indice com chaves únicas: Quando você utiliza os comandos INDEX...UNIQUE or SET UNIQUE ON, o Clipper cria um índice que tem atributo de unicidade. Ù medida em que é feita a indexação e dois ou mais registros têm o mesmo valor chave, o Clipper inclui somente o primeiro registro no índice. Toda vez que o índice com chaves únicas for atualizado, reindexado, ou removido, somente registros com chaves únicas são acrescidos. Note que um índice de chaves únicas retém o atributo de unicidade e não é afetado por utilizações subsequentes do comando UNIQUE.

Usando TRIM(): O Clipper armazena valores de chave de indexação em incrementos fixos. Uma <expChave> que muda o tamanho da chave pode criar um índice inoperável. Isto acontece porque o tamanho das chaves de indexação é calculado por avaliação da <expChave> num registro em branco. Uma <expChave> com TRIM(), portanto, sempre é avaliada como sendo um string nulo (""), o que ocasiona uma falta de correspondência entre o destino e o tamanho da chave definida. Para usar qualquer uma das funções TRIM() use a função PADR() para fazer com que os tamanhos das chaves sejam os mesmos, conforme o exemplo abaixo:

USE Customer NEWINDEX ON PADR(RTRIM(Last) + First, 40) TO CustName

Exemplos

Estes exemplos mostram resultados do comando INDEX simples:

? TYPE("Branch") // Resulta: CINDEX ON Branch TO Branch? TYPE("Amount") // Resulta: NINDEX ON Amount TO Amount? TYPE("Date") // Resulta: DINDEX ON Date TO Date

Os dois exemplos abaixo criam índices de ordem descendente:

USE Invoices NEWINDEX ON DESCEND(InvDate) TO InvStackINDEX ON Customer + DESCEND(DTOS(InvDate)) TO CustStack

Tabela 4-12: Teclas de Saída de um READ



Tecla AçãoCtrl-W, Ctrl-C, PgUp, PgDn

Encerra um READ gravando GET corrente

Return, Ctrl-M Encerra um READ a partir do último GETEsc Encerra um READ sem gravar o GET correnteCursor para cima Encerra um READ a partir do primeiro GET se READEXIT()=.T.Cursor para baixo Encerra um READ do último GET se READEXIT()=.T.

Notas

BREAK dentro de um READ: Observe que um BREAK dentro de um comando READ finaliza o READ e limpa os GETs mesmo se a cláusula SAVE for usada.

READs aninhados: Para executar um comando READ aninhado dentro de um procedimento SET KEY, VALID, ou WHEN ou de uma função definida por usuário, declare ou crie uma nova GetList, execute uma série de declarações @...GET, e depois o comando READ. Quando o procedimento terminar, a nova GetList é liberada e a anterior torna-se visível novamente. Veja o exemplo abaixo.

Home e End: Teclando Home ou End vai para o primeiro ou último caractere que não estiver em branco num buffer de objeto GET.

Finalizando um READ: Você pode finalizar um comando READ executando um CLEAR, CLEAR GETS, ou CLEAR ALL de dentro de uma rotina SET KEY ou uma função definida pelo usuário iniciada por VALID.

UPDATED(): Caso qualquer buffer de objeto GET tenha sido mudado durante o comando READ corrente, a função UPDATED() é configurada em verdadeiro (.T.).

Exemplos

O exemplo abaixo define vários GETs e a seguir usa o comando READ:

CLScVar1 := cVar2 := cVar3 := SPACE(10)@ 10, 10 SAY "Variavel Um :" GET cVar1 VALID !EMPTY(cVar1)@ 11, 10 SAY "Variavel Dois:" GET cVar2 WHEN RTRIM(cVar1) != "Um"@ 12, 10 SAY "Variavel Tres:" GET cVar3 VALID !EMPTY(cVar3)READ

Este exemplo ilustra como executar um READ aninhado dentro de um procedimento SET KEY, WHEN, ou VALID ou função definida pelo usuário:

LOCAL cName := SPACE(10)@ 10, 10 GET cName VALID SubForm( cName )READRETURN

FUNCTION SubForm( cLookup )PRIVATE GetList := {} // Cria novo GetListUSE Sales INDEX Salesman NEW



SEEK cLookupIF FOUND()

@ 15, 10 GET Salesman // Adiciona novos GETS a GetList@ 16, 10 GET AmountREAD // READ GetList

ENDIFCLOSE SalesRETURN .T. // LIbera GetList

REPLACE

Atribui novos valores a variáveis campo

Sintaxe

REPLACE <idCampo> WITH <exp>[, <idCampo2> WITH <exp2>...][<abrangência>] [WHILE <lCondição>] [FOR <lCondição>]

Argumentos

<idCampo> é o nome da variável campo à qual será atribuído novo valor. Se <idCampo> for precedido de um alias, a atribuição ocorre na área de trabalho designada.

<exp> é o valor a ser atribuído a <idCampo>.

<abrangência> é a parte do arquivo de dados corrente onde atuará o comando REPLACE. Sendo especificada uma condição, o assumido será todos (ALL) os registros na área de trabalho corrente.

WHILE <lCondição> especifica o conjunto de registros que atendem a condição do registro corrente, até que a condição seja falsa.

FOR <lCondição> especifica o conjunto condicional de registros sobre os quais atuará o comando REPLACE dentro da abrangência.

Descrição

O comando REPLACE atribui novos valores aos conteúdos de uma ou mais variáveis campo nos registros correntes nas áreas de trabalho especificadas. As variáveis campo destino podem ser do tipo caractere, data, lógico, memo, ou numérico. O comando REPLACE tem a mesma função que o operador inline (:=) com a diferença que ele assume que uma referência sem um alias é sempre para uma variável campo. Isto significa que você pode atribuir novos valores a variáveis campo usando declarações de atribuição, desde que as referências a variáveis campo sejam precedidas de um alias, o alias do campo, ou declaradas através de declaração de comando do campo, caso a referência seja ambígua.

A abrangência padrão do comando REPLACE é o registro corrente, a não ser que seja especificada uma abrangência ou condição. Caso haja abrangência ou condição especificadas, o comando REPLACE atua em cada registro que atenda a condição e/ou abrangência.



Aviso

Ao usar o comando REPLACE num campo chave, o índice é atualizado e a posição relativa do ponteiro de registro dentro do índice é modificada. Isto significa que utilizar o comando REPLACE num campo chave com uma abrangência ou condição pode ocasionar um resultado errôneo. Para atualizar um campo chave, use o comando SET ORDER TO 0 antes do comando REPLACE. Isto assegura que o ponteiro de registro mova-se sequencialmente em ordem natural. Todos os índices abertos, porém, são atualizados se o comando REPLACE for usado no campo chave.

Num ambiente de Rede, usar o comando REPLACE no registro corrente requer a função RLOCK(). Executar o comando REPLACE com uma abrangência e/ou condição exige um FLOCK() ou USE EXCLUSIVE do arquivo de dados corrente. Caso o comando REPLACE estiver sendo executado em outra área de trabalho através da especificação de seu alias, esse registro também deve ser travado com um RLOCK().

Exemplos

Este exemplo ilustra um uso simples do comando REPLACE:

USE Customer NEWAPPEND BLANKUSE Invoices NEWAPPEND BLANK//REPLACE Charges WITH Customer->Markup * Cost,;Custid WITH Customer->Custid,;Customer->TranDate WITH DATE()

Ao usar declarações de atribuição em lugar do comando REPLACE siga o seguinte exemplo:

FIELD->Charges := Customer->Markup * FIELD->CostFIELD->Custid := Customer->CustidCustomer->TranDate := DATE()

SELECT

Muda a área de trabalho corrente

Sintaxe

SELECT <xnArea> | <idAlias>

Argumentos

<xnArea> é o número da área de trabalho entre zero e 250. Este argumento é uma expressão extendida e pode ser especificada literalmente por um número ou expressão numérica entre parênteses.

<idAlias> é o nome de uma área de trabalho existente a ser selecionada caso haja um arquivo de dados aberto naquela área.



Descrição

O comando SELECT é usado para mudar áreas de trabalho. O Clipper aceita até 250 áreas de trabalho, e com cada área de trabalho um handle lógico para abrir um arquivo de dados juntamente com todos os seus atributos. Referências a áreas de trabalho com o comando SELECT podem ser feitas através de números ou alias. O alias de uma área de trabalho é automaticamente atribuído quando um arquivo de dados é usado naquela área de trabalho ou utilizando-se a cláusula ALIAS.

Àrea de trabalho zero refere-se à primeira área de trabalho vazia.Usando isto, você pode selecionar 0 e usar <xcArquivo> como um método para a abertura de arquivos de dados.

Notas

Expressões alias: Expressões alias são um método muito mais eficiente de selecionar novas áreas de trabalho do que o comando SELECT. Ao invés de selecionar uma área de trabalho e depois executar uma operação para aquela área de trabalho, você pode aplicar um alias a uma expressão que execute aquela operação. Isto é feito especificando-se o alias da área de trabalho desejada e a expressão entre parênteses. Por exemplo, para acessar o valor da função EOF() numa área de trabalho não selecionada, você normalmente executaria uma série de declarações como as seguintes:

SELECT Remote? EOF()SELECT Main

Usando a forma de expressão alias, estas declarações ficam da seguinte forma:

? Remote->(EOF())

USE...NEW: Ao invés de usar os comandos SELECT 0 e USE<xcArquivo> para abrir um arquivo de dados numa nova área de trabalho, você pode utilizar USE <xcArquivo> NEW.

Exemplos

Este exemplo ilustra como uma série de arquivos de dados pode ser aberta selecionando-se cada área de trabalho através de seu número e depois abrindo cada arquivo de dados naquela área:

SELECT 1USE CustomerSELECT 2USE InvoicesSELECT 3USE PartsSELECT Customer

Um método mais correto é abrir cada arquivo de dados na próxima área de trabalho disponível especificando a cláusula NEW na linha de comando USE. Neste exemplo, USE...NEW é empregado ao invés do comando SELECT 0 e depois USE:

USE Customer NEWUSE Invoices NEW



SELECT Customer

Este fragmento de código ilustra a mudança de áreas de trabalho juntamente com a gravação do nome da área de trabalho corrente em uma variável utilizando a função SELECT(). Após executar uma operação na nova área de trabalho, a área de trabalho original pode ser re-selecionada através do nome da área de trabalho armazenada:

nLastArea := SELECT()USE Newfile NEW//<declarações>...//SELECT (nLastArea)

SKIP

Move o ponteiro de registro para uma nova posição

Sintaxe

SKIP [<nRegistros>] [ALIAS <idAlias> | <nAreaTrabalho>]

Argumentos

<nRegistros> é uma expressão numérica que especifica o número de registros para mover o ponteiro a partir da posição corrente. Um valor positivo especifica deslocamento do ponteiro para frente e valores negativos significam deslocamento do ponteiro para trás.

ALIAS <idAlias>|<nAreaTrabalho> especifica o nome alias como literal ou a área de trabalho como expressão numérica.

SKIP especificado sem argumentos move o ponteiro 1 registro para frente.

Descrição

SKIP move o ponteiro para uma nova posição relativa à posição corrente na área corrente e dentro do filtro corrente, caso exista um. SKIP é geralmente usado para operações com relatórios, que necessitam mover o ponteiro para o próximo registro.

Se o alias for especificado, o ponteiro pode ser movido em outra área sem selecioná-la. SKIP pode mover o ponteiro para frente ou para trás. Caso não exista índice ativo, SKIP move o ponteiro relativo à posição corrente no arquivo destino. Se existe um índice ativo, SKIP move o ponteiro relativo à posição corrente no índice ao invés do arquivo de dados.

SKIP a frente em posições além do fim de arquivo com o ponteiro em LASTREC() + 1 e EOF() sempre retornam verdadeiro (.T.). Mover o ponteiro para antes do BOF() retona verdadeiro (.T.).

Em rede, qualquer movimentação de ponteiro, inclusive SKIP, irá tornar as modificações na área corrente visíveis a outras aplicações se o arquivo corrente está SHARED e as alterações foram feitas durante um RLOCK(). Se, entretanto, as modificações forem feitas durante um FLOCK(), a



visibilidade não é garantida até a liberação do travamento, um COMMIT, ou o fechamento do arquivo. Para forçar uma atualização a ser visível sem mudar a posição corrente, use SKIP 0

Exemplos

O exemplo seguinte usa SKIP com vários argumentos e mostra o resultado:

USE Customers NEWSKIP? RECNO() // Resulta: 2SKIP 10? RECNO() // Resulta: 12SKIP -5? RECNO() // Resulta: 7

O exemplo seguinte move o ponteiro em áreas remotas:

USE Customers NEWUSE Invoices NEWSKIP ALIAS Customers

Este exemplo imprime um relatório usando SKIP para mover o ponteiro sequencialmente através do arquivo:

LOCAL nLine := 99USE Customers NEWSET PRINTER ONDO WHILE !EOF()

IF nLine > 55EJECTnLine := 1

ENDIF? Customer, Address, City, State, ZipnLine++SKIP

ENDDOSET PRINTER OFF

ZAP

Remove todos os registros do arquivo corrente

Sintaxe

ZAP

Descrição

O comando ZAP remove permanentemente todos os registros dos arquivos presentes na área corrente. Isto inclui arquivos de dados, índices e memo. O espaço em disco ocupado é liberado. ZAP executa o mesmo que DELETE ALL e PACK, porém é quase instantâneo.



Para emitir ZAP na rede, o arquivo deve estar em USE EXCLUSIVE

Exemplos

Este exemplo demonstra um ZAP em rede:

USE Sales NEW EXCLUSIVEIF !NETERR()

SET INDEX TO Sales, Branch, SalesmanZAPCLOSE Sales

ELSE? "Zap não executado"BREAK

ENDIf

Comandos para pesquisa em arquivos

SEEK

Pesquisa um índice através de um valor chave especificado

Sintaxe

SEEK <expPesquisa>

Argumentos

<expPesquisa> é uma expressão à qual a chave de indexação deverá corresponder.

Descrição

O comando SEEK pesquisa o índice de controle que começa com a primeira chave e continua até que seja encontrada correspondência ou até que haja um valor chave maior do que o argumento de pesquisa. Caso haja correspondência, o ponteiro de registro é posicionado no número do registro encontrado no índice. Se SOFTSEEK estiver em OFF (o padrão) e não seja encontrada correspondência, o ponteiro de registro é posicionado em LASTREC() + 1, EOF() retorna valor verdadeiro (.T.), e FOUND() retorna valor falso (.F.). Caso SOFTSEEK esteja em ON, o ponteiro de registro é posicionado no registro que tenha o primeiro valor chave maior do que o argumento de procura, e FOUND() retorna valor falso (.F.). Nesse caso, EOF() retornará valor verdadeiro (.T.) somente se não houver nenhuma chave no índice que seja maior do que o argumento de pesquisa.

O comando SET EXACT não tem efeito algum sobre a operação do comando SEEK.

Exemplos

Este exemplo ilustra o efeito do comando SEEK em vários arquivos de dados:



USE Sales INDEX Branch NEWSEEK "100"? FOUND(), EOF(), RECNO() // Resulta: .T. .F. 1

A função definida pelo usuário exemplificada abaixo executa um comando SEEK exato para um índice com uma chave de caractere:

USE Invoice INDEX Invoice NEW? IF(SeekExact("10001"),"Encontrado","Não Encontrado")RETURN

FUNCTION SeekExact( cSearch )SEEK PADL( cSearch, LEN(&(INDEXKEY(0))) )RETURN (FOUND())

Comandos para cálculos sobre registros

COUNT

Totaliza o número de registros e coloca o resultado numa variável

Sintaxe

COUNT TO <idVar>[<abrangência>] [WHILE <lCondição>] [FOR <lCondição>]

Argumentos

TO <idVar> identifica a variável à qual será atribuído o resultado do comando COUNT. Uma variável que não existe ou não é visível é criada como uma variável do tipo privada cuja abrangência é o procedimento corrente.

<abrangência> é a parte do arquivo de dados corrente onde o comando COUNT atuará. O padrão é todos (ALL) os registros.

WHILE <lCondição> especifica o conjunto de registros que atendem a condição do registro corrente até que a condição seja falsa.

FOR <lCondição> especifica o conjunto de registros condicional para o comando COUNT dentro da abrangência.

Descrição

O comando COUNT totaliza o número de registros da área de trabalho corrente que atendem as condições e abrangência especificadas. O resultado é então alocado à variável em questao.<idVar> pode ser uma variável de qualquer classe de armazenamento, inclusive um campo.

Exemplos

Este exemplo demonstra um COUNT do campo Branches em Sales.dbf:



USE Sales NEW? LASTREC() // Resulta: 84COUNT TO nBranchCnt FOR Branch == 100? nBranchCnt // Resulta: 4

Este exemplo totaliza o número de registros em Sales.dbf, cujo campo Branch tem o valor de 100, e atribui o resultado ao campo Count no Branch.dbf para branch == 100:

USE Branch INDEX Branch NEWSEEK 100USE Sales INDEX SalesBranch NEWSEEK 100COUNT TO Branch->Count WHILE Branch == 100

SUM

Soma expressões numéricas e coloca o valor em variáveis

Sintaxe

SUM <nLista expr> TO <idLista var>[<abrangência>] [WHILE <lCondição>] [FOR <lCondição>]

Argumentos

<nLista expr> é a lista de valores numéricos a serem somados para cada registro processado.

<idLista var> identifica as variáveis receptoras da soma.Variáveis que não existam ou não sejam visíveis são criadas como privadas. <idList var> deve conter o mesmo número de elementos de <nLista expr>.<abrangência> é a porção do arquivo de dados a ser somada (SUM). O assumido é todos (ALL).

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

FOR <lCondição> especifica o conjunto condicional de registros a serem somados dentro da abrangência dada.

Descrição

SUM soma uma série de expressões numéricas e armazena o resultado em variáveis para uma faixa de registros na área corrente.

Note que <nLista expr> é necessária e não opcional como em outros dialetos.

Exemplos

O exemplo seguinte ilustra o uso de SUM:



USE Sales NEWSUM Price * .10, Amount TO nSum1, nSum2

? nSum1 // Resulta: 151515.00? nSum2 // Resulta: 150675.00

Comandos para controle do fluxo do programas

DO*

Invoca um procedure

Sintaxe

DO <idProcedure> [WITH <lista argumentos>]

Argumentos

<idProcedure> é o nome do procedure a executar.

WITH especifica uma <lista argumentos> de até 128 argumentos, separados por vírgulas, a passar para <idProcedure>. Cada argumento pode ser uma variável, campo, vetor, elemento de vetor, expressão ou objeto. Argumentos podem ser saltados ou não mencionados no fim da lista.

Descrição

A declaração DO invoca um procedure, opcionalmente passando parâmetros para a rotina invocada. Ele executa a mesma função de um procedure ou função de usuário chamada na linha pelo próprio nome com exceção de que outras variáveis que não campos são passados por referência. De forma a ser passado como argumento, um campo deve ser colocado entre parênteses a menos que declarado FIELD ou especificado com alias.

Em Clipper, o número de argumentos passados não precisa ser o mesmo que aquele que temos na rotina invocada. Se o número for menor que o número de parâmetros, os parâmetros sem correspondência serão inicializados com NIL. O mesmo ocorre com os argumentos saltados em <lista argumentos>. Para detectar a posição do último argumento passado em <lista argumentos>, use PCOUNT(). Para detectar um argumento saltado, compare-o com NIL.

Adicionalmente, DO também tem o efeito de compilar se o programa corrente está sendo compilado sem a opção /M. Se o Clipper encontra um DO e a rotina corrente não foi compilada ainda, ele busca no diretório corrente por um arquivo (.prg) com o mesmo nome e o compila. Se este arquivo com o mesmo nome da rotina não for encontrado, ele é assumidoEXTERNAL, e uma referência é adicionada ao arquivo objeto (.obj). Em tempo de linkagem, o linker irá procurar em outros arquivos objeto e bibliotecas por esta referência.

Em Clipper 5.0, DO é uma declaração de compatibilidade e portanto não recomendada. Ele é superado por invocar uma função ou procedure pelo próprio nome na linha. Desde que a convenção é passagem por valor, você deve prefixar o argumento com o sinal de passagem por referência (@) de forma a passá-lo por referência. Se você está usando DO para melhorar a legibilidade do código, um



comando definido pelo usuário especificado com a diretiva #command pode prover grande legibilidade sem sacrificar a segurança de variáveis passadas como parâmetros.

Exemplos

Este exemplo executa um procedure sem parâmetros:

DO AcctsRptAcctsRpt()// Método preferido

Este exemplo executa um procedure passando duas constantes:

DO QtrRpt WITH "2", "Divisão de Vendas"QtrRpt("2", "Divisão de Vendas") // Método preferido

Neste exemplo, um procedure é executado com o primeiro argumento passado por valor e o segundo por referência:

nNumber = 12DO YearRpt WITH nNumber + 12, nNumberYearRpt(nNumber + 12, @nNumber) // Método preferido

Aqui, um procedure é invocado com argumentos saltados numa lista de argumentos:

DO DisplayWindow WITH ,,,,"Janela"DisplayWindow(,,,,"Janela") // Método preferido

DO CASE

Executa um de vários blocos de declarações.

Sintaxe

DO CASECASE <lCondição1><declarações>...[CASE <lCondição2>]<declarações>...

[OTHERWISE]<declarações>...

END[CASE]

Argumentos

CASE <lCondição> define um bloco de declarações para executar caso <lCondiçoo> é avaliada como verdadeira (.T.).

OTHERWISE define um bloco de declarações para executar caso nenhum dos CASE seja verdadeiro (.T.).



Descrição

DO CASE...ENDCASE é uma estrutura de controle que executa um de vários blocos de declarações dependendo de qual das condições associadas seja verdadeira (.T.). Ele trabalha desviando a execução para as declarações seguintes ao primeiro CASE <lCondição> que for verdadeiro (.T.). Execução continua até que o próximo CASE, OTHERWISE ou ENDCASE seja encontrado. Controle então é desviado para a primeira instrução seguinte ao ENDCASE.

Se nenhuma das condições CASE for avalida como verdadeira (.T.), as declarações seguintes ao OTHERWISE são executadas até que seja encontrado o ENDCASE. Caso não seja especificado um OTHERWISE, o controle desvia para a instrução em seguida ao ENDCASE.

Qualquer número de declarações incluindo outras estruturas de controle (i.e., DO WHILE e FOR), podem ser aninhados dentro de uma estrutura DO CASE. Adicionalmente, não há limite físico de declarações CASE que podem ser contidas dentro de uma estrutura DO CASE.DO CASE...ENDCASE é idêntico ao IF...ELSEIF...ENDIF sem qualquer vantagem de um sobre o outro.

Exemplos

O exemplo a seguir demonstra uma estrutura de menu usando DO CASE:

@ 3, 25 PROMPT "Primeira escolha"@ 4, 25 PROMPT "Segunda escolha"MENU TO nChoice//DO CASE

CASE nChoice == 0RETURN

CASE nChoice == 1ChoiceOne()

CASE nChoice == 2ChoiceTwo()

ENDCASE

DO WHILE

Executa um bloco enquanto uma condição é verdadeira.

Sintaxe

[DO] WHILE <lCondição><declarações>...

[EXIT]<declarações>...

[LOOP]<declarações>...

END[DO]

Argumentos



<lCondição> é a expressão lógica de controle do DO WHILE.

EXIT incondicionalmente desvia o controle de dentro de um DO WHILE para a instrução imediatamente seguinte ao ENDDO.

LOOP desvia o controle para o DO WHILE mais recente.

Descrição

DO WHILE...ENDDO é uma estrutura de controle que executa um bloco repetitivamente, enquanto <lCondição> for avaliada como verdadeira (.T.). Quando a condição é avaliada como verdadeira (.T.), o controle passa para dentro da estrutura e assim continua até que um EXIT, LOOP, ou ENDDO seja encontrado. ENDDO retorna o controle para o DO WHILE e processo se repete. Se um EXIT for encontrado, o controle é desviado para o próximo ENDDO. Se um LOOP for encontrado, controle desvia para o mais recente DO WHILE. Se a condição é avaliada como falsa (.F.), a estrutura DO WHILE termina e o controle passa para a instrução imediatamente seguinte ao ENDDO.

EXIT é usado geralmente para encerrar a execução de um DO WHILE baseado em uma condição diferente da condição deste. LOOP, ao contrário, é usado para evitar a execução de instruções dentro do DO WHILE, baseado numa condição intermediária, e desvia imediatamente de volta para a declaração DO WHILE.

Estruturas DO WHILE podem ser aninhadas dentro de quaisquer outras estruturas até qualquer nível. O único requisito é que estas estruturas estejam devidamente aninhadas.

Exemplos

O exemplo a seguir demonstra uma estrutura de controle típica para um relatório por grupos:

LOCAL cOldSalesman, nTotalAmountUSE Sales INDEX Salesman NEWWHILE !EOF()

cOldSalesman = Sales->SalesmannTotalAmount = 0WHILE cOldSalesman = Sales->Salesman .AND. (.NOT. EOF())

? Sales->Salesman, Sales->AmountnTotalAmount = nTotalAmount + Sales->AmountSKIP

ENDDO? "Total: ", nTotalAmount, "para", cOldSalesman

ENDDOCLOSE Sales

O fragmento de código a seguir demonstra como LOOP pode ser utilizado para fornecer uma condição intermediária:

WHILE <lCondição><processamento inicial>...

IF <condição intermediária>LOOP

ENDIF<continua processamento>...



ENDDO

Este exemplo mostra o uso de DO WHILE para simular uma estrutura repita enquanto:

LOCAL lMore = .T.WHILE lMore

<instruções>...lMore := (<lCondição>)

ENDDO

O exemplo a seguir mostra uma estrutura que se move sequencialmente num arquivo de dados:

WHILE !EOF()<bloco>...SKIP

ENDDO

FOR

Executa um bloco um certo número de vezes.

Sintaxe

FOR <idContador> = <nInicio> TO <nFim> [STEP <nIncremento>]<Instruções>...[EXIT]<Instruções>...[LOOP]

NEXT

Argumentos

<idContador> é o nome da variável de controle do loop. Se o <idContador> não existe ou não está visível, uma variável PRIVATE é criada.

<nInício> é o valor inicial atribuído a <idContador>. Se <nIncremento> é negativo, <nInicio> deve ser menor que <nFim>.

TO <nFim> define o valor final de <idContador>. Se <nIncremento> é negativo,<nInicio> deve ser maior que <nFim>, senão <nInicio> deve ser menor que <nFim>.

STEP <nIncremento> define a quantidade de <idContador> a ser mudada para cada iteração do loop. <nIncremento> pode ser positivo ou negativo. Se a cláusula STEP não for especificada, <idContador> é incrementado de um para cada iteração do loop.

EXIT incondicionalmente desvia o controle de dentro de um FOR...NEXT para a próxima instrução seguindo ao NEXT.

LOOP desvia o controle para o mais recente FOR.



Descrição

FOR...NEXT é uma estrutura de controle que executa um bloco um determinado número de vezes. A estrutura de controle parte do valor inicial de <idContador> até o valor de <nFim>, movendo-se no incremento especificado por <nIncremento>. Todas as expressões na declaração FOR são avaliadas para cada iteração do loop. No entanto, <nInicio> e <nFim> podem ser modificados conforme a estrutura é operada.

Uma estrutura FOR opera até que <idContador> seja maior que <nFim>, ou seja encontrado um EXIT. Controle então desvia para a instrução seguinte ao NEXT. Se um LOOP for encontrado, controle desvia para a declaração FOR.

Se <nIncremento> é um valor negativo, <idContador> é decrementado ao invés de incrementado. O FOR, entretanto, continua até que <idContador> seja menor que <nFim>. Isto significa que <nFim> deve ser menor que <nInicio> quando o FOR iniciar.

Estruturas FOR são úteis para percorrer através de vetores onde <idContador> é usado como indíce do vetor. Veja exemplo abaixo.

FOR...NEXT como qualquer outra estrutura pode ser aninhado em qualquer nível. O único requisito é que as estruturas de controle sejam corretamente aninhadas.

Exemplos

Este exemplo percorre um vetor em ordem ascendente:

nLenArray := LEN(aArray)FOR i = 1 TO nLenArray

<instruções>...NEXT

Para percorrer em ordem descentente:

nLenArray := LEN(aArray)FOR i = nLenArray TO 1 STEP -1

<instruções>...NEXT

FUNCTION

Declara o nome de uma função e seus parâmetros formais.

Sintaxe

[STATIC] FUNCTION <idFunção>[(<idParam lista>)][LOCAL <identificador> [[:= <inicializador>], ... ]][STATIC <identificador> [[:= <inicializador>], ... ]][FIELD <lista identificadores> [IN <idAlias>][MEMVAR <lista identificadores>].. <corpo da função>



.RETURN <exp>

Argumentos

<idFunção> é o nome da função de usuário a declarar. Nomes de função podem ter qualquer tamanho, mas somente os 10 primeiros caracteres são considerados.Nomes podem ter qualquer combinação de caracteres, números e sublinhados, mas sublinhados na primeira posição são reservados.

<idParam lista> é a declaração de uma ou mais variáveis parâmetro.Variáveis especificadas nesta lista são declaradas local.

STATIC FUNCTION declara uma função que pode ser invocada somente por rotinas declaradas no mesmo arquivo (.prg).

LOCAL declara e opcionalmente inicializa uma lista de variáveis ou vetores que tenham visibilidade e vida útil para a função corrente.

STATIC declara e opcionalmente inicializa uma lista de variáveis ou vetores que tem visibilidade na função corrente mas vida útil durante a execução do programa.

FIELD declara uma lista de identificadores para usar quando forem encontrados nomes de campo. Se a cláusula IN for especificada, referir-se ao nome especificado inclui uma referência implícita ao alias especificado.

MEMVAR declara uma lista de identificadores para utilizar como variáveis ou vetores public ou private onde quer que encontrados.

RETURN <exp> passa o controle de volta a rotina que invocou, retornando o valor <exp> como valor de retorno da função. Cada função deve ter ao menos um RETURN que retorne um valor. RETURN pode ocorrer em qualquer local do corpo da função.

Descrição

FUNCTION declara uma função definida pelo usuário e opcionalmente uma lista de variáveis locais para recepção de parâmetros frequentemente chamados de parâmetros formais. Uma função de usuário é um subprograma compreendendo um conjunto de declarações e instruções executadas onde quer que você faça referência a <idFunção> seguido de abre e fecha parênteses. Uma definição de função inicia com a declaração FUNCTION e termina com a próxima declaração FUNCTION, declaração PROCEDURE ou fim de arquivo.

Funções são usadas para encapsular um bloco de código e mais tarde criar expressões usando o valor retornado. Funções e procedures, aumentam a modularidade, legibilidade, isolam modificações e auxiliam no gerenciamento de aplicações complexas.

Uma função em Clipper é similar a um procedure com a exceção de que retorna um valor. O valor retornado pode ser qualquer tipo de dado incluindo um vetor, bloco de código ou NIL. Toda função deve iniciar com a declaração FUNCTION e deve conter ao menos um RETURN com um argumento. Declarações de função não podem ser aninhadas com outras declarações de função. Uma função pode ser usada em qualquer lugar onde uma função padrão pode ser usada, incluindo expressões.



A visibilidade das funções cai em duas classes. Funções que são visíveis em qualquer lugar e que são denominadas funções públicas e declaradas com FUNCTION. Funções que são visíveis somente no (.prg) corrente e são denominadas funções estáticas e são declaradas com STATIC FUNCTION.

Funções estáticas são muito úteis por várias razoes. Primeira, elas limitam a visibilidade do nome da função, restringindo o acesso a esta.Por causa disto, subsistemas definidos dentro de um único (.prg) podem fornecer um protocolo de acesso com uma série de funções públicas e conceber os detalhes de implementação do subsistema dentro de funções e procedures. Segundo, desde que referências para funções static são resolvidas em tempo de compilação, elas precedem referências a funções public que são resolvidas em tempo de linker. Isto assume que dentro de um arquivo de programa, uma referência para uma função static executa aquela função se existir um conflito com uma função public.

Notas

Chamando uma função definida pelo usuário: Uma função definida pelo usuário é chamada usando a mesma notação de uma função Clipper:

<idFunção>([<lista argumentos>])

Uma função definida pelo usuário pode ser chamada dentro de uma expressão ou na linha pelo seu nome. Se chamada na linha pelo próprio nome, o valor de retorno é ignorado.

Uma função de usuário pode ser chamada como uma expressão com alias e entre parênteses, como por exemplo:

<idAlias>->(<idFunção>(<lista argumentos>))

Quando uma função é chamada como expressão com alias, a área de trabalho associada com <idAlias> é selecionada, a expressão executada, e a área original selecionada novamente. Como qualquer outra expressão, uma expressão com alias pode ser invocada na linha por si mesma.

Uma função de usuário pode chamar a si mesma de forma recursiva.

Parâmetros: Funções podem receber parâmetros a partir de outra função, procedure, ou linha de comando do DOS. Em Clipper 5.0, existem duas maneiras de receber parâmetros: uma lista de nomes de variáveis locais pode ser declarada como parte da declaração FUNCTION (chamada de parâmetros formais) ou uma lista de variáveis privadas pode ser especificada em separado com uma declaração PARAMETERS. Note que as duas não podem ser misturadas. Caso o sejam, irá resultar num erro fatal de compilação.

Funções recebem parâmetros na ordem em que são passados. Em Clipper, o número de parâmetros não precisa ser igual ao número de argumentos enviados. Argumentos podem ser saltados ou não inclusos no final da lista. Um parâmetro que não venha a receber um valor será inicializado com NIL. Se forem especificados argumentos, PCOUNT() irá retornar a posição do último argumento passado.

Parâmetros especificados em funções de usuário podem receber valores passados por valor ou por referência. O método assumido para expressões e variaveis é por valor. Isto inclui variáveis que contenham referências a vetores ou objetos. Variáveis que não sejam campos precedidas do operador passa por referência (@) são passadas por referência. Campos não podem ser passados por referência e são sempre passados por valor.



Exemplos

Este exemplo mostra uma função destinada a formatar valores monetários:

? Currency( 1000 )// Resulta: $1.000,00

FUNCTION Currency( nNumber )LOCAL cNumberIF nNumber < 0

cNumber := TRANSFORM(-1 * nNumber, "@E 999.999.999.999,99")cNumber := PADL("($" + LTRIM(cNumber) + ")", LEN(cNumber))

ELSEcNumber := TRANSFORM(nNumber, "@E 999.999.999.999,99")cNumber := PADL("$" + LTRIM(cNumber), LEN(cNumber))

ENDIFRETURN cNumber

Este exemplo demonstra uma função de usuário que toma um string que é uma lista de ítens separados por vírgulas e retorna um vetor com um ítem por elemento:

aList := ListAsArray("One,Two") // Resulta: {"One", "Two"}

FUNCTION ListAsArray( cList )LOCAL nPosLOCAL aList := {} // Define vetor vazio//DO WHILE (nPos := AT(",", cList)) != 0

AADD(aList, SUBSTR(cList, 1, nPos - 1))// Adiciona novo elementocList := SUBSTR(cList, nPos + 1)

ENDDOAADD(aList, cList)//RETURN aList// Retorna o vetor

O exemplo a seguir demonstra como determinar se um argumento foi saltado comparando um parâmetro com NIL:

FUNCTION MyFunc( param1, param2, param3 )IF param2 != NIL

param2 := "valor assumido"ENDIF.. <instruções>.RETURN NIL

Este exemplo mostra como a função Currency() (definida acima), pode ser chamada como expressão com alias:

USE Invoices NEWUSE Customer NEW? Invoices->(Currency(Amount))



IF

Executa um dentre vários blocos de instruções.

Sintaxe

IF <lCondição1><instruções>...

[ELSEIF <lCondição2>]<instruções>...

[ELSE]<instruções>...

END[IF]

Argumentos

<lCondição> é uma expressão lógica de controle. Se ela é avaliada como verdadeira (.T.), o bloco seguinte é executado até que um ELSEIF, ELSE ou ENDIF seja encontrado.

ELSEIF identifica um bloco a ser executado caso <lCondição> seja avaliada como vardadeira (.T.) e todas as condições IF e ELSEIF anteriores foram avaliadas como falsas (.F.). Qualquer número de ELSEIFs pode ser especificado dentro de uma estrutura IF...ENDIF.

ELSE identifica o bloco a ser executado se todos os IF e ELSEIF preliminares foram avaliados como falso (.F.).

Descrição

A estrutura de controle IF trabalha desviando a execução para as instruções seguintes ao primeiro verdadeiro (.T.) avaliado para uma condição IF ou ELSEIF. Execução então continua até que um ELSEIF, ELSE, ENDIF seja encontrado, local onde a execução será desviada para a primeira instrução seguindo o ENDIF.

Se nenhuma condição for avaliada como verdadeira (.T.), o controle passa para a primeira instrução seguinte ao ELSE. Se um ELSE não foi especificado, o controle é desviado para a primeira instrução seguindo o ENDIF.

IF...ENDIF pode ser aninhado dentro de outros IF...ENDIF e estruturas. Estas estruturas, entretanto, devem ser aninhadas própriamente.

A forma IF...ELSEIF...ENDIF é idêntica a DO CASE...ENDCASE. não existe vantagem específica no uso de uma sobre a outra. A forma IF...ENDIF é similar a função IF() a qual pode ser usada em expressões.

Exemplos

O exemplo a seguir avalia um número de condições usando uma construção IF...ELSEIF...ENDIF:

LOCAL nNumber := 0//IF nNumber < 50



? "Menor que 50"ELSEIF nNumber == 50? "Igual a 50"

ELSE? "Maior que 50"

ENDIFSTATIC

QUIT

Finaliza a execução de um programa

Sintaxe

QUIT | CANCEL*

Descrição

Tanto o comando QUIT quanto o comando CANCEL encerram a execução de programas, fecham todos os arquivos abertos, e retornam o controle ao sistema operacional. Cada um destes comandos pode ser usado de qualquer parte de um programa. O comando RETURN executado na rotina principal dá o mesmo resultado.

Notas

Código de retorno: Quando um programa Clipper termina, o código de retorno é ajustado para 1 se o processo acabar com um erro fatal. Se o programa terminar normalmente, o código de retorno é configurado para zero ou o último ERRORLEVEL() ajustado no programa.

Exemplos

O exemplo seguinte demonstra a atuação do comando QUIT usando uma caixa com mensagem:

IF YesNoBox(10, 10, "Volta ao Dos?", "BG+/B,B/W", 2)QUIT

ENDIFRETURN

RETURN

Encerra uma função de usuário, programa ou procedure

Sintaxe

RETURN [<exp>]

Argumentos



<exp> é uma expressão de qualquer tipo que é avaliada para ser o valor de retorno de uma função de usuário. Se a função terminar sem RETURN, o valor de retorno será NIL.

Descrição

RETURN encerra uma função de usuário, programa ou procedure, devolvendo o controle para a rotina chamadora. Quando RETURN é executado na rotina de nível mais alto, controle é devolvido ao sistema operacional. Todas as variáveis private criadas e variáveis local declaradas na rotina corrente são liberadas quando o controle é devolvido ao chamador.

Pode haver mais de um RETURN numa rotina, da mesma forma que não é necessário terminar com um RETURN. Desde que funções de usuário devem retornar valores, cada uma deve conter ao menos um RETURN com um argumento.

Nota

Uma função de usuário ou procedure é encerrado por uma declaração PROCEDURE, FUNCTION, ou fim de arquivo, mas não por um RETURN.

Notas

Vetores: Desde que vetor é um tipo de dado como qualquer outro, o mesmo pode ser retornado de uma função de usuário.

RETURN TO MASTER: Clipper não suporta RETURN TO MASTER ou qualquer outro tipo de RETURN onde se especifique o nível. Você pode simular isto com BEGIN SEQUENCE...END.

Exemplos

Estes exemplos ilustram a forma geral da declaração RETURN em uma função ou procedure:

FUNCTION <idFunction>//<instruções>...//RETURN <expReturn>

PROCEDURE <idProcedure>//<instruções>...//RETURN

Este exemplo demonstra como um vetor criado numa função pode ser retornado para a rotina chamadora:

FUNCTION PassArrayBackPRIVATE aArray[10][10]aArray[1][1] = "myString"RETURN aArray



RUN

Executa um programa ou comando DOS

Sintaxe

RUN | !* <xcLinhaComando>

Argumentos

<xcLinhaComando> é qualquer programa executável, inclusive os comandos residentes DOS e COMMAND.COM. Pode ser especificado literalmente ou por expressão caractere entre parênteses.

Descrição

O comando RUN executa um comando ou programa DOS de dentro de uma aplicação compilada. Quando você utiliza o comando RUN num programa DOS, o Clipper executa outra cópia de COMMAND.COM, passando a linha de comando DOS ao mesmo tempo. Isto tem duas implicações. A primeira é que você deve ter memória suficiente para o COMMAND.COM (27K para DOS 3.2) e o programa que você deseja executar. A segunda é que o COMMAND.COM deve estar disponível no local especificado pelo COMSPEC (o padrão é o diretório raiz do disco onde você carregou o DOS). Se o COMMAND.COM não estiver localizado neste disco ou o disco for trocado, mude SET COMSPEC para a nova localização antes de executar a operação Clipper. Observe que os comandos SET DEFAULT e SET PATH não têm efeito algum sobre o comando RUN.

A forma ! do comando RUN é fornecida unicamente por razoes de compatibilidade e, portanto, desaconselhada.

Aviso

Não utilize o comando RUN para instalar programas residentes em memória de dentro do Clipper porque pode haver perda de memória quando o controle retornar ao seu programa aplicativo.

Exemplos

O exemplo seguinte demonstra como utilizar o comando RUN combinado com as funções MEMOREAD() e MEMOWRIT() para criar uma função definida por usuário que chama seu editor com o campo memo corrente:

lSuccess = EditorMemo("Brief", "Notes")RETURN

FUNCTION EditorMemo( cEditor, cMemofld )IF MEMOWRIT("Clipedit.tmp", &cMemofld.)

RUN (cEditor + " Clipedit.tmp")REPLACE &cMemofld. WITH MEMOREAD("Clipedit.tmp")ERASE Clipedit.tmpRETURN .T.

ELSERETURN .F.

ENDIF



Uma das opções que você pode desejar oferecer a seus usuários é o acesso direto ao DOS. Você pode fazer isso com o comando:RUN COMMAND

Para facilitar ao usuário o retorno ao programa de aplicação, mude o prompt DOS no arquivo batch de aplicação desta forma:

REM Application batch fileECHO OFFPROMPT Acesso ao DOS:Digite EXIT para retornar ao programa $_$p$g <seu programa aplicativo>PROMPT $p$g

Depois, instrua o usuário a executar o arquivo batch de aplicação em lugar do aplicativo .EXE.

Comandos para geração de relatórios e etiquetas

LABEL FORM

Emite etiquetas

Sintaxe

LABEL FORM <xcArquivo>[TO PRINTER] [TO FILE <xcArquivo>][<abrangência>] [WHILE <lCondição>] [FOR <lCondição>][SAMPLE]

Argumentos

<xcArquivo> é o nome do arquivo de etiquetas (.lbl) que contém a definição da forma da etiqueta e pode ser especificado literalmente ou por expressão caractere entre parênteses. Se não for especificada extensão, será assumido (.lbl).

TO PRINTER envia a saída para a impressora.

TO FILE <xcArquivo> envia a saída para <xcArquivo>.<XcArquivo> pode ser especificado literalmente ou por uma expressão caractere entre parênteses. Se não for especificada extensão, será assumido (.txt).

<abrangência> é a parte do arquivo de dados corrente que deverá ser usado. O padrão é todos (ALL) os registros.


FOR <lCondição> especifica o conjunto condicional de registros de onde serão tiradas as informações para etiquetas dentro da abrangência dada.



SAMPLE emite etiquetas com conteúdo de asteriscos. Cada etiqueta texto tem o mesmo número de colunas e linhas da definição da etiqueta.Após cada exibição de etiqueta texto, aparece a pergunta, "Deseja mais amostras?". A resposta não "N" faz o comando LABEL FORM exibir as etiquetas reais para a condição e abrangência especificadas.

Descrição

LABEL FORM é um comando de console que acessa sequencialmente registros na área de trabalho corrente, exibindo etiquetas que usam uma definição armazenada num arquivo (.lbl). Este arquivo pode ser criado usando-se RL.EXE.

Quando chamada, a saída é enviada para a tela e opcionalmente para a impressora e/ou para um arquivo. Para evitar que a saída apareça na tela enquanto esta estiver sendo impressa ou enviada para um arquivo, use o comando SET CONSOLE OFF antes de usar o comando LABEL FORM.

Quando chamado, o comando LABEL FORM procura no diretório e disco correntes, caso o arquivo <xcArquivo> não seja encontrado no diretório corrente e o path não tenha sido especificado.

Notas

Interrompendo LABEL FORM: Para interromper o comando LABEL FORM, use a função INKEY() como parte da condição FOR, verificando se acontece a interrupção ao toque de uma tecla.

Margem da impressora: Sendo LABEL FORM um comando de console, ele obedece ao que estiver especificado correntemente por SET MARGIN para saídas repetidas para a impressora.

Exemplos

O seguinte exemplo imprime um conjunto de etiquetas e escreve-as num arquivo com um único comando. Duas formas do comando são mostradas:

USE Sales INDEX Sales NEWLABEL FORM Sales TO PRINTER TO FILE SalesLABEL FORM Sales TO PRINTER TO FILE Sales

Este exemplo demonstra como interromper um comando LABEL FORM usando a função INKEY() para verificar se o usuário teclou Esc:

#define K_ESC 27USE Sales NEWUSE Sales NEWLABEL FORM Sales FOR INKEY() != K_ESC

REPORT FORM

Exibe um relatório no console

Sintaxe



REPORT FORM <xcRelatório>[TO PRINTER] [TO FILE <xcArquivo>][<abrangência>] [WHILE <lCondição>] [FOR <lCondição>][PLAIN | HEADING <cCabeçalho>] [NOEJECT] [SUMMARY]

Argumentos

<xcRelatório> é o nome do arquivo de formato de relatório (.frm) que contém a definição do relatório (REPORT). Caso não haja especificação de extensão, (.frm) é assumido. <xcRelatório> é uma expressão que pode ser especificada literalmente por expressão caractere entre parênteses.

TO PRINTER envia a saída para a impressora.TO FILE <xcArquivo> envia a saída para um arquivo sem caracteres de form feed (ASCII 12). Se não for especificada extensão de arquivo, um (.txt) é adicionado. <xcArquivo> é uma expressão literal, ou seja, o próprio nome do arquivo, ou expressão caractere entre parênteses.

<abrangência> é a parte do arquivo de dados corrente onde atuará o comando REPORT FORM. O padrão é todos (ALL).


FOR <lCondição> especifica o conjunto condicional de registros no qual o comando irá atuar dentro da abrangência.PLAIN evita a exibição de data e número de página, e condiciona a impressão a ser feita sem quebras de página. Além disso, o título do relatório e cabeçalhos de colunas aparecem apenas no início do relatório.

HEADING coloca o resultado de <cCabeçalho> na primeira linha de cada página. <cCabeçalho> é avaliado somente uma vez no começo do relatório, antes que o ponteiro de registro seja movido. Caso ambos PLAIN e HEADING estejam especificados, PLAIN tem a preferência.

NOEJECT evita que a página inicial seja ejetada quando a cláusula TO PRINTER for usada.

SUMMARY faz o comando REPORT FORM exibir somente linhas de grupo, subgrupo e total geral. As demais linhas são omitidas.

Descrição

REPORT FORM é um comando de console que acessa sequencialmente registros na área de trabalho corrente exibindo um relatório tabular e opcionalmente agrupado com cabeçalhos de página e coluna a partir de uma definição existente num arquivo (.frm). O arquivo REPORT FORM real (.frm) é criado utilizando-se RL.EXE ou através de dBASE III PLUS.

Quando chamada, a saída é enviada para a tela e opcionalmente para a impressora e/ou um arquivo. Para evitar que a saída seja enviada para a tela quando da impressão ou envio da mesma para um arquivo, use o comando SET CONSOLE OFF antes de utilizar o comando REPORT FORM.

Quando chamado, o comando REPORT FORM procura na unidade e diretório SET PATH corrente se o arquivo <xcRelatório> não for encontrado no diretório corrente e o PATH não tiver sido especificado.



Notas

Interrompendo REPORT FORM: Para interromper um comando REPORT FORM, use a função INKEY() como parte da condição FOR para verificar a interrupção ao pressionar uma tecla.

Margem da impressora: Como REPORT FORM é um comando de console, ele obedece ao que estiver definido em SET MARGIN para a saída para a impressora.

Incluindo caracteres form feed: Para incluir caracteres de alimentação de formulário ao enviar um comando REPORT FORM TO FILE, redirecione a saída da impressora para um arquivo usando o comando SET PRINTER desta forma:

SET PRINTER TO <xcArquivo>REPORT FORM <xcArquivo> TO PRINTERSET PRINTER TO

Relatórios em ambientes de rede: Comandos REPORT FORM em ambientes de rede podem ser afetados por mudanças feitas em arquivos de dados por outros usuários enquanto o relatório está sendo executado. Por exemplo, se um usuário mudar um valor chave de "A" para "Z" enquanto o relatório estiver sendo impresso, o mesmo registro poderá aparecer repetido.

Exemplos

O exemplo a seguir usa ao mesmo tempo uma expressão extendida e uma expressão literal para executar um comando REPORT FORM:

LOCAL xcReport := "Sales"USE Sales INDEX Sales NEWREPORT FORM (xcReport) TO PRINTER FOR Branch != "100"

Este exemplo demonstra como interromper um comando LABEL FORMusando a função INKEY() para verificar se o usuário teclou Esc:

#define K_ESC 27USE Sales NEWLABEL FORM Sales FOR INKEY() != K_ESC

EJECT

Avança a cabeça da impressora para o começo da página

Sintaxe

EJECT

Descrição

O comando EJECT envia um caractere de form feed (ASCII 12) à impressora e ajusta os valores das funções PCOL() e PROW() para zero. Se você especificar uma linha e coluna da impressora menores que a última posição dada por um comando EJECT ou uma função SETPRC(), o Clipper



automaticamente realiza um EJECT e reconfigura os valores internos das funções PROW() e PCOL(). Por causa disso, a sua lógica de impressão deve proceder sequencialmente da esquerda para a direita e para o fim da página. Caso você necessitar reconfigurar linha e coluna da impressora para zero sem mudança de página, use a função SETPRC().

Exemplos

Este exemplo imprime um relatório em forma de listagem simples e usa o comando EJECT para avançar para uma nova página quando o contador de linhas chega ao número máximo de linhas a ser impresso por página:

LOCAL nLine := 99, nPage := 0USE Sales NEWSET PRINTER ONSET CONSOLE OFFDO WHILE !EOF()

IF nLine > 55EJECT? "Pagina " + LTRIM(STR(nPage++, 3))? "Data " + CTOD(DATE())?? "Vendedor ", "Quantia"?nLine := 6

ENDIF? Sales->Salesman, Sales->AmountnLine++SKIP

ENDDOSET PRINTER OFFSET CONSOLE ONCLOSE

Outros comandos para configuração do ambiente

SET BELL

Determina se haverá alarme sonoro automático durante operações de entrada de dados

Sintaxe

SET BELL on | OFF | <xlComuta>

Argumentos

ON possibilita o alarme.

OFF impossibilita o alarme.



<xlComuta> é uma expressão lógica que deve ser colocada entre parêntses. Um valor de verdadeiro (.T.) é o mesmo que ON, e um valor de falso (.F.) é o mesmo que OFF.

Descrição

Se o comando SET BELL estiver em ON, o alarme soa nas seguintes situações:

O usuário entra um caractere na última posição em um GET.

O usuário tenta entrar dados inválidos num GET. Os dados são validados pelo tipo de dado da variável GET, pelo template de PICTURE, e pela cláusula RANGE. Violar uma condição VALID não faz o alarme soar, não importando qual o status do comando SET BELL.

Para soar o alarme mais claramente você pode usar ?? CHR(7) ou a função TONE().TONE() talvez seja o mais útil, pois com ele você pode variar o tom e a duração do som.

SET COLOR*

Define cores de tela.

Sintaxe

SET COLOR | COLOUR TO [<padrão>[, <destaque>][, <borda>][, <fundo>][, <nãoselecionados>]] | (<cStringCor>)

Argumentos

<padrão> é a cor utilizada para escrever em toda a tela do vídeo, incluindo a utilização de todos os comandos e funções quando exibidas na tela. Isto inclui comandos como @...PROMPT, @...SAY, e ?; e funções como ACHOICE(), DBEDIT(), e MEMOEDIT().

<destaque> é a cor utilizada para configurar a exibição das barras luminosas. Este argumento influi sobre a barra luminosa de seleção sobre os GETs com INTENSITY ON, o comando MENU TO, a função DBEDIT(), e ACHOICE().

<borda> é a cor utilizada para configurar a cor que será colocada na área em torno da tela de vídeo, que é inacessível para a utilização normal dos programas que escrevem algo na tela. Esta configuração somente funciona com adaptadores de vídeo do tipo CGA, mas não comadaptadores EGA ou VGA.

<fundo> atualmente não é suportada por máquinas nas quais a Nantucket não provê drivers apropriados. Esta configuração é suportada somente para propósitos de compatibilidade.

<nãoselecionados> é o par de cores utilizado para configurar uma determinada entrada de dados exibindo o GET corrente na cor de destaque definida, enquanto que os outros GETs são mostrados nesta cor.

<cStringCor> é uma cadeia de caracteres contendo a configuração de cores. Esta cadeia de caracteres pode ainda ser guardada em uma variável de memória, sendo utilizada no comando englobando-a com parênteses. Esta facilidade permite a você especificar a configuração de cores como sendo uma



expressão, no lugar de utilizar um simples literal (cadeia de caracteres) ou mesmo uma macro-substituição de uma variável.

SET COLOR TO sem argumentos restaura as cores padrão para W/N,N/W,N,N,N/W.

Descrição

SET COLOR é um comando sinônimo para a função SETCOLOR() que define cores para as operações subsequentes de escrita em tela. Cada comando SET COLOR especifica uma lista de argumentos para as cores utilizadas nos cinco tipos de operações de escrita em tela. Cada configuração de argumento é um par de cores contendo a cor do caractere e a cor de fundo do caractere separados por uma barra (/). A cor do caractere define a cor dos caracteres que serão exibidos na tela. A cor de fundo do caractere define que cor será exibida atrás do caractere.Espaços e quaisquer caracteres que não sejam exibíveis são considerados somente como cor de fundo do caractere.

Além das cores, uma configuração para a cor do caractere pode ter um atributo de alta intensidade ou piscante. Com um vídeo do tipo monocromático, a alta intensidade aumenta o brilho do texto escrito.Com um vídeo colorido, a Alta Intensidade altera a tonalidade da cor especificada tornando-a uma cor diferente. Por exemplo, a letra N exibe os caracteres de um texto com a cor preta, e utilizando-se o arqumento N+ mostrará o mesmo texto com a cor cinza. A Alta Intensidade é identificada pelo sinal +. O atributo de Piscante causa ao texto escrito em tela que pisque ou não a intervalos regulares. O atributo de Piscante é identificado pelo sinal *. Um caractere de atributo pode estar colocado em qualquer lugar da configuração, mas é sempre aplicado à cor do caractere, portanto as cores de fundo dos caracteres não possuem os atributos de Alta Intensidade e Piscante.

Cada cor pode ser especificada utilizando uma letra ou número.Entretanto, a especificação de números é fornecida somente para propósitos de compatibilidade. Quando for especificado um argumento de configuração de cor, números e letras não devem ser misturados.

Todos os argumentos são opcionais. Se um argumento for omitido, seu valor anterior é retido e somente os novos são configurados. Dentro de uma configuração, a omissão da cor do caractere ou da cor de fundo do caractere torna esta cor com o padrão preto.

Veja na página seguinte as cores suportadas.

Tabela 4-13: Tabela de Cores

Cor Letra Número MonocromáticoPreto N,Espaço 0 PretoAzul B 1 SublinhadoVerde G 2 BrancoCiano BG 3 BrancoVermelho R 4 BrancoMagenta RB 5 BrancoMarrom GR 6 BrancoBranco W 7 BrancoCinza N+ 8 PretoAzul Brilahnte B+ 9 Sublinhado BrilhanteVerde Brilhante G+ 10 Branco Brilhante



Ciano Brilhante BG+ 11 Branco BrilhanteVerme lho Brilhante R+ 12 Branco BrilhanteMagenta Brilhante RB+ 13 Branco BrilhanteAmarelo GR+ 14 Branco BrilhanteBranco Brilhante W+ 15 Branco BrilhantePreto U SublinhadoVídeo Inverso I Vídeo InversoIncolor X Incolor

SET COLOR é um comando de compatibilidade e assim sendo não é recomendado. Ele é superado pela função SETCOLOR(), que pode retornar tanto a cor corrente que está sendo utilizada no momento como também configurar uma nova cor.

Notas

Monitores monocromáticos: Nos monitores monocromáticos, as cores não são suportadas. O Clipper, contudo, suporta os atributos monocromáticos de vídeo reverso (I) e sublinhado (U).

Drivers de tela: O comando SET COLOR TO utilizando números não é suportado caso seja linkado o ANSI.OBJ com o programa corrente.

ExemplosO exemplo seguinte utiliza a configuração para os GETs não selecionados, fazendo o GET corrente trabalhar com letras vermelhas (R) sobre um fundo branco (W), enquanto que os demais permanecem com letras pretas (N) sobre um fundo branco (W):color = "W/N,R/W,,,N/W"SET COLOR TO (color)cOne := cTwo := SPACE(10)@ 1, 1 SAY "Enter Um : " GET cOne@ 2, 1 SAY "Enter Dois: " GET cTwoREAD

Este exemplo demonstra uma função definida pelo usuário (UDF) para obter uma senha do usuário utilizando o argumento de destaque com o tipo de cor (X) para esconder a senha que está sendo digitada pelo usuário:

IF !DialogPassWord(12, 13, "W+/N", "FUNSUN", 3)? "Desculpe, senha errada!"QUIT

ENDIF

FUNCTION DialogPassWord( nRow, nCol, cStandard, cPassword, nTries )LOCAL nCount := 1, cColor := SETCOLOR(cStandard + ", X")DO WHILE nCount < nTries

cUserEntry = SPACE(6)@ nRow, nCol SAY "Entre Senha: " GET cUserEntryREAD

IF LASTKEY() == 27SETCOLOR(cColor)RETURN .F.



ELSEIF cUserEntry == cPasswordSETCOLOR(cColor)RETURN .T.

ELSEnCount++

ENDIFENDDO

SETCOLOR(cColor)RETURN .F.

SET CURSOR

Comuta a visibilidade do cursor em tela.

Sintaxe

SET CURSOR ON | off | <xlComuta>

Argumentos

ON Torna o cursor visível.

OFF Torna o cursor invisível.

<xlComuta> é uma expressão lógica que deve ser colocada entre parênteses. O valor de verdadeiro (.T.) é o mesmo que ON, e o valor falso (.F.) tem o mesmo significado que OFF.

Descrição

SET CURSOR comuta o estado do cursor entre ON e OFF (ligado e desligado). Quando o CURSOR está OFF, entradas via teclado e exibições em tela não são afetadas. O cursor é simplesmente escondido, podendo a entrada de dados ser efetuada sem que o cursor esteja visível. As funções ROW() e COL() são atualizadas como se o cursor estivesse vísivel.Este comando é geralmente utilizado para suprimir o cursor enquanto uma tela está sendo montada. A forma mais ideal é de somente mostrar o cursor em um programa de produção quando o usuário se encontrar no modo de edição, ou seja, utilizando GETs, MEMOEDIT(), ou algum outro tipo de modo de edição.

Exemplos

O exemplo seguinte mostra a utilização típica do SET CURSOR:

LOCAL lAnswer := .F.@ 24, 0@ 24, 15 SAY "Deseja encerrar [S/N]?";GET lAnswer PICT "@!";SET CURSOR ONREADSET CURSOR OFF



SET DATE

Configura o formato de datas para entrada de dados e exibição em tela

Sintaxe

SET DATE FORMAT [TO] <cFormatoData>SET DATE [TO]AMERICAN | ansi | british | french | german | italian | japan | usa

Argumentos

<cFormatoData> é uma extressão caractere que especifica diretamente o formato de data quando a cláusula FORMAT é especificada.<cFormatoData> deve conter um string de 12 ou menos caracteres.

Quando especificado, <cFormatoData> é analisado para determinar a colocação adequada dos digitos de mes, dia e ano. A posição destes é determinada baseada na posição das letras, d, m e y, respectivamente.Outros caracteres são copiados como estao para exibição de valores de data.

Descrição

O SET DATE é uma configuração global que afeta o comportamento das datas em todo o programa, permitindo a você controlar a formatação das datas de forma a facilitar o envio de aplicativos a outros países.

A tabela a seguir ilustra os formatos de datas para cada configuração de data:

Tabela 4-14: Formatos SET DATE

SET FormatoAMERICAN mm/dd/yyANSI yy.mm.ddBRITISH dd/mm/yyFRENCH dd/mm/yyGERMAN dd.mm.yyITALIAN dd-mm-yyJAPAN yy/mm/ddUSA mm-dd-yy

Exemplos

O exemplo a seguir configura um programa para o devido ajuste de datas em tempo de execução. Isto é feito passando-se uma variável ambiental DOS para o programa, carregando-se seu valor com a função GETENV(), e ajustando a data com o valor que foi carregado. Para começar, o formato da data é atribuído a uma variável ambiental DOS da seguinte forma:

SET CLIP_DATE=BRITISH



Depois na seção de configuração do programa de aplicação:

FUNCTION AppConfigSET DATE FORMAT TO GETENV("CLIP_DATE")RETURN NIL

Usando o seguinte procedimento para efetivamente ajustar a data:

SET DATE FORMAT "yyyy:mm:yy"

SET DECIMALS

Ajusta a quantidade de casas decimais exibidas

Sintaxe

SET DECIMALS TO [<nDecimais>]

Argumentos

<nDecimais> é a quantidade de casas decimais a serem exibidas. O valor padrão é dois.

SET DECIMALS TO sem argumento é equivalente a SET DECIMALS TO 0.

Descrição

O comando SET DECIMALS determina a quantidade de casas decimais que serão exibidas nos resultados das funções e cálculos numéricos. Sua operação depende diretamente da configuração afixada. Se FIXED estiver em OFF, SET DECIMALS estabelece o número mínimo de casas decimais exibidas pelas funções EXP(), LOG(), SQRT(), e operações de divisão.Caso FIXED esteja em ON, todos os valores numéricos são exibidos com a quantidade exata de casas decimais especificada pelo comando SET DECIMALS. Observe que nem SET DECIMALS nem SET FIXED afetam a precisão numérica dos cálculos--somente o formato de exibição é afetado.

A fim de obter um melhor controle da exibição numérica, você pode utilizar-se da cláusula PICTURE de @...SAY, @...GET, e da função TRANSFORM().

Exemplos

Os exemplos a seguir ilustram vários resultados do comando SETDECIMALS:

SET FIXED ONSET DECIMALS TO 2 // O padrão? 2/4 // Resulta: 0.50? 1/3 // Resulta: 0.33SET DECIMALS TO 4? 2/4 // Resulta: 0.5000? 1/3 // Resulta: 0.3333



SET DELIMITERS

Determina ou define os delimitadores GET

Sintaxe

SET DELIMITERS on | OFF | <xlComuta>SET DELIMITERS TO [<cDelimitadores> | DEFAULT]

Argumentos

ON exibe delimitadores para variáveis GET.

OFF suprime a exibição de delimitadores.

<xlComuta> é uma expressão lógica que deve ser colocada entre parênteses. Um valor de verdadeiro (.T.) é o mesmo que ON, e um valor de falso (.F.) é o mesmo que OFF.

TO <cDelimitadores> define um delimitador de um ou dois caracteres. A especificação de um único caractere usa o mesmo caractere como o delimitador inicial e final. A especificação de dois caracteres usa o primeiro como o delimitador inicial e o segundo como o delimitador final. A especificação padrão (DEFAULT) ou sem delimitadores ajusta os delimitadores para sinais de dois pontos, que são os delimitadores padrão.

Descrição

SET DELIMITERS é um comando com a finalidade dupla de definir caracteres usados para delimitar os GETs e determinar que os delimitadores sejam ou não exibidos automaticamente. Os GETs no Clipper podem ter delimitadores opcionais que cercam um campo GET quando este é exibido na tela. Se DELIMITERS está em ON, os delimitadores adicionam dois caracteres ao tamanho da exibição do campo GET.

Os caracteres dos delimitadores podem ser configurados utilizando-se a cláusula TO <cDelimitador>. O caractere de demilimitador padrão é o sinal de dois pontos (:). Ao especificar delimitadores, os delimitadores inicial e final podem ser diferentes. Caso você deseje omitir o delimitador da direita, da esquerda, ou ambos, use um espaço no lugar do caractere delimitador.

Regra geral, os delimitadores não são necessários já que os GETs são exibidos em vídeo reverso ou cor destacada se INTENSITY estiver em ON.

Exemplos

Este exemplo configura os delimitadores em um sinal de dois pontos ": " e um espaço para o primeiro GET, e o par de colchetes "[]" para o segundo GET:

LOCAL cVar := SPACE(5), cVar2 := SPACE(5)SET DELIMITERS ONSET DELIMITERS TO ": "@ 1, 0 SAY "Entre" GET cVarSET DELIMITERS TO "[]"@ 2, 0 SAY "Entre" GET cVar2



READ

SET DEVICE

Envia os comandos @...SAY à tela ou à impressora

Sintaxe

SET DEVICE TO SCREEN | printer

Argumentos

SCREEN envia todos os comandos @...SAY à tela e independe de como os comandos SET PRINTER e CONSOLE estejam ajustados.

PRINTER envia todos os comandos @...SAY ao dispositivo ajustado em SET PRINTER TO. Isto pode incluir um port de impressora local, um spooler de rede, ou um arquivo.

Descrição

O comando SET DEVICE envia a saída dos comandos @...SAY para a tela ou para a impressora. Quando DEVICE está em SET TO PRINTER, os comandos @...SAY são enviados à impressora e não são repetidos para a tela. Os comandos @...GET são ignorados.

Ao enviar os comandos @...SAY à impressora, o Clipper executa um EJECT automático sempre que a posição da cabeça da impressora estiver numa linha menor do que a última linha impressa. Um EJECT reajusta os valores das funções PCOL() e PROW() para zero. Para reajustar PCOL() e PROW() para novos valores, use a função SETPRC().

Para enviar comandos @...SAY para um arquivo, use SET PRINTER TO<xcArquivo> juntamente com o comando SET DEVICE TO PRINTER.

Exemplos

Este exemplo simples envia comandos @...SAY à impressora:

SET DEVICE TO PRINTER@ 2,10 SAY "Alo pessoal"EJECT

Este exemplo, por outro lado, envia comandos @...SAYs a um arquivo:

SET PRINTER TO Output.txtSET DEVICE TO PRINTER@ 10, 10 SAY "Arquivo: Output.txt"@ 11, 10 SAY DATE()SET PRINTER TO // Fecha o arquivoSET DEVICE TO SCREEN



SET FILTER

Esconde registros que não atendam uma condição

Sintaxe

SET FILTER TO [<lCondição>]

Argumentos

<lCondição> é uma expressão lógica que define um conjunto específico de registros das área de trabalho corrente que sejam acessíveis para processamento.

SET FILTER TO sem um argumento desativa a condição filtro.

Descrição

Quando uma condição FILTER está ativa, a área de trabalho corrente age como se contivesse somente os registros que atendem a condição especificada. Uma condição FILTER é uma das propriedades de uma área de trabalho. Uma vez ativada, a condição pode ser retornada na forma de uma cadeia de caracteres usando-se a função DBFILTER().

A maioria dos comandos e funções que movem o ponteiro de registros obedece ao filtro corrente, com exceção daqueles comandos que acessam registros através do número dos mesmos. Isto inclui GOTO, comandos especificados com a cláusula RECORD, e relações conectadas por expressão numérica a uma área de trabalho que não possua nenhum índice ativo.

Uma vez estabelecido, um FILTER não é ativado até que o ponteiro de registro seja movido de sua posição corrente. Você pode utilizar GO TOP para ativá-lo.

Tal como SET DELETED, um filtro não tem efeito algum sobre os comandos INDEX e REINDEX.

Nota

Embora o comando SET FILTER atue na área de trabalho corrente de forma que ela pareça conter um subconjunto de registros, este comando na realidade processa sequencialmente todos os registros na área de trabalho. Por esta razao, o tempo necessário para o processamento de uma área de trabalho filtrada será o mesmo que numa área de trabalho não filtrada.

Exemplos

Este exemplo filtra somente aqueles registros onde a idade seja maior do que 50 no arquivo Employee.dbf:

USE Employee INDEX Name NEWSET FILTER TO Age > 50LIST Lastname, Firstname, Age, PhoneSET FILTER TO



SET KEY

Atribui a chamada de uma rotina a uma tecla

Sintaxe

SET KEY <nCodigoTecla> TO [<idRotina>]

Argumentos

<nCodigoTecla> é o valor INKEY() da tecla à qual se atribui a rotina.

TO <idRotina> especifica o nome da rotina que é executada quando se aperta uma tecla. Se <idRotina> não é especificada, a definição corrente é liberada.

Descrição

SET KEY permite que uma rotina seja executada a partir de um estado de espera quando uma determinada tecla é pressionada. Um estado de espera é qualquer modo que extraia teclas com exceção de INKEY(). Estes modos incluem ACHOICE(), DBEDIT(), MEMOEDIT(), ACCEPT, INPUT, READ e WAIT.Após uma tecla ser redefinida, pressionando-a executa a rotina corente passando automaticamente três parâmetros correspondentes a: PROCNAME(), PROCLINE(), e READVAR(). O nome da rotina e da variável são caractere, enquanto que número de linha é numérico.

Um máximo de 32 teclas pode ser definido ao mesmo tempo. No start-up (início da execução), o sistema automaticamante define F1 para executar uma rotina de Help (auxílio). Se uma rotina com este nome é linkada junto do programa corrente e está visível, apertando F1 a partir de um estado de espera irá invocá-lo.

Note que rotinas de SET KEY devem ser desenhadas de modo a preservar o estado da aplicação (isto é, aparência da tela, área de trabalho corrente, etc) e restaurá-la após encerrar a execução.

Aviso

Em Clipper 5.0, SET FUNCTION é pré processada na forma de SET KEY e KEYBOARD.Isto significa que SET FUNCTION tem o poder de liberar qualquer SET KEY para o mesmo número de tecla e vice versa. Isto é incompatível com versões prévias, as quais mantinham listas separadas para SET KEY e SET FUNCTION.

Notas

Precedência: SET KEY tem precedência sobre SET ESCAPE e SETCANCEL().

Terminando READ a partir de SET KEY: Existem várias formas de terminar um READ a partir de SET KEY.



Tabela 4-16: Encerrando um READ a partir de uma rotina SET KEY

Comando AçãoCLEAR GETS Encerra o READ sem gravar o GET correnteBREAK Encerra o READ sem gravar o GET correnteKEYBOARD Ctrl-W Encerra o READ e grava o GET correnteKEYBOARD Esc Encerra o READ sem gravar o GET corrente

CLEAR com SET KEY: CLEAR não deve ser usado para apagar a tela dentro de uma rotina de SET KEY pelo fato de emitir um CLEAR GETS e encerrar o READ. Para apagar a tela use CLEAR SCREEN ou CLS.

Exemplos

Este exemplo demonstra como usar SET KEY para invocar uma rotina que apresente uma lista de itens quando o usuário aperta F2 estando numa tela de entrada de dados:

#include"Inkey.ch"

SET KEY K_F2 TO ScrollAccountsUSE Accounts NEWUSE Invoices NEW@ 10, 10 GET Invoices->IdREADRETURNFUNCTION ScrollAccounts( cProc, nLine, cVar )LOCAL s_creenIF cVar == "ID"

s_creen := SAVESCREEN( 0, 0,24,79)Accounts->(DBEDIT(10, 10, 18, 40, {"Company"}))KEYBOARD CHR(K_CTRL_Y) + Accounts->Id + CHR(K_HOME)RESTSCREEN( 0, 0,24,79, s_creen)

ELSETONE(100, 2)

ENDIFRETURN NIL

SET PRINTER

Comuta o eco da saída do console para impressora ou arquivo

Sintaxe

SET PRINTER on | OFF | <xlComuta>SET PRINTER TO [<xcDispositivo> | <xcArquivo>]

Argumentos

ON ecoa saída de console para a impressora.



OFF suprime a impressão da saída de console.

<xlComuta> é uma expressão entre parênteses. Um valor verdadeiro (.T.) é ON, e falso (.F.) é OFF.

TO <xcDispositivo> identifica o nome do dispositivo (DEVICE) para onde será enviada a saída impressa. Um nome de dispositivo pode ser especificado literalmente ou como expressão caractere entre parênteses. Adicionalmente, um dispositivo pode ser local ou rede.Configurar SET PRINTER para um dispositivo não existente cria um arquivo com o nome deste. Assegure-se de não utilizar dois pontos (:) como caractere inicial de nome de dispositivo.

TO <xcArquivo> identifica o nome do arquivo de saída. O nome pode ser especificado literalmente ou como expressão caractere entre parênteses. Se a extensão não for especificada (.prn) é adicionada automaticamente.

Caso SET PRINTER TO seja especificado sem argumentos, o dispositivo especificado é fechado e o destino padrão é selecionado.

Descrição

SET PRINTER, da mesma forma que outros SETs, tem duas formas de uso com sua funcionalidade própria. A forma on|OFF de SET PRINTER controla se a saída será enviada ou não para a impressora. Comandos de console são aqueles em que geralmente não se especifica linha e coluna. Todos estes comandos, exceto ?|??, possuem a cláusula TO PRINT que também dirige a saída para a impressora. A saída de comandos de console é enviada para tela a menos que CONSOLE esteja OFF. Esteja advertido que @...SAYs não são afetados por SET PRINTER ON. Para enviá-los para impressora use SET DEVICE TO PRINTER.

SET PRINTER TO, ao contrário, determina o destino da saída de todos os comandos e funções que enviam saída para impressora. Isto inclui @...SAYs se SET DEVICE é TO PRINTER. A saída pode ser enviada para um dispositivo ou arquivo. Se o destino é um arquivo, Os seguintes nomes são válidos: LPT1, LPT2, LPT3 (todas portas paralelas), COM1, e COM2 (portas seriais) e PRN. O assumido é PRN.

Se o destino é arquivo, ele é criado no diretório DEFAULT corrente. Se um arquivo com o mesmo nome existir no mesmo local, ele é sobregravado sem nenhum aviso. Todas as saídas para impressora serão escritas neste arquivo até que seja fechado com SET PRINTER TO sem argumento.

Existem vários usos para SET PRINTER TO, incluindo:

Alternar portas para gerenciar múltiplas impressoras.

Saída em arquivo para posterior impressão, ou transferência para outra máquina via telecomunicação.

Esvaziar o spool de impressão e reselecionar o dispositivo padrão.

Notas

Compatibilidade: O Clipper não suporta a sintaxe SET PRINTER TO \\SPOOLER ou \\CAPTURE. Especificar SET PRINTER com estas opções cria arquivos Spooler.prn ou Capture.prn. Os símbolos \\ são ignorados.



Marcas de fim de arquivo: Quando a saída em impressora é redirecionada para um arquivo, a marca de fim de arquivo (CHR(26)) não é gravada quando este arquivo é fechado. Para encerrar um arquivo com uma marca de fim de arquivo, emita um ?? CHR(26) antes de SET PRINTER TO.

Rede: Para algumas redes, a impressora da estação deve ser primeiro redirecionada para o servidor de arquivo (geralmente rodando o spooler de rede).

Exemplos

Este exemplo ecoa a saída de um comando ? para a impressora, suprimindo a saída em console usando SET CONSOLE OFF:

USE Customers NEWSET PRINTER ONSET CONSOLE OFF

DO WHILE !EOF()? CustomerSKIP

ENDDO

EJECTSET PRINTER OFFSET CONSOLE ONCLOSERETURN

Este exemplo direciona a saída em LPT1 e esvazia o spooler após completar a impressão:

SET PRINTER TO LPT1<Comandos de impressão>...

SET PRINTER TO // Esvazia o spooler.

Este exemplo envia a saída de impressora para um arquivo texto, sobregravando um arquivo já existente:

SET PRINTER TO Prnfile.txtSET DEVICE TO PRINTERSET PRINTER ON

@ 0, 0 SAY "Isto vai para Prnfile.txt"? "Assim como isto!"

SET DEVICE TO SCREENSET PRINTER OFFSET PRINTER TO // Fecha arquivo de impressão

SET PROCEDURE*Compilar rotinas dentro do .OBJ corrente



Sintaxe

SET PROCEDURE TO [<idArquivoPrograma>[.<ext>]]

Argumentos

<idArquivoPrograma> é o nome do arquivo de rotinas a ser compilado dentro do objeto corrente.

<ext> é a extensão opcional. Caso não seja especificada, (.prg) é assumida.

SET PROCEDURE TO sem argumentos é ignorado.

Descrição

SET PROCEDURE faz com que o compilador compile todas as rotinas declaradas dentro de um arquivo e as inclua dentro do arquivo OBJ corrente. SET PROCEDURE é pré processado como a diretiva _procreq_() para compilar o arquivo especificado.

Este comando é um comando de compatibilidade e como tal não recomendado. Ele é superado por outras instruções como #include e os arquivos script (.clp).

SET UNIQUE*

Comuta a inclusão de chaves não-únicas num índice

Sintaxe

SET UNIQUE on | OFF | <xlComuta>

Argumentos

ON faz com que os índices sejam criados com atributo de unicidade.

OFF faz com que os índices possam ser criados sem atributo de unicidade.

<xlComuta> é uma expressão lógica entre parênteses. Um valor verdadeiro (.T.) é o mesmo que ON, e falso (.F.) é OFF.

Descrição

SET UNIQUE controla se um índice será criado com atributo de unicidade ou não. Com UNIQUE ON, novos índices são criados incluindo apenas chaves únicas. Se, durante o processo de indexação, dois ou mais registros forem encontrados com o mesmo valor de chave, o Clipper inclui somente o primeiro registro no índice. Onde quer que a chave seja atualizada, REINDEXada, ou sofra PACK, somente registros únicos serão mantidos. O índice mantém seu atributo de unicidade sem importar-se com o SET UNIQUE corrente, o mesmo se tivesse sido criado com INDEX ON...UNIQUE.

Alterar o valor da chave num índice único tem algumas implicações importantes. Primeiro, se uma chave é alterada para um valor de chave já existente no arquivo, o registro alterado é perdido no índice.



Segundo, se houver mais de um caso de um valor chave dentro de um arquivo de dados, alterar a chave visível não traz à tona outro registro com a mesma chave quando o índice é reconstruído com REINDEX, PACK, ou INDEX...UNIQUE.

Com UNIQUE OFF, índices são criados com todos os registros no índice.Modificações posteriores aos arquivos de dados adicionam todos os valores de chave ao índice, independente do estado de SET UNIQUE.

SET UNIQUE é um comando de compatibilidade e portanto não recomendado.Ele é superado pela cláusula UNIQUE no comando INDEX.

SET WRAP

Comuta rotação em MENUs

Sintaxe

SET WRAP on | OFF | <xlComuta>

Argumentos

ON permite à barra luminosa rotacionar quando estiver navegando em um menu de barra.OFF suprime a rotação num menu de barra.

<xlComuta> é uma expressão lógica entre parênteses. Um valor verdadeiro (.T.) é o mesmo que ON, e falso (.F.) é o mesmo que OFF.

Descrição

SET WRAP comuta a rotação da barra luminosa em um @...PROMPT do primeiro para o último item e vice-versa. Quando WRAP está ON e o último item está iluminado, Cursor para direita ou Cursor para baixo movem a barra luminosa para o primeiro item. Também quando o primeiro item de menu está iluminado, Cursor para esquerda ou Cursor para cima movem a barra para o último item.

Quando WRAP está OFF, pressionar Cursor para cima ou Cursor para esquerda no primeiro item ou Cursor para baixo ou Cursor para direita no último item, não causam nenhuma ação.

Funções

Funções numéricas

ABS()

Retorna o valor absoluto de uma expressão numérica

Sintaxe



ABS(<nExp>) --> nPositivo

Argumentos

<nExp> é a expressão numérica a ser avaliada.

Retorno

ABS() retorna um número que representa o valor absoluto de seu argumento. O valor retornado é um número positivo ou zero.

Descrição

ABS() é uma função numérica utilizada para determinar a magnitude de um valor numérico independente de seu sinal. Ela permite, por exemplo, que você obtenha a diferença entre dois números como um valor positivo sem saber com antecedência qual dos dois é o maior.

Normalmente, ABS(x) é definida nos termos de seu argumento, x, como segue: se x >= 0, ABS(x) retorna x; caso contrário, ABS(x) retorna -x.

Exemplos

Os exemplos a seguir ilustram resultados típicos da função ABS():

nNum1 := 100nNum2 := 150? nNum1 - nNum2 // Resulta: -50? ABS(nNum1 - nNum2) // Resulta: 50? ABS(nNum2 - nNum1) // Resulta: 50? ABS(-12) // Resulta: 12? ABS(0) // Resulta: 0

EXP()

Calcula e**x

Sintaxe

EXP(<nExpoente>) --> nLogNatural

Argumentos

<nExpoente> é o logaritmo natural para o qual um valor numérico será calculado.

Retorno

EXP() retorna um valor numérico equivalente ao valor de e elevado à potência especificada.



Descrição

EXP() é uma função matemática que calcula e**x, onde e é a base do logaritmo natural e x é o <nExpoente>. O valor máximo de <nExpoente> é 45 antes que ocorra um excedente numérico. EXP() e LOG() são funções inversas.

A quantidade de casas decimais exibidas é determinada unicamente por SET DECIMALS, não importando o valor corrente de SET FIXED.

Exemplos

Este exemplo demonstra várias invocações de EXP():

? EXP(1) // Resulta: 2.72SET DECIMALS TO 10? EXP(1) // Resulta: 2.7182818285? LOG(EXP(1)) // Resulta: 1.0000000000

INT()

Converte um valor numérico para um inteiro

Sintaxe

INT(<nExp>) --> nInteiro

Argumentos

<nExp> é uma expressão numérica a ser convertida para um inteiro.

Retorno

INT() retorna um valor numérico inteiro.

Descrição

INT() é uma função numérica que converte um valor numérico para um inteiro truncando--e não arredondando--todos os dígitos à direita do ponto decimal. INT() é útil em operações onde a porção decimal de um número não é necessária.

Exemplos

O exemplo a seguir demonstra os resultados de várias invocações da função INT():

? INT(100.00)// Resulta: 100? INT(.5) // Resulta: 0? INT(-100.75) // Resulta: -100



LOG()

Calcula o logaritmo natural de um valor numérico

Sintaxe

LOG(<nExp>) --> nLogNatural

Argumentos

<nExp> é um valor numérico maior do que zero a ser convertido para seu logaritmo natural.

Retorno

LOG() retorna o logaritmo natural na forma de um valor numérico. Caso <nExp> seja menor ou igual a zero, LOG() retorna um estouro numérico (exibido na forma de uma fila de asteriscos).

Descrição

LOG() é uma função numérica que calcula o logaritmo natural de um número, sendo o inverso da função EXP(). O logaritmo natural tem como base e, que é aproximadamente 2,7183. A função LOG() retorna x na seguinte equação:

e**x = y

onde y é a expressão numérica utilizada como o argumento LOG() (ou seja, LOG(y) = x). Devido ao arredondamento matemático, os valores retornados por LOG() e EXP() podem não coincidir exatamente (isto é, EXP(LOG(x)) pode não ser sempre igual a x).

Exemplos

Os exemplos a seguir demonstram vários resultados de LOG():

? LOG(10) // Resulta: 2.30? LOG(10 * 2) // Resulta: 3.00? EXP(LOG(1)) // Resulta: 1.00? LOG(2.71) // Resulta: 1.00

Este exemplo é uma função de usuário que retorna o logaritmo de base 10:

FUNCTION Log10( nNum )IF nNum > 0

RETURN LOG(nNum)/LOG(10)ELSE

RETURN NILENDIF

MOD()*

Retorna o módulo dBASE III PLUS de dois números



Sintaxe

MOD(<nDividendo>, <nDivisor>) --> nResto

Argumentos

<nDividendo> é o dividendo da operação de divisão.

<nDivisor> é o divisor da operação de divisão.

Retorno

MOD() retorna um número que representa o resto de <nDividendo> dividido por <nDivisor>.

Descrição

MOD() é uma função numérica que corresponde à função MOD() do dBASE III PLUS. Ela é implementada usando o operador módulo (%) do Clipper. Note que há diferenças entre a função MOD() do dBASE III PLUS e o operador módulo do Clipper, que estao descritas na tabela seguinte:

Tabela 5-25: Diferenças entre a função MOD() do dBASE III PLUS e o Operador Módulo do Clipper

Dividendo Divisor Operador Módulo MOD() Função MOD() no dBASE III Plus

3 0 Erro Erro 33 -2 1 -1 -1-3 2 -1 1 1-3 0 Erro Erro -3-1 3 -1 2 2-2 3 -2 1 12 -3 2 -1 -11 -3 1 -2 -2

Notas

Divisor zero em dBASE III PLUS: Em dBASE III PLUS, um divisor zero retorna o dividendo para cada valor do dividendo. Em Clipper, pelo contrário, o módulo de qualquer dividendo utilizando um divisor zero causa um erro em tempo de execução.

Divisor zero em versões anteriores: Em versões anteriores à Summer '87 do Clipper, operações de módulo com divisor zero retornavam zero para todos os dividendos. Na versão Summer '87 e posteriores, elas retornam um erro em tempo de execução.

ROUND()

Retorna um valor numérico arredondado para uma quantidade especificada de dígitos.

Sintaxe



ROUND(<nNúmero>, <nDecimais>) --> nArredondado

Argumentos

<nNúmero> é o valor numérico a ser arredondado.

<nDecimais> define a quantidade de casas decimais a serem retidas. Especificando-se um valor <nDecimais> negativo arredonda números inteiros.

Retorno

ROUND() retorna um valor numérico.

Descrição

ROUND() é uma função numérica que arredonda <nNúmero> para a quantidade de casas especificada por <nDecimais>. Especificando-se um valor zero ou negativo para <nDecimais> permite o arredondamento de números inteiros. Um <nDecimais> negativo indica a quantidade de casas à esquerda do ponto decimal a serem arredondadas. Dígitos entre cinco e nove, inclusive, são arredondados para cima. Dígitos abaixo de cinco são arredondados para baixo.

A exibição do valor de retorno não obedece à cofiguração de DECIMALS, a não ser que SET FIXED esteja ON. Com SET FIXED OFF, a exibição do valor de retorno contém a mesma quantidade de casas decimais que você especificar para <nDecimais>, ou zero se <nDecimais> for menor do que um.

Exemplos

Os exemplos a seguir arredondam valores com dígitos decimais:

SET DECIMALS TO 2SET FIXED ON//? ROUND(10.4, 0) // Resulta: 10.00? ROUND(10.5, 0) // Resulta: 11.00? ROUND(10.51, 0) // Resulta: 11.00? ROUND(10.49999999999999, 2) // Resulta: 10.50

Estes exemplos utilizam um argumento <nDecimais> negativo para arredondar valores numéricos para valores numéricos inteiros:

? ROUND(101.99, -1) // Resulta: 100.00? ROUND(109.99, -1) // Resulta: 110.00? ROUND(109.99, -2) // Resulta: 100.00

SQRT()

Retorna a raiz quadrada de um número positivo.

Sintaxe



SQRT(<nNúmero>) --> nRaiz

Argumentos

<nNúmero> é um número positivo do qual será calculada a raiz quadrada.

Retorno

SQRT() retorna um valor numérico calculado com precisão dupla. A quantidade de casas decimais exibidas é determinada apenas por SET DECIMALS, sem importar a configuração de SET FIXED. Um número negativo <nNúmero> retorna zero.

Descrição

SQRT() é uma função numérica utilizada em qualquer lugar em um cálculo numérico para computar uma raiz quadrada. Por exemplo, pode ser o caso de uma expressão para calcular o desvio padrão de um conjunto de números.

Exemplos

Estes exemplos ilustram vários resultados de SQRT():

SET DECIMALS TO 5//? SQRT(2) // Resulta: 1.41421? SQRT(4) // Resulta: 2.00000? SQRT(4) ** 2 // Resulta: 4.00000? SQRT(2) ** 2 // Resulta: 2.00000

Funções Caracteres

ALLTRIM()

Remove espaços em branco à direita e à esquerda de uma cadeia de caracteres

Sintaxe

ALLTRIM(<cString>) --> cTrimString

Argumentos

<cString> é a expressão caractere cujos espaços em branco serão eliminados.

Retorno

ALLTRIM() retorna uma cadeia de caracteres cujos espaços em branco à direita e à esquerda foram removidos.



Descrição

ALLTRIM() é uma função de tratamento de dados do tipo caractere que remove os espaços em branco à direita e à esquerda de uma cadeia de caracteres. É relacionada a LTRIM() e RTRIM(), que removem espaços em branco à esquerda e à direita de uma cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM() são as funções PADC(), PADR(), e PADL(), as quais centralizam, alinham à direita, ou alinham à esquerda cadeias de caracteres através da nserção de caracteres de preenchimento.

Exemplos

O exemplo a seguir cria uma cadeia de caracteres com espaços em branco à direita e à esquerda, e depois remove os espaços com ALLTRIM():

cString := SPACE(10) + "string" + SPACE(10)? LEN(cString) // Resulta: 26? LEN(ALLTRIM(cString)) // Resulta: 6

CHR()

Converte um código ASCII para um valor caractere

Sintaxe

CHR(<nCodigo>) --> cCar

Argumentos

<nCodigo> é um código ASCII na faixa de zero a 255.

Retorno

CHR() retorna um único valor caractere cujo código ASCII está especificado em <nCodigo>.

Descrição

CHR() é uma função de conversão numérica que converte um código ASCII para um caractere. É o inverso de ASC(). CHR() é muito versátil e serve para uma série de operações comuns tais como:

Enviar códigos de controle e caracteres gráficos para a tela ou impressora

Soar o alarme sonoro Converter valores de retorno de INKEY() para caracteres

Preencher o buffer de teclado

Notas



O caractere nulo: CHR(0) tem o tamanho de um e é tratado da mesma forma que qualquer outro caractere. Isto permite a você enviá-lo a qualquer dispositivo ou arquivo, inclusive arquivos de bancos de dados.

Exemplos

Os exemplos a seguir ilustram CHR() com vários argumentos:? CHR(72) // Resulta: H? CHR(ASC("A") + 32) // Resulta: a? CHR(7) // Resulta: alarme soa

Estas duas linhas de código demonstram a diferença entre uma cadeia de caracteres nula e um caractere nulo:

? LEN("") // Resulta: 0? LEN(CHR(0)) // Resulta: 1

LTRIM()

Remove os espaços em branco à esquerda de uma cadeia de caracteres.

Sintaxe

LTRIM(<cString>) --> cStringResult

Argumentos

<cString> é a cadeia de caracteres a ser copiada sem os espaços em branco à esquerda.

Retorno

LTRIM() retorna uma cópia de <cString>, sendo que os espaços em branco à esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres nula ("") ou toda composta de espaços em branco, LTRIM() retorna uma cadeia de caracteres nula ("").

Descrição

LTRIM() é uma função de tratamento de caracteres utilizada para formatar cadeias de caracteres que possuam espaços em branco à esquerda. Pode ser o caso de, por exemplo, números convertidos para cadeias de caracteres através da função STR().

LTRIM() é relacionada a RTRIM(), a qual remove espaços em branco à direita, e a ALLTRIM(), que remove espaços tanto à esquerda quanto à direita. O contrário de ALLTRIM(), LTRIM(), e RTRIM() são as funções PADC(), PADR(), e PADL(), as quais centralizam, alinham à direita, ou alinham à esquerda as cadeias de caracteres, através da inserção de caracteres de preenchimento.

Exemplos

Os exemplos a seguir ilustram LTRIM() utilizada em combinação com várias outras funções:



nNumber = 18? STR(nNumber) // Resulta: 18? LEN(STR(nNumber)) // Resulta: 10? LTRIM(STR(nNumber)) // Resulta: 18? LEN(LTRIM(STR(nNumber))) // Resulta: 2

REPLICATE()

Retorna uma cadeia de caracteres repetida uma quantidade de vezes especificada.

Sintaxe

REPLICATE(<cString>, <nCont>) --> cStringRepetido

Argumentos

<cString> é a cadeia de caracteres a ser repetida.

<nCont> é a quantidade de vezes que <cString> será repetido.

Retorno

REPLICATE() retorna uma cadeia de caracteres de no máximo 65.535 (64K) bytes. Se for especificado zero como o argumento <nCont> retorna uma cadeia de caracteres nula ("").

Descrição

REPLICATE() é uma função de tratamento de caracteres utilizada para exibir, imprimir, ou preencher o teclado repetidamente com um ou mais caracteres. REPLICATE() é semelhante à função SPACE(), a qual retorna uma quantidade especificada de caracteres em branco.

Exemplos

Estes exemplos demonstram REPLICATE() repetindo cadeias de caracteres:

? REPLICATE("*", 5) // Resulta: *****? REPLICATE("Oi ", 2) // Resulta: Oi Oi? REPLICATE(CHR(42), 5) // Resulta: *****

Este exemplo utiliza REPLICATE() para preencher o teclado com várias teclas Cursor para baixo:

#include "Inkey.ch"KEYBOARD REPLICATE(CHR(K_DN), 25)

SPACE()

Retorna um string de espaços.



Sintaxe

SPACE(<nCont>) --> cEspaços

Argumentos

<nCont> é a quantidade de espaços a serem retornados, sendo que o número máximo é 65.535 (64K).

Retorno

SPACE() retorna uma cadeia de caracteres. Se <nCont> for zero, SPACE() retorna uma cadeia de caracteres nula ("").

Descrição

SPACE() é uma função de tratamento de caracteres utilizada para retornar uma quantidade especificada de espaços. É o mesmo que REPLICATE(" ", <nCont>). SPACE() é utilizada para inicializar uma variável do tipo caractere, antes que a mesma seja associada a um GET. SPACE() também é usada para preencher cadeias de caracteres com espaços. Observe, porém, que as funções PADC(), PADL(), e PADR() são mais eficazes neste caso.

Exemplos

Este exemplo utiliza SPACE() para inicializar uma variável para entrada de dados:

USE Customer NEWMEMVAR->Name := SPACE(LEN(Customer->Name))@ 10,10 SAY "Nome do Cliente:" GET MEMVAR->NameREAD

STR()

Converte uma expressão numérica para uma cadeia de caracteres.

Sintaxe

STR(<nNúmero>, [<nTamanho>], [<nDecimais>]) --> cNúmero

Argumentos

<nNúmero> é a expressão numérica a ser convertida para uma cadeia de caracteres.

<nTamanho> é o tamanho da cadeia de caracteres a ser retornada incluindo dígitos decimais, ponto decimal, e sinal.

<nDecimais> é a quantidade de casas decimais a serem retornadas.

Retorno



STR() retorna <nNúmero> formatado como uma cadeia de caracteres. Se os argumentos opcionais de tamanho e decimais não foram especificados, STR() retorna a cadeia de caracteres conforme as seguintes regras:

Tabela 5-32: Resultados de STR() sem Argumentos

Expressão Tamanho do Valor de RetornoVariável Campo Tamanho do campo mais decimaisExpressões/constantes Mínimo de 10 dígitos mais decimaisVAL() Mínimo de 3 dígitosMONTH()/DAY() 3 dígitosYEAR() 5 dígitosRECNO() 7 dígitos

Descrição

STR() é uma função que converte valores numéricos para cadeias de caracteres. Ela é comumente utilizada para concatenar valores numéricos a cadeias de caracteres. STR() é aplicada na exibição de números, criação de códigos tais como números de produtos, e criação de chaves de indexação que combinam dados do tipo numérico e caractere.

STR() é semelhante a TRANSFORM(), que formata valores numéricos como cadeias de caracteres utilizando uma máscara ao invés de especificações de tamanho e decimais. Como TRANSFORM() usa uma máscara, ela pode inserir caracteres de formatação tais como vírgulas, cifroes, e parênteses.

O inverso de STR() é VAL(), a qual converte números presentes em cadeias de caracteres em valores numéricos.

Notas

Se <nTamanho> for menor do que a quantidade de dígitos numéricos inteiros em <nNúmero>, STR() retorna asteriscos ao invés do número.

Caso <nTamanho> seja menor do que a quantidade de dígitos decimais necessários à parte decimal da cadeia de caracteres retornada, o Clipper arredonda o número para a quantidade de casas decimais disponíveis.

Se <nTamanho> for especificado, mas <nDecimais> for omitido (sem casas decimais), o valor de retorno é arredondado para um inteiro.

Exemplos

Estes exemplos demonstram a faixa de valores retornados por STR(), de acordo com os argumentos especificados:

nNumber = 123.45? STR(nNumber) // Resulta:123.45? STR(nNumber, 4) // Resulta: 123? STR(nNumber, 2) // Resulta: **? STR(nNumber * 10, 7, 2) // Resulta: 1234.50



? STR(nNumber * 10, 12, 4) // Resulta: 1234.5000? STR(nNumber, 10, 1) // Resulta: 1234.5

Este exemplo utiliza STR() para criar um índice com uma chave composta de números de ordem e nomes de clientes:

USE Customer NEWINDEX ON STR(NumOrders, 9) + CustName TO CustOrd

SUBSTR()

Extrai um substring de uma cadeia de caracteres.

Sintaxe

SUBSTR(<cString>, <nInício>, [<nCont>]) --> cSubstring

Argumentos

<cString> é a cadeia de caracteres da qual será extraido um substring, podendo ter até 65.535 (64K) bytes, que é o tamanho máximo de uma cadeia de caracteres em Clipper.

<nInício> é a posição inicial em <cString>. Se <nInício> for positivo, ele é relativo ao caractere mais à esquerda em <cString>. Se <nInício> for negativo, ele é relativo ao caractere mais à direita em <cString>.

<nCont> é a quantidade de caracteres a serem extraidos. Se omitido, o substring começa em <nInício> e continua até o fim da cadeia de caracteres. Se <nCont> for maior do que a quantidade de caracteres existentes a partir de <nInício> até o final de <cString>, o excedente é ignorado.

Retorno

SUBSTR() retorna uma cadeia de caracteres.

Descrição

SUBSTR() é uma função de tratamento de caracteres que extrai um substring de qualquer outra cadeia ou campo memo. SUBSTR() está relacionada às funções LEFT() e RIGHT(), que extraem substrings que começam com os caracteres mais à esquerda e mais à direita em <cString>, respectivamente.

As funções SUBSTR(), RIGHT(), e LEFT() são utilizadas juntamente com as funções AT() e RAT() para localizar a primeira e/ou última posição de um substring antes de extrai-lo. Elas também são utilizadas para exibir ou imprimir apenas uma parte de uma cadeia de caracteres.

Exemplos

Os exemplos a seguir extraem o primeiro e o último nome de uma variável:

cName := "Biff Styvesent"? SUBSTR(cNome, 1, 4) // Resulta: Biff



? SUBSTR(cNome, 6) // Resulta: Styvesent? SUBSTR(cNome, LEN(cNome) + 2) // Resulta: null string? SUBSTR(cNome, -9) // Resulta: Styvesent? SUBSTR(cNome, -9, 3) // Resulta: Sty

Este exemplo utiliza SUBSTR() juntamente com AT() e RAT() para criar uma função definida pelo usuário com a finalidade de extrair um nome de arquivo de uma especificação dada:

? FileBase("C:\PRG\MYFILE.OBJ") // Resulta: MYFILE.OBJ

FUNCTION FileBase( cFile )LOCAL nPosIF (nPos := RAT("\", cFile)) != 0

RETURN SUBSTR(cFile, nPos + 1)ELSEIF (nPos := AT(":", cFile)) != 0

RETURN SUBSTR(cFile, nPos + 1)ELSE

RETURN cFileENDIF

UPPER()

Converte caracteres minúsculos para maiúsculos.

Sintaxe

UPPER(<cString>) --> cStringMaiusc

Argumentos

<cString> é a cadeia de caracteres a ser convertida.

Descrição

UPPER() é uma função de tratamento de caracteres utilizada para converter todos os caracteres em um string para maiúsculos. Ela está relacionada a LOWER(), que converte todos os caracteres em um string para minúsculos. UPPER() está relacionada às funções ISUPPER() e ISLOWER(), as quais determinam se um string começa com uma letra maiúscula ou minúscula. UPPER() geralmente é utilizada para formatar cadeias de caracteres para fins de exibição. Ela pode, porém, ser usada para normalizar strings para fins de comparações onde não se diferencia maiúsculas de minúsculas, ou para fins de INDEXação.

Exemplos

Os exemplos a seguir ilustram os efeitos de UPPER():

? UPPER("a string") // Resulta: A STRING? UPPER("123 char = <>") // Resulta: 123 CHAR = <>



Este exemplo utiliza UPPER() como parte de uma condição que não diferencia maiúsculas de minúsculas:

USE Customer INDEX CustName NEWLIST CustName FOR "ISABELLA" $ UPPER(Customer)

UPPER() também é útil para criar expressões de chave de indexação onde não é feita a diferenciação entre maiúsculas e minúsculas, desta forma:

USE Customer NEWINDEX ON UPPER(Last) TO CustLast

Depois, use a mesma expressão para fazer uma pesquisa em Customers:

MEMVAR->Last = SPACE(15)@ 10, 10 GET MEMVAR->LastREADSEEK UPPER(MEMVAR->Last)

VAL()

Converte um número presente em uma cadeia de caracteres para um valor numérico.

Sintaxe

VAL(<cNúmero>) --> nNúmero

Argumentos

<cNúmero> é a expressão caractere a ser convertida.

Retorno

VAL() retorna <cNúmero> convertido para um valor numérico, incluindo dígitos decimais.

Descrição

VAL() é uma função de conversão de caracteres, a qual converte uma cadeia de caracteres que contém dígitos numéricos para um valor numérico. Quando VAL() é executada, ela avalia <cNúmero> até encontrar o segundo ponto decimal, o primeiro caractere não numérico, ou o final da expressão. Os espaços à direita são ignorados. Com SET FIXED em ON, VAL() retorna a quantidade de casas decimais especificadas por SET DECIMALS, arredondando <cNúmero> se ele for especificado com uma quantidade de dígitos maior do que o valor corrente de DECIMALS. Da mesma forma que todas as outras funções que arredondam, os dígitos entre zero e quatro são arredondados para baixo, e os dígitos entre cinco e nove são arredondados para cima. Com SET FIXED em OFF, VAL() retorna a quantidade de casas decimais especificadas em <cNúmero>.

VAL() é o oposto de STR() e TRANSFORM(), as quais convertem valores numéricos para cadeias de caracteres.



Exemplos

Os exemplos a seguir ilustram VAL() com SET FIXED ON, e SET DECIMALS TO 2:

SET DECIMALS TO 2SET FIXED ON//? VAL("12.1234") // Resulta: 12.12? VAL("12.1256") // Resulta: 12.13? VAL("12A12") // Resulta: 12.00? VAL("A1212") // Resulta: 0.00? VAL(SPACE(0)) // Resulta: 0.00? VAL(SPACE(1)) // Resulta: 0.00? VAL(" 12.12") // Resulta: 12.12? VAL("12 .12") // Resulta: 12.00

Funções Cronológicas

CTOD()

Converte uma cadeia de caracteres em uma data correspondente

Sintaxe

CTOD(<cData>) --> dData

Argumentos

<cData> é uma cadeia de caracteres que contém números representando o mês, dia, e ano separados por qualquer outro caractere que não um número. Os dígitos do mês, dia, e ano devem ser especificados de acordo com o formato indicado pelo SET DATE. Se os dígitos do século não são especificados, o século é determinado pelas regras do SET EPOCH.

Retorno

CTOD() retorna um dado do tipo data. Se <cData> não é uma data válida, CTOD() retorna uma data vazia.

Descrição

TOD() é uma função de conversão de caracteres que converte uma cadeia e caracteres em uma data. Para inicializar uma data vazia para uma ntrada de dados, especifique a <cData> como sendo uma cadeia de aracteres nula (""), SPACE(8), ou " / / ".

TOD() é usado sempre que você precisar um dado literal do tipo data. lguns exemplos são:

Inicializando uma variável para um valor do tipo data

Especificando um literal do tipo data como sendo um argumento de uma cláusula RANGE de um @...GET



Especificando um literal do tipo data a fim de realizar operações aritméticas com esta

Comparando o resultado de uma expressão do tipo data com um cadeia literal do mesmo tipo Efetuando REPLACE em um campo do tipo data com uma cadeia literal do mesmo tipo CTOD() é

o inverso de DTOC() na qual converte um valor do tipo data para uma cadeia de caracteres no formato especificado pelo SET DATE e SET CENTURY. DTOS() também converte um valor do tipo data para uma cadeia de caracteres na forma aaaammdd.

Exemplos

O exemplo seguinte utiliza CTOD() para inicializar duas variáveis do tipo data, usando uma no GET e a outra para a validação do RANGE:

SET CENTURY ONdBegin = CTOD("01-26-1876")dCurrent = CTOD("")@ 10, 10 SAY "Digite a data:" GET dCurrent RANGE dBegin, DATE()READ

Este exemplo utiliza CTOD() para criar um valor do tipo data

USE Inventory NEWREPLACE ALL Inventory->Price WITH Inventory->Price * 1.1;FOR Inventory->InvDate < CTOD("10/10/90")

DATE()

Retorna a data do sistema como sendo um valor do tipo data

Sintaxe

DATE() --> dSistema

Retorno

DATE() retorna a data do sistema como sendo um valor do tipo data.

Descrição

DATE() é uma função de tratamento de datas que provê um meio de inicializar variáveis de memória com a data corrente, comparando outros valores do tipo data para a data corrente, e realizando operações aritméticas relativas à data corrente.

O formato para a exibição de datas é controlado pelo comando SET DATE.O formato padrão assumido é mm/dd/aa.

Exemplos

Os exemplos seguintes mostram a função DATE() utilizada de várias maneiras:



? DATE() // Resulta: 09/01/90? DATE() + 30 // Resulta: 10/01/90? DATE() - 30 // Resulta: 08/02/90dDate = DATE()? CMONTH(dDate) // Resulta: Setembro

DTOC()

Converte um valor data para uma cadeia de caracteres

Sintaxe

DTOC(<dData>) --> cData

Argumentos

<dData> é o valor data que será convertido.

Retorno

DTOC() retorna uma cadeia de caracteres que representa uma data. O valor de retorno é formatado de acordo com o formato de datas corrente. O formato padrão é mm/dd/aa. Uma data nula retorna uma cadeia de caracteres em branco igual em tamanho ao formato de data corrente.

Descrição

DTOC() é uma função de conversão de datas utilizada por motivos de formatação quando você deseja exibir a data no formato SET DATE e é necessária uma expressão caractere (em um LABEL FORM, por exemplo). Caso você precise de um formato de data específico, você pode utilizar TRANSFORM() ou uma expressão customizada.

Se você estiver INDEXando uma data juntamente com uma cadeia de caracteres, use DTOS() ao invés de DTOC() para converter o valor data para uma cadeia de caracteres.

Exemplos

Os exemplos a seguir demonstram utilizações gerais de DTOC():

? DATE() // Resulta: 09/01/90? DTOC(DATE()) // Resulta: 09/01/90? "Hoje e " + DTOC(DATE()) // Resulta: Hoje e 09/01/90

DTOS()

Converte um valor data para uma cadeia de caracteres com formato aaaammdd

Sintaxe



DTOS(<dData>) --> cData

Argumentos

<dData> é o valor data que será convertido.

Retorna

DTOS() retorna uma cadeia com oito caracteres no formato, aaaammdd. Quando <dData> for uma data nula (CTOD("")), DTOS() retorna uma cadeia de oito caracteres em branco. O valor de retorno não é afetado pelo formato de data corrente.

Descrição

DTOS() é uma função de conversão de datas utilizada para criar expressões de índice que consistem em um valor data e uma expressão caractere. DTOS() converte um valor data para uma cadeia de caracteres que pode ser concatenada a qualquer outra expressão caractere. O valor de retorno é estruturado para preservar a ordem de data (ano, mês, e dia).

Exemplos

Os exemplos a seguir ilustram DTOS() em conjunto com várias outras funções:

? DATE() // Resulta: 09/01/90? DTOS(DATE()) // Resulta: 19900901? LEN(DTOS(CTOD(""))) // Resulta: 8

Este exemplo demonstra como criar um índice com uma data composta e chave de caractere utilizando DTOS():

USE Sales NEWINDEX ON DTOS(Date) + Salesman TO DateName

YEAR()

Converte um valor data para ano na forma de um valor numérico.

Sintaxe

YEAR(<dData>) --> nAno

Argumentos

<dData> é o valor data a ser convertido.

Retorno



YEAR() retorna o ano do valor data especificado, inclusive dígitos indicativos de século, na forma de um valor numérico de quatro dígitos. O valor retornado não é influenciado pelo formato de DATE ou CENTURY corrente. A especificação de uma data nula (CTOD("")) retorna zero.

Descrição

YEAR() é uma função de conversão de datas utilizada para converter um valor data para um valor numérico indicativo do ano. Pode ser utilizada em cálculos de, por exemplo, relatórios periódicos, ou para formatação de exibições de data.

YEAR() é membro de um grupo de funções que retornam componentes de um valor data na forma de valores numéricos. Este grupo inclui DAY() e MONTH(), que retornam valores de dia e mês na forma de valores numéricos.

Exemplos

Os exemplos a seguir ilustram YEAR() usando a data do sistema:

? DATE() // Resulta: 09/01/90? YEAR(DATE()) // Resulta: 1990? YEAR(DATE()) + 11 // Resulta: 2001

Este exemplo cria uma função definida pelo usuário usando YEAR() para formatar um valor data na forma : mês dia, ano:

? Mdy(DATE()) // Resulta: September 20, 1990

FUNCTION Mdy( dDate )RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate)));+ "," + STR(YEAR(dDate))

Funções Matriciais

ACHOICE()

Executa um menu pop-up

Sintaxe

ACHOICE(<nTopo>, <nEsquerda>, <nBase>, <nDireita>, <acItensMenu>,[<alItensSelecionaveis> | <lItemsSelecionáveis>], [<cFunçãoUsuário>],[<nItemInicial>], [<nLinhaJanela>]) --> nPosição

Argumentos

<nTopo>, <nEsquerda> e <nBase>, <nDireita> são as coordenadas do canto superior esquerdo e canto inferior direito da janela. Valores de linha podem variar entre zero e MAXROW(), e valores de coluna podem variar entre zero e MAXCOL().



<acItensMenu> é um vetor que contém as cadeias de caracteres que serão exibidas como sendo os itens de menu. Cada item de menu será mais tarde identificado através de sua posição numérica neste vetor.

<alItensSelecionaveis> é um vetor paralelo de valores lógicos--diretamente relacionado a <acItensMenu>--que especifica os itens de menu que poderão ser selecionados. Os elementos podem ser valores lógicos ou cadeias de caracteres. Caso o elemento seja uma cadeia de caracteres, ele é avaliado como uma expressão macro que deverá retornar um tipo de dados lógico. Em ambos os casos, um valor de falso (.F.) significa que o item de menu correspondente não está disponível, e um valor de verdadeiro (.T.) significa que está disponível. Se for especificado <lItensSelecionaveis> ao invés de um vetor, falso (.F.) torna todos os itens de menu não disponíveis e verdadeiro (.T.) torna todos os itens de menu disponíveis. O padrão adotado é que todos os itens de menu estejam disponíveis para seleção.

<cFunçãoUsuário> é o nome de uma função definida pelo usuário que é executada quando uma tecla não reconhecível for pressionada. O nome da função é especificado como uma expressão caractere sem parênteses ou argumentos. Note que o comportamento de ACHOICE() é afetado pela presença deste argumento.

<nItemInicial> é a posição ocupada no vetor de <acItensMenu> pelo item que aparecerá em destaque quando o menu for exibido pela primeira vez. Caso você especifique um item de menu que não esteja disponível, ou caso você não use argumento algum, o item que aparecerá em destaque será o primeiro item selecionável do vetor.

<nLinhaJanela> é o número da linha da janela na qual o item de menu inicial aparecerá. A numeração de linhas começa com zero. O padrão é que o item de menu inicial apareça o mais próximo do topo da janela possível, sem deixar nenhuma linha vazia na parte de baixo. Consequentemente, caso haja um número suficiente de itens de menu após o primeiro para completar a janela, ele aparecerá na primeira linha (linha zero) do menu. Este argumento é utilizado para controlar a disposição inicial do menu nos casos em que haja mais itens de menu do que a janela comporta.

Como toda função, os argumentos opcionais são omitidos usando-se uma vírgula ao invés do argumento propriamente dito.

Retorno

ACHOICE() retorna a posição numérica ocupada pelo item de menu selecionado no vetor de <acItensMenu>. Se o processo de seleção for interrompido, ACHOICE() retorna zero.

Descrição

ACHOICE() é uma função de interface com o usuário que pode ser utilizada para criar vários tipos de menus pop-up. Cada menu usa um vetor de cadeia de caracteres, que serão os itens de menu, e um vetor paralelo de valores lógicos que determina se os itens são selecionáveis. Quando ACHOICE() é invocada, a lista de itens de menu é exibida dentro das coordenadas de janela especificadas. Quando o usuário tecla Return, o item corrente é selecionado, e ACHOICE() retorna a posição ocupada por este item de menu em <acItensMenu>. Quando o usuário pressiona Esc, ACHOICE() aborta e retorna zero.

Caso a quantidade de itens em <acItensMenu> exceda a quantidade de linhas na janela de menu, os itens de menu aparecem na medida em que o usuário tenta mover a barra luminosa para cima ou para baixo, além dos limites da janela de menu. Observe que a barra luminosa não pula do último para o



primeiro item de menu quando se chega ao fim da lista de itens, ou vice-versa. Porém, se o usuário pressionar a primeira letra do item, a barra luminosa irá automaticamente para o primeiro item de menu cuja primeira letra for a mesma pressionada.

Navegando pelo menu: ACHOICE() tem dois modos, dependendo se o argumento <cFunçãoUsuário> for especificado. Caso não seja especificado, as seguintes teclas de navegação são ativas:

Tabela 5-1: Teclas em ACHOICE() (Sem função de Controle)

Tecla AçãoCursor para cima Vai para o item anteriorCursor para baixo Vai para o próximo itemHome Vai para o primeiro item do menuEnd Vai para o último item do menuCtrl-Home Vai para o primeiro item da janelaCtrl-End Vai para o último item da janelaPgUp Vai para a página anteriorPgDn Vai para a próxima páginaCtrl-PgUp Vai para o primeiro item do menuCtrl-PgDn Vai para o último item do menuReturn Seleciona item correnteEsc Aborta seleçãoCursor para esquerda Aborta seleçãoCursor para direita Aborta seleçãoPrimeira letra Vai para o próximo item iniciando com a letra

Cor: Os itens de menu são exibidos na cor padrão, o item onde está a barra luminosa na cor destaque, e os itens não disponíveis na cor não seleciionada. Por exemplo, a seguinte declaração de cores:

SETCOLOR("W+/N, BG+/B, , , W/N")

Exibe um menu que é de cor branca intensificada sobre preto, a barra luminosa é de cor ciano intensificado sobre azul, e os itens de menu não disponíveis são brancos sobre preto.

Função de usuário: Da mesma forma que as demais funções de interface com o usuário, ACHOICE() aceita uma função de usuário. A função de usuário é especificada quando você deseja aninhar invocações da função ACHOICE() para criar menus hierárquicos ou redefinir teclas.

Quando é especificada uma função de usuário, ACHOICE() processa somente um conjunto limitado de teclas automaticamente. Estas estao relacionadas na tabela abaixo. Todas as outras teclas geram uma exceção de tecla que passa o controle para a função de usuário. O controle também será passado à função de usuário quando ACHOICE() fica inativo (ou seja, quando não há mais teclas a processar).

Tabela 5-2: Teclas em ACHOICE() (Com função de controle)

Tecla AçãoCursor para cima Vai para o item anterior



Cursor para baixo Vai para o próximo itemCtrl-Home Vai para o primeiro item da janelaCtrl-End Vai para o último item da janelaPgUp Vai para a página anteriorPgDn Vai para a próxima páginaCtrl-PgUp Vai para o primeiro item do menuCtrl-PgDn Vai para o último item do menu

Quando ACHOICE() executa a função de usuário, ela passa automaticamente os três parâmetros a seguir:

O modo ACHOICE() corrente

O elemento corrente no vetor de itens

A posição de linha relativa dentro da janela de menu

O modo indica o estado atual de ACHOICE(), que depende da tecla pressionada e da ação tomada por ACHOICE() antes da execução da função de usuário. O parâmetro modo pode ter os seguintes valores:

Tabela 5-3: Modos de ACHOICE()

Modo Achoice.ch Descrição0 AC_IDLE Inativo1 AC_HITTOP Tentativa de passar início da lista2 AC_HITBOTTOM Tentativa de passasr final da lista3 AC_EXCEPT Teclagemn exceção4 AC_NOITEM Itens não selecionados

Após a função de usuário ter executado as operações apropriadas ao modo ACHOICE() ou LASTKEY(), ela deve retornar um valor que solicite a ACHOICE() executar uma operação entre o seguinte conjunto de ações:

Tabela 5-4: Valores de Retorno da Função de Controle de ACHOICE()

Valor Achoice.ch Ação0 AC_ABORT Aborta seleção1 AC_SELECT Executa seleção2 AC_CONT Continua ACHOICE()3 AC_GOTO Vai para o próximo item cuja primeira letra for a tecla pressionada

Exemplos

O exemplo a seguir utiliza dois vetores literais para especificar os itens de menu e critérios de seleção. Depois que o menu foi exibido e o usuário fez sua escolha, o nome do item de menu selecionado é exibido:



acMenuItens := {Um, Dois, "", Três}alSelectableItens := {.T., .T., .F., .T.}nPosition := ACHOICE(10, 10, 12, 15, acMenuItens, alSelectableItens)? acMenuItens[nPosition]

No próximo exemplo, os vetores são declarados, é especificada uma condição de seleção para um dos itens de menu, e há uma função de usuário:

FUNCTION MyMenuLOCAL acMenuItens[4], alSelectableItens[4], cUserFunction := "DoIt"//acMenuItens[1] := "Adiciona Registro"acMenuItens[2] := "Edita Registro"acMenuItens[3] := "Elimina Registro"acMenuItens[4] := "Atualiza Registro"//alSelectableItens[1] := .T.alSelectableItens[2] := .T.alSelectableItens[3] := .T.alSelectableItens[4] := "!UPDATED()" // Condicao de selecaoRETURN ACHOICE(10, 10, 12, 30, acMenuItens,;

alSelectableItens, cUserFunction)

Funções para controle de arquivos de dados

BROWSE()

Faz Browse de registros dentro de uma janela

Sintaxe

BROWSE([<nTopo>], [<nEsquerda>], [<nBase>], [<nDireita>]) --> NIL

Argumentos

<nTopo>, <nEsquerda>, <nBase>, e <nDireita> definem as coordenadas da janela. Se não forem especificadas, as coordenadas padrão da janela são 1, 0 até MAXROW(), e MAXCOL().

Retorno

BROWSE() sempre retorna NIL.

Descrição

BROWSE() é uma função de interface com o usuário que invoca um editor e um browser (orientado por tabela) de utilização geral para os registros na área de trabalho corrente. Para uma lista das teclas de navegação utilizadas por BROWSE(), consulte a função DBEDIT().



Notas

Linha de status: BROWSE() suporta uma linha de status no canto superior direito da janela de browse que indica um dos itens a seguir:

Tabela 5-6: Mensagens de Status de BROWSE()

Mensagem Significado<new> Modo de Append<bof> Início de arquivo<delete> Registro corrente está marcado para eliminaçãoRecord Número do registro atual

Modos: BROWSE() tem os três modos seguintes:

Browse: Este é o modo padrão de BROWSE(). Ao ser pressionada qualquer uma das teclas de navegação DBEDIT(), a barra luminosa move-se para uma nova linha ou coluna.

Edita Campos: Ao ser pressionado Return em qualquer campo, entra-se na edição de campos usando um GET. Pressionar Return termina o modo de edição, gravando as alterações. Esc termina sem gravar as alterações. Já que o modo de edição de campos utiliza-se de GET, todas as teclas de navegação e edição são teclas READ.

Inserir: Quando se vai para o fim do arquivo com Ctrl-PgDn e depois aperta-se Cursor para baixo entra-se no modo append, sendo que na linha de comando aparecerá a mensagem "<new>". É inserido, então, um novo registro. Ao pressionar-se Cursor para cima termina-se o modo append, gravando o novo registro caso tenham sido entrados dados. Se não foram entrados quaisquer dados, o novo registro não é gravado.

DBEDIT()*

Faz um browse em registros no formato de tabela

Sintaxe

DBEDIT([<nTopo>], [<nEsquerda>],[<nBase>], <nDireita>],[<acColunas>],[<cFunçãoUsuário>],[<acMáscarasColunas> | <cMáscaraColunas>],[<acCabeçalhosColunas> | <cCabeçalhoColunas>],[<acSeparadoresCabeçalhos> | <cSeparadorCabeçalhos>],[<acSeparadoresColunas> | <cSeparadorColunas>],[<acSeparadoresRodapés> | <cSeparadorRodapés>],[<acRodapésColunas> | <cRodapéColunas>]) --> NIL

Argumentos

<nTopo>, <nEsquerda> e <nBase>, <nDireita> definem as coordenadas do canto superior esquerdo e o canto inferior direito da janela da DBEDIT(). Os valores da linha podem variar de zero até



MAXROW() e os posicionamentos de coluna podem variar de zero até MAXCOL(). Caso não sejam especificados, as coordenadas assumidas são 0, 0, MAXROW(), e MAXCOL().<acColunas> é um vetor de expressões caractere contendo os nomes de campos do arquivo de dados ou expressões para utilizar como valores para cada linha exibida. Se este argumento não é especificado, DBEDIT() exibe todos os campos presentes na área corrente como sendo as colunas.

<cFunçãoUsuário> é o nome de uma função definida pelo usuário que é executada quando uma tecla não reconhecível é pressionada ou quando não há nenhuma tecla pendente no buffer do teclado. O nome da função é especificada como sendo uma expressão caractere sem os parênteses ou argumentos. Note que o comportamento da função DBEDIT() é afetado pela presença desses argumentos. Para maiores informações veja os tópicos discutidos abaixo.

<acMáscarasColunas> é um vetor paralelo contendo as máscaras de formatação de cada coluna. Especificando <cMáscaraColunas> em vez do vetor, este será assumido para a exibição de todas as colunas com o mesmo formato.

<acCabeçalhosColunas> é um vetor paralelo contendo expressões caractere que definem os cabeçalhos para cada coluna. Se especificada <cCabeçalhoColuna> em vez do vetor de cabeçalhos, é assumido o mesmo cabeçalho para todas as colunas. Para exibir cabeçalhos em mais de uma linha, inclua um ponto-e-vírgula dentro da expressão de cabeçalho onde você deseje que a cadeia seja separada. Caso não seja especificado, os cabeçalhos das colunas são tomados do vetor <acColunas>, ou são assumidos os nomes dos campos presentes na área corrente se o argumento <acColunas> não for mencionado.

<acSeparadoresCabeçalhos> é um vetor paralelo contendo expressões do tipo caractere que definem os caracteres que serão utilizados para desenhar as linhas horizontais separando os cabeçalhos das colunas da área de exibição dos campos. Especificando a expressão <cSeparadorCabeçalhos> em vez do vetor é utilizado o mesmo separador para todas as colunas. Caso este argumento não seja mencionado, o separador assumido é uma linha gráfica dupla.<acSeparadoresColunas> é um vetor paralelo contendo expressões caractere que definem os caracteres utilizados para desenhar as linhas verticais que separam as colunas. Especificando a expressão<cSeparadorColunas> em vez do vetor é utilizado o mesmo separador para todas as colunas. Caso este argumento não seja mencionado, o separador assumido é uma linha gráfica simples.

<acSeparadoresRodapés> é um vetor paralelo contendo expressões caractere que definem os caracteres que serão utilizados para desenhar as linhas horizontais que separam os rodapés das colunas da área de exibição dos campos. Especificando a expressão <cSeparadorRodapés> em vez do vetor é utilizado o mesmo separador de rodapé para todas as colunas. Caso este argumento não seja mencionado, não é exibido nenhum separador para os rodapés.

<acRodapésColunas> é um vetor paralelo contendo expressões caractere que definem os rodapés para cada coluna. Especificando a expressão <cRodapéColunas> em vez do vetor é utilizado o mesmo rodapé para todas as colunas. Para exibir rodapés em mais de uma linha, inclua um ponto-e-vírgula na expressão contendo o rodapé onde você deseje que a cadeia seja separada. Caso este argumento não seja mencionado, não é exibido nenhum rodapé para as colunas.

Retorno

DBEDIT() sempre retorna NIL.

Descrição



DBEDIT() além de ser uma função de interface com o usuário é também uma função de compatibilidade que exibe registros de uma ou mais áreas de trabalho na forma de tabela. A janela de visualização da DBEDIT() é uma área com células dividida em colunas e linhas. As colunas correspondem aos campos do arquivo de dados e as linhas aos registros deste arquivo. Cada coluna é definida por um elemento do vetor <acColunas>. A largura assumida para a exibição de cada coluna é determinada pela avaliação da expressão da coluna contida no vetor <acColunas> ou pela máscara da coluna especificada no vetor <acMáscarasColunas>.

Todas as teclas de movimentação do cursor são manipuladas dentro da DBEDIT(), incluíndo PgUp, PgDn, Home, End, as quatro setas de navegação, e todas as combinações válidas da tecla Ctrl que realizam a movimentação do cursor. As teclas de navegação às quais a DBEDIT() responde quando o argumento da função do usuário não é especificado estao mostradas na tabela Teclas Ativas na próxima página.

Tabela 5-8: Teclas Ativas em DBEDIT()

Tecla AçãoCursor para cima Sobe uma linhaCursor para baixo Desce uma linhaCursor para esquerda Coluna à esquerdaCursor para direita Coluna à direitaCtrl-Cursor para esquerda Painel uma coluna para esquerdaCtrl-Cursor para direita Painel uma coluna para direitaHome Coluna mais à esquerda na telaEnd Coluna mais à direita na telaCtrl-Home Coluna inicialCtrl-End Coluna finalPgUp Tela anteriorPgDn Próxima telaCtrl-PgUp Primeira linha da coluna correnteCtrl-PgDn Ultima linha da coluna correnteReturn Encerra DBEDIT()Esc Encerra DBEDIT()

Quando o argumento da função do usuário (<cFunçãoUsuário>) é especificado, todas as teclas indicadas na tabela Teclas Ativas estao ativas com exceção do Esc e Return. Quando a DBEDIT() chama a função do usuário, esta passa automaticamente dois argumentos:

O modo corrente passado como um valor numérico

O índice da coluna corrente com base no vetor <acColunas> passado como um valor numérico

O parâmetro modo indica o estado corrente da DBEDIT() dependendo da última tecla que foi executada. Os possíveis valores dos modos estao mostrados na tabela Modos da DBEDIT().

Tabela 5-9: Modos de DBEDIT()Status bedit.ch escrição0 E_IDLE nativa, todas teclas foram manipuladas e não há teclas pendentes



1 E_HITTOP entativa de passar início de arquivo2 E_HITBOTTOM entativa de passar final de arquivo3 E_EMPTY rquivo vazio na área corrente4 DC_EXCEPT eclagem exceção

O parâmetro índice aponta para a posição da coluna corrente definida no vetor <acColunas>. Caso o vetor <acColunas> não seja especificado, o parâmetro índice apontará para a posição do campo da estrutura do arquivo de dados corrente. O nome do campo pode ser acessado utilizando a função FIELD().

Quando a função do usuário tiver sido chamada, um valor deve ser retornado para instruir à DBEDIT() que ação realizar em seguida. A tabela Valores de Retorno da Função do Usuário sumariza os possíveis valores de retorno e as ações correspondentes:

Tabela 5-10: Valores de Retorno da Função de Usuário de DBEDIT()

Valor bedit.ch escrição0 E_ABORT Aborta DBEDIT()1 E_CONT ontinua DBEDIT()2 E_REFRESH Força reler e reescrever a tela e continuar; após reescrever, processa

teclas, e vai para inativa

A função do usuário é chamada nos seguintes casos:

Ocorrência de uma tecla de exceção. Isto acontece quando a DBEDIT() captura uma tecla pressionada e esta não é reconhecida. Quaisquer teclas pendentes permanecem no buffer do teclado até que seja capturada dentro da função do usuário ou até que a DBEDIT() continue.

DBEDIT() entra no modo inativo (i.e., quando todas as teclas pendentes tenham sido executadas). Isto acontece quando o buffer do teclado está vazio ou após ser efetuado um refresh da tela. Nesta ocorrência, há uma chamada para a função do usuário e então a DBEDIT() espera por uma tecla.

Início ou final do arquivo é encontrado. Esta ocorrência é a mesma que a inatividade da DBEDIT(). Todas as teclas pendentes são executadas, e há uma chamada à função do usuário com a mensagem de status indicadora.

Note que quando a DBEDIT() é executada pela primeira vez, todas as teclas pendentes no buffer do teclado são executadas e logo após a DBEDIT() entra no modo inativo com a chamada à função do usuário. Caso não existam teclas pendentes, o modo inativo é imediato.

A estrutura da função do usuário deve ser desenhada para manipular todos os modos e as mensagens de status recebidas da DBEDIT().

DBEDIT() é completamente recursiva, isto significa que você pode realizar chamadas aninhadas a ela. Utilizando esta característica, você pode ter múltiplas janelas de browse na tela ao mesmo tempo.

DBEDIT() é uma função de compatibilidade e, portanto, não é recomendada sua utilização como dispositivo de browse. Para este propósito, ela está superada pela classe de objeto TBrowse.

Exemplos



Este exemplo demonstra como chamar a DBEDIT() com uma função do usuário:

USE Customer INDEX Customer NEWUSE Sales INDEX Sales NEWSET RELATION TO CustNum INTO Customer//acColumns = {"Branch", "Salesman", "Amount", "Customer->Customer"}DBEDIT(4, 0, 22, 79, acColumns, "UserFunc")

EOF()

Determina se o final do arquivo foi atingido

Sintaxe

EOF() --> lLimite

Retorno

EOF() retorna verdadeiro (.T.) quando é feita uma tentativa de mover o ponteiro de registros para além do último registro lógico em um arquivo de banco de dados; do contrário, ela retorna falso (.F.). Caso não haja nenhum arquivo de banco de dados aberto na área de trabalho corrente, EOF() retorna falso (.F.). Se o arquivo de banco de dados corrente não possui registros, EOF() retorna verdadeiro (.T.).

Descrição

EOF() é uma função de tratamento de banco de dados utilizada para testar uma condição de limite de final de arquivo quando o ponteiro de registros está se movendo para frente em um arquivo de banco de dados. Qualquer comando que possa mover o ponteiro de registros pode configurar EOF().

A aplicação mais típica é como parte do argumento <lCondicao> de uma construção DO WHILE que processa registros sequencialmente em um arquivo de banco de dados. Neste caso <lCondicao> incluiria um teste para .NOT. EOF(), forçando o laço DO WHILE a terminar quando EOF() retornar verdadeiro (.T.).

Tanto EOF() quanto FOUND() são frequentemente utilizados para verificar se um comando SEEK, FIND, ou LOCATE falhou. Com estes comandos, porém, é preferível usar FOUND().

Quando EOF() retorna verdadeiro (.T.), o ponteiro de registros é posicionado em LASTREC() + 1 sem importar se há um SET FILTER ativo ou se SET DELETED está ON. Caso haja tentativas de mover o ponteiro de registros para frente, o mesmo resultado será retornado sem erro. Uma vez que a função EOF() retorna verdadeiro (.T.), ela retém seu valor até que haja outra tentativa de mover o ponteiro de registros. O padrão é que EOF() opere na área de trabalho correntemente selecionada. Pode-se fazer esta função operar em uma área de trabalho não selecionada desde que esta seja especificada em uma expressão alias (veja o exemplo abaixo).

Exemplos



O exemplo a seguir demonstra o resultado da função EOF() quando se tenta deliberadamente mover o ponteiro de registros para além do último registro:

USE SalesGO BOTTOM? EOF() // Resulta: .F.SKIP? EOF() // Resulta: .T.

Este exemplo utiliza expressões alias para questionar o valor de EOF() em áreas de trabalho não selecionadas:

USE Sales NEWUSE Sales NEWUSE Customer NEW? Sales->(EOF())? Customer->(EOF())

Este exemplo ilustra como EOF() pode ser utilizada como parte de uma condição para operações sequenciais em bancos de dados:

USE Sales INDEX CustNum NEWWHILE !EOF()

nOldCust := Sales->CustNumnTotalAmount := 0WHILE nOldCust = Sales->CustNum .AND. (!EOF())

? Sales->CustNum, Sales->Description, Sales->SaleAmountnTotalAmount += Sales->SaleAmountSKIP

ENDDO? "Quantia total: ", nTotalAmount

ENDDO

ERRORBLOCK()Envia um bloco de código a ser avaliado quando ocorre um erro em tempo de execução

Sintaxe

ERRORBLOCK([<bErrorHandler>]) --> bCurrentErrorHandler

Argumentos

<bErrorHandler> é o bloco de código a ser executado toda vez que ocorrer um erro em tempo de execução. Quando avaliado, o <bErrorHandler> é passado na forma de um objeto erro como um argumento pelo sistema.

Retorno

ERRORBLOCK() retorna o bloco de código corrente que tratará o erro. Caso não tenha sido enviado nenhum bloco de tratamento de erro desde que o programa foi invocado, ERRORBLOCK() retorna o bloco de tratamento de erro padrão.



Descrição

ERRORBLOCK() é uma função de tratamento de erros que define a atuação de um handler de erros sempre que ocorrer um erro em tempo de execução. O manipulador de erros é especificado como um bloco de código da seguinte forma:

{ |<objError>| <lista de expressões>,... }

Onde <objError> é um error object que contém informações sobre o erro. Dentro do bloco de código, podem ser enviadas mensagens ao error object para obter informações sobre o erro. Se o bloco de tratamento de erros retornar verdadeiro (.T.), a operação que falhou é repetida, e se retornar falso (.F.), o processamento recomeça.

O bloco de tratamento de erros pode ser especificado como uma lista de expressões ou como uma chamada a uma função definida por usuário. Uma chamada a uma função definida por usuário é mais útil pois você pode utilizar declarações de controle do Clipper ao invés de expressões. Este é em particular o caso se houver um BEGIN SEQUENCE pendente e você deseja BREAK para a próxima declaração RECOVER.

Como consequência, blocos de tratamento de erro podem ser utilizados em combinação com estruturas de controle BEGIN SEQUENCE...END. Dentro de um bloco de tratamento de erros, você manipula erros comuns, de baixo nível, e de dispositivos que têm um mecanismo de recuperação geral. Se a operação necessita tratamento de erros específicos, defina um BEGIN SEQUENCE e depois BREAK para a declaração RECOVER, retornando o error object para processamento local. Veja o exemplo abaixo.Se não foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer um erro em tempo de execução, o bloco de tratamento ao de erros padrão é avaliado. Este manipulador de erros exibe uma mensagem descritiva na tela, ajusta a função ERRORLEVEL() para 1, e depois sai do programa (QUIT).

Como ERRORBLOCK() retorna o bloco de tratamento ao de erros corrente, é possível especificar um bloco de tratamento de erros para uma operação gravando-se o bloco de manipulação de erros corrente e depois recuperando-o após o final da operação. Além disso, uma importante consequência do fato de os blocos de tratamento de erros serem especificados como blocos de código, é que eles podem ser passados para rotinas e funções definidas por usuário e depois retornadas como valores.

Exemplos

O fragmento de código a seguir ilustra como um bloco de tratamento de erros pode ser enviado e depois chamado quando há um erro dentro de uma construção BEGIN SEQUENCE:

LOCAL bErrorHandler, bLastHandler, objErrbErrorHandler := { |objError| MyErrorHandler(objError) }//bLastHandler := ERRORBLOCK(bErrorHandler) // Salva manipulador corrente//BEGIN SEQUENCE.. <declarações da operação>.RECOVER USING objErrorInfo // Recebe objeto de erro de BREAK.



. <declarações de recuperação>

.ENDERRORBLOCK(bLastHandler) // Restaura manipuladorRETURN

FUNCTION MyErrorHandler( objError )//BREAK objError // Retorna objeto para RECOVERRETURN NIL

FCOUNT()

Retorna a quantidade de campos no arquivo (.dbf) corrente

Sintaxe

FCOUNT() --> nCampos

Retorno

FCOUNT() retorna a quantidade de campos no arquivo de banco de dados aberto na área de trabalho corrente na forma de um valor numérico inteiro. Caso não haja nenhum arquivo de banco de dados aberto, FCOUNT() retorna zero.

Descrição

FCOUNT() é uma função de tratamento de banco de dados. Ela é útil em aplicações que contêm programas independentes de dados os quais podem operar em qualquer arquivo de banco de dados. Nestes incluem-se programas gerais para importar e exportar dados e programas de relatórios. Normalmente, utiliza-se FCOUNT() para estabelecer o limite superior de um laço FOR...NEXT ou DO WHILE que processa um único campo por vez.

O padrão é que a função FCOUNT() opere na área de trabalho correntemente selecionada. Pode-se fazê-la operar numa área de trabalho não selecionada se esta for especificada em uma expressão alias.

Exemplos

A seguir FCOUNT() retorna a quantidade de campos nas áreas detrabalho corrente e não selecionada:

USE Sales NEWUSE Customer NEW? FCOUNT() // Resulta: 5? Sales->(FCOUNT()) // Resulta: 8

Este exemplo usa FCOUNT() para declarar um vetor a ser carregado com informações sobre campos:

LOCAL aFields := ARRAY(FCOUNT())AFIELDS(aFields)



Este exemplo utiliza a função FCOUNT() como o limite superior de um laço FOR na lista de campos da área de trabalho corrente:

LOCAL nFieldUSE Sales NEWFOR nField := 1 TO FCOUNT()

? FIELD(nField)NEXT

FOUND()

Determina se a operação de pesquisa anterior foi bem sucedida

Sintaxe

FOUND() --> lSucesso

Retorno

FOUND() retorna verdadeiro (.T.) se o último comando de pesquisa foi bem sucedido; do contrário, ela retorna falso (.F.).

Descrição

FOUND() é uma função de tratamento de banco de dados utilizada para determinar se uma operação de pesquisa (isto é, FIND, LOCATE, CONTINUE, SEEK, SET RELATION) foi bem sucedida antes que o próximo passo no programa seja executado. Quando qualquer um destes comandos é executado, FOUND() retorna verdadeiro (.T.) caso haja correspondência;do contrário, ele retorna falso (.F.).

Se o comando de pesquisa for LOCATE ou CONTINUE, a correspondência é o próximo registro que atender a abrangência e condição. Caso o comando de pesquisa seja FIND, SEEK ou SET RELATION, a correspondência é a primeira chave no índice controlador que seja igual ao argumento de pesquisa. Se SET SOFTSEEK está ON, o ponteiro de registros é posicionado no primeiro registro cuja chave seja maior ou igual ao argumento de pesquisa. Se o valor de chave for igual ao argumento de pesquisa, FOUND() é verdadeiro (.T.); do contrário, é falso (.F.).

O valor de FOUND() é retido até que seja executado outro comando de movimentação de registros. A não ser que o comando seja outro comando de pesquisa, FOUND() é automaticamente configurado em falso (.F.).

Cada área de trabalho tem um valor FOUND(). Isto significa que se uma área de trabalho tem um relacionamento configurado para uma área de trabalho secundária, questionando-se FOUND() na área secundária fará a função retornar verdadeiro (.T.) caso haja correspondência.

O padrão é que a função FOUND() opere na área de trabalho correntemente selecionada. Pode-se fazê-la operar em uma área de trabalho não selecionada se esta for especificada em uma expressão alias (veja o exemplo abaixo).



Exemplos

O exemplo a seguir ilustra o comportamento da função FOUND() após um comando de movimentação de registros:

USE Sales INDEX Sales? INDEXKEY(0) // Resulta: SALESMANSEEK "1000"? FOUND() // Resulta: .F.SEEK "100"? FOUND() // Resulta: .T.SKIP? FOUND() // Resulta: .F.

Este exemplo demonstra como acessar um valor FOUND() em uma área de trabalho não selecionada através de uma expressão alias:

USE Sales INDEX Sales NEWUSE Customer INDEX Customer NEWSET RELATION TO CustNum INTO Sales//SEEK "Smith"? FOUND(), Sales->(FOUND())

Este fragmento de código processa todos os registros de Customer que têm o valor chave "Smith" usando FOUND() para determinar quando há mudança no valor chave:

USE Customer INDEX Customer NEWSEEK "Smith"WHILE FOUND() . . <declarações> . SKIP LOCATE REST WHILE Name = "Smith"ENDDO

MEMOEDIT()

Exibe ou edita cadeias de caracteres e campos memo.

Sintaxe

MEMOEDIT([<cString>],[<nTopo>], [<nEsquerda>],[<nBase>], [<nDireita>],[<lModoEdição>],[<cFunçãoControle>],[<nTamanhoLinha>],[<nTamanhoTab>],[<nLinhaBufferTexto>],[<nColunaBufferTexto>],



[<nLinhaJanela>],[<nColunaJanela>]) --> cBufferTexto

Argumentos

<cString> é a cadeia de caracteres ou campo memo a ser copiado para o buffer de texto da MEMOEDIT(). Caso não seja especificado, o buffer de texto fica vazio.

<nTopo>, <nEsquerda>, <nBase>, e <nDireita> são as coordenadas superior esquerda e inferior direita da janela. Valores de linha podem variar de zero a MAXROW(), e posições de coluna podem variar de zero a MAXCOL(). Se não forem especificadas, as coordenadas padrão são 0, 0, MAXROW(), e MAXCOL().

<lModoEdição> determina se o buffer de texto pode ser editado ou simplesmente exibido. Especificar verdadeiro (.T.) permite ao usuário fazer alterações no buffer de texto, enquanto que especificar falso (.F.) permite ao usuário somente a leitura do buffer de texto. Caso não seja especificado, o valor padrão é verdadeiro (.T.).

<cFunçãoControle> é o nome de uma função de usuário que é executada quando o usuário pressionar uma tecla não reconhecida pela MEMOEDIT() e quando não houver teclas pendentes no buffer de teclado.<cFunçãoControle> é especificada como um valor caractere sem parênteses ou argumentos. Especificando-se falso (.F.) neste argumento, o <cString> é exibido, e a MEMOEDIT() é terminada. Caso este argumento seja especificado, o comportamento automático da MEMOEDIT() é alterado.

<nTamanhoLinha> determina o tamanho das linhas exibidas na janela da MEMOEDIT(). Caso exista uma linha maior do que <nTamanhoLinha>, ela é transportada para a próxima linha na janela de MEMOEDIT(). Se <nTamanhoLinha> for maior do que o número de colunas na janela de MEMOEDIT(), a janela de edição será deslocada caso o cursor se mova para além do limite da janela. Se <nTamanhoLinha> não for especificado, o tamanho de linha padrão é (<nDireita> - <nEsquerda>).

<nTamanhoTab> determina o tamanho de um caractere de tabulação a ser inserido quando o usuário pressionar Tab. Caso <nTamanhoTab> não seja especificado, são inseridos quatro espaços ao invés de um caractere de tabulação.

<nLinhaBufferTexto> e <nColunaBufferTexto> definem a posição de exibição do cursor dentro do buffer de texto quando é invocada a MEMOEDIT(). <nLinhaBufferTexto> começa com 1 (um) e <nColunaBufferTexto> começa com zero. Se estes argumentos não forem especificados, o cursor é posicionado na linha 1 (um) e coluna zero da janela de MEMOEDIT().

<nLinhaJanela> e <nColunaJanela> definem a posição inicial do cursor dentro da janela da MEMOEDIT(). Posições de linha e coluna começam com zero. Caso estes argumentos não sejam especificados, a posição inicial na janela é linha zero mais a posição de coluna onde o cursor estiver.

Retorno

MEMOEDIT() retorna o buffer de texto caso o usuário termine a edição com Ctrl-W, ou uma cópia de <cString> caso o usuário termine com Esc.

Descrição



MEMOEDIT() é uma função de interface com o usuário e de edição de textos, que pode ser utilizada para editar campos memo e cadeias de caracteres longas. A edição ocorre dentro de uma regiao de janela especificada, posicionada em qualquer lugar na tela. Da mesma forma que outras funções de interface com o usuário (ACHOICE(), DBEDIT()), MEMOEDIT() suporta uma série de modos distintos, e inclui uma função de See also: LASTKEY() MEMOREAD() MEMOTRAN() MEMOWRIT().

usuário para permitir a reconfiguração de teclas e outras atividades relevantes à programação da tarefa de edição de textos.

O buffer de texto: Quando é invocada a MEMOEDIT() e é especificado <cString>, <cString> é copiado para o buffer de texto.O buffer de texto é o que o usuário realmente edita. Caso não seja especificado <cString>, é apresentado ao usuário um buffer de texto vazio para edição.

Quando o usuário sai da MEMOEDIT() pressionando Ctrl-W, o conteúdo do buffer de texto é retornado. Se o usuário sair pressionando Esc, o buffer de texto é descartado e o valor original de <cString> é retornado. De qualquer maneira, o valor retornado pode então ser atribuido a uma variável ou campo memo, ou passado como um argumento para outra função.

Modos de Edição: MEMOEDIT() suporta dois modos de edição, dependendo do valor de <lModoEdição>. Quando <lModoEdição> é verdadeiro (.T.), MEMOEDIT() entra no modo de edição, e ao usuário é permitido alterar o conteúdo do buffer de texto da MEMOEDIT().

Quando <lModoEdição> é falso (.F.), MEMOEDIT() entra no modo visualizar, e ao usuário é permitido navegar pelo buffer de texto, mas sem editar ou inserir textos. Para facilitar a visualização para o usuário, é desabilitado a rolagem, fazendo com que as teclas Cursor para cima e Cursor para baixo naveguem uma linha para cima ou para baixo no buffer de texto dentro da janela de MEMOEDIT().

Entrando e editando textos: Dentro da MEMOEDIT(), o usuário pode entrar e editar textos posicionando o cursor, adicionando, ou eliminando caracteres. Para facilitar a edição de textos, há uma série de teclas de navegação e edição:

Tabela 5-20: Teclas de Navegação e Edição em MEMOEDIT()

Tecla AçãoCursor para cima/Ctrl-E Move para cima uma linhaCursor para baixo/Ctrl-X Move para baixo uma linhaCursor para esquerda/Ctrl-S Move para esquerda um caractereCursor para direita/Ctrl-D Move para direita um caractereCtrl-Cursor para esquerda/Ctrl-A Move para esquerda uma palavraCtrl-Cursor para direita/Ctrl-F Move para direita uma palavraHome Move para o início da linha correnteEnd Move para o final da linha correnteCtrl-Home Move para o início da janela correnteCtrl-End Move para o final da janela correntePgUp Move para janela anteriorPgDn Move para a próxima janelaCtrl-PgUp Move para o início do textoCtrl-PgDn Move para o final do texto



Return Move para o início da próxima linhaDel Elimina caractere onde está o cursorBackspace Elimina caractere à esquerda do cursorTab Insere tab ou espaços Caracteres Imprimíveis Insere caractereCtrl-Y Elimina a linha correnteCtrl-T Elimina a palavra à direitaCtrl-B Reformata parágrafoCtrl-V/Ins Comuta modo de inserçãoCtrl-W Grava e finaliza a ediçãoEsc Aborta edição e retorna o original

A tela de edição: Quando MEMOEDIT() exibe, ela sobreescreve a área especificada da tela e não grava a tela original. Além disso, ela não exibe bordas nem títulos. Para fornecer estas ferramentas, você deve criar uma rotina ou função de usuário que execute estas ações e depois chame a MEMOEDIT(). Veja o exemplo abaixo.

A função de controle: A função de controle é especificada no argumento <cFunçãoControle>, que manipula exceções de tecla e reconfigura teclas especiais. A função de controle é chamada várias vezes pela MEMOEDIT(), muito frequentemente em resposta a teclas que ela não reconhece. Teclas que causam uma exceção são todas as teclas Alt, de função, e teclas de controle disponíveis. Como estas teclas não são processadas pela MEMOEDIT(), elas podem ser reconfiguradas. Algumas destas teclas têm uma ação padrão atribuida às mesmas. Na função de controle, você executa várias ações que dependem do modo corrente da MEMOEDIT() e depois Retorna um valor que diz à MEMOEDIT() o que fazer.

Quando o argumento função de controle é especificado, MEMOEDIT() define duas classes de teclas: não configuráveis e exceções de tecla. Quando é pressionada uma tecla não configurável, MEMOEDIT() a executa; caso contrário é gerada uma exceção de tecla e a função de controle é chamada. Quando não houver mais nenhuma tecla pendente no buffer de teclado a ser processada pela MEMOEDIT(), a função de controle é chamada novamente.

Quando a MEMOEDIT() chama a função de controle, ela automaticamente passa parâmetros indicando o modo da MEMOEDIT(), a linha corrente no buffer de texto, e a coluna corrente no buffer de texto. O modo indica o estado atual da MEMOEDIT(), dependendo da última ação tomada antes da execução da função de controle. São possíveis os seguintes modos:

Tabela 5-21: Modos de MEMOEDIT()

Modo Memoedit.ch Descrição0 ME_IDLE Inativo, todas as teclas foram processadas1 ME_UNKEY Tecla desconhecida,memo inalterado2 ME_UNKEYX Tecla desconhecida, memo alterado3 ME_INT Modo de inicialização

Um valor de modo 3 indica que a MEMOEDIT() está em modo de inicialização. Quando você especifica a <cFunçãoControle>, MEMOEDIT() faz uma chamada à função de controle imediatamente após ser invocada. Neste ponto, você retorna uma solicitação de configuração dos vários modos de formatação de texto da MEMOEDIT():



Transporte, rolagem, ou inserir. MEMOEDIT() chama a função de controle repetidamente, permanencendo no modo de inicialização até que você retorne 0. O buffer de texto é então exibido, e o controle entra no modo de edição configurado por <lModoEdição>. Observe que se o transporte estiver ativo quando MEMOEDIT() mudar do modo de inicialização para o de edição, todo o buffer de texto é formatado com <nTamanhoLinha>. Para evitar esta formatação inicial, desligue o transporte durante a inicialização. Observe também que a ativação ou não de transporte e rolagem não é atribuida a nenhuma tecla, porém isto pode ser feito a partir da função de controle.

Os modos 1 e 2 indicam que a MEMOEDIT() capturou uma tecla não reconhecida ou configurável do buffer de teclado. Teclas configuráveis são processadas retornando-se 0 para que seja executada a ação padrão da MEMOEDIT(). O retorno de um valor diferente executa outra ação de tecla, desta forma redefinindo a tecla. Caso seja uma tecla não reconhecida, você pode definir uma ação para ela retornando um valor que solicita uma ação de tecla ou executa uma ação que você mesmo definiu.

O modo 0 indica que a MEMOEDIT() encontra-se inativa, e nenhuma tecla falta ser processada.Sempre que isto acontecer, a MEMOEDIT() faz uma chamada à função de controle. Neste ponto, você geralmente atualiza exibições de número de linha e coluna.

Os outros dois parâmetros, linha corrente e coluna, indicam a posição corrente do cursor no buffer de texto quando a função de controle é chamada. O parâmetro linha começa com posição 1 (um), e coluna começa com posição zero.

Quando o modo é 1, 2 ou 3, você pode retornar um valor que instrui a MEMOEDIT() qual a próxima ação a ser executada. A tabela a seguir See also: LASTKEY() MEMOREAD() MEMOTRAN() MEMOWRIT() resume os valores de retorno possíveis e suas consequências:

Tabela 5-22: Valores de Retorno da Função de Controle de MEMOEDIT()

Valor Memoedit.ch Ação0 ME_DEFAULT Executa ação padrão1-31 ME_UNKEY Processa ação correspondente ao valor da tecla32 ME_IGNORE Ignora tecla33 ME_DATA Trata tecla como dado34 ME_TOGGLEWRAP Comuta modo de transporte35 ME_TOGGLESCROLL Comuta modo de rolagem100 ME_WORDRIGHT Próxima palavra101 ME_BOTTOMRIGHT Base da tela

Arquivos header: Para que os valores de modo e solicitação sejam mais fáceis de ser lembrados e utilizados, é fornecido o arquivo Memoedit.ch no \CLIPPER5\INCLUDE. Além disso, Inkey.ch está localizado no mesmo diretório, e contém constantes para todos os valores INKEY().

Notas

Configurando teclas: Se a <cFunçoUsuário> for especificada, as teclas na tabela abaixo sãoconfiguráveis. Se a tecla for reconfigurável, retornar 0 executa a ação padrão da MEMOEDIT(). retornar um valor diferente, porém, executa outra ação de tecla, desta forma redefinindo a mesma. Caso a tecla não seja do tipo configurável reconhecido pela MEMOEDIT(), você pode definir uma ação para ela também retornando um valor que pede uma ação de tecla da tabela abaixo.



Tabela 5-23: Teclas Configuráveis em MEMOEDIT()

Tecla Ação PadrãoCtrl-Y Elimina a linha correnteCtrl-T Elimina a palavra à direitaCtrl-B Reformata parágrafoCtrl-V/Ins Comuta modo de inserçãoCtrl-W Finaliza edição e gravaEsc Aborta edição e retorna original

Transporte: Transporte é um modo de formatação que você pode alternar se retornar 34 da função de usuário. Quando está on (o padrão), MEMOEDIT() insere um soft carriage return/line feed (retorno automático) ao final da palavra mais próxima da borda da janela ou tamanho de linha, valendo o que ocorrer primeiro. Quando transporte está desligado, MEMOEDIT() rola o buffer de texto para além dos limites da janela até que o cursor atinja o final da linha. Neste ponto, o usuário deve pressionar Return (inserindo um hard carriage return/line feed) para avançar para a próxima linha.

Alterando parágrafos: Pressionar Ctrl-B ou retornar 2 de uma função de usuário causa a reformatação do buffer de texto até que um hard carriage return (final de parágrafo) ou o final do buffer de texto seja alcançado. Isto acontece sem importar se trabsporte está ligado ou desligado.

Carriage returns automáticos: Carriage returns automáticos podem interferir na exibição de comandos de console tais como ? e REPORT FORM, ou o processamento com outro processador de textos. Use HARDCR(), MEMOTRAN(), ou STRTRAN() para substituir estes caracteres, conforme sua necessidade.

Editando arquivos texto: MEMOEDIT() pode ser utilizada para editar arquivos texto se o arquivo texto puder ser lido para uma variável caractere Clipper. Isto pode ser feito com a função MEMOREAD(). Após a edição do conteúdo do arquivo texto contido na variável caractere, ele pode ser escrita no arquivo novamente com MEMOWRIT().

Exemplos

O exemplo a seguir permite ao usuário visualizar um campo memo, sem deixar que sejam feitas alterações no buffer de texto:

USE Customer NEWSET CURSOR OFFMEMOEDIT(CustNotes, 5, 10, 20, 69, .F.)SET CURSOR ON

Este exemplo ilustra como permitir ao usuário editar um campo memo, sendo que depois estas alterações serão atribuidas ao campo memo:

USE Customer NEWREPLACE CustNotes WITH MEMOEDIT(CustNotes, 5, 10, 20, 69)

Este exemplo demonstra como criar uma cadeia de caracteres usando MEMOEDIT():

LOCAL cNotescNotes = MEMOEDIT()



Este exemplo demonstra uma função definida pelo usuário que edita uma cadeia de caracteres em uma janela com moldura exibida com um título:

FUNCTION MemoEdit( cString, cTítulo, nTop, nLeft, nBottom, nRight )LOCAL cTela := SAVESCREEN(nTop, nLeft, nBottom, nRight)@ nTop - 1, nLeft - 2 CLEAR TO nBottom + 1, nRight + 2@ nTop - 1, nLeft - 2 TO nBottom + 1, nRight + 2@ nTop - 1, nLeft SAY "[" + cTitle + "]"cString = MEMOEDIT(cString, nTop, nLeft, nBottom, nRight)RESTSCREEN(nTop, nLeft, nBottom, nRight, cTela)RETURN (cString)

O exemplo a seguir lê o conteúdo de um arquivo texto para umavariável caractere, edita, e depois escreve o novo conteúdo no disco:

LOCAL cString := MEMOREAD("Text.txt")cString := MEMOEDIT(cString)IF !MEMOWRIT("Text.txt", cString)

? "Erro de gravacao"BREAK

ENDIFRETURN

MEMOREAD()

Retorna o conteúdo de um arquivo em disco na forma de uma cadeia de caracteres.

Sintaxe

MEMOREAD(<cArq>) --> cString

Argumentos

<cArq> é o nome do arquivo a ser lido do disco. Ele deve incluir uma extensão no caso de haver uma, e pode opcionalmente incluir path.

Retorno

MEMOREAD() retorna o conteúdo de um arquivo texto na forma de uma cadeia de caracteres. O arquivo pode ter um tamanho de no máximo 65.535 caracteres (64K)--ou seja, o tamanho máximo de uma cadeia de caracteres. Se <cArq> não puder ser encontrado, MEMOREAD() retorna uma cadeia de caracteres nula ("").

Descrição

MEMOREAD() é uma função de tratamento de memos que lê um arquivo em disco para a memória, onde ele pode ser manipulado como uma cadeia de caracteres ou atribuido a um campo memo. MEMOREAD() é utilizado juntamento com MEMOEDIT() e MEMOWRIT() para editar um arquivo



de disco importado e depois escrevê-lo novamente no disco. MEMOREAD() procura o <cArq> a partir do diretório DOS corrente. Se o arquivo não for encontrado, MEMOREAD() pesquisa o path DOS . MEMOREAD() não utiliza as configurações DEFAULT ou PATH do Clipper para procurar o <cArq>.

Em ambientes de rede, MEMOREAD() tenta abrir o arquivo especificado de modo compartilhado e somente para leitura. Se o arquivo for aberto de modo exclusivo através de outro processo, MEMOREAD() retorna uma cadeia de caracteres nula ("").

Exemplos

O exemplo a seguir utiliza MEMOREAD() para atribuir o conteúdo de um arquivo texto ao campo memo Notas e a uma variável caractere:

REPLACE Notas WITH MEMOREAD("Temp.txt")cString = MEMOREAD("Temp.txt")

Este exemplo define uma função que edita um arquivo em disco:

FUNCTION Editor( cArq )LOCAL cStringIF (cString := MEMOREAD(cArq)) == ""

? "Erro de leitura em " + cArqRETURN .F.

ELSEMEMOWRIT(cArq, MEMOEDIT(cString))RETURN .T.

ENDIF

RECNO()

Retorna o número do registro corrente de uma área de trabalho

Sintaxe

RECNO() --> nRegistro

Retorno

RECNO() retorna o número do registro corrente na forma de um valor numérico inteiro. Se a área de trabalho contém um arquivo de banco de dados com zero registros, RECNO() retorna um, BOF() e EOF() retornam verdadeiro (.T.), e LASTREC() retorna zero.

Se o ponteiro de registros for movido para além do último registro, RECNO() retorna LASTREC() + 1 e EOF() retorna verdadeiro (.T.). Caso seja feita uma tentativa para mover o ponteiro além do primeiro registro, RECNO() retorna o número do primeiro registro lógico no arquivo de banco de dados, e BOF() retorna verdadeiro (.T.).

Descrição



RECNO() é uma função de tratamento de banco de dados que retorna o número do registro corrente em uma área de trabalho. No esquema de arquivos de bancos de dados do Clipper, cada arquivo de banco de dados é ordenado fisicamente pelo número do registro. Cada área de trabalho, por sua vez, mantém um ponteiro para o registro corrente em seu arquivo de banco de dados aberto. Aquele número de registro é informado pela função RECNO(). A ferramenta de numeração de registros permite acesso direto a um registro sem pesquisar sequencialmente o arquivo de banco de dados para atingir a posição do registro especificado.

RECNO() é normalmente utilizada para generalizar rotinas que processam os registros através do número dos mesmos. Isto inclui SET RELATION...TO RECNO(), que faz a likagem de arquivos de banco de dados por número de registro. GO RECNO() também é usada para fazer um refresh dos dados de registro correntes do disco.

O padrão é que RECNO() opere na área de trabalho correntemente selecionada. Pode-se fazê-la operar em uma área de trabalho não selecionada se esta for especificada em uma expressão alias (veja oexemplo abaixo).

Exemplos

O exemplo a seguir questiona RECNO() após mover deliberadamente o ponteiro de registros:

USE Customers NEWGO 3? RECNO() // Resulta: 3GO TOP? RECNO() // Resulta: 1nRecord := 3GO nRecord? RECNO() // Resulta: 3GO BOTTOMSKIP? RECNO(), LASTREC() // Resulta: 11 10

Este exemplo utiliza expressões alias para questionar o valor de RECNO() em áreas de trabalho não selecionadas:

USE Sales NEWUSE Customer NEW//? Sales->(RECNO())? Customer->(RECNO())

Funções especiais

INKEY()

Extrai um caractere do buffer de teclado



Sintaxe

INKEY([<nSegundos>]) --> nCodInkey

Argumentos

<nSegundos> especifica a quantidade de segundos que INKEY() deve esperar por uma tecla. O valor pode ser especificado em incrementos do tamanho de até um décimo de segundo. Se for especificado zero, o programa pára até que uma tecla seja pressionada. Caso <nSegundos> seja omitido, INKEY() não espera por uma tecla.

Retorno

INKEY() retorna um valor numérico inteiro de -39 até 386, que identifica a tecla extraída do buffer de teclado. Caso o buffer de teclado esteja vazio, INKEY() retorna zero. INKEY() retorna valores para todas as combinações de caracteres ASCII, teclas de função, Alt-tecla de função, Ctrl-tecla de função, Alt-letra, e Ctrl-letra.

Descrição

INKEY() é uma função de tratamento de teclado que extrai a próxima tecla pendente no buffer de teclado e retorna um valor que representa esta tecla. O valor também é gravado internamente e pode ser acessado através da função LASTKEY(). Caso o argumento <nSegundos> seja especificado e não haja teclas pendentes no buffer, acontece uma pausa na execução do programa até que apareça uma tecla no buffer de teclado, ou então até os <nSegundos> especificados tenham passado. O período de tempo que INKEY() espera baseia-se no relógio do sistema operacional e não é relacionado à velocidade do microprocessador. Se <nSegundos> for zero, há uma pausa na execução do programa até que uma tecla seja colocada no buffer. Observe que INKEY() não é um estado de espera e, portanto, as teclas configuradas por SET KEY não são ativas.

INKEY() é semelhante à função NEXTKEY(). De forma diferente de INKEY(), porém, NEXTKEY() lê mas não extrai a tecla do buffer de teclado. Esta função é útil quando você precisa verificar se uma tecla foi pressionada sem que a mesma seja processada.

INKEY() é a função básica do sistema Clipper para capturar teclas do buffer de teclado. É utilizada para receber o teclado ou parar a execução do programa até que o usuário pressione uma tecla. Por exemplo, você pode utilizar INKEY() para terminar comandos com abrangência de registros tais como LIST, LABEL FORM, e REPORT FORM se ela for incluída em uma condição WHILE. Consulte o exemplo abaixo.

Para uma lista completa de códigos INKEY() e constantes Inkey.ch.

Exemplos

O exemplo a seguir captura qualquer tecla do teclado e depois exibe o valor caractere da tecla seguido do valor INKEY():

#include "Inkey.ch"//LOCAL nInkeyCode := 0DO WHILE LASTKEY() != K_ESC



? "Aperte qualquer tecla: "nInkeyCode := INKEY(0)?? "Caractere:", CHR(nInkeyCode),;"Codigo INKEY():", LTRIM(STR(nInkeyCode))

ENDDORETURN

Este exemplo utiliza INKEY() para receber uma tecla de interrupção do usuário durante um REPORT FORM. Se o usuário pressionar Esc durante o processo de impressão, o comando REPORT FORM termina:

#include "Inkey.ch"//USE Sales INDEX Salesman NEWREPORT FORM Monthly FOR MONTH(SalesDate) == MONTH(DATE());WHILE INKEY() != K_ESC

TONE()

Aciona o alto-falante por uma duração e frequência especificadas.

Sintaxe

TONE(<nFrequência>, <nDuração>) --> NIL

Argumentos

<nFrequência> é um valor numérico positivo que indica a frequência do som a ser produzido.

<nDuração> é um valor numérico positivo que indica a duração do som, medida em incrementos de 1/18 de segundo; um segundo, portanto, é 18.

Para os dois argumentos, valores não inteiros são truncados--e não arredondados--para sua porção inteira.

Retorno

TONE() sempre retorna NIL.

Descrição

TONE() é uma função de tratamento de sons utilizada para indicar ao usuário os vários estados do programa. Por estados entende-se estados de erro, condições de limite, ou o final de um processo longo. Por exemplo, um estado de erro pode acionar um som de erro antes de alertar o usuário através de uma mensagem ou diálogo interativo. Um condição de limite pode indicar que o usuário está tentando levar o cursor para além dos limites superior ou inferior de uma coluna em um objeto TBrowse. Um processo de batch também pode indicar que chegou ao seu final através de um som para alertar o usuário, caso este tenha se afastado da tela.



TONE() funciona acionando o alto-falante na frequência especificada, e pela duração especificada. A duração é medida em incrementos de 1/18 de segundo. A frequência é medida em hertz (ciclos por segundo).

Frequências abaixo de 20 são inaudíveis. A tabela abaixo demonstra as frequências de notas musicais padrão.

Nota

TONE() funciona apenas em IBM-PC e computadores 100% compatíveis.

Tabela 5-33: Notas Musicais

Nota Frequência Nota FrequênciaC 130.80 mid C 261.70C# 138.60 C# 277.20D 146.80 D 293.70D# 155.60 D# 311.10E 164.80 E 329.60F 174.60 F 349.20F# 185.00 F# 370.00G 196.00 G 392.00G# 207.70 G# 415.30A 220.00 A 440.00A# 233.10 A# 466.20B2 46.90 B 493.90C 523.30 - -

Exemplos

O exemplo a seguir é uma função de bip, utilizada para indicar que uma operação de batch terminou:

FUNCTION DoneBeepTONE(300, 1)TONE(100, 1)TONE(300, 1)TONE(100, 1)RETURN NIL

Este exemplo é uma sequência de sons usada para indicar teclagens inválidas ou condições de limite:

FUNCTION ErrorBeepTONE(100, 3)RETURN NIL


Documents

Apostila de Clipper