Introduo

Existem muitas opes no mundo altamente competitivo dos produtos de bancos de dados para PCs. Com o lanamento da verso 5.3, o primeiro upgrade do Clipper num espao de mais de trs anos, a Computer Associates aperfeioou bastante o seu pacote de desenvolvimento de banco de dados em termos de desempenho, capacidade e facilidade de uso. E, com a verso 5.3, melhorou tanto a estabilidade quanto a funcionalidade do Clipper. Mas as perguntas que logo surgem so: Por que se fala tanto no Clipper? O que ele faz? O Que o Clipper?

Em linhas gerais, o Clipper uma linguagem de programao de banco de dados completa, com todas as ferramentas necessrias para desenvolver aplicaes de banco de dados independentes. Como o Clipper originariamente baseou-se na srie dBASE da Ashton-Tate, muitos programas do dBASE so compatveis com o Clipper, com poucas modificaes. Voc pode pensar no Clipper como um superconjunto da "linguagem" dBASE.

O Clipper to fcil que at mesmo um programador inexperiente pode us-lo para desenvolver aplicaes rpidas e poderosas. Quem estiver familiarizado com o dBASE III estar apto a criar aplicaes do Clipper em apenas um dia. Os programadores com experincia em outras linguagens o acharo incrivelmente atual (em muitos aspectos ele se parece bastante com as atuais implementaes da linguagem C) e o ambiente ideal para a criao rpida de aplicaes de banco de dados. Caso precise de interfaces planejadas cuidadosamente, ficar satisfeito com o utilitrio de criao de banco de dados (DBU) e com o depurador de cdigos-fonte (CLD) do Clipper. Compilando Programas do Clipper

O compilador do Clipper converte arquivos-fonte (.PRG) que contm um nmero qualquer de procedures e funes escritas pelo usurio em arquivos-objeto (.OBJ). Esses ltimos podem ento ser linkados com outros arquivos-objeto do Clipper para formar um arquivo executvel (.EXE). Os arquivos-fonte contendo cdigos a serem compilados pelo Clipper preciso de extenses .PRG. Alguns exemplos de nomes de arquivos so MENU.PRG ou REPORT.PRG. Atribuir nomes aos arquivos-fonte com extenses consistentes tornar fcil encontr-los no disco rgido, e as ferramentas do Clipper como o PE e o compilador fornecero

automaticamente a extenso .PRG nos arquivos de entrada, evitando assim o problema de ter que digitar extenses cada vez que se usar um desses programas. Chamando o Compilador do Clipper

Para compilar um arquivo fonte do Clipper com a extenso .PRG, basta indicar no prompt do DOS. CLIPPER <nome do arquivo>

O CLIPPER.EXE assumir .PRG. Ento, para compilar o arquivo SAMPLE.PRG, voc digitaria: Clipper Sample Criando Arquivos Executveis com o EXOSPACE

Agora que j discutimos como compilar arquivos, apenas mais uma ferramenta do Clipper necessria para criar aplicaes executveis 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 jarges. Chamando o EXOSPACE

O EXOSPACE inicializado digitando-se seu nome no prompt do DOS. No modo Linha de Comandos, todas as informaes de que o EXOSPACE precisa para criar um arquivo executvel tambm so digitadas nesse prompt. Os nicos parmetros obrigatrios na linha de comandos so o parmetro 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 vrgulas. No caso de arquivos listados sem extenses, o programa assume .OBJ. A menos que um nome de arquivo de sada seja especificado o arquivo executvel (.EXE) criado pelo EXOSPACE usar o nome do primeiro arquivo da <lista de arquivos-objeto>. Alm do parmetro FILE, existem bem poucas opes 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 aplicao simples do Clipper: aproximadamente 500 Kb

O tamanho aparentemente excessivo desta aplicao deve-se ao espao extra requerido para os overlays dinmicos, o gerenciamento de memria virtual e as funes de biblioteca do Clipper. No caso de aplicaes grandes, quanto mais memria ( incluindo a estendida e expandida ) estiver disponvel, mais rapidamente sero executadas. Como o EXOSPACE encontra Arquivos da Biblioteca

As procedures e funes do Clipper esto contidas num conjunto de bibliotecas que foram carregadas no diretrio \CLIP53\LIB do disco rgido durante a instalao. Quando chegar a hora do link, o EXOSPACE tentar encontrar essas bibliotecas para que possa fazer o link dos comandos e das funes da biblioteca necessrios sua aplicao. Ele sabe onde procurar as bibliotecas por causa do SET LIB=C:\CLIP53\LIB (ou equivalente da estrutura do seu diretrio) que voc incluiu no comando AUTOEXEC.BAT. Se o EXOSPACE lhe pediu a localizao do diretrio que contm 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 manipulao de variveis CLEAR MEMORY

Libera todas variveis pblicas e privadas Sintaxe

CLEAR MEMORY Descrio

CLEAR MEMORY elimina as variveis pblicas e privadas da tabela de variveis. Ele opera contrastando com RELEASE ALL, o qual no libera realmente as variveis pblicas e privadas, mas coloca NIL em todas que tenham por abrangncia a rotina corrente.

CLEAR MEMORY a nica forma de excluir todas as variveis pblicas da memria corrente. Variveis locais e estticas no so afetadas por CLEAR MEMORY. DECLARE*

Cria e inicializa variveis e vetores PRIVATE Sintaxe

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

<identificador> o nome da varivel ou vetor a ser criado PRIVATE. Se o <identificador> seguido por colchtes ([ ]), ele criado como um vetor. Se o <identificador> um vetor, a sintaxe para especificar o nmero de elementos para cada dimenso pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>][<nElementos2>]... O mximo de elementos por dimenso

 4096.

<inicializador> a atribuio opcional de um valor a nova varivel. Um <inicializador> para uma varivel PRIVATE consiste do operador in-line (:=) seguido de qualquer expresso Clipper, incluindo um vetor. Se nenhum <inicializador> implcito for especificado, a varivel ter o valor de NIL. Em caso de vetor, cada elemento NIL.

Uma lista de variveis ou vetores pode ser criada e opcionalmente inicializada com uma declarao DECLARE se cada definio for separada por uma vrgula. Descrio

DECLARE uma declarao de compatibilidade que exatamente igual a PRIVATE. Seu uso no recomendado. PRIVATE deve ser usado em seu lugar. Veja PRIVATE para maiores detalhes. LOCAL

Declara e inicializa variveis e vetores local Sintaxe

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

<identificador> o nome de uma varivel ou vetor a ser declarado LOCAL. Se o <identificador> seguido de colchtes ([ ]), ele criado como vetor. Se o <identificador> um vetor, a sintaxe para especificar o nmero de elementos para cada dimenso pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>][<nElementos2>]... O mximo de elementos por dimenso 4096. O nmero de dimenses limitado somente pela memria disponvel.

<inicializador> a atribuio opcional de um valor para uma nova varivel local. Identificadores vetor, entretanto, no podem receber valores com um

<inicializador>. Um <inicializador> para uma varivel local consiste do operador in-line (:=) seguido de qualquer expresso vlida em Clipper incluindo um vetor. Se no for fornecido explicitamente um <inicializador>, a varivel ter o valor NIL. No caso de um vetor, cada um dos elementos ser NIL. Nota

O operador macro (&) no pode ser usado numa declarao de varivel local. Descrio

LOCAL uma declarao de uma ou mais variveis ou vetores para a rotina corrente e deve ocorrer antes de qualquer instruo executvel incluindo PRIVATE, PUBLIC, e PARAMETERS. Declaraes de variveis locais ocultam todas as variveis private e as variveis public com o <inicializador> a atribuio opcional de um valor para uma nova varivel local. Identificadores vetor, entretanto, no podem receber valores com um <inicializador>. Um <inicializador> para uma varivel local consiste do operador in-line (:=) seguido de qualquer expresso vlida em Clipper incluindo um vetor. Se no for fornecido explicitamente um <inicializador>, a varivel ter o valor NIL. No caso de um vetor, cada um dos elementos ser NIL. Nota

O operador macro (&) no pode ser usado numa declarao de varivel local. Descrio

LOCAL uma declarao de uma ou mais variveis ou vetores para a rotina corrente e deve ocorrer antes de qualquer instruo executvel incluindo PRIVATE, PUBLIC, e PARAMETERS. Declaraes de variveis locais ocultam todas as variveis private e as variveis public com o mesmo nome. Uma declarao LOCAL, entretanto, que declare um nome de varivel que j esteja declarado causa um erro fatal de compilador e no ser gerado um arquivo (.obj). Este erro pode ocorrer como resultado de duas declaraes para a mesma varivel na mesma rotina, ou como resultado de declarar uma varivel que possua abrangncia para todo o arquivo (.prg). Declaraes incluem FIELD, MEMVAR, STATIC.

Variveis locais so visveis somente dentro da rotina corrente, e de forma diferente de variveis private, no so visveis para as rotinas invocadas a partir da rotina corrente. Variveis locais so automaticamente criadas cada vez que a rotina onde elas estao executada. Elas continuam a existir e retm 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 variveis locais.

O valor inicial para variveis locais ou elementos de vetor no especificamente inicializados NIL, seja na lista de inicializador ou por atribuio. A expresso inicializadora pode ser qualquer expresso vlida Clipper, incluindo chamadas de funo. Note que uma declarao de vetor no pode ter um inicializador.

O nmero mximo de variveis em um programa limitado apenas pela memria disponvel. Vetores, entretanto, quando atribudos para uma varivel local so ainda limitados a 4096 elementos por dimenso. Notas

Inspecionando variveis locais dentro do Debugger: Para acessar nomes de variveis locais dentro do Clipper Debugger, voc primeiro deve compilar o programa com a opo /B para que a informao sobre locais seja inclusa no arquivo objeto.

Parmetros locais: Uma lista de parmetros locais pode ser declarada especificando a lista entre parnteses seguindo <idFuno> desta forma:

FUNCTION <idFuno>(<idLista Param>)

Declarar parmetros locais supera a criao de parmetros privados com a declarao PARAMETERS.

Macro expresses: Variveis locais no podem ser referenciadas dentro de macro variveis ou expresses. Se uma varivel referenciada dentro de uma macro varivel, uma varivel public ou private com o mesmo nome ser referenciada. Se tal varivel no existir, um erro em tempo de execuo ser

gerado.

Arquivos de memria: Variveis locais no podem ser gravadas ou recuperadas de arquivos (.mem).

Tipo de uma varivel local: Desde que TYPE() usa o operador macro (&) para avaliar seu argumento, ele no pode ser usado para determinar o tipo de varivel local ou esttica ou uma expresso contendo uma referncia a uma varivel local ou esttica. Para permitir isso, use VALTYPE().

Exemplos

O exemplo a seguir declara dois vetores locais e duas variveis locais:

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

Este exemplo declara duas variveis 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 variveis de memria e vetores private. Sintaxe

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

Argumentos

<identificador> o nome da varivel ou vetor private a ser criado. Se <identificador> seguido de colchtes ([ ]), um vetor criado e atribudo a <identificador>. Quando o <identificador> indica um vetor, a sintaxe para especificar o nmero de elementos em cada dimenso pode ser vetor[<nElementos>, <nElementos2>,...] ou vetor[<nElementos>] [<nElementos2>]... O nmero mximo de elementos por dimenso 4096. O nmero mximo de dimenses limitado pela memria disponvel.

<inicializador> a atribuio opcional de um valor para a nova varivel private. Para um vetor no se pode dar valores usando

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

Uma lista de variveis e vetores pode ser criada e opcionalmente inicializada com uma nica declarao PRIVATE se cada definio for separada por vrgula. Descrio

A declarao PRIVATE cria variveis visveis dentro da rotina corrente e aquelas que forem por esta invocadas. A classe de varivel dita como tendo abrangncia dinmica. Variveis private existem durante a durao da rotina ativa ou at que explcitamente liberadas com CLEAR ALL, CLEAR MEMORY, ou RELEASE. Quando uma varivel ou vetor private criado, variveis e vetores public ou private existentes de mesmo nome so ocultos at que a rotina corrente se encerre.

Tentativas de especificar uma varivel private que conflite com declaraes FIELD, LOCAL, ou STATIC prvias de mesmo nome iro resultar num erro fatal de compilador. Isto ocorre no importando as abrangncia da declarao.

Declaraes PRIVATE so executveis e portanto devem ser especificadas dentro do corpo da rotina e devem seguir todas as declaraes de variveis como FIELD, LOCAL, MEMVAR, e STATIC.

Adicionalmente a declarao PRIVATE, variveis PRIVATE podem ser criadas de duas maneiras:

Atribuio a uma varivel que no exista ou no seja visvel ir criar uma varivel private

Parmetros recebidos com a declarao PARAMETERS so criados como variveis private com a mesma vida til e visibilidade

O nmero mximo de variveis e vetores private que podem existir simultneamente num programa de 2048. Notas

Compatibilidade: As clusulas ALL, LIKE, e EXCEPT da declarao PRIVATE suportadas por outros dialetos dBASE no o so em Clipper.

Exemplos

O exemplo a seguir cria dois vetores private e outras tres variveis tambm private:

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

Este exemplo cria um vetor multi dimensional private usando as convenes de endereamento de cada elemento:

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

Este exemplo demonstra vrias declaraes PRIVATE para declarar e inicializar vetores e variveis:

PRIVATE aArray := { 1, 2, 3, 4 }, aArray2 := ARRAY(12, 24)

PRIVATE cChar := SPACE(10), cColor := SETCOLOR() PUBLIC

Cria e inicializa variveis e vetores pblicos. Sintaxe

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

<identificador> o nome da varivel ou vetor a ser criado. Se <identificador> seguido de colchetes ([ ]), ele criado como vetor.

Se <identificador> um vetor, a sintaxe para especificar o nmero de elementos em cada dimenso pode ser vetor [<nElementos>, <nElementos2>, ...]ou vetor[<nElementos>][<nElementos2>]... O nmero mximo de elementos por dimenso 4096. O nmero mximo de dimenses por vetor limitado pela memria disponvel.

<inicializador> a atribuio opcional de um valor para uma nova varivel pblica. Identificadores de vetor, no podem ser inicializados com <inicializador>. Um <inicializador> para uma varivel pblica contitui-se do operador in-line (:=) seguido de qualquer expresso Clipper incluindo um vetor. Se nenhum <inicializador> for especificado, o valor inicial para estas variveis ser falso (.F.). Esta uma exceo j que todas as variveis no inicializadas

assumem valor NIL. Contudo, para o caso de vetores, o valor de cada elemento no inicializado continua sendo NIL.

Uma lista de variveis e vetores pode ser criada e opcionalmente inicializada com uma declarao PUBLIC se cada definio for separada por uma vrgula. Descrio

A declarao PUBLIC cria variveis e vetores visveis para todas as rotinas no programa. Variveis public existem durante toda a durao do programa ou at que sejam explicitamente liberadas com CLEAR ALL, CLEAR MEMORY, ou RELEASE. Declarar nomes de variveis private, local ou static com o mesmo nome de uma public, temporariamente esconde estas public at que as outras sejam liberadas ou no estejam mais visveis.

Uma tentativa de criar uma varivel public com o mesmo nome de uma private visvel e existente simplesmente ignorado (veja Notas abaixo para uma excesso).

Tentativas de especificar uma varivel PUBLIC que conflite com uma declarao anterior FIELD, LOCAL, ou STATIC com o mesmo nome, ir causar um erro fatal de compilador. Isto sempre verdade no importando a abrangncia da declarao.

Declaraes PUBLIC so executveis e portanto devem ser especificadas no corpo da rotina. Elas devem tambm seguir as declaraes em tempo de compilador, ou seja: FIELD, LOCAL, MEMVAR, e STATIC.

O mximo nmero de variveis public e private que podem existir simultaneamente de 2048. Notas

PUBLIC Clipper: Para incluir extenses Clipper num programa e ainda permitir que o mesmo seja executado debaixo de dBASE III PLUS, uma varivel public

especial, Clipper, inicializada como verdadeira (.T.) quando criada PUBLIC.

Vetores public e conflitos de nome com variveis private: A declarao PUBLIC x[10], no ir criar um vetor public x se j existir uma varivel public ou private x. Ela ir, entretanto, destruir o contedo de x existente, trocando-o por uma referncia a um vetor de 10 elementos.

Exemplos

Este exemplo cria dois vetores e uma varivel PUBLIC:

PUBLIC aArray1[10, 10], var2

PUBLIC aArray2[20][10]

Aqui criamos vrias variveis e as inicializamos:

PUBLIC cString := SPACE(10), cColor := SETCOLOR()

PUBLIC aArray := {1, 2, 3}, aArray2 := ARRAY(12, 24) RELEASE

Libera variveis de memria dos tipos pblica e privada Sintaxe

RELEASE <idLista Varmem>

RELEASE ALL [LIKE | EXCEPT <esqueleto>]

Argumentos

<idLista Varmem> uma lista de variveis de memria ou vetores do tipo pblica ou privada a serem liberados.

ALL [LIKE|EXCEPT <esqueleto>] define o conjunto de variveis de memria do tipo privada visveis a serem atribudas ou serem excludas da atribuio de um NIL. <esqueleto> a mscara do tipo coringa que especifica um grupo de variveis de memria a serem eliminadas. Os caracteres do tipo coringa aceitos so "*" e "?." Descrio

O comando RELEASE executa uma de duas aes, dependendo da forma do comando. Se RELEASE especificado com <idLista Varmem>, as variveis de memria dos tipos pblica e privada e/ou vetores especificados so liberados da memria. No caso de variveis escondidas previamente (variveis dos tipos pblica e privada definidas em rotinas de nvel mais elevado) tornam-se acessveis ao trmino da rotina na qual a varivel foi inicialmente criada.

Caso RELEASE seja especificado com qualquer forma da clusula ALL, s variveis de memria do tipo privada criadas no nvel da rotina corrente atribudo um NIL, e elas no so eliminadas at que a rotina corrente termine. Variveis do tipo pblica no so afetadas por esta forma do comando RELEASE. Para eliminar o contedo deste tipo de variveis, voc deve usar o comando RELEASE explicitamente ou usar CLEAR MEMORY.

Variveis dos tipos local ou esttica no so afetadas pelo comando RELEASE. As do primeiro tipo so liberadas automaticamente quando a rotina na qual elas foram declaradas termina. As do ltimo tipo no podem ser liberadas, pois a existncia das mesmas extende-se at o final do programa. Comandos para apresentao 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> so 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. Descrio

@...BOX desenha uma caixa na tela usando bordas configurveis e caractere de preenchimento. @...BOX desenha a caixa usando <cStringCaixa>a partir do canto superior esquerdo, continuando no sentido horrio e preenchendo a regiao de tela com o nono caractere.

Se o nono caractere no for especificado, a regiao de tela dentro da caixa no preenchida. Textos e cores pr-existentes no so alterados.

Aps @...BOX ter sido executado, o cursor colocado no canto superior esquerdo em <nLinTopo> + 1 e <nColTopo> + 1. ROW() e COL() tm seus valores atualizados para refletir a nova posio 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 espaos:

#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 espaos

@ 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> so as coordenadas de linha e coluna para exibir o item de menu. Valores de linha esto 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. Descrio

@...PROMPT a poro 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 configurao 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 padro. Quando MENU TO ativado, o item corrente iluminado utilizando a cor destaque.

Aps cada comando @...PROMPT, o cursor posicionado uma coluna direita do item no qual voc est. ROW() e COL() so atualizados de modo a refletir a posio do cursor. Isto lhe permite utilizar ROW() e COL() de modo a especificar posies 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 prxima linha. Quando o usurio apertar Return, a posio do item de menu atribuda a nChoice:

LOCAL nChoice := 1

CLS ; SET WRAP ON

SET 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> so as coordenadas de linha e coluna da sada. 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 expresso de qualquer tipo--inclusive um campo memo--ao DEVICE corrente.

PICTURE <cSayPicture> define a mscara para a sada de exp. O Clipper fornece dois mecanismos de controle de formatao: funes e templates. Funes aplicam-se ao SAY inteiro, enquanto que templates mascaram caracteres posio por posio. Descrio

@...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 sada usando a clusula PICTURE. @...SAY usado para criar telas de entrada de dados ou relatrios que podem ser enviados para a tela ou impressora.

Quando um @...SAY executado, a sada 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 no ecoado em tela quando est sendo enviado para a impressora e SET CONSOLE no tem efeito na sada de @...SAY em tela.

Se o DEVICE corrente SCREEN (o padro do sistema), @...SAY exibe a sada em tela deixando o cursor uma coluna direita do ltimo caractere mostrado. ROW() e COL() so atualizados. Exibio que saia fora da tela definida por MAXROW() e MAXCOL() faz com que o cursor seja posicionado fora da tela visvel. Todas as sadas de @...SAY so exibidas na cor padro.

Se o dispositivo corrente (DEVICE) for impressora (PRINTER), a sada direcionada para esta em <nLin> adicionando ao valor de SET MARGIN e nCol>. A cabea de impresso sofre avano para uma coluna direita do ltimo caractere impresso. PROW() e PCOL() so atualizados conforme esta posio. Comandos @...SAY para a impressora comportam-se de uma forma levemente diferente que na tela quando a sada endereada para a impressora numa linha e coluna menor que a corente em PROW() e PCOL().

Caso <nLin> seja menor que PROW(), um EJECT automtico (CHR(12)) enviado impressora seguido pelo nmero de caracteres line-feed (CHR(10)) necessrios para posicionar a cabea de impresso em <nLin>.

Caso <nCol> inclua o valor SET MARGIN menor que PCOL(), um caractere carriage return (CHR(13)) e o nmero de espaos necessrios para posicionar <exp> em <nCol> so enviados impressora.

Para evitar este comportamento de forma a enviar cdigos de controle para a impressora, ou por qualquer outra razo, voc pode usar SETPRC() para reconfigurar PROW() e PCOL() para novos valores.

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

Como citado acima, @...SAY pode ter sua sada formatada usando a clusula PICTURE com <cSayPicture>. Isto executa a mesma ao que TRANSFORM(). Uma <cSayPicture> pode consistir em uma funo e/ou template. Uma funo PICTURE impoe uma regra de como @...SAY deve ser exibido como um todo. Um template PICTURE define o tamanho da sada de @...SAY, e a regra de formatao dentro da sada.

Funes: Uma funo PICTURE um smbolo precedido do smbolo @. Um smbolo de template segue a funo, e deve ser precedido de um espao. Note que mais de uma funo pode ser aplicada dentro da mesma PICTURE. A tabela seguinte resume as opes disponveis para as funes PICTURE:

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

Funo

Ao

Exibe nmeros alinhados esquerda

Exibe CR aps nmeros positivos

Exibe datas no formato SET DATE

Exibe datas e nmeros no formato British

Caracteres no template sero inseridos

Exibe DB aps nmeros negativos

Exibe zeros como brancos

Coloca nmeros negativos entre parnteses

Converte caracteres alfabticos para maisculas

Templates: Smbolos de template seguem as funes no string de PICTURE se forem especificados. Cada posio no fluxo de entrada ou sada mapeada para o smbolo na mesma posio no string template. Clipper fornece vrios smbolos os quais esto discriminados na tabela da pgina seguinte:

Tabela 4-4: Smbolos Template para SAY e TRANSFORM()

Template

Ao

A,N,X,9,#

Exibe dgitos em qualquer tipo de dados

Exibe lgicos como "T" ou "F"

Exibe lgicos como "Y" ou "N"

Converte um caractere alfabtico para maiscula

Exibe o sinal de dolar em lugar de espaos esquerda de um numrico

Exibe asteriscos em lugar de espaos esquerda de um numrico

Especifica a posio do ponto decimal

Especifica a posio da vrgula

Outros caracteres especificados no template sobreescrevem o caractere na mesma posio no stream fonte e sada. Se, entretanto, voc usar a funo R, smbolos no-template especificados sero inseridos para exibio. Exemplos

O exemplo seguinte demonstra o uso de @...SAY com uma clusula PICTURE para exibir sada formatada:

nNetIncome = 7125.50

nNetLoss = -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 impresso de etiquetas que utiliza SET DEVICE para direcionar para impressora e SETPRC() para suprimir EJECTs automticos:

USE Salesman INDEX Salesman NEW

SET DEVICE TO PRINTER

DO 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 etiqueta

SETPRC(0, 0) // Suprime ejeo de pgina

SKIP // Prximo registro

ENDDO

SET DEVICE TO SCREEN

CLOSE 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 no for especificado, a caixa desenhada em linha simples. Descrio

@...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.

Aps @...TO finalizar o desenho, o cursor posicionado no canto superior da regio em <nLinTopo> + 1 e <nColTopo> + 1. ROW() e COL() so tambm atualizadas de forma a refletir a posio do cursor.

@...TO similar a @...BOX com duas excees: primeiro, @...BOX permite-lhe definir os caracteres para moldura e, segundo, ele permite um caractere para preeenchimento. Exemplos

O exemplo seguinte apaga uma regio 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 posio inicial Sintaxe

CLEAR [SCREEN] | CLS Argumentos

SCREEN suprime a limpeza automtica de GETs quando a tela apagada com CLEAR. Descrio

CLEAR apaga a tela, libera GETs pendentes, e posiciona o curosr em 0,0. Caso

seja usado SCREEN, os GETs no so 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 funo definida pelo usurio 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>] Argumentos

FROM <cTela> especifica a expresso caractere a ser exibida na tela. Descrio

RESTORE SCREEN um comando sinnimo da funo RESTSCREEN() que reexibe 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 clusula FROM for especificada ou no. Caso ela seja especificada, a tela ser recuperada de <cTela>. <cTela> uma expresso caractere, geralmente uma varivel qual foi atribuda uma imagem de tela pelo comando SAVE SCREEN. Caso a clusula FROM no seja especificada, a tela recuperada do buffer de telas gravadas padro que foi criado pelo comando SAVE SCREEN especificado sem a clusula TO.

Para gravar e recuperar o contedo parcial das telas, ao invs de seu contedo completo, use as funes SAVESCREEN() e RESTSCREEN().

RESTORE SCREEN um comando de compatibilidade e, portanto, desaconselhado. Ele est superado pela funo RESTSCREEN(), a qual pode recuperar telas parciais, bem como telas completas. Aviso

Os comandos e funes SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), e RESTSCREEN() no so 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.txt

ELSE

BREAK

ENDIF

FUNCTION FileAlert

LOCAL lAnswer = .F., cScreen

SAVE 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"

READ

RESTORE SCREEN FROM cScreen

RETURN lAnswer == "S" SAVE SCREEN*

Grava a tela corrente num buffer ou varivel Sintaxe

SAVE SCREEN [TO <idVar>] Argumentos

TO <idVar> especifica a varivel qual sero atribudos os contedos da tela corrente como um valor de caractere. Se <idVar> no for visvel ou no existir,

uma varivel de memria do tipo privada criada e a ela atribuda a tela. Descrio

SAVE SCREEN um comando sinnimo funo SAVESCREEN() que grava a tela de 0, 0 a MAXROW(), MAXCOL() no buffer de tela padro, ou em uma varivel opcional. Se a tela for gravada em uma varivel, esta pode ser de qualquer classe de armazenamento, inclusive campo, local, esttica, ou elemento de vetor. Observe, porm, que voc no pode gravar variveis tipo vetor, local ou esttica em arquivos (.mem) com a finalidade de gravar telas mtiplas no disco.

O comando SAVE SCREEN utilizado juntamente com o comando RESTORE SCREEN para impossibilitar que uma tela original que tenha sido temporariamente substituda seja re-escrita. Telas mltiplas podem ser gravadas atravs da atribuio de cada tela a uma varivel diferente.

SAVE SCREEN um comando de compatibilidade e, portanto, desaconselhado. Ele est superado pela funo SAVESCREEN(), a qual pode gravar telas parciais ou completas. Aviso

Os comandos e funes SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), e RESTSCREEN() no so aceitos quando ANSI.OBJ ou IBMANSI.OBJ estao linkados ao programa corrente. Exemplos

Este fragmento de cdigo demonstra o uso de um vetor esttico para armazenar telas gravadas:

STATIC aScreens[10]

SAVE SCREEN TO aScreens[1]

//

<declaraooes>...

//

RESTORE SCREEN FROM aScreens[1]

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

USE Screens INDEX Name NEW

APPEND BLANK

Screens->Name := "Screen001" // Guarda o nome da tela

SAVE SCREEN TO Screens->Image // Guarda uma tela

//

<declaraes>...

//

SEEK "Screen001" // Acha a tela

RESTORE SCREEN FROM Screens->Image // Restaura Comandos para entrada e edio de dados @...GET

Cria um novo objeto GET e o coloca em exibio na tela Sintaxe

@ <nLin>, <nCol> [SAY <exp>

[PICTURE <cSayPicture>]]

GET <idVar> [PICTURE <cGetPicture>]

[WHEN <lPreCondio>]

[RANGE <dnMnimo>, <dnMximo>] | [VALID <lPosCondio>] Argumentos

<nLin> e <nCol> so as coordenadas de linha e coluna para a operao. Se a clasula SAY est presente, especificam as coordenadas para o SAY, e o GET exibido a direita deste. Caso a sada esteja alm da extenso visvel ela no aparecer.

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

GET <idVar> define o nome da varivel de qualquer tipo de dados a ser editada. Ela pode ser caractere, data, numrica ou lgica (Se o tipo for ambguo, FIELD

assumido). Vetores, NIL, e blocos de cdigo no podem ser editados.

PICTURE <cGetPicture> especifica uma mscara para exibio e as regras para edio do GET.

WHEN <lPreCondio> especifica uma expresso que deve ser satisfeita antes do cursor entrar na regio de edio de GET. Se <lCondio> avaliada como verdadeira (.T.), permitido ao cursor entrar; de outra forma, o GET corrente saltado e o cursor move-se para o prximo GET no vetor GetList.

RANGE <dnMnimo>, <dnMximo> limita a edio de datas ou variveis numricas especificando os limites mnimos e mximos aceitveis (o mnimo deve preceder o mximo). Se o valor entrado no est dentro do RANGE especificado, uma mensagem indicativa aparece no SCOREBOARD e o controle retorna ao objeto GET. A verificao de RANGE (faixa) executada a menos que o usurio aperte Esc para terminar a edio do GET corrente. Quando isto ocorre, a verificao de RANGE no executada e reatribudo seu valor original.

VALID <lPosCondio> especifica uma expresso que deve ser satisfeita antes que o cursor possa deixar a regio de edio do GET corrente. De forma semelhante s expresses RANGE, o VALID<lPosCondio> avaliado sempre que o usurio tenta deixar a regio de edio do GET, a menos que a tecla Esc seja pressionada e ESCAPE esteja ON. Se <lPosCondio> retorna falso (.F.), o controle retorna ao GET e o usurio no pode deix-lo at que <lPosCondio> retorne verdadeiro (.T.) ou o usurio aperte Esc. Um VALID <lPosCondio> pode conter ou ser uma funo definida pelo usurio ,permitindo-lhe executar buscas e outros tipos de operaes de validao. Descrio

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

Quando um comando READ especificado, um GET executa uma edio do

contedo de <idVar> de qualquer tipo de dado, incluindo campo de arquivo, elemento de vetor, varivel de memria local ou esttica.

Quando um objeto GET criado, o nome e valor corrente de <idVar> so 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.

Formatao automtica e validao: Quando o usurio estiver editando o buffer do objeto GET, existe uma formatao implcita e validao da edio para cada tipo de dado. Isto significa que enquanto o usurio digita, um teste automtico de tipo executado para cada tecla pressionada de forma a evitar que o usurio digite um caractere imprprio para aquele tipo de dado contido em <idVar>. Este comportamento assumido aplica-se a datas, numricos, e lgicos. Tipo caractere no automticamente verificado.

PICTURE: Cada objeto GET pode opcionalmente conter uma PICTURE e string template para explicitamente impor formatao e validao da entrada. Um funo PICTURE impoe uma regra de como o GET pode ser editado pelo usurio. Por exemplo, se a funo de PICTURE @! especificada para um GET, todos os caracteres alfabticos sero convertidos para maisculas antes de tomarem lugar no buffer. Um template PICTURE define o tamanho do buffer de GET, e a regra de validao para cada posio dentro do buffer. Por exemplo, o template "999" define o tamanho do buffer de GET em trs dgitos, com cada dgito devendo ser um nmero entre 0 e 9.

Funes: Uma funo PICTURE um smbolo precedido do smbolo @. Um smbolo de template segue a funo, e deve ser precedido de um espao. Note que mais de uma funo pode ser aplicada dentro da mesma PICTURE. A tabela na pgina seguinte mostra as opes disponveis para as funes PICTURE:

Tabela 4-1: Formatos de PICTURE para um GET

Funo

Tipo

Ao

Permite somente caracteres alfabticos

Exibe nmeros alinhados esquerda

Exibe CR aps nmeros positivos

D,N

Exibe datas segundo o formato SET DATE

D,N

Exibe datas com o ms e dia invertidos independente do SET DATE corrente, nmericos com pontos e vrgulas period reverse invertidos

TODOS

Elimina texto assumido caso a primeira tecla no seja cursor

Caracteres no-template so inseridos na tela mas no so guardados na varivel

S<n>

Permite rolagem horizontal dentro de um GET. <n> um inteiro que especifica a largura da regio

Exibe DB aps nmeros negativos

Exibe zeros como brancos

Exibe nmeros negativos entre parnteses com espaos esquerda

Exibe nmeros negativos entre parnteses sem espaos esquerda

Converte caracteres alfabticos para maisculas

Templates: Smbolos de template seguem as funes no string de PICTURE se forem especificados. Cada posio no fluxo de entrada ou sada mapeada para o smbolo na mesma posio no string template. O Clipper fornece vrios smbolos os quais esto discriminados na tabela da pgina seguinte:

Tabela 4-2: Smbolos Template para PICTURES de GETs

Template

Ao

Permite somente caracteres alfabticos

Permite somente caracteres alfabticos e alfanumricos

Permite qualquer caractere

Permite dgitos para qualquer tipo de dados incluindo sinal para numricos

Permite dgitos, sinais, e espaos para qualquer tipo de dados

Permite somente T, F, Y ou N

Permite somente Y ou N

Converte um caractere alfabtico para maisculo

Exibe o sinal de dolar em lugar de um espao esquerda de um numrico

Exibe um asterisco em lugar de um espao esquerda de um numrico

Exibe um ponto decimal

Exibe uma vrgula

Outros caracteres especificados no template sobreescrevem o caractere localizado na mesma posio no fluxo fonte e sada. Se, entretanto, voc usar a

funo R, smbolos no-template especificados so inseridos na tela mas no so gravados no buffer de GET.

WHEN e VALID: Um objeto GET tambm possui expresses de pr condio e ps condio usando WHEN e VALID respectivamente. A expresso WHEN executada sempre que o usurio tenta entrar com o cursor na regio de GET. A expresso VALID executada sempre que o usurio tentar sair do GET exceto se o usurio apertar uma tecla com SET KEY ou Esc.

SET KEY: Quando existe uma rotina definida para SET KEY, o usurio pode apertar a tecla designada de forma a desviar o controle para a rotina definida. Aps tal rotina ter sido executada, o controle retorna ao GET com o cursor restaurado sua posio prvia.

Vida til de um objeto GET: Objetos GET existem enquanto existirem referncias ativas a eles em algum local do programa corrente. Caso voc no tenha atribudo um objeto GET a outra varivel ou GetList, ele ter uma durao enquanto o vetor GetList corrente existir, ou at que o vetor GetList seja reatribudo. O vetor GetList corrente atribudo a um vetor vazio sempre que for emitido CLEAR GETS, CLEAR, ou um comando READ sem a clusula SAVE.

Varivel associada: Cada objeto GET criado associado a uma varivel que voc especifica como <idVar>. Quando o objeto GET ativado durante um READ, <idVar> atribudo, em vrios pontos, com o valor corrente do buffer do objeto GET. Isto ocorre nas seguintes situaes:

O usurio aperta uma tecla de sada e antes a expresso de validao executada.

O usurio aperta um SET KEY

Da mesma forma, o buffer do GET corrente sofre refresh e reexibido aps vrios intervalos, incluindo:

Quando do trmino de uma rotina SET KEY

Aps uma expresso WHEN

Aps uma expresso VALID

Isto permite a voc explicitamente atribuir <idVar> dentro destas operaes. Em Clipper 5.0, entretanto, no mais necessrio utilizar KEYBOARD para atualizar o buffer do GET corrente. Veja a nota abaixo para maiores informaes.

Exibio do objeto GET: Quando o comando @...GET executado, o novo objeto GET exibido em <nLin> e <nCol>, a menos que a clusula 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 no so atributos do objeto GET, mas simplesmente so exibidos como na clusula SAY.

Se INTENSITY est ON, um objeto GET exibido na cor destaque ou vdeo reverso dependendo do adaptador utilizado pelo seu monitor. Se a cor no selecionado definida, o objeto GET exibido na cor destaque, enquanto os GET remanescentes sero exibidos na cor no selecionado. Com INTENSITY OFF, um objeto GET exibido na cor corrente para a cor padro.

Quando um objeto GET exibido, o tamanho da rea determinado pelo tamanho de <idVar>, ou pelo nmero de dgitos especificado por <cGetPicture> se a clusula PICTURE foi especificada. Caso a funo @S for especificada como parte de <cGetPicture>, o tamanho da rea a ser exibida o argumento da funo @S. Notas

Atribuindo <idVar>: Devido s propriedades de refresh automtico e exibio de um objeto GET quando sofre um READ, voc pode fazer uma atribuio

explcita de <idVar> ao objeto GET dentro de um WHEN ou VALID. Existem duas formas de faz-lo. Para aplicaes onde as expresses de validao esto acopladas ao objeto GET, voc pode atribuir a varivel por nome na expresso de validao ou numa funo definida pelo usurio.

Para aplicaes onde a rotina de validao genrica e <idVar> no uma varivel campo ou elemento de vetor, voc pode passar <idVar> por referncia e atribuir seu parmetro formal. Help em GET: Voc exibe texto de help (auxlio) usando uma rotina de SET KEY. Dentro da rotina de SET KEY, use a funo READVAR() para determinar a varivel <idVar> associada ao objeto GET corrente. Ento use esta informao 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 exibio de um objeto GET com o comando @...GET no direcionada para a impressora ou arquivo caso SET DEVICE seja TO PRINTER.

Exemplos

O exemplo seguinte demonstra o uso da clusula VALID para validar entradas num GET:

nNumber = 0

@ 10, 10 SAY "Digite um nmero maior que zero:";

GET nNumber;

VALID nNumber > 0

Este exemplo mostra como a clusula 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 usurio permitido entrar com a informao. Se o cliente no 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 secundria:

USE Invoice NEW

APPEND BLANK

USE Inventory NEW

@ 1, 1 GET Invoice->CustNo

READ

Este exemplo demonstra o uso da funo @K para sugerir um valor padro de

entrada, mas elimina-o caso a primeira tecla pressionada no seja uma tecla de movimentao 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 varivel qual ser atribuda o resultado da seleo de menu. Caso a varivel especificada no seja visvel ou no exista, uma do tipo privada criada e a ela atribudo o resultado. Descrio

O comando MENU TO o mecanismo de seleo 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 srie de comandos @...PROMPT. Depois, ative o menu com MENU TO <idVar>. Se <idVar> no existir ou no for visvel, o comando MENU TO ir cri-la como uma varivel do tipo privada e coloca a barra luminosa sobre o primeiro PROMPT. Se ele no existir, seu valor inicial determina o primeiro PROMPT sobre o qual ficar a barra luminosa. Notas

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

Navegao e seleo: As teclas de navegao 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 seleo, tecle Return ou o primeiro caractere de um PROMPT. O comando MENU TO ento retorna a posio do PROMPT selecionado como um valor numrico para a varivel de memria especificada. A tecla Esc interrompe a seleo de menu e retorna zero. A tabela na pgina 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 no acontece com os comandos GET/READ.

Tabela 4-8: Teclas Ativas em MENU TO

Tecla

Ao

Cursor para cima

Move para o item anterior

Cursor para baixo

Move para o prximo item

Home

Move para o primeiro item

End

Move para o ltimo item Cursor para esquerda Move para o item anterior Cursor para direita Move para o prximo item

PgUp

Seleciona item de menu, retorna posio

PgDn

Seleciona item de menu, retorna posio

Return

Seleciona item de menu, retorna posio

Esc

Aborta seleo, retorna zero

Primeira letra

Seleciona primeiro item iniciando com a letra,retorna posio 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 := 2

SET WRAP ON

SET 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

QUIT

ENDIF

RETURN READ

Ativa edio em tela usando objetos GET. Sintaxe

READ [SAVE] Argumentos

SAVE retm o contedo do vetor GetList corrente aps o fim da operao do comando READ. Depois, voc pode editar os mesmos objetos GET atravs de outro comando READ. Caso no esteja especificada, GetList corrente atribudo um vetor vazio eliminando todos os objetos GET anteriores quando o comando READ tiver terminado. Descrio

O comando READ executa um mdulo de edio 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 formatao ativa, o comando READ executa essa rotina antes de entrar no mdulo de edio em tela.

Dentro de um READ, o usurio pode editar o buffer de cada objeto GET bem como mover-se de um objeto GET para outro. Antes que o usurio possa entrar com um objeto GET, o controle passa para o respectivo WHEN <lPreCondio> caso alguma tenha sido atribuda quele objeto GET. Se <lPreCondio> retornar valor verdadeiro (.T.), permitido ao usurio editar o buffer do objeto GET. Caso contrrio, o controle passa para o prximo objeto GET na GetList. Dentro de um buffer GET, o usurio pode editar, utilizando-se do conjunto completo de teclas de navegao e edio. Veja as tabelas abaixo.

Quando o usurio pressiona uma tecla de sada de GET, o controle passa pscondio RANGE ou VALID respectiva, caso tenha sido especificada. Se alguma das condies retornar valor verdadeiro (.T.), a edio do objeto GET encerrada e o controle passa para o prximo objeto GET. Caso contrrio, o controle permanece dentro do objeto GET corrente at que um valor vlido for entrado ou

at que o usurio tecle Esc.

Quando o usurio consegue entrar com um valor num objeto GET, atribudo respectiva varivel o valor do buffer do objeto GET.

As seguintes tabelas listam teclas ativas num comando READ: Tabela 4-9: Teclas de Navegao em um READ

Tecla

Ao

Cursor para esquerda, Ctrl-S

Caractere esquerda. No move cursor para o GET anterior

Cursor para direita, Ctrl-D

Caractere direita. No move cursor para o prximo GET

Ctrl-Cursor para esquerda, Ctrl-A

Palavra esquerda

Ctrl-Cursor para direita, Ctrl-F

Palavra direita

Cursor para cima, Ctrl-E

GET anterior

Cursor para baixo, Ctrl-X,

Return, Ctrl-M Prximo GET

Home

Primeiro caractere do GET

End ltimo caractere do GET

Ctrl-Home

Incio do primeiro GET

Ctrl-End

Incio do ltimo GET Tabela 4-10: Teclas de Edio de READs

Tecla

Ao

Del, Ctrl-G

Elimina caractere onde est o cursor

Backspace, Ctrl-H

Backspace

Ctrl-T

Elimina palavra direita

Ctrl-Y

Elimina do cursor at o final do GET

Ctrl-U

Retorna o GET ao seu valor original Tabela 4-11: Teclas Comutativas em um READ

Tecla

Ao

Ins, Ctrl-V

Comuta modo de insero WAIT*

Suspende a execuo de um programa at que seja pressionada uma tecla

Sintaxe

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

<expPrompt> uma expresso de qualquer tipo. O assumido "Aperte qualquer tecla para continuar..."

TO <idVar> a varivel de qualquer categoria qual ser atribuda a tecla pressionada seu valor caractere. Se <idVar> no existe ou no est visivel, ela criada como privada e ento lhe atribudo o valor caractere. Descrio

WAIT um estado de espera que exibe um prompt aps enviar um carriage return/line feed para a tela. Ento aguarda at que o usurio aperte um tecla. Se a clusula 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 no alfanumricos entrados por Alt-nmericos atribuem o caractere especificado. Se o caractere for do tipo que pode ser exibido, ele ecoado em tela. Teclas de funo so ignoradas a menos que atribudas com SET FUNCTION E SET KEY.

WAIT um comando de compatibilidade e portanto no recomendado. Ele superado por @...GET/READ e INKEY(). Notas

WAIT sem prompt: Para interromper a execuo de um programa, especifique WAIT "" ou INKEY(0), o segundo recomendado pois no perturba a posio do cursor na tela.

Exemplos

WAIT "Aperte uma tecla..." TO key Comandos para manuteno de arquivos de dados APPEND BLANK

Adiciona um registro vazio ao arquivo de dados corrente Sintaxe

APPEND BLANK Descrio

APPEND BLANK adiciona um registro vazio no fim do arquivo corrente e o torna o registro corrente. Os novos valores de campos so inicializados em valores vazios para cada tipo de dado. A campos caractere so atribudos espaos, campos numricos so inicializados com zero, campos lgicos so inicializados com falso (.F.), a campos data so atribudos CTOD(""), e campos memo so deixados vazios.

Quando estiver operando em ambiente de rede e o arquivo corrente estiver compartilhado, APPEND BLANK tenta adicionar e ento travar o registro novo. Se outro usurio tiver travado o arquivo com FLOCK() ou travado LASTREC() + 1 com RLOCK(), NETERR() retorna verdadeiro (.T.). Note que um registro recm APPENDado permanece travado at que voc trave outro registro ou execute UNLOCK. Note tambm que APPEND BLANK no libera um FLOCK() imposto pelo usurio corrente. Exemplos

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

USE Vendas SHARED NEW

APPEND BLANK

IF !NETERR()

<atualiza registro vazio>...

ELSE

? "Append no realizado"

BREAK

ENDIF

APPEND RECORD 5 FROM Temp CLEAR ALL

Fecha arquivos e libera as variveis pblicas e privadas Sintaxe

CLEAR ALL Descrio

CLEAR ALL libera todas as variveis pblicas 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 so ndices, alternate, e memo. Note que CLEAR ALL no libera variveis estticas ou locais.

CLEAR ALL um comando de compatibilidade e portanto no recomendado.

Seu uso em Clipper superado por comandos ou funes que executam a ao que voc necessita. Arquivos associados a reas de trabalho podem ser fechados de vrias formas com o comando CLOSE. Liberao explcita de variveis no recomendada na maioria dos casos. CLOSE

Fecha um conjunto especfico de arquivos Sintaxe

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

<idAlias> especifica a rea de trabalho onde os arquivos sero fechados.

ALL Fecha arquivos de dados, alternate, e de indces em todas as reas. Alm disso, libera todos os filtros, relaes 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 relaes ativas. Entretanto, ele no causa efeito

no formato ativo.

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

INDEXES Fecha todos arquivos de ndice na rea corrente. Descrio

CLOSE um comando de propsito geral que fecha vrios tipos de arquivos Clipper dependendo da clusula opcional especificada. CLOSE sem opo fecha o arquivo de dados corrente e seus ndices, o mesmo que USE sem argumentos.

Em Clipper, vrios outros comandos fecham arquivos, incluindo:

QUIT

CANCEL*

RETURN a partir da rotina principal

CLEAR ALL*

USE sem argumentos

COMMIT

Executa uma gravao em disco para todas as reas ativas Sintaxe

COMMIT Descrio

COMMIT dirige os buffers do Clipper para disco e executa sua gravao para todas as reas de trabalho com arquivos de dados ou ndices abertos. Tal caracterstica est disponvel 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 atualizao para um arquivo de dados e seus ndices visiveis a outros processos. Exemplos

Neste exemplo, COMMIT utilizado para forar a escrita em disco, aps atribuir o contedo de variveis de memria a variveis campo:

USE Sales EXCLUSIVE NEW

MEMVAR->Name := Sales->Name

MEMVAR->Amount := Sales->Amount

//

@ 10, 10 GET MEMVAR->Name

@ 11, 10 GET MEMVAR->Amount

READ

//

IF UPDATED()

APPEND BLANK

Sales->Name := MEMVAR->Name

Sales->Amount := MEMVAR->Amount

COMMIT

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 expresso caractere entre parnteses. Se no for colocada extenso, o assumido ser (.dbf). Descrio

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

Decimais

Field_name

Caractere

10

Field_type

Caractere

Field_len

Numrico

Field_dec

Numrico

Tal como o comando COPY STRUCTURE EXTENDED, CREATE pode ser usado juntamente com CREATE FROM para formar um novo arquivo de dados. Ao contrrio do comando COPY STRUCTURE EXTENDED, CREATE produz um arquivo de dados vazio, e no necessita da presena de um outro arquivo de dados para isso.

<xcArquivoEstrutura> automaticamente aberto na rea de trabalho corrente aps ser criado. Exemplos

Este exemplo cria um novo arquivo de estrutura, coloca a definio de um campo dentro do mesmo, e ento cria um novo arquivo de dados a partir da estrutura:

CREATE TempStru

APPEND BLANK

REPLACE;

Field_name WITH "Name";

Field_type WITH "C";

Field_len WITH 25;

Field_dec WITH 0

CLOSE

CREATE NewFile FROM TempStru DELETE

Marca registros para eliminao Sintaxe

DELETE [<abrangncia> [WHILE <lCondio>] [FOR <lCondio>]

Argumentos

<abrangncia> a poro do arquivo de dados corrente a ser eliminada. Se abrangncia no for especificada, o comando DELETE agir somente no registro corrente. Se uma <abrangncia> ou clusula condicional for especificada, o padro torna-se todos (ALL) os registros.

WHILE <lCondio> especifica o conjunto dos registros que atendem a condio do registro corrente at que a condio seja falsa.

FOR <lCondio> especifica o conjunto de registros condicional a ser eliminado dentro da abrangncia. Descrio

O comando DELETE marca os registros para que eles possam ser filtrados com o comando SET DELETED ON, identificados com a funo DELETED(), ou fisicamente removidos do arquivo de dados com o comando PACK. Alm disso, comandos de visualizao de registros como, por exemplo, LIST e DISPLAY identificam os registros marcados para eliminao 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 invs dos comandos DELETE ALL e PACK.

Num ambiente de rede, o comando DELETE pede que o registro corrente seja travado atravs da funo RLOCK(), caso voc esteja marcando um nico registro. Se voc estiver marcando vrios registros, o arquivo de dados corrente deve ser travado com a funo FLOCK() ou aberto EXCLUSIVE. Notas

Marcao com o comando SET DELETED ON: Se o registro corrente for eliminado com o comando SET DELETED ON, ele permanecer visvel at que o ponteiro de registro seja movido. Exemplos

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

USE Sales INDEX Salesman NEW

DELETE ALL FOR Inactive GO

Move o ponteiro de registro para um registro especfico Sintaxe

GO[TO] <nRegistro> | BOTTOM | TOP Argumentos

<nRegistro> especifica o nmero do registro destino.

BOTTOM especifica o ltimo registro na rea de trabalho corrente.

TOP especifica o primeiro registro na rea de trabalho corrente. Descrio

O comando GO posiciona o ponteiro num registro especificado na rea de trabalho corrente. O registro pode ser especificado atravs de seu nmero ou como registro incio ou fim do arquivo. Se a nova posio incio (TOP) e h um ndice ativo, o ponteiro de registros vai at o primeiro registro do ndice, ou ento para o registro 1. Caso a nova posio seja fim (BOTTOM) e haja um ndice ativo, o ponteiro de registros vai para o ltimo registro do ndice, ou ento para a funo LASTREC().

A forma GO <nRegistro> do comando a mesma da clusula RECORD de qualquer comando de arquivo de dados que aceite uma abrangncia.

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 lgico que no tiver sido marcado e/ou atenda a condio do filtro.

Caso o comando DELETED estiver em ON ou haja um FILTER ativo, o comando GO TOP vai para o primeiro registro lgico que no tiver sido marcado e/ou atenda a condio do filtro.

Indices de chave nica: Registros no 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 no gera um erro em tempo de execuo. Pelo contrrio, as funes 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 funo GO RECNO Exemplos

Estes exemplos mostram resultados do comando GO simples:

USE Sales NEW

? LASTREC() // Resulta: 84

GO 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 expresso 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, lgico, ou numrico. O tamanho mximo da expresso da chave de indexao 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 expresso caractere entre parnteses. Normalmente, a extenso de arquivo padro (.ntx). Se, contudo, voc linkou NDX.OBJ a fim de usar arquivos de ndice compatveis com dBASE III PLUS, a extenso padro passa a ser (.ndx).

UNIQUE especifica que <xcIndice> inclui somente valores de chave nicos. Descrio

O comando INDEX ON cria um arquivo que contm 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 expresso chave, embora o ndice no altere a ordem fsica 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 numricos em ordem numrica, ordem cronolgica dos valores de datas, considerando datas em branco como valores baixos, e valores lgicos classificados com valor verdadeiro (.T.) considerados como valores altos. Campos memo no podem ser indexados.

Quando o comando INDEX ON usado, todos os arquivos de ndice abertos na rea de trabalho corrente so fechados e o novo arquivo de ndices criado. Quando a operao de indexao 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, porm no faz uma cpia fsica 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 execuo e a funo de erro respectiva chamada. Consulte o captulo Programando em Rede no livro Programando e Utilitrios para mais informaes. Notas

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

USE Invoices

INDEX ON Customer + DTOS(InvDate) TO Invoice

Variveis declaradas: Variveis locais e estticas no podem ser usadas em expresses de chave de indexao. Isto acontece porque tais expresses so gravadas como texto nos arquivos de ndice e so mais tarde expandidas para produzir valores chave. Uma vez que variveis locais e as estticas so invisveis dentro das variveis macro, referncias a elas dentro de expresses de chave de indexao no sero reconhecidas devidamente.

Pela mesma razo, uma varivel declarada com qualquer uma das outras declaraes em tempo de compilao como, por exemplo, MEMVAR ou FIELD, no so vlidas dentro de uma expresso de chave de indexao. Se for necessria qualificao de nome (alias) ou de varivel numa expresso de chave de indexao, deve-se faz-lo claramente na expresso e no atravs de declaraes ao compilador.

Registros marcados e filtrados: Registros que esto filtrados ou marcados para eliminao no so includos no ndice.

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

Indices de ordem tipo dicionrio: Para criar um ndice de ordem tipo dicionrio de chaves de caractere, use UPPER(<expChave>) como expresso de ndice. Ordens do tipo dicionrio so aquelas onde a diferenciao entre letras maisculas e minsculas no feita.

Arquivos de ndice compatveis: O Clipper aceita arquivos de ndice dBASE III PLUS compatveis atravs da conexo de um driver de arquivo de dados.

Cuidado

O driver de arquivo de dados no aceita os mecanismos de segurana do dBASE III PLUS. Isto significa que voc no 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, porm, o driver dBASE III PLUS funciona da mesma forma que o driver padro.

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 indexao e dois ou mais registros tm 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 so acrescidos. Note que um ndice de chaves nicas retm o atributo de unicidade e no afetado por utilizaes subsequentes do comando UNIQUE.

Usando TRIM(): O Clipper armazena valores de chave de indexao em incrementos fixos. Uma <expChave> que muda o tamanho da chave pode criar um ndice inopervel. Isto acontece porque o tamanho das chaves de indexao

 calculado por avaliao da <expChave> num registro em branco. Uma <expChave> com TRIM(), portanto, sempre avaliada como sendo um string nulo (""), o que ocasiona uma falta de correspondncia entre o destino e o tamanho da chave definida. Para usar qualquer uma das funes TRIM() use a funo PADR() para fazer com que os tamanhos das chaves sejam os mesmos, conforme o exemplo abaixo:

USE Customer NEW

INDEX ON PADR(RTRIM(Last) + First, 40) TO CustName Exemplos

Estes exemplos mostram resultados do comando INDEX simples:

? TYPE("Branch") // Resulta: C

INDEX ON Branch TO Branch

? TYPE("Amount") // Resulta: N

INDEX ON Amount TO Amount

? TYPE("Date") // Resulta: D

INDEX ON Date TO Date

Os dois exemplos abaixo criam ndices de ordem descendente:

USE Invoices NEW

INDEX ON DESCEND(InvDate) TO InvStack

INDEX ON Customer + DESCEND(DTOS(InvDate)) TO CustStack Tabela 4-12: Teclas de Sada de um READ

Tecla

Ao

Ctrl-W, Ctrl-C, PgUp, PgDn

Encerra um READ gravando GET corrente

Return, Ctrl-M

Encerra um READ a partir do ltimo GET

Esc

Encerra um READ sem gravar o GET corrente

Cursor 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 clusula SAVE for usada.

READs aninhados: Para executar um comando READ aninhado dentro de um procedimento SET KEY, VALID, ou WHEN ou de uma funo definida por usurio, declare ou crie uma nova GetList, execute uma srie de declaraes @...GET, e depois o comando READ. Quando o procedimento terminar, a nova GetList liberada e a anterior torna-se visvel novamente. Veja o exemplo abaixo.

Home e End: Teclando Home ou End vai para o primeiro ou ltimo caractere que no 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 funo definida pelo usurio iniciada por VALID.

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

Exemplos

O exemplo abaixo define vrios GETs e a seguir usa o comando READ:

CLS

cVar1 := 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 funo definida pelo usurio:

LOCAL cName := SPACE(10)

@ 10, 10 GET cName VALID SubForm( cName )

READ

RETURN

FUNCTION SubForm( cLookup )

PRIVATE GetList := {} // Cria novo GetList

USE Sales INDEX Salesman NEW

SEEK cLookup

IF FOUND()

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

@ 16, 10 GET Amount

READ // READ GetList

ENDIF

CLOSE Sales

RETURN .T. // LIbera GetList REPLACE

Atribui novos valores a variveis campo Sintaxe

REPLACE <idCampo> WITH <exp>

[, <idCampo2> WITH <exp2>...]

[<abrangncia>] [WHILE <lCondio>] [FOR <lCondio>] Argumentos

<idCampo> o nome da varivel campo qual ser atribudo novo valor. Se <idCampo> for precedido de um alias, a atribuio ocorre na rea de trabalho designada.

<exp> o valor a ser atribudo a <idCampo>.

<abrangncia> a parte do arquivo de dados corrente onde atuar o comando REPLACE. Sendo especificada uma condio, o assumido ser todos (ALL) os registros na rea de trabalho corrente.

WHILE <lCondio> especifica o conjunto de registros que atendem a condio do registro corrente, at que a condio seja falsa.

FOR <lCondio> especifica o conjunto condicional de registros sobre os quais atuar o comando REPLACE dentro da abrangncia. Descrio

O comando REPLACE atribui novos valores aos contedos de uma ou mais variveis campo nos registros correntes nas reas de trabalho especificadas. As variveis campo destino podem ser do tipo caractere, data, lgico, memo, ou numrico. O comando REPLACE tem a mesma funo que o operador inline (:=) com a diferena que ele assume que uma referncia sem um alias sempre para uma varivel campo. Isto significa que voc pode atribuir novos valores a

variveis campo usando declaraes de atribuio, desde que as referncias a variveis campo sejam precedidas de um alias, o alias do campo, ou declaradas atravs de declarao de comando do campo, caso a referncia seja ambgua.

A abrangncia padro do comando REPLACE o registro corrente, a no ser que seja especificada uma abrangncia ou condio. Caso haja abrangncia ou condio especificadas, o comando REPLACE atua em cada registro que atenda a condio e/ou abrangncia. Aviso

Ao usar o comando REPLACE num campo chave, o ndice atualizado e a posio relativa do ponteiro de registro dentro do ndice modificada. Isto significa que utilizar o comando REPLACE num campo chave com uma abrangncia ou condio pode ocasionar um resultado errneo. 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, porm, so atualizados se o comando REPLACE for usado no campo chave.

Num ambiente de Rede, usar o comando REPLACE no registro corrente requer a funo RLOCK(). Executar o comando REPLACE com uma abrangncia e/ou condio exige um FLOCK() ou USE EXCLUSIVE do arquivo de dados corrente. Caso o comando REPLACE estiver sendo executado em outra rea de trabalho atravs da especificao de seu alias, esse registro tambm deve ser travado com um RLOCK(). Exemplos

Este exemplo ilustra um uso simples do comando REPLACE:

USE Customer NEW

APPEND BLANK

USE Invoices NEW

APPEND BLANK

//

REPLACE Charges WITH Customer->Markup * Cost,;

Custid WITH Customer->Custid,;

Customer->TranDate WITH DATE()

Ao usar declaraes de atribuio em lugar do comando REPLACE siga o seguinte exemplo:

FIELD->Charges := Customer->Markup * FIELD->Cost

FIELD->Custid := Customer->Custid

Customer->TranDate := DATE() SELECT

Muda a rea de trabalho corrente Sintaxe

SELECT <xnArea> | <idAlias> Argumentos

<xnArea> o nmero da rea de trabalho entre zero e 250. Este argumento uma expresso extendida e pode ser especificada literalmente por um nmero ou expresso numrica entre parnteses.

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

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 lgico para abrir um arquivo de dados juntamente com todos os seus atributos. Referncias a reas de trabalho com o comando SELECT podem ser feitas atravs de nmeros ou alias. O alias de uma rea de trabalho automaticamente atribudo quando um arquivo de dados usado naquela rea de trabalho ou utilizando-se a clusula ALIAS.

rea de trabalho zero refere-se primeira rea de trabalho vazia.

Usando isto, voc pode selecionar 0 e usar <xcArquivo> como um mtodo para a abertura de arquivos de dados. Notas

Expresses alias: Expresses alias so um mtodo muito mais eficiente de selecionar novas reas de trabalho do que o comando SELECT. Ao invs de selecionar uma rea de trabalho e depois executar uma operao para aquela rea de trabalho, voc pode aplicar um alias a uma expresso que execute aquela operao. Isto feito especificando-se o alias da rea de trabalho desejada e a expresso entre parnteses. Por exemplo, para acessar o valor da funo EOF() numa rea de trabalho no selecionada, voc normalmente executaria uma srie de declaraes como as seguintes:

SELECT Remote

? EOF()

SELECT Main

Usando a forma de expresso alias, estas declaraes ficam da seguinte forma:

? Remote->(EOF())

USE...NEW: Ao invs 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 srie de arquivos de dados pode ser aberta selecionando-se cada rea de trabalho atravs de seu nmero e depois abrindo cada arquivo de dados naquela rea:

SELECT 1

USE Customer

SELECT 2

USE Invoices

SELECT 3

USE Parts

SELECT Customer

Um mtodo mais correto abrir cada arquivo de dados na prxima rea de trabalho disponvel especificando a clusula NEW na linha de comando USE. Neste exemplo, USE...NEW empregado ao invs do comando SELECT 0 e depois USE:

USE Customer NEW

USE Invoices NEW

SELECT Customer

Este fragmento de cdigo ilustra a mudana de reas de trabalho juntamente com a gravao do nome da rea de trabalho corrente em uma varivel utilizando a funo SELECT(). Aps executar uma operao na nova rea de trabalho, a rea de trabalho original pode ser re-selecionada atravs do nome da rea de trabalho armazenada:

nLastArea := SELECT()

USE Newfile NEW

//

<declaraes>...

//

SELECT (nLastArea) SKIP

Move o ponteiro de registro para uma nova posio Sintaxe

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

<nRegistros> uma expresso numrica que especifica o nmero de registros para mover o ponteiro a partir da posio corrente. Um valor positivo especifica deslocamento do ponteiro para frente e valores negativos significam deslocamento do ponteiro para trs.

ALIAS <idAlias>|<nAreaTrabalho> especifica o nome alias como literal ou a rea de trabalho como expresso numrica.

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

SKIP move o ponteiro para uma nova posio relativa posio corrente na rea corrente e dentro do filtro corrente, caso exista um. SKIP geralmente usado para operaes com relatrios, que necessitam mover o ponteiro para o prximo 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 trs. Caso no

exista ndice ativo, SKIP move o ponteiro relativo posio corrente no arquivo destino. Se existe um ndice ativo, SKIP move o ponteiro relativo posio corrente no ndice ao invs do arquivo de dados.

SKIP a frente em posies alm 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 movimentao de ponteiro, inclusive SKIP, ir tornar as modificaes na rea corrente visveis a outras aplicaes se o arquivo corrente est SHARED e as alteraes foram feitas durante um RLOCK(). Se, entretanto, as modificaes forem feitas durante um FLOCK(), a visibilidade no garantida at a liberao do travamento, um COMMIT, ou o fechamento do arquivo. Para forar uma atualizao a ser visvel sem mudar a posio corrente, use SKIP 0 Exemplos

O exemplo seguinte usa SKIP com vrios argumentos e mostra o resultado:

USE Customers NEW

SKIP

? RECNO() // Resulta: 2

SKIP 10

? RECNO() // Resulta: 12

SKIP -5

? RECNO() // Resulta: 7

O exemplo seguinte move o ponteiro em reas remotas:

USE Customers NEW

USE Invoices NEW

SKIP ALIAS Customers

Este exemplo imprime um relatrio usando SKIP para mover o ponteiro sequencialmente atravs do arquivo:

LOCAL nLine := 99

USE Customers NEW

SET PRINTER ON

DO WHILE !EOF()

IF nLine > 55

EJECT

nLine := 1

ENDIF

? Customer, Address, City, State, Zip

nLine++

SKIP

ENDDO

SET PRINTER OFF ZAP

Remove todos os registros do arquivo corrente Sintaxe

ZAP Descrio

O comando ZAP remove permanentemente todos os registros dos arquivos presentes na rea corrente. Isto inclui arquivos de dados, ndices e memo. O espao em disco ocupado liberado. ZAP executa o mesmo que DELETE ALL e PACK, porm quase instantneo.

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

Este exemplo demonstra um ZAP em rede:

USE Sales NEW EXCLUSIVE

IF !NETERR()

SET INDEX TO Sales, Branch, Salesman

ZAP

CLOSE Sales

ELSE

? "Zap no executado"

BREAK

ENDIf Comandos para pesquisa em arquivos SEEK

Pesquisa um ndice atravs de um valor chave especificado Sintaxe

SEEK <expPesquisa> Argumentos

<expPesquisa> uma expresso qual a chave de indexao dever corresponder. Descrio

O comando SEEK pesquisa o ndice de controle que comea com a primeira chave e continua at que seja encontrada correspondncia ou at que haja um valor chave maior do que o argumento de pesquisa. Caso haja correspondncia, o ponteiro de registro posicionado no nmero do registro encontrado no ndice. Se SOFTSEEK estiver em OFF (o padro) e no seja encontrada correspondncia, 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 no houver nenhuma chave no ndice que seja maior do que o argumento de pesquisa.

O comando SET EXACT no tem efeito algum sobre a operao do comando SEEK. Exemplos

Este exemplo ilustra o efeito do comando SEEK em vrios arquivos de dados:

USE Sales INDEX Branch NEW

SEEK "100"

? FOUND(), EOF(), RECNO() // Resulta: .T. .F. 1

A funo definida pelo usurio exemplificada abaixo executa um comando SEEK exato para um ndice com uma chave de caractere:

USE Invoice INDEX Invoice NEW

? IF(SeekExact("10001"),"Encontrado","No Encontrado")

RETURN

FUNCTION SeekExact( cSearch )

SEEK PADL( cSearch, LEN(&(INDEXKEY(0))) )

RETURN (FOUND()) Comandos para clculos sobre registros COUNT

Totaliza o nmero de registros e coloca o resultado numa varivel Sintaxe

COUNT TO <idVar>

[<abrangncia>] [WHILE <lCondio>] [FOR <lCondio>] Argumentos

TO <idVar> identifica a varivel qual ser atribudo o resultado do comando COUNT. Uma varivel que no existe ou no visvel criada como uma varivel do tipo privada cuja abrangncia o procedimento corrente.

<abrangncia> a parte do arquivo de dados corrente onde o comando COUNT atuar. O padro todos (ALL) os registros.

WHILE <lCondio> especifica o conjunto de registros que atendem a condio do registro corrente at que a condio seja falsa.

FOR <lCondio> especifica o conjunto de registros condicional para o comando COUNT dentro da abrangncia. Descrio

O comando COUNT totaliza o nmero de registros da rea de trabalho corrente que atendem as condies e abrangncia especificadas. O resultado ento alocado varivel em questao.<idVar> pode ser uma varivel 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: 84

COUNT TO nBranchCnt FOR Branch == 100

? nBranchCnt // Resulta: 4

Este exemplo totaliza o nmero 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 NEW

SEEK 100

USE Sales INDEX SalesBranch NEW

SEEK 100

COUNT TO Branch->Count WHILE Branch == 100 SUM

Soma expresses numricas e coloca o valor em variveis Sintaxe

SUM <nLista expr> TO <idLista var>

[<abrangncia>] [WHILE <lCondio>] [FOR <lCondio>] Argumentos

<nLista expr> a lista de valores numricos a serem somados para cada registro processado.

<idLista var> identifica as variveis receptoras da soma.

Variveis que no existam ou no sejam visveis so criadas como privadas. <idList var> deve conter o mesmo nmero de elementos de <nLista expr>.

<abrangncia> a poro do arquivo de dados a ser somada (SUM). O assumido todos (ALL).

WHILE <lCondio> especifica o conjunto de registros a partir do registro corrente at que a condio seja falsa.

FOR <lCondio> especifica o conjunto condicional de registros a serem somados dentro da abrangncia dada. Descrio

SUM soma uma srie de expresses numricas e armazena o resultado em variveis para uma faixa de registros na rea corrente.

Note que <nLista expr> necessria e no opcional como em outros dialetos. Exemplos

O exemplo seguinte ilustra o uso de SUM:

USE Sales NEW

SUM 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 vrgulas, a passar para <idProcedure>. Cada argumento pode ser uma varivel, campo, vetor, elemento de vetor, expresso ou objeto. Argumentos podem ser saltados ou no mencionados no fim da lista. Descrio

A declarao DO invoca um procedure, opcionalmente passando parmetros para a rotina invocada. Ele executa a mesma funo de um procedure ou funo de usurio chamada na linha pelo prprio nome com exceo de que outras variveis que no campos so passados por referncia. De forma a ser passado como argumento, um campo deve ser colocado entre parnteses a menos que declarado FIELD ou especificado com alias.

Em Clipper, o nmero de argumentos passados no precisa ser o mesmo que aquele que temos na rotina invocada. Se o nmero for menor que o nmero de parmetros, os parmetros sem correspondncia sero inicializados com NIL. O mesmo ocorre com os argumentos saltados em <lista argumentos>. Para detectar a posio do ltimo argumento passado em <lista argumentos>, use PCOUNT(). Para detectar um argumento saltado, compare-o com NIL.

Adicionalmente, DO tambm tem o efeito de compilar se o programa corrente est sendo compilado sem a opo /M. Se o Clipper encontra um DO e a rotina corrente no foi compilada ainda, ele busca no diretrio corrente por um arquivo (.prg) com o mesmo nome e o compila. Se este arquivo com o mesmo nome da rotina no for encontrado, ele assumido

EXTERNAL, e uma referncia adicionada ao arquivo objeto (.obj). Em tempo de linkagem, o linker ir procurar em outros arquivos objeto e bibliotecas por esta

referncia.

Em Clipper 5.0, DO uma declarao de compatibilidade e portanto no recomendada. Ele superado por invocar uma funo ou procedure pelo prprio nome na linha. Desde que a conveno passagem por valor, voc deve prefixar o argumento com o sinal de passagem por referncia (@) de forma a pass-lo por referncia. Se voc est usando DO para melhorar a legibilidade do cdigo, um comando definido pelo usurio especificado com a diretiva #command pode prover grande legibilidade sem sacrificar a segurana de variveis passadas como parmetros. Exemplos

Este exemplo executa um procedure sem parmetros:

DO AcctsRpt

AcctsRpt()// Mtodo preferido

Este exemplo executa um procedure passando duas constantes:

DO QtrRpt WITH "2", "Diviso de Vendas"

QtrRpt("2", "Diviso de Vendas") // Mtodo preferido

Neste exemplo, um procedure executado com o primeiro argumento passado por valor e o segundo por referncia:

nNumber = 12

DO YearRpt WITH nNumber + 12, nNumber

YearRpt(nNumber + 12, @nNumber) // Mtodo preferido

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

DO DisplayWindow WITH ,,,,"Janela"

DisplayWindow(,,,,"Janela") // Mtodo preferido DO CASE

Executa um de vrios blocos de declaraes. Sintaxe

DO CASE

CASE <lCondio1>

<declaraes>...

[CASE <lCondio2>]

<declaraes>...

[OTHERWISE]

<declaraes>...

END[CASE] Argumentos

CASE <lCondio> define um bloco de declaraes para executar caso <lCondioo> avaliada como verdadeira (.T.).

OTHERWISE define um bloco de declaraes para executar caso nenhum dos CASE seja verdadeiro (.T.). Descrio

DO CASE...ENDCASE uma estrutura de controle que executa um de vrios blocos de declaraes dependendo de qual das condies associadas seja verdadeira (.T.). Ele trabalha desviando a execuo para as declaraes seguintes ao primeiro CASE <lCondio> que for verdadeiro (.T.). Execuo continua at que o prximo CASE, OTHERWISE ou ENDCASE seja encontrado. Controle ento desviado para a primeira instruo seguinte ao ENDCASE.

Se nenhuma das condies CASE for avalida como verdadeira (.T.), as declaraes seguintes ao OTHERWISE so executadas at que seja encontrado o ENDCASE. Caso no seja especificado um OTHERWISE, o controle desvia para a instruo em seguida ao ENDCASE.

Qualquer nmero de declaraes incluindo outras estruturas de controle (i.e., DO WHILE e FOR), podem ser aninhados dentro de uma estrutura DO CASE. Adicionalmente, no h limite fsico de declaraes CASE que podem ser contidas dentro de uma estrutura DO CASE.

DO CASE...ENDCASE idntico 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 == 0

RETURN

CASE nChoice == 1

ChoiceOne()

CASE nChoice == 2

ChoiceTwo()

ENDCASE DO WHILE

Executa um bloco enquanto uma condio verdadeira. Sintaxe

[DO] WHILE <lCondio>

<declaraes>...

[EXIT]

<declaraes>...

[LOOP]

<declaraes>...

END[DO] Argumentos

<lCondio> a expresso lgica de controle do DO WHILE.

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

LOOP desvia o controle para o DO WHILE mais recente. Descrio

DO WHILE...ENDDO uma estrutura de controle que executa um bloco repetitivamente, enquanto <lCondio> for avaliada como verdadeira (.T.). Quando a condio 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 prximo ENDDO. Se um LOOP for encontrado, controle desvia para o mais recente DO WHILE. Se a condio avaliada como falsa (.F.), a estrutura DO WHILE termina e o controle passa para a instruo imediatamente seguinte ao ENDDO.

EXIT usado geralmente para encerrar a execuo de um DO WHILE baseado em uma condio diferente da condio deste. LOOP, ao contrrio, usado para evitar a execuo de instrues dentro do DO WHILE, baseado numa condio intermediria, e desvia imediatamente de volta para a declarao DO WHILE.

Estruturas DO WHILE podem ser aninhadas dentro de quaisquer outras estruturas at qualquer nvel. O nico requisito que estas estruturas estejam devidamente aninhadas. Exemplos

O exemplo a seguir demonstra uma estrutura de controle tpica para um relatrio por grupos:

LOCAL cOldSalesman, nTotalAmount

USE Sales INDEX Salesman NEW

WHILE !EOF()

cOldSalesman = Sales->Salesman

nTotalAmount = 0

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

? Sales->Salesman, Sales->Amount

nTotalAmount = nTotalAmount + Sales->Amount

SKIP

ENDDO

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

ENDDO

CLOSE Sales

O fragmento de cdigo a seguir demonstra como LOOP pode ser utilizado para fornecer uma condio intermediria:

WHILE <lCondio>

<processamento inicial>...

IF <condio intermediria>

LOOP

ENDIF

<continua processamento>...

ENDDO

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

LOCAL lMore = .T.

WHILE lMore

<instrues>...

lMore := (<lCondio>)

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 nmero de vezes. Sintaxe

FOR <idContador> = <nInicio> TO <nFim> [STEP <nIncremento>]

<Instrues>...

[EXIT]

<Instrues>...

[LOOP]

NEXT Argumentos

<idContador> o nome da varivel de controle do loop. Se o <idContador> no existe ou no est visvel, uma varivel PRIVATE criada.

<nIncio> o valor inicial atribudo 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>, seno <nInicio> deve ser menor que <nFim>.

STEP <nIncremento> define a quantidade de <idContador> a ser mudada para cada iterao do loop. <nIncremento> pode ser positivo ou negativo. Se a clusula STEP no for especificada, <idContador> incrementado de um para cada iterao do loop.

EXIT incondicionalmente desvia o controle de dentro de um FOR...NEXT para a prxima instruo seguindo ao NEXT.

LOOP desvia o controle para o mais recente FOR. Descrio

FOR...NEXT uma estrutura de controle que executa um bloco um determinado nmero 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 expresses na declarao FOR so avaliadas para cada iterao 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 ento desvia para a instruo seguinte ao NEXT. Se um LOOP for encontrado, controle desvia para a declarao FOR.

Se <nIncremento> um valor negativo, <idContador> decrementado ao invs 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 so teis para percorrer atravs de vetores onde <idContador> usado como indce do vetor. Veja exemplo abaixo.

FOR...NEXT como qualquer outra estrutura pode ser aninhado em qualquer nvel. 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

<instrues>...

NEXT

Para percorrer em ordem descentente:

nLenArray := LEN(aArray)

FOR i = nLenArray TO 1 STEP -1

<instrues>...

NEXT FUNCTION

Declara o nome de uma funo e seus parmetros formais.

Sintaxe

[STATIC] FUNCTION <idFuno>[(<idParam lista>)]

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

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

[FIELD <lista identificadores> [IN <idAlias>]

[MEMVAR <lista identificadores>]

. <corpo da funo>

RETURN <exp> Argumentos

<idFuno> o nome da funo de usurio a declarar. Nomes de funo podem ter qualquer tamanho, mas somente os 10 primeiros caracteres so considerados.Nomes podem ter qualquer combinao de caracteres, nmeros e sublinhados, mas sublinhados na primeira posio so reservados.

<idParam lista> a declarao de uma ou mais variveis parmetro.

Variveis especificadas nesta lista so declaradas local.

STATIC FUNCTION declara uma funo que pode ser invocada somente por rotinas declaradas no mesmo arquivo (.prg).

LOCAL declara e opcionalmente inicializa uma lista de variveis ou vetores que tenham visibilidade e vida til para a funo corrente.

STATIC declara e opcionalmente inicializa uma lista de variveis ou vetores que tem visibilidade na funo corrente mas vida til durante a execuo do programa.

FIELD declara uma lista de identificadores para usar quando forem encontrados nomes de campo. Se a clusula IN for especificada, referir-se ao nome especificado inclui uma referncia implcita ao alias especificado.

MEMVAR declara uma lista de identificadores para utilizar como variveis 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 funo. Cada funo deve ter ao menos um RETURN que retorne um valor. RETURN pode ocorrer em qualquer local do corpo da funo. Descrio

FUNCTION declara uma funo definida pelo usurio e opcionalmente uma lista de variveis locais para recepo de parmetros frequentemente chamados de parmetros formais. Uma funo de usurio um subprograma compreendendo um conjunto de declaraes e instrues executadas onde quer que voc faa referncia a <idFuno> seguido de abre e fecha parnteses. Uma definio de funo inicia com a declarao FUNCTION e termina com a prxima declarao FUNCTION, declarao PROCEDURE ou fim de arquivo.

Funes so usadas para encapsular um bloco de cdigo e mais tarde criar expresses usando o valor retornado. Funes e procedures, aumentam a modularidade, legibilidade, isolam modificaes e auxiliam no gerenciamento de aplicaes complexas.

Uma funo em Clipper similar a um procedure com a exceo de que retorna um valor. O valor retornado pode ser qualquer tipo de dado incluindo um vetor, bloco de cdigo ou NIL. Toda funo deve iniciar com a declarao FUNCTION e deve conter ao menos um RETURN com um argumento. Declaraes de funo no podem ser aninhadas com outras declaraes de funo. Uma funo pode ser usada em qualquer lugar onde uma funo padro pode ser usada, incluindo expresses.

A visibilidade das funes cai em duas classes. Funes que so visveis em qualquer lugar e que so denominadas funes pblicas e declaradas com FUNCTION. Funes que so visveis somente no (.prg) corrente e so denominadas funes estticas e so declaradas com STATIC FUNCTION.

Funes estticas so muito teis por vrias razoes. Primeira, elas limitam a visibilidade do nome da funo, restringindo o acesso a esta.Por causa disto, subsistemas definidos dentro de um nico (.prg) podem fornecer um protocolo de acesso com uma srie de funes pblicas e conceber os detalhes de implementao do subsistema dentro de funes e procedures. Segundo, desde que referncias para funes static so resolvidas em tempo de compilao, elas precedem referncias a funes public que so resolvidas em tempo de linker. Isto assume que dentro de um arquivo de programa, uma referncia para uma funo static executa aquela funo se existir um conflito com uma funo public. Notas

Chamando uma funo definida pelo usurio: Uma funo definida pelo usurio chamada usando a mesma notao de uma funo Clipper:

<idFuno>([<lista argumentos>])

Uma funo definida pelo usurio pode ser chamada dentro de uma expresso ou na linha pelo seu nome. Se chamada na linha pelo prprio nome, o valor de retorno ignorado.

Uma funo de usurio pode ser chamada como uma expresso com alias e entre parnteses, como por exemplo:

<idAlias>->(<idFuno>(<lista argumentos>))

Quando uma funo chamada como expresso com alias, a rea de trabalho associada com <idAlias> selecionada, a expresso executada, e a rea original selecionada novamente. Como qualquer outra expresso, uma expresso com alias pode ser invocada na linha por si mesma.

Uma funo de usurio pode chamar a si mesma de forma recursiva.

Parmetros: Funes podem receber parmetros a partir de outra funo, procedure, ou linha de comando do DOS. Em Clipper 5.0, existem duas maneiras de receber parmetros: uma lista de nomes de variveis locais pode ser declarada como parte da declarao FUNCTION (chamada de parmetros formais) ou uma lista de variveis privadas pode ser especificada em separado com uma declarao PARAMETERS. Note que as duas no podem ser misturadas. Caso o sejam, ir resultar num erro fatal de compilao.

Funes recebem parmetros na ordem em que so passados. Em Clipper, o nmero de parmetros no precisa ser igual ao nmero de argumentos enviados. Argumentos podem ser saltados ou no inclusos no final da lista. Um parmetro que no venha a receber um valor ser inicializado com NIL. Se forem especificados argumentos, PCOUNT() ir retornar a posio do ltimo argumento passado.

Parmetros especificados em funes de usurio podem receber valores passados por valor ou por referncia. O mtodo assumido para expresses e variaveis por valor. Isto inclui variveis que contenham referncias a vetores

ou objetos. Variveis que no sejam campos precedidas do operador passa por referncia (@) so passadas por referncia. Campos no podem ser passados por referncia e so sempre passados por valor. Exemplos

Este exemplo mostra uma funo destinada a formatar valores monetrios:

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

FUNCTION Currency( nNumber )

LOCAL cNumber

IF nNumber < 0

cNumber := TRANSFORM(-1 * nNumber, "@E 999.999.999.999,99")

cNumber := PADL("($" + LTRIM(cNumber) + ")", LEN(cNumber))

ELSE

cNumber := TRANSFORM(nNumber, "@E 999.999.999.999,99")

cNumber := PADL("$" + LTRIM(cNumber), LEN(cNumber))

ENDIF

RETURN cNumber

Este exemplo demonstra uma funo de usurio que toma um string que uma lista de tens separados por vrgulas e retorna um vetor com um tem por elemento:

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

FUNCTION ListAsArray( cList )

LOCAL nPos

LOCAL aList := {} // Define vetor vazio

//

DO WHILE (nPos := AT(",", cList)) != 0

AADD(aList, SUBSTR(cList, 1, nPos - 1))

// Adiciona novo elemento

cList := SUBSTR(cList, nPos + 1)

ENDDO

AADD(aList, cList)

//

RETURN aList// Retorna o vetor

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

FUNCTION MyFunc( param1, param2, param3 )

IF param2 != NIL

param2 := "valor assumido"

ENDIF

. <instrues>

RETURN NIL

Este exemplo mostra como a funo Currency() (definida acima), pode ser chamada como expresso com alias:

USE Invoices NEW

USE Customer NEW

? Invoices->(Currency(Amount)) IF

Executa um dentre vrios blocos de instrues. Sintaxe

IF <lCondio1>

<instrues>...

[ELSEIF <lCondio2>]

<instrues>...

[ELSE]

<instrues>...

END[IF] Argumentos

<lCondio> uma expresso lgica 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 <lCondio> seja avaliada como vardadeira (.T.) e todas as condies IF e ELSEIF anteriores foram avaliadas como falsas (.F.). Qualquer nmero 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.). Descrio

A estrutura de controle IF trabalha desviando a execuo para as instrues seguintes ao primeiro verdadeiro (.T.) avaliado para uma condio IF ou ELSEIF. Execuo ento continua at que um ELSEIF, ELSE, ENDIF seja encontrado, local onde a execuo ser desviada para a primeira instruo seguindo o ENDIF.

Se nenhuma condio for avaliada como verdadeira (.T.), o controle passa para a primeira instruo seguinte ao ELSE. Se um ELSE no foi especificado, o controle desviado para a primeira instruo seguindo o ENDIF.

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

A forma IF...ELSEIF...ENDIF idntica a DO CASE...ENDCASE. no existe vantagem especfica no uso de uma sobre a outra. A forma IF...ENDIF similar a funo IF() a qual pode ser usada em expresses. Exemplos

O exemplo a seguir avalia um nmero de condies usando uma construo IF...ELSEIF...ENDIF:

LOCAL nNumber := 0

//

IF nNumber < 50

? "Menor que 50"

ELSEIF nNumber == 50

? "Igual a 50"

ELSE

? "Maior que 50"

ENDIF

STATIC QUIT

Finaliza a execuo de um programa Sintaxe

QUIT | CANCEL* Descrio

Tanto o comando QUIT quanto o comando CANCEL encerram a execuo 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

Cdigo de retorno: Quando um programa Clipper termina, o cdigo de retorno ajustado para 1 se o processo acabar com um erro fatal. Se o programa terminar normalmente, o cdigo de retorno configurado para zero ou o ltimo ERRORLEVEL() ajustado no programa. Exemplos

O exemplo seguinte demonstra a atuao do comando QUIT usando uma caixa com mensagem:

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

QUIT

ENDIF

RETURN RETURN

Encerra uma funo de usurio, programa ou procedure Sintaxe

RETURN [<exp>] Argumentos

<exp> uma expresso de qualquer tipo que avaliada para ser o valor de retorno de uma funo de usurio. Se a funo terminar sem RETURN, o valor de retorno ser NIL. Descrio

RETURN encerra uma funo de usurio, programa ou procedure, devolvendo o controle para a rotina chamadora. Quando RETURN executado na rotina de nvel mais alto, controle devolvido ao sistema operacional. Todas as variveis private criadas e variveis local declaradas na rotina corrente so liberadas quando o controle devolvido ao chamador.

Pode haver mais de um RETURN numa rotina, da mesma forma que no necessrio terminar com um RETURN. Desde que funes de usurio devem retornar valores, cada uma deve conter ao menos um RETURN com um argumento. Nota

Uma funo de usurio ou procedure encerrado por uma declarao PROCEDURE, FUNCTION, ou fim de arquivo, mas no por um RETURN. Notas

Vetores: Desde que vetor um tipo de dado como qualquer outro, o mesmo pode ser retornado de uma funo de usurio.

RETURN TO MASTER: Clipper no suporta RETURN TO MASTER ou qualquer outro tipo de RETURN onde se especifique o nvel. Voc pode simular isto com BEGIN SEQUENCE...END.

Exemplos

Estes exemplos ilustram a forma geral da declarao RETURN em uma funo

ou procedure:

FUNCTION <idFunction>

//

<instrues>...

//

RETURN <expReturn>

PROCEDURE <idProcedure>

//

<instrues>...

//

RETURN

Este exemplo demonstra como um vetor criado numa funo pode ser retornado para a rotina chamadora:

FUNCTION PassArrayBack

PRIVATE aArray[10][10]

aArray[1][1] = "myString"

RETURN aArray RUN

Executa um programa ou comando DOS Sintaxe

RUN | !* <xcLinhaComando> Argumentos

<xcLinhaComando> qualquer programa executvel, inclusive os comandos residentes DOS e COMMAND.COM. Pode ser especificado literalmente ou por expresso caractere entre parnteses. Descrio

O comando RUN executa um comando ou programa DOS de dentro de uma aplicao compilada. Quando voc utiliza o comando RUN num programa DOS, o Clipper executa outra cpia de COMMAND.COM, passando a linha de comando DOS ao mesmo tempo. Isto tem duas implicaes. A primeira que voc deve ter memria 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 disponvel no local especificado pelo COMSPEC (o padro o diretrio raiz do disco onde voc carregou o DOS). Se o COMMAND.COM no estiver localizado neste disco ou o disco for trocado, mude SET COMSPEC para a nova localizao antes de executar a operao Clipper. Observe que os comandos SET DEFAULT e SET PATH no tm efeito algum sobre o comando RUN.

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

Aviso

No utilize o comando RUN para instalar programas residentes em memria de dentro do Clipper porque pode haver perda de memria quando o controle retornar ao seu programa aplicativo. Exemplos

O exemplo seguinte demonstra como utilizar o comando RUN combinado com as funes MEMOREAD() e MEMOWRIT() para criar uma funo definida por usurio 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.tmp

RETURN .T.

ELSE

RETURN .F.

ENDIF

Uma das opes que voc pode desejar oferecer a seus usurios o acesso direto ao DOS. Voc pode fazer isso com o comando:

RUN COMMAND

Para facilitar ao usurio o retorno ao programa de aplicao, mude o prompt DOS no arquivo batch de aplicao desta forma:

REM Application batch file

ECHO OFF

PROMPT Acesso ao DOS:

Digite EXIT para retornar ao programa $_$p$g <seu programa aplicativo>

PROMPT $p$g

Depois, instrua o usurio a executar o arquivo batch de aplicao em lugar do aplicativo .EXE. Comandos para gerao de relatrios e etiquetas LABEL FORM

Emite etiquetas Sintaxe

LABEL FORM <xcArquivo>

[TO PRINTER] [TO FILE <xcArquivo>]

[<abrangncia>] [WHILE <lCondio>] [FOR <lCondio>]

[SAMPLE] Argumentos

<xcArquivo> o nome do arquivo de etiquetas (.lbl) que contm a definio da forma da etiqueta e pode ser especificado literalmente ou por expresso caractere entre parnteses. Se no for especificada extenso, ser assumido (.lbl).

TO PRINTER envia a sada para a impressora.

TO FILE <xcArquivo> envia a sada para <xcArquivo>.

<XcArquivo> pode ser especificado literalmente ou por uma expresso caractere entre parnteses. Se no for especificada extenso, ser assumido (.txt).

<abrangncia> a parte do arquivo de dados corrente que dever ser usado. O padro todos (ALL) os registros.

WHILE <lCondio> especifica o conjunto de registros que atendem a condio

do registro corrente at que a condio seja falsa.

FOR <lCondio> especifica o conjunto condicional de registros de onde sero tiradas as informaes para etiquetas dentro da abrangncia dada.

SAMPLE emite etiquetas com contedo de asteriscos. Cada etiqueta texto tem o mesmo nmero de colunas e linhas da definio da etiqueta.

Aps cada exibio de etiqueta texto, aparece a pergunta, "Deseja mais amostras?". A resposta no "N" faz o comando LABEL FORM exibir as etiquetas reais para a condio e abrangncia especificadas. Descrio

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

Quando chamada, a sada enviada para a tela e opcionalmente para a impressora e/ou para um arquivo. Para evitar que a sada aparea 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 diretrio e disco correntes, caso o arquivo <xcArquivo> no seja encontrado no diretrio corrente e o path no tenha sido especificado. Notas

Interrompendo LABEL FORM: Para interromper o comando LABEL FORM, use a funo INKEY() como parte da condio FOR, verificando se acontece a interrupo 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 sadas 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 so mostradas:

USE Sales INDEX Sales NEW

LABEL FORM Sales TO PRINTER TO FILE Sales

LABEL FORM Sales TO PRINTER TO FILE Sales

Este exemplo demonstra como interromper um comando LABEL FORM usando a funo INKEY() para verificar se o usurio teclou Esc:

#define K_ESC 27

USE Sales NEW

USE Sales NEW

LABEL FORM Sales FOR INKEY() != K_ESC REPORT FORM

Exibe um relatrio no console Sintaxe

REPORT FORM <xcRelatrio>

[TO PRINTER] [TO FILE <xcArquivo>]

[<abrangncia>] [WHILE <lCondio>] [FOR <lCondio>]

[PLAIN | HEADING <cCabealho>] [NOEJECT] [SUMMARY] Argumentos

<xcRelatrio> o nome do arquivo de formato de relatrio (.frm) que contm a definio do relatrio (REPORT). Caso no haja especificao de extenso, (.frm) assumido. <xcRelatrio> uma expresso que pode ser especificada literalmente por expresso caractere entre parnteses.

TO PRINTER envia a sada para a impressora.

TO FILE <xcArquivo> envia a sada para um arquivo sem caracteres de form feed (ASCII 12). Se no for especificada extenso de arquivo, um (.txt) adicionado. <xcArquivo> uma expresso literal, ou seja, o prprio nome do arquivo, ou expresso caractere entre parnteses.

<abrangncia> a parte do arquivo de dados corrente onde atuar o comando REPORT FORM. O padro todos (ALL).

WHILE <lCondio> especifica o conjunto de registros que atendem a condio do registro corrente at que a condio seja falsa.

FOR <lCondio> especifica o conjunto condicional de registros no qual o comando ir atuar dentro da abrangncia.

PLAIN evita a exibio de data e nmero de pgina, e condiciona a impresso a ser feita sem quebras de pgina. Alm disso, o ttulo do relatrio e cabealhos de colunas aparecem apenas no incio do relatrio.

HEADING coloca o resultado de <cCabealho> na primeira linha de cada pgina. <cCabealho> avaliado somente uma vez no comeo do relatrio, antes que o ponteiro de registro seja movido. Caso ambos PLAIN e HEADING estejam especificados, PLAIN tem a preferncia.

NOEJECT evita que a pgina inicial seja ejetada quando a clusula TO PRINTER for usada.

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

REPORT FORM um comando de console que acessa sequencialmente registros na rea de trabalho corrente exibindo um relatrio tabular e opcionalmente agrupado com cabealhos de pgina e coluna a partir de uma definio existente num arquivo (.frm). O arquivo REPORT FORM real (.frm) criado utilizando-se RL.EXE ou atravs de dBASE III PLUS.

Quando chamada, a sada enviada para a tela e opcionalmente para a impressora e/ou um arquivo. Para evitar que a sada seja enviada para a tela quando da impresso 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 diretrio SET PATH corrente se o arquivo <xcRelatrio> no for encontrado no diretrio corrente e o PATH no tiver sido especificado. Notas

Interrompendo REPORT FORM: Para interromper um comando REPORT FORM,

use a funo INKEY() como parte da condio FOR para verificar a interrupo 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 sada para a impressora.

Incluindo caracteres form feed: Para incluir caracteres de alimentao de formulrio ao enviar um comando REPORT FORM TO FILE, redirecione a sada da impressora para um arquivo usando o comando SET PRINTER desta forma:

SET PRINTER TO <xcArquivo>

REPORT FORM <xcArquivo> TO PRINTER

SET PRINTER TO

Relatrios em ambientes de rede: Comandos REPORT FORM em ambientes de rede podem ser afetados por mudanas feitas em arquivos de dados por outros usurios enquanto o relatrio est sendo executado. Por exemplo, se um usurio mudar um valor chave de "A"

para "Z" enquanto o relatrio estiver sendo impresso, o mesmo registro poder aparecer repetido. Exemplos

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

LOCAL xcReport := "Sales"

USE Sales INDEX Sales NEW

REPORT FORM (xcReport) TO PRINTER FOR Branch != "100"

Este exemplo demonstra como interromper um comando LABEL FORM

usando a funo INKEY() para verificar se o usurio teclou Esc:

#define K_ESC 27

USE Sales NEW

LABEL FORM Sales FOR INKEY() != K_ESC EJECT

Avana a cabea da impressora para o comeo da pgina Sintaxe

EJECT Descrio

O comando EJECT envia um caractere de form feed (ASCII 12) impressora e ajusta os valores das funes PCOL() e PROW() para zero. Se voc especificar uma linha e coluna da impressora menores que a ltima posio dada por um comando EJECT ou uma funo SETPRC(), o Clipper automaticamente realiza um EJECT e reconfigura os valores internos das funes PROW() e PCOL(). Por causa disso, a sua lgica de impresso deve proceder sequencialmente da esquerda para a direita e para o fim da pgina. Caso voc necessitar reconfigurar linha e coluna da impressora para zero sem mudana de pgina, use a funo SETPRC().

Exemplos

Este exemplo imprime um relatrio em forma de listagem simples e usa o comando EJECT para avanar para uma nova pgina quando o contador de linhas chega ao nmero mximo de linhas a ser impresso por pgina:

LOCAL nLine := 99, nPage := 0

USE Sales NEW

SET PRINTER ON

SET CONSOLE OFF

DO WHILE !EOF()

IF nLine > 55

EJECT

? "Pagina " + LTRIM(STR(nPage++, 3))

? "Data " + CTOD(DATE())

? "Vendedor ", "Quantia"

nLine := 6

ENDIF

? Sales->Salesman, Sales->Amount

nLine++

SKIP

ENDDO

SET PRINTER OFF

SET CONSOLE ON

CLOSE Outros comandos para configurao do ambiente SET BELL

Determina se haver alarme sonoro automtico durante operaes de entrada de dados Sintaxe

SET BELL on | OFF | <xlComuta> Argumentos

ON possibilita o alarme.

OFF impossibilita o alarme.

<xlComuta> uma expresso lgica que deve ser colocada entre parntses. Um valor de verdadeiro (.T.) o mesmo que ON, e um valor de falso (.F.) o mesmo que OFF. Descrio

Se o comando SET BELL estiver em ON, o alarme soa nas seguintes situaes:

O usurio entra um caractere na ltima posio em um GET.

O usurio tenta entrar dados invlidos num GET. Os dados so validados pelo tipo de dado da varivel GET, pelo template de PICTURE, e pela clusula RANGE. Violar uma condio VALID no faz o alarme soar, no importando qual o status do comando SET BELL.

Para soar o alarme mais claramente voc pode usar ?? CHR(7) ou a funo TONE().

TONE() talvez seja o mais til, pois com ele voc pode variar o tom e a durao do som. SET COLOR*

Define cores de tela.

Sintaxe

SET COLOR | COLOUR TO [<padro>

[, <destaque>][, <borda>][, <fundo>]

[, <noselecionados>]] | (<cStringCor>) Argumentos

<padro> a cor utilizada para escrever em toda a tela do vdeo, incluindo a utilizao de todos os comandos e funes quando exibidas na tela. Isto inclui comandos como @...PROMPT, @...SAY, e ?; e funes como ACHOICE(), DBEDIT(), e MEMOEDIT().

<destaque> a cor utilizada para configurar a exibio das barras luminosas. Este argumento influi sobre a barra luminosa de seleo sobre os GETs com INTENSITY ON, o comando MENU TO, a funo DBEDIT(), e ACHOICE().

<borda> a cor utilizada para configurar a cor que ser colocada na rea em torno da tela de vdeo, que inacessvel para a utilizao normal dos programas que escrevem algo na tela. Esta configurao somente funciona com adaptadores de vdeo do tipo CGA, mas no com

adaptadores EGA ou VGA.

<fundo> atualmente no suportada por mquinas nas quais a Nantucket no prov drivers apropriados. Esta configurao suportada somente para propsitos de compatibilidade.

<noselecionados> 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 so mostrados nesta cor.

<cStringCor> uma cadeia de caracteres contendo a configurao de cores. Esta cadeia de caracteres pode ainda ser guardada em uma varivel de memria, sendo utilizada no comando englobando-a com parnteses. Esta facilidade permite a voc especificar a configurao de cores como sendo uma expresso, no lugar de utilizar um simples literal (cadeia de caracteres) ou mesmo uma macro-substituio de uma varivel.

SET COLOR TO sem argumentos restaura as cores padro para W/N,N/W,N,N,N/W. Descrio

SET COLOR um comando sinnimo para a funo SETCOLOR() que define cores para as operaes subsequentes de escrita em tela. Cada comando SET COLOR especifica uma lista de argumentos para as cores utilizadas nos cinco tipos de operaes de escrita em tela. Cada configurao 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 sero exibidos na tela. A cor de fundo do caractere define que cor ser exibida atrs do caractere.

Espaos e quaisquer caracteres que no sejam exibveis so considerados somente como cor de fundo do caractere.

Alm das cores, uma configurao para a cor do caractere pode ter um atributo de alta intensidade ou piscante. Com um vdeo do tipo monocromtico, a alta intensidade aumenta o brilho do texto escrito.

Com um vdeo 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 no a intervalos regulares. O atributo de Piscante identificado pelo sinal *. Um

caractere de atributo pode estar colocado em qualquer lugar da configurao, mas sempre aplicado cor do caractere, portanto as cores de fundo dos caracteres no possuem os atributos de Alta Intensidade e Piscante.

Cada cor pode ser especificada utilizando uma letra ou nmero.

Entretanto, a especificao de nmeros fornecida somente para propsitos de compatibilidade. Quando for especificado um argumento de configurao de cor, nmeros e letras no devem ser misturados.

Todos os argumentos so opcionais. Se um argumento for omitido, seu valor anterior retido e somente os novos so configurados. Dentro de uma configurao, a omisso da cor do caractere ou da cor de fundo do caractere torna esta cor com o padro preto.

Veja na pgina seguinte as cores suportadas. Tabela 4-13: Tabela de Cores

Cor

Letra

Nmero

Monocromtico

Preto

N,Espao

Preto

Azul

Sublinhado

Verde

Branco

Ciano

BG

Branco

Vermelho

Branco

Magenta

RB

Branco

Marrom

GR

Branco

Branco

Branco

Cinza

N+

Preto

Azul Brilahnte

B+

Sublinhado Brilhante

Verde Brilhante

G+

10

Branco Brilhante

Ciano Brilhante

BG+

11

Branco Brilhante

Verme lho Brilhante

R+

12

Branco Brilhante

Magenta Brilhante

RB+

13

Branco Brilhante

Amarelo

GR+

14

Branco Brilhante

Branco Brilhante

W+

15

Branco Brilhante

Preto

Sublinhado

Vdeo Inverso

Vdeo Inverso

Incolor

Incolor

SET COLOR um comando de compatibilidade e assim sendo no recomendado. Ele superado pela funo SETCOLOR(), que pode retornar tanto a cor corrente que est sendo utilizada no momento como tambm configurar uma nova cor. Notas

Monitores monocromticos: Nos monitores monocromticos, as cores no so suportadas. O Clipper, contudo, suporta os atributos monocromticos de vdeo reverso (I) e sublinhado (U).

Drivers de tela: O comando SET COLOR TO utilizando nmeros no suportado caso seja linkado o ANSI.OBJ com o programa corrente. Exemplos

O exemplo seguinte utiliza a configurao para os GETs no 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 cTwo

READ

Este exemplo demonstra uma funo definida pelo usurio (UDF) para obter uma senha do usurio utilizando o argumento de destaque com o tipo de cor (X) para esconder a senha que est sendo digitada pelo usurio:

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 cUserEntry

READ

IF LASTKEY() == 27

SETCOLOR(cColor)

RETURN .F.

ELSEIF cUserEntry == cPassword

SETCOLOR(cColor)

RETURN .T.

ELSE

nCount++

ENDIF

ENDDO

SETCOLOR(cColor)

RETURN .F. SET CURSOR

Comuta a visibilidade do cursor em tela. Sintaxe

SET CURSOR ON | off | <xlComuta> Argumentos

ON Torna o cursor visvel.

OFF Torna o cursor invisvel.

<xlComuta> uma expresso lgica que deve ser colocada entre parnteses. O valor de verdadeiro (.T.) o mesmo que ON, e o valor falso (.F.) tem o mesmo

significado que OFF. Descrio

SET CURSOR comuta o estado do cursor entre ON e OFF (ligado e desligado). Quando o CURSOR est OFF, entradas via teclado e exibies em tela no so afetadas. O cursor simplesmente escondido, podendo a entrada de dados ser efetuada sem que o cursor esteja visvel. As funes ROW() e COL() so atualizadas como se o cursor estivesse vsivel.

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 produo quando o usurio se encontrar no modo de edio, ou seja, utilizando GETs, MEMOEDIT(), ou algum outro tipo de modo de edio. Exemplos

O exemplo seguinte mostra a utilizao tpica do SET CURSOR:

LOCAL lAnswer := .F.

@ 24, 0

@ 24, 15 SAY "Deseja encerrar [S/N]?";

GET lAnswer PICT "@!";

SET CURSOR ON

READ

SET CURSOR OFF SET DATE

Configura o formato de datas para entrada de dados e exibio em tela Sintaxe

SET DATE FORMAT [TO] <cFormatoData>

SET DATE [TO]

AMERICAN | ansi | british | french | german | italian | japan | usa Argumentos

<cFormatoData> uma extresso caractere que especifica diretamente o formato de data quando a clusula FORMAT especificada.

<cFormatoData> deve conter um string de 12 ou menos caracteres.

Quando especificado, <cFormatoData> analisado para determinar a colocao adequada dos digitos de mes, dia e ano. A posio destes determinada baseada na posio das letras, d, m e y, respectivamente.

Outros caracteres so copiados como estao para exibio de valores de data. Descrio

O SET DATE uma configurao global que afeta o comportamento das datas em todo o programa, permitindo a voc controlar a formatao das datas de forma a facilitar o envio de aplicativos a outros pases.

A tabela a seguir ilustra os formatos de datas para cada configurao de data: Tabela 4-14: Formatos SET DATE

SET

Formato

AMERICAN

mm/dd/yy

ANSI

yy.mm.dd

BRITISH

dd/mm/yy

FRENCH

dd/mm/yy

GERMAN

dd.mm.yy

ITALIAN

dd-mm-yy

JAPAN

yy/mm/dd

USA

mm-dd-yy Exemplos

O exemplo a seguir configura um programa para o devido ajuste de datas em tempo de execuo. Isto feito passando-se uma varivel ambiental DOS para o programa, carregando-se seu valor com a funo GETENV(), e ajustando a data com o valor que foi carregado. Para comear, o formato da data atribudo a

uma varivel ambiental DOS da seguinte forma:

SET CLIP_DATE=BRITISH

Depois na seo de configurao do programa de aplicao:

FUNCTION AppConfig

SET 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 padro dois.

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

Descrio

O comando SET DECIMALS determina a quantidade de casas decimais que sero exibidas nos resultados das funes e clculos numricos. Sua operao depende diretamente da configurao afixada. Se FIXED estiver em OFF, SET DECIMALS estabelece o nmero mnimo de casas decimais exibidas pelas funes EXP(), LOG(), SQRT(), e operaes de diviso.

Caso FIXED esteja em ON, todos os valores numricos so exibidos com a quantidade exata de casas decimais especificada pelo comando SET DECIMALS. Observe que nem SET DECIMALS nem SET FIXED afetam a preciso numrica dos clculos--somente o formato de exibio afetado.

A fim de obter um melhor controle da exibio numrica, voc pode utilizar-se da clusula PICTURE de @...SAY, @...GET, e da funo TRANSFORM(). Exemplos

Os exemplos a seguir ilustram vrios resultados do comando SET

DECIMALS:

SET FIXED ON

SET DECIMALS TO 2 // O padro

? 2/4 // Resulta: 0.50

? 1/3 // Resulta: 0.33

SET 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 variveis GET.

OFF suprime a exibio de delimitadores.

<xlComuta> uma expresso lgica que deve ser colocada entre parnteses. 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 especificao de um nico caractere usa o mesmo caractere como o delimitador inicial e final. A especificao de dois caracteres usa o primeiro como o delimitador inicial e o segundo como o delimitador final. A especificao padro (DEFAULT) ou sem delimitadores ajusta os delimitadores para sinais de dois pontos, que so os delimitadores padro. Descrio

SET DELIMITERS um comando com a finalidade dupla de definir caracteres usados para delimitar os GETs e determinar que os delimitadores sejam ou no 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 exibio do campo GET.

Os caracteres dos delimitadores podem ser configurados utilizando-se a clusula TO <cDelimitador>. O caractere de demilimitador padro 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 espao no lugar do caractere delimitador.

Regra geral, os delimitadores no so necessrios j que os GETs so exibidos em vdeo reverso ou cor destacada se INTENSITY estiver em ON. Exemplos

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

LOCAL cVar := SPACE(5), cVar2 := SPACE(5)

SET DELIMITERS ON

SET DELIMITERS TO ": "

@ 1, 0 SAY "Entre" GET cVar

SET 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. Descrio

O comando SET DEVICE envia a sada dos comandos @...SAY para a tela ou para a impressora. Quando DEVICE est em SET TO PRINTER, os comandos @...SAY so enviados impressora e no so repetidos para a tela. Os comandos @...GET so ignorados.

Ao enviar os comandos @...SAY impressora, o Clipper executa um EJECT automtico sempre que a posio da cabea da impressora estiver numa linha menor do que a ltima linha impressa. Um EJECT reajusta os valores das funes PCOL() e PROW() para zero. Para reajustar PCOL() e PROW() para novos valores, use a funo 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.txt

SET DEVICE TO PRINTER

@ 10, 10 SAY "Arquivo: Output.txt"

@ 11, 10 SAY DATE()

SET PRINTER TO // Fecha o arquivo

SET DEVICE TO SCREEN

SET FILTER

Esconde registros que no atendam uma condio Sintaxe

SET FILTER TO [<lCondio>] Argumentos

<lCondio> uma expresso lgica que define um conjunto especfico de registros das rea de trabalho corrente que sejam acessveis para processamento.

SET FILTER TO sem um argumento desativa a condio filtro. Descrio

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

A maioria dos comandos e funes que movem o ponteiro de registros obedece ao filtro corrente, com exceo daqueles comandos que acessam registros atravs do nmero dos mesmos. Isto inclui GOTO, comandos especificados com a clusula RECORD, e relaes conectadas por expresso numrica a uma rea de trabalho que no possua nenhum ndice ativo.

Uma vez estabelecido, um FILTER no ativado at que o ponteiro de registro seja movido de sua posio corrente. Voc pode utilizar GO TOP para ativ-lo.

Tal como SET DELETED, um filtro no 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 parea conter um subconjunto de registros, este comando na realidade processa sequencialmente todos os registros na rea de trabalho. Por esta razao, o tempo necessrio para o processamento de uma rea de trabalho filtrada ser o mesmo que numa rea de trabalho no filtrada. Exemplos

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

USE Employee INDEX Name NEW

SET FILTER TO Age > 50

LIST Lastname, Firstname, Age, Phone

SET 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> no especificada, a definio corrente liberada. Descrio

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 exceo de INKEY(). Estes modos incluem ACHOICE(), DBEDIT(), MEMOEDIT(), ACCEPT, INPUT, READ e WAIT.

Aps uma tecla ser redefinida, pressionando-a executa a rotina corente passando automaticamente trs parmetros correspondentes a: PROCNAME(), PROCLINE(), e READVAR(). O nome da rotina e da varivel so caractere, enquanto que nmero de linha numrico.

Um mximo de 32 teclas pode ser definido ao mesmo tempo. No start-up (incio da execuo), o sistema automaticamante define F1 para executar uma rotina de Help (auxlio). Se uma rotina com este nome linkada junto do programa corrente e est visvel, apertando F1 a partir de um estado de espera ir invoclo.

Note que rotinas de SET KEY devem ser desenhadas de modo a preservar o estado da aplicao (isto , aparncia da tela, rea de trabalho corrente, etc) e restaur-la aps encerrar a execuo. 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 nmero de tecla e vice versa. Isto incompatvel com verses prvias, as quais mantinham listas separadas para SET KEY e SET FUNCTION.

Notas

Precedncia: SET KEY tem precedncia sobre SET ESCAPE e SETCANCEL().

Terminando READ a partir de SET KEY: Existem vrias formas de terminar um READ a partir de SET KEY. Tabela 4-16: Encerrando um READ a partir de uma rotina SET KEY

Comando

Ao

CLEAR GETS

Encerra o READ sem gravar o GET corrente

BREAK

Encerra o READ sem gravar o GET corrente

KEYBOARD Ctrl-W

Encerra o READ e grava o GET corrente

KEYBOARD Esc

Encerra o READ sem gravar o GET corrente

CLEAR com SET KEY: CLEAR no 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 usurio aperta F2 estando numa tela de entrada de dados:

#include"Inkey.ch"

SET KEY K_F2 TO ScrollAccounts

USE Accounts NEW

USE Invoices NEW

@ 10, 10 GET Invoices->Id

READ

RETURN

FUNCTION ScrollAccounts( cProc, nLine, cVar )

LOCAL s_creen

IF 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)

ELSE

TONE(100, 2)

ENDIF

RETURN NIL SET PRINTER

Comuta o eco da sada do console para impressora ou arquivo Sintaxe

SET PRINTER on | OFF | <xlComuta>

SET PRINTER TO [<xcDispositivo> | <xcArquivo>] Argumentos

ON ecoa sada de console para a impressora.

OFF suprime a impresso da sada de console.

<xlComuta> uma expresso entre parnteses. Um valor verdadeiro (.T.) ON, e falso (.F.) OFF.

TO <xcDispositivo> identifica o nome do dispositivo (DEVICE) para onde ser enviada a sada impressa. Um nome de dispositivo pode ser especificado literalmente ou como expresso caractere entre parnteses. Adicionalmente, um dispositivo pode ser local ou rede.

Configurar SET PRINTER para um dispositivo no existente cria um arquivo com o nome deste. Assegure-se de no utilizar dois pontos (:) como caractere inicial de nome de dispositivo.

TO <xcArquivo> identifica o nome do arquivo de sada. O nome pode ser especificado literalmente ou como expresso caractere entre parnteses. Se a extenso no for especificada (.prn) adicionada automaticamente.

Caso SET PRINTER TO seja especificado sem argumentos, o dispositivo especificado fechado e o destino padro selecionado. Descrio

SET PRINTER, da mesma forma que outros SETs, tem duas formas de uso com sua funcionalidade prpria. A forma on|OFF de SET PRINTER controla se a sada ser enviada ou no para a impressora. Comandos de console so aqueles em que geralmente no se especifica linha e coluna. Todos estes comandos, exceto ?|??, possuem a clusula TO PRINT que tambm dirige a sada para a impressora. A sada de comandos de console enviada para tela a menos que CONSOLE esteja OFF. Esteja advertido que @...SAYs no so afetados por SET PRINTER ON. Para envi-los para impressora use SET DEVICE TO PRINTER.

SET PRINTER TO, ao contrrio, determina o destino da sada de todos os comandos e funes que enviam sada para impressora. Isto inclui @...SAYs se SET DEVICE TO PRINTER. A sada pode ser enviada para um dispositivo ou arquivo. Se o destino um arquivo, Os seguintes nomes so vlidos: LPT1, LPT2, LPT3 (todas portas paralelas), COM1, e COM2 (portas seriais) e PRN. O assumido PRN.

Se o destino arquivo, ele criado no diretrio DEFAULT corrente. Se um arquivo com o mesmo nome existir no mesmo local, ele sobregravado sem nenhum aviso. Todas as sadas para impressora sero escritas neste arquivo at que seja fechado com SET PRINTER TO sem argumento.

Existem vrios usos para SET PRINTER TO, incluindo:

Alternar portas para gerenciar mltiplas impressoras.

Sada em arquivo para posterior impresso, ou transferncia para outra mquina via telecomunicao.

Esvaziar o spool de impresso e reselecionar o dispositivo padro. Notas

Compatibilidade: O Clipper no suporta a sintaxe SET PRINTER TO \\SPOOLER ou \\CAPTURE. Especificar SET PRINTER com estas opes cria arquivos Spooler.prn ou Capture.prn. Os smbolos \\ so ignorados.

Marcas de fim de arquivo: Quando a sada em impressora redirecionada para um arquivo, a marca de fim de arquivo (CHR(26)) no 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 estao deve ser primeiro redirecionada para o servidor de arquivo (geralmente rodando o spooler de rede). Exemplos

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

USE Customers NEW

SET PRINTER ON

SET CONSOLE OFF

DO WHILE !EOF()

? Customer

SKIP

ENDDO

EJECT

SET PRINTER OFF

SET CONSOLE ON

CLOSE

RETURN

Este exemplo direciona a sada em LPT1 e esvazia o spooler aps completar a impresso:

SET PRINTER TO LPT1

<Comandos de impresso>...

SET PRINTER TO // Esvazia o spooler.

Este exemplo envia a sada de impressora para um arquivo texto, sobregravando um arquivo j existente:

SET PRINTER TO Prnfile.txt

SET DEVICE TO PRINTER

SET PRINTER ON

@ 0, 0 SAY "Isto vai para Prnfile.txt"

? "Assim como isto!"

SET DEVICE TO SCREEN

SET PRINTER OFF

SET PRINTER TO // Fecha arquivo de impresso

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 extenso opcional. Caso no seja especificada, (.prg) assumida.

SET PROCEDURE TO sem argumentos ignorado. Descrio

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 no recomendado. Ele superado por outras instrues como #include e os arquivos script (.clp). SET UNIQUE*

Comuta a incluso de chaves no-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 expresso lgica entre parnteses. Um valor verdadeiro (.T.) o mesmo que ON, e falso (.F.) OFF. Descrio

SET UNIQUE controla se um ndice ser criado com atributo de unicidade ou no. Com UNIQUE ON, novos ndices so criados incluindo apenas chaves nicas. Se, durante o processo de indexao, 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 sero mantidos. O ndice mantm 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 implicaes 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 visvel no traz tona outro registro com a mesma chave quando o ndice reconstrudo com REINDEX, PACK, ou INDEX...UNIQUE.

Com UNIQUE OFF, ndices so criados com todos os registros no ndice.

Modificaes 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 no recomendado.

Ele superado pela clusula UNIQUE no comando INDEX. SET WRAP

Comuta rotao 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 rotao num menu de barra.

<xlComuta> uma expresso lgica entre parnteses. Um valor verdadeiro (.T.) o mesmo que ON, e falso (.F.) o mesmo que OFF. Descrio

SET WRAP comuta a rotao 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. Tambm 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, no causam nenhuma ao. Funes Funes numricas ABS()

Retorna o valor absoluto de uma expresso numrica Sintaxe

ABS(<nExp>) --> nPositivo Argumentos

<nExp> a expresso numrica a ser avaliada. Retorno

ABS() retorna um nmero que representa o valor absoluto de seu argumento. O valor retornado um nmero positivo ou zero. Descrio

ABS() uma funo numrica utilizada para determinar a magnitude de um valor numrico independente de seu sinal. Ela permite, por exemplo, que voc obtenha a diferena entre dois nmeros como um valor positivo sem saber com antecedncia 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 contrrio, ABS(x) retorna -x. Exemplos

Os exemplos a seguir ilustram resultados tpicos da funo ABS():

nNum1 := 100

nNum2 := 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 numrico ser calculado. Retorno

EXP() retorna um valor numrico equivalente ao valor de e elevado potncia especificada. Descrio

EXP() uma funo matemtica que calcula e**x, onde e a base do logaritmo natural e x o <nExpoente>. O valor mximo de <nExpoente> 45 antes que ocorra um excedente numrico. EXP() e LOG() so funes inversas.

A quantidade de casas decimais exibidas determinada unicamente por SET DECIMALS, no importando o valor corrente de SET FIXED. Exemplos

Este exemplo demonstra vrias invocaes de EXP():

? EXP(1) // Resulta: 2.72

SET DECIMALS TO 10

? EXP(1) // Resulta: 2.7182818285

? LOG(EXP(1)) // Resulta: 1.0000000000 INT()

Converte um valor numrico para um inteiro Sintaxe

INT(<nExp>) --> nInteiro Argumentos

<nExp> uma expresso numrica a ser convertida para um inteiro. Retorno

INT() retorna um valor numrico inteiro. Descrio

INT() uma funo numrica que converte um valor numrico para um inteiro truncando--e no arredondando--todos os dgitos direita do ponto decimal. INT() til em operaes onde a poro decimal de um nmero no necessria. Exemplos

O exemplo a seguir demonstra os resultados de vrias invocaes da funo INT():

? INT(100.00)// Resulta: 100

? INT(.5) // Resulta: 0

? INT(-100.75) // Resulta: -100 LOG()

Calcula o logaritmo natural de um valor numrico Sintaxe

LOG(<nExp>) --> nLogNatural Argumentos

<nExp> um valor numrico maior do que zero a ser convertido para seu logaritmo natural. Retorno

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

LOG() uma funo numrica que calcula o logaritmo natural de um nmero, sendo o inverso da funo EXP(). O logaritmo natural tem como base e, que aproximadamente 2,7183. A funo LOG() retorna x na seguinte equao:

e**x = y

onde y a expresso numrica utilizada como o argumento LOG() (ou seja, LOG(y) = x). Devido ao arredondamento matemtico, os valores retornados por LOG() e EXP() podem no coincidir exatamente (isto , EXP(LOG(x)) pode no ser sempre igual a x). Exemplos

Os exemplos a seguir demonstram vrios 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 funo de usurio que retorna o logaritmo de base 10:

FUNCTION Log10( nNum )

IF nNum > 0

RETURN LOG(nNum)/LOG(10)

ELSE

RETURN NIL

ENDIF MOD()*

Retorna o mdulo dBASE III PLUS de dois nmeros

Sintaxe

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

<nDividendo> o dividendo da operao de diviso.

<nDivisor> o divisor da operao de diviso. Retorno

MOD() retorna um nmero que representa o resto de <nDividendo> dividido por <nDivisor>. Descrio

MOD() uma funo numrica que corresponde funo MOD() do dBASE III PLUS. Ela implementada usando o operador mdulo (%) do Clipper. Note que h diferenas entre a funo MOD() do dBASE III PLUS e o operador mdulo do Clipper, que estao descritas na tabela seguinte:

Tabela 5-25: Diferenas entre a funo MOD() do dBASE III PLUS e o Operador Mdulo do Clipper

Dividendo

Divisor

Operador Mdulo

MOD()

Funo MOD() no dBASE III Plus

Erro

Erro

-2

-1

-1

-3

-1

-3

Erro

Erro

-3

-1

-1

-2

-2

-3

-1

-1

-3

-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 contrrio, o mdulo de qualquer dividendo utilizando um divisor zero causa um erro em tempo de execuo.

Divisor zero em verses anteriores: Em verses anteriores Summer '87 do Clipper, operaes de mdulo com divisor zero retornavam zero para todos os dividendos. Na verso Summer '87 e posteriores, elas retornam um erro em tempo de execuo.

ROUND()

Retorna um valor numrico arredondado para uma quantidade especificada de dgitos. Sintaxe

ROUND(<nNmero>, <nDecimais>) --> nArredondado Argumentos

<nNmero> o valor numrico a ser arredondado.

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

ROUND() retorna um valor numrico. Descrio

ROUND() uma funo numrica que arredonda <nNmero> para a quantidade de casas especificada por <nDecimais>. Especificando-se um valor zero ou negativo para <nDecimais> permite o arredondamento de nmeros inteiros. Um <nDecimais> negativo indica a quantidade de casas esquerda do ponto decimal a serem arredondadas. Dgitos entre cinco e nove, inclusive, so arredondados para cima. Dgitos abaixo de cinco so arredondados para baixo.

A exibio do valor de retorno no obedece cofigurao de DECIMALS, a no ser que SET FIXED esteja ON. Com SET FIXED OFF, a exibio do valor de retorno contm 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 dgitos decimais:

SET DECIMALS TO 2

SET 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 numricos para valores numricos 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 nmero positivo. Sintaxe

SQRT(<nNmero>) --> nRaiz Argumentos

<nNmero> um nmero positivo do qual ser calculada a raiz quadrada. Retorno

SQRT() retorna um valor numrico calculado com preciso dupla. A quantidade de casas decimais exibidas determinada apenas por SET DECIMALS, sem importar a configurao de SET FIXED. Um nmero negativo <nNmero> retorna zero. Descrio

SQRT() uma funo numrica utilizada em qualquer lugar em um clculo numrico para computar uma raiz quadrada. Por exemplo, pode ser o caso de uma expresso para calcular o desvio padro de um conjunto de nmeros. Exemplos

Estes exemplos ilustram vrios 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 Funes Caracteres ALLTRIM()

Remove espaos em branco direita e esquerda de uma cadeia de caracteres Sintaxe

ALLTRIM(<cString>) --> cTrimString Argumentos

<cString> a expresso caractere cujos espaos em branco sero eliminados. Retorno

ALLTRIM() retorna uma cadeia de caracteres cujos espaos em branco direita e esquerda foram removidos. Descrio

ALLTRIM() uma funo de tratamento de dados do tipo caractere que remove os espaos em branco direita e esquerda de uma cadeia de caracteres. relacionada a LTRIM() e RTRIM(), que removem espaos em branco esquerda e direita de uma cadeia de caracteres, respectivamente. O inverso de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres atravs da nsero de caracteres de preenchimento. Exemplos

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

cString := SPACE(10) + "string" + SPACE(10)

? LEN(cString) // Resulta: 26

? LEN(ALLTRIM(cString)) // Resulta: 6 CHR()

Converte um cdigo ASCII para um valor caractere Sintaxe

CHR(<nCodigo>) --> cCar Argumentos

<nCodigo> um cdigo ASCII na faixa de zero a 255. Retorno

CHR() retorna um nico valor caractere cujo cdigo ASCII est especificado em <nCodigo>. Descrio

CHR() uma funo de converso numrica que converte um cdigo ASCII para um caractere. o inverso de ASC(). CHR() muito verstil e serve para uma srie de operaes comuns tais como:

Enviar cdigos de controle e caracteres grficos 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 vrios argumentos:

? CHR(72) // Resulta: H

? CHR(ASC("A") + 32) // Resulta: a

? CHR(7) // Resulta: alarme soa

Estas duas linhas de cdigo demonstram a diferena entre uma cadeia de caracteres nula e um caractere nulo:

? LEN("") // Resulta: 0

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

Remove os espaos em branco esquerda de uma cadeia de caracteres. Sintaxe

LTRIM(<cString>) --> cStringResult Argumentos

<cString> a cadeia de caracteres a ser copiada sem os espaos em branco esquerda. Retorno

LTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres nula ("") ou toda composta de espaos em branco, LTRIM() retorna uma cadeia de caracteres nula (""). Descrio

LTRIM() uma funo de tratamento de caracteres utilizada para formatar cadeias de caracteres que possuam espaos em branco esquerda. Pode ser o caso de, por exemplo, nmeros convertidos para cadeias de caracteres atravs da funo STR().

LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a ALLTRIM(), que remove espaos tanto esquerda quanto direita. O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs da insero de caracteres de preenchimento. Exemplos

Os exemplos a seguir ilustram LTRIM() utilizada em combinao com vrias outras funes:

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 mximo 65.535 (64K) bytes. Se for especificado zero como o argumento <nCont> retorna uma cadeia de caracteres nula (""). Descrio

REPLICATE() uma funo de tratamento de caracteres utilizada para exibir, imprimir, ou preencher o teclado repetidamente com um ou mais caracteres. REPLICATE() semelhante funo 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 vrias teclas Cursor para baixo:

#include "Inkey.ch"

KEYBOARD REPLICATE(CHR(K_DN), 25) SPACE()

Retorna um string de espaos. Sintaxe

SPACE(<nCont>) --> cEspaos Argumentos

<nCont> a quantidade de espaos a serem retornados, sendo que o nmero mximo 65.535 (64K). Retorno

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

SPACE() uma funo de tratamento de caracteres utilizada para retornar uma quantidade especificada de espaos. o mesmo que REPLICATE(" ", <nCont>). SPACE() utilizada para inicializar uma varivel do tipo caractere, antes que a mesma seja associada a um GET. SPACE() tambm usada para preencher cadeias de caracteres com espaos. Observe, porm, que as funes PADC(), PADL(), e PADR() so mais eficazes neste caso. Exemplos

Este exemplo utiliza SPACE() para inicializar uma varivel para entrada de dados:

USE Customer NEW

MEMVAR->Name := SPACE(LEN(Customer->Name))

@ 10,10 SAY "Nome do Cliente:" GET MEMVAR->Name

READ STR()

Converte uma expresso numrica para uma cadeia de caracteres. Sintaxe

STR(<nNmero>, [<nTamanho>], [<nDecimais>]) --> cNmero Argumentos

<nNmero> a expresso numrica a ser convertida para uma cadeia de caracteres.

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

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

STR() retorna <nNmero> formatado como uma cadeia de caracteres. Se os argumentos opcionais de tamanho e decimais no foram especificados, STR() retorna a cadeia de caracteres conforme as seguintes regras: Tabela 5-32: Resultados de STR() sem Argumentos

Expresso

Tamanho do Valor de Retorno

Varivel

Campo Tamanho do campo mais decimais

Expresses/constantes

Mnimo de 10 dgitos mais decimais

VAL()

Mnimo de 3 dgitos

MONTH()/DAY()

3 dgitos

YEAR()

5 dgitos

RECNO()

7 dgitos Descrio

STR() uma funo que converte valores numricos para cadeias de caracteres. Ela comumente utilizada para concatenar valores numricos a cadeias de caracteres. STR() aplicada na exibio de nmeros, criao de cdigos tais como nmeros de produtos, e criao de chaves de indexao que combinam dados do tipo numrico e caractere.

STR() semelhante a TRANSFORM(), que formata valores numricos como cadeias de caracteres utilizando uma mscara ao invs de especificaes de tamanho e decimais. Como TRANSFORM() usa uma mscara, ela pode inserir caracteres de formatao tais como vrgulas, cifroes, e parnteses.

O inverso de STR() VAL(), a qual converte nmeros presentes em cadeias de caracteres em valores numricos. Notas

Se <nTamanho> for menor do que a quantidade de dgitos numricos inteiros em <nNmero>, STR() retorna asteriscos ao invs do nmero.

Caso <nTamanho> seja menor do que a quantidade de dgitos decimais necessrios parte decimal da cadeia de caracteres retornada, o Clipper arredonda o nmero para a quantidade de casas decimais disponveis.

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 nmeros de ordem e nomes de clientes:

USE Customer NEW

INDEX ON STR(NumOrders, 9) + CustName TO CustOrd SUBSTR()

Extrai um substring de uma cadeia de caracteres. Sintaxe

SUBSTR(<cString>, <nIncio>, [<nCont>]) --> cSubstring Argumentos

<cString> a cadeia de caracteres da qual ser extraido um substring, podendo

ter at 65.535 (64K) bytes, que o tamanho mximo de uma cadeia de caracteres em Clipper.

<nIncio> a posio inicial em <cString>. Se <nIncio> for positivo, ele relativo ao caractere mais esquerda em <cString>. Se <nIncio> for negativo, ele relativo ao caractere mais direita em <cString>.

<nCont> a quantidade de caracteres a serem extraidos. Se omitido, o substring comea em <nIncio> e continua at o fim da cadeia de caracteres. Se <nCont> for maior do que a quantidade de caracteres existentes a partir de <nIncio> at o final de <cString>, o excedente ignorado. Retorno

SUBSTR() retorna uma cadeia de caracteres. Descrio

SUBSTR() uma funo de tratamento de caracteres que extrai um substring de qualquer outra cadeia ou campo memo. SUBSTR() est relacionada s funes LEFT() e RIGHT(), que extraem substrings que comeam com os caracteres mais esquerda e mais direita em <cString>, respectivamente.

As funes SUBSTR(), RIGHT(), e LEFT() so utilizadas juntamente com as funes AT() e RAT() para localizar a primeira e/ou ltima posio de um substring antes de extrai-lo. Elas tambm so 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 varivel:

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 funo definida pelo usurio com a finalidade de extrair um nome de arquivo de uma especificao dada:

? FileBase("C:\PRG\MYFILE.OBJ") // Resulta: MYFILE.OBJ

FUNCTION FileBase( cFile )

LOCAL nPos

IF (nPos := RAT("\", cFile)) != 0

RETURN SUBSTR(cFile, nPos + 1)

ELSEIF (nPos := AT(":", cFile)) != 0

RETURN SUBSTR(cFile, nPos + 1)

ELSE

RETURN cFile

ENDIF UPPER()

Converte caracteres minsculos para maisculos. Sintaxe

UPPER(<cString>) --> cStringMaiusc Argumentos

<cString> a cadeia de caracteres a ser convertida. Descrio

UPPER() uma funo de tratamento de caracteres utilizada para converter todos os caracteres em um string para maisculos. Ela est relacionada a LOWER(), que converte todos os caracteres em um string para minsculos. UPPER() est relacionada s funes ISUPPER() e ISLOWER(), as quais determinam se um string comea com uma letra maiscula ou minscula. UPPER() geralmente utilizada para formatar cadeias de caracteres para fins de exibio. Ela pode, porm, ser usada para normalizar strings para fins de comparaes onde no se diferencia maisculas de minsculas, ou para fins de INDEXao. 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 condio que no diferencia maisculas de minsculas:

USE Customer INDEX CustName NEW

LIST CustName FOR "ISABELLA" $ UPPER(Customer)

UPPER() tambm til para criar expresses de chave de indexao onde no feita a diferenciao entre maisculas e minsculas, desta forma:

USE Customer NEW

INDEX ON UPPER(Last) TO CustLast

Depois, use a mesma expresso para fazer uma pesquisa em Customers:

MEMVAR->Last = SPACE(15)

@ 10, 10 GET MEMVAR->Last

READ

SEEK UPPER(MEMVAR->Last)

VAL()

Converte um nmero presente em uma cadeia de caracteres para um valor numrico. Sintaxe

VAL(<cNmero>) --> nNmero Argumentos

<cNmero> a expresso caractere a ser convertida. Retorno

VAL() retorna <cNmero> convertido para um valor numrico, incluindo dgitos decimais. Descrio

VAL() uma funo de converso de caracteres, a qual converte uma cadeia de caracteres que contm dgitos numricos para um valor numrico. Quando VAL() executada, ela avalia <cNmero> at encontrar o segundo ponto decimal, o primeiro caractere no numrico, ou o final da expresso. Os espaos direita so ignorados. Com SET FIXED em ON, VAL() retorna a quantidade de casas decimais especificadas por SET DECIMALS, arredondando <cNmero> se ele for especificado com uma quantidade de dgitos maior do que o valor corrente de DECIMALS. Da mesma forma que todas as outras funes que arredondam, os dgitos entre zero e quatro so arredondados para baixo, e os dgitos entre cinco e nove so arredondados para cima. Com SET FIXED em OFF, VAL() retorna a quantidade de casas decimais especificadas em <cNmero>.

VAL() o oposto de STR() e TRANSFORM(), as quais convertem valores numricos para cadeias de caracteres. Exemplos

Os exemplos a seguir ilustram VAL() com SET FIXED ON, e SET DECIMALS TO 2:

SET DECIMALS TO 2

SET 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 Funes Cronolgicas CTOD()

Converte uma cadeia de caracteres em uma data correspondente Sintaxe

CTOD(<cData>) --> dData Argumentos

<cData> uma cadeia de caracteres que contm nmeros representando o ms, dia, e ano separados por qualquer outro caractere que no um nmero. Os dgitos do ms, dia, e ano devem ser especificados de acordo com o formato indicado pelo SET DATE. Se os dgitos do sculo no so especificados, o sculo determinado pelas regras do SET EPOCH. Retorno

CTOD() retorna um dado do tipo data. Se <cData> no uma data vlida, CTOD() retorna uma data vazia. Descrio

TOD() uma funo de converso 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 so:

Inicializando uma varivel para um valor do tipo data

Especificando um literal do tipo data como sendo um argumento de uma clusula RANGE de um @...GET

Especificando um literal do tipo data a fim de realizar operaes aritmticas com esta

Comparando o resultado de uma expresso 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() tambm converte um valor do tipo data para uma cadeia de caracteres na forma aaaammdd.

Exemplos

O exemplo seguinte utiliza CTOD() para inicializar duas variveis do tipo data, usando uma no GET e a outra para a validao do RANGE:

SET CENTURY ON

dBegin = 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 NEW

REPLACE 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. Descrio

DATE() uma funo de tratamento de datas que prov um meio de inicializar variveis de memria com a data corrente, comparando outros valores do tipo data para a data corrente, e realizando operaes aritmticas relativas data corrente.

O formato para a exibio de datas controlado pelo comando SET DATE.

O formato padro assumido mm/dd/aa. Exemplos

Os exemplos seguintes mostram a funo DATE() utilizada de vrias maneiras:

? DATE() // Resulta: 09/01/90

? DATE() + 30 // Resulta: 10/01/90

? DATE() - 30 // Resulta: 08/02/90

dDate = 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 padro mm/dd/aa. Uma data nula retorna uma cadeia de caracteres em branco igual em tamanho ao formato de data corrente. Descrio

DTOC() uma funo de converso de datas utilizada por motivos de formatao quando voc deseja exibir a data no formato SET DATE e necessria uma

expresso caractere (em um LABEL FORM, por exemplo). Caso voc precise de um formato de data especfico, voc pode utilizar TRANSFORM() ou uma expresso customizada.

Se voc estiver INDEXando uma data juntamente com uma cadeia de caracteres, use DTOS() ao invs de DTOC() para converter o valor data para uma cadeia de caracteres. Exemplos

Os exemplos a seguir demonstram utilizaes 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 no afetado pelo formato de data corrente. Descrio

DTOS() uma funo de converso de datas utilizada para criar expresses de ndice que consistem em um valor data e uma expresso caractere. DTOS() converte um valor data para uma cadeia de caracteres que pode ser concatenada a qualquer outra expresso caractere. O valor de retorno estruturado para preservar a ordem de data (ano, ms, e dia). Exemplos

Os exemplos a seguir ilustram DTOS() em conjunto com vrias outras funes:

? 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 NEW

INDEX ON DTOS(Date) + Salesman TO DateName YEAR()

Converte um valor data para ano na forma de um valor numrico.

Sintaxe

YEAR(<dData>) --> nAno Argumentos

<dData> o valor data a ser convertido. Retorno

YEAR() retorna o ano do valor data especificado, inclusive dgitos indicativos de sculo, na forma de um valor numrico de quatro dgitos. O valor retornado no influenciado pelo formato de DATE ou CENTURY corrente. A especificao de uma data nula (CTOD("")) retorna zero. Descrio

YEAR() uma funo de converso de datas utilizada para converter um valor data para um valor numrico indicativo do ano. Pode ser utilizada em clculos de, por exemplo, relatrios peridicos, ou para formatao de exibies de data.

YEAR() membro de um grupo de funes que retornam componentes de um valor data na forma de valores numricos. Este grupo inclui DAY() e MONTH(), que retornam valores de dia e ms na forma de valores numricos. 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 funo definida pelo usurio usando YEAR() para formatar um valor data na forma : ms dia, ano:

? Mdy(DATE()) // Resulta: September 20, 1990

FUNCTION Mdy( dDate )

RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate)));

+ "," + STR(YEAR(dDate)) Funes Matriciais ACHOICE()

Executa um menu pop-up Sintaxe

ACHOICE(<nTopo>, <nEsquerda>, <nBase>, <nDireita>, <acItensMenu>,

[<alItensSelecionaveis> | <lItemsSelecionveis>], [<cFunoUsurio>],

[<nItemInicial>], [<nLinhaJanela>]) --> nPosio Argumentos

<nTopo>, <nEsquerda> e <nBase>, <nDireita> so 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 contm as cadeias de caracteres que sero exibidas como sendo os itens de menu. Cada item de menu ser mais tarde identificado atravs de sua posio numrica neste vetor.

<alItensSelecionaveis> um vetor paralelo de valores lgicos--diretamente relacionado a <acItensMenu>--que especifica os itens de menu que podero ser selecionados. Os elementos podem ser valores lgicos ou cadeias de caracteres. Caso o elemento seja uma cadeia de caracteres, ele avaliado como uma expresso macro que dever retornar um tipo de dados lgico. Em ambos os casos, um valor de falso (.F.) significa que o item de menu correspondente no est disponvel, e um valor de verdadeiro (.T.) significa que est disponvel. Se for especificado <lItensSelecionaveis> ao invs de um vetor, falso (.F.) torna todos os itens de menu no disponveis e verdadeiro (.T.) torna todos os itens de menu disponveis. O padro adotado que todos os itens de menu estejam disponveis para seleo.

<cFunoUsurio> o nome de uma funo definida pelo usurio que executada quando uma tecla no reconhecvel for pressionada. O nome da funo especificado como uma expresso caractere sem parnteses ou argumentos. Note que o comportamento de ACHOICE() afetado pela presena deste argumento.

<nItemInicial> a posio 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 no esteja disponvel, ou caso voc no use argumento algum, o item que aparecer em destaque ser o primeiro item selecionvel do vetor.

<nLinhaJanela> o nmero da linha da janela na qual o item de menu inicial aparecer. A numerao de linhas comea com zero. O padro que o item de menu inicial aparea o mais prximo do topo da janela possvel, sem deixar nenhuma linha vazia na parte de baixo. Consequentemente, caso haja um nmero suficiente de itens de menu aps o primeiro para completar a janela, ele aparecer na primeira linha (linha zero) do menu. Este argumento utilizado para controlar a disposio inicial do menu nos casos em que haja mais itens de

menu do que a janela comporta.

Como toda funo, os argumentos opcionais so omitidos usando-se uma vrgula ao invs do argumento propriamente dito. Retorno

ACHOICE() retorna a posio numrica ocupada pelo item de menu selecionado no vetor de <acItensMenu>. Se o processo de seleo for interrompido, ACHOICE() retorna zero. Descrio

ACHOICE() uma funo de interface com o usurio que pode ser utilizada para criar vrios tipos de menus pop-up. Cada menu usa um vetor de cadeia de caracteres, que sero os itens de menu, e um vetor paralelo de valores lgicos que determina se os itens so selecionveis. Quando ACHOICE() invocada, a lista de itens de menu exibida dentro das coordenadas de janela especificadas. Quando o usurio tecla Return, o item corrente selecionado, e ACHOICE() retorna a posio ocupada por este item de menu em <acItensMenu>. Quando o usurio 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 usurio tenta mover a barra luminosa para cima ou para baixo, alm dos limites da janela de menu. Observe que a barra luminosa no pula do ltimo para o primeiro item de menu quando se chega ao fim da lista de itens, ou vice-versa. Porm, se o usurio 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 <cFunoUsurio> for especificado. Caso no seja especificado, as seguintes teclas de navegao so ativas:

Tabela 5-1: Teclas em ACHOICE() (Sem funo de Controle)

Tecla

Ao

Cursor para cima

Vai para o item anterior

Cursor para baixo

Vai para o prximo item

Home

Vai para o primeiro item do menu

End

Vai para o ltimo item do menu

Ctrl-Home

Vai para o primeiro item da janela

Ctrl-End

Vai para o ltimo item da janela

PgUp

Vai para a pgina anterior

PgDn

Vai para a prxima pgina

Ctrl-PgUp

Vai para o primeiro item do menu

Ctrl-PgDn

Vai para o ltimo item do menu

Return

Seleciona item corrente

Esc

Aborta seleo

Cursor para esquerda

Aborta seleo

Cursor para direita

Aborta seleo

Primeira letra

Vai para o prximo item iniciando com a letra

Cor: Os itens de menu so exibidos na cor padro, o item onde est a barra luminosa na cor destaque, e os itens no disponveis na cor no seleciionada. Por exemplo, a seguinte declarao 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 no disponveis so brancos sobre preto.

Funo de usurio: Da mesma forma que as demais funes de interface com o usurio, ACHOICE() aceita uma funo de usurio. A funo de usurio especificada quando voc deseja aninhar invocaes da funo ACHOICE() para criar menus hierrquicos ou redefinir teclas.

Quando especificada uma funo de usurio, ACHOICE() processa somente um conjunto limitado de teclas automaticamente. Estas estao relacionadas na tabela abaixo. Todas as outras teclas geram uma exceo de tecla que passa o controle para a funo de usurio. O controle tambm ser passado funo de usurio quando ACHOICE() fica inativo (ou seja, quando no h mais teclas a processar). Tabela 5-2: Teclas em ACHOICE() (Com funo de controle)

Tecla

Ao

Cursor para cima

Vai para o item anterior

Cursor para baixo

Vai para o prximo item

Ctrl-Home

Vai para o primeiro item da janela

Ctrl-End

Vai para o ltimo item da janela

PgUp

Vai para a pgina anterior

PgDn

Vai para a prxima pgina

Ctrl-PgUp

Vai para o primeiro item do menu

Ctrl-PgDn

Vai para o ltimo item do menu

Quando ACHOICE() executa a funo de usurio, ela passa automaticamente os trs parmetros a seguir: O modo ACHOICE() corrente O elemento corrente no vetor de itens A posio de linha relativa dentro da janela de menu

O modo indica o estado atual de ACHOICE(), que depende da tecla pressionada e da ao tomada por ACHOICE() antes da execuo da funo de usurio. O parmetro modo pode ter os seguintes valores: Tabela 5-3: Modos de ACHOICE()

Modo

Achoice.ch

Descrio

AC_IDLE

Inativo

AC_HITTOP

Tentativa de passar incio da lista

AC_HITBOTTOM

Tentativa de passasr final da lista

AC_EXCEPT

Teclagemn exceo

AC_NOITEM

Itens no selecionados

Aps a funo de usurio ter executado as operaes apropriadas ao modo ACHOICE() ou LASTKEY(), ela deve retornar um valor que solicite a ACHOICE() executar uma operao entre o seguinte conjunto de aes: Tabela 5-4: Valores de Retorno da Funo de Controle de ACHOICE()

Valor

Achoice.ch

Ao

AC_ABORT

Aborta seleo

AC_SELECT

Executa seleo

AC_CONT

Continua ACHOICE()

AC_GOTO

Vai para o prximo item cuja primeira letra for a tecla pressionada Exemplos

O exemplo a seguir utiliza dois vetores literais para especificar os itens de menu e critrios de seleo. Depois que o menu foi exibido e o usurio fez sua escolha, o nome do item de menu selecionado exibido:

acMenuItens := {Um, Dois, "", Trs}

alSelectableItens := {.T., .T., .F., .T.}

nPosition := ACHOICE(10, 10, 12, 15, acMenuItens, alSelectableItens)

? acMenuItens[nPosition]

No prximo exemplo, os vetores so declarados, especificada uma condio de seleo para um dos itens de menu, e h uma funo de usurio:

FUNCTION MyMenu

LOCAL 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 selecao

RETURN ACHOICE(10, 10, 12, 30, acMenuItens,;

alSelectableItens, cUserFunction) Funes 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 no forem especificadas, as coordenadas padro da janela so 1, 0 at MAXROW(), e MAXCOL(). Retorno

BROWSE() sempre retorna NIL. Descrio

BROWSE() uma funo de interface com o usurio que invoca um editor e um browser (orientado por tabela) de utilizao geral para os registros na rea de trabalho corrente. Para uma lista das teclas de navegao utilizadas por BROWSE(), consulte a funo 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>

Incio de arquivo

<delete>

Registro corrente est marcado para eliminao

Record

Nmero do registro atual

Modos: BROWSE() tem os trs modos seguintes:

Browse: Este o modo padro de BROWSE(). Ao ser pressionada qualquer uma das teclas de navegao DBEDIT(), a barra luminosa move-se para uma nova

linha ou coluna.

Edita Campos: Ao ser pressionado Return em qualquer campo, entra-se na edio de campos usando um GET. Pressionar Return termina o modo de edio, gravando as alteraes. Esc termina sem gravar as alteraes. J que o modo de edio de campos utiliza-se de GET, todas as teclas de navegao e edio so 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, ento, um novo registro. Ao pressionar-se Cursor para cima termina-se o modo append, gravando o novo registro caso tenham sido entrados dados. Se no foram entrados quaisquer dados, o novo registro no gravado. DBEDIT()*

Faz um browse em registros no formato de tabela Sintaxe

DBEDIT([<nTopo>], [<nEsquerda>],

[<nBase>], <nDireita>],

[<acColunas>],

[<cFunoUsurio>],

[<acMscarasColunas> | <cMscaraColunas>],

[<acCabealhosColunas> | <cCabealhoColunas>],

[<acSeparadoresCabealhos> | <cSeparadorCabealhos>],

[<acSeparadoresColunas> | <cSeparadorColunas>],

[<acSeparadoresRodaps> | <cSeparadorRodaps>],

[<acRodapsColunas> | <cRodapColunas>]) --> 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 no sejam especificados, as coordenadas assumidas so 0, 0, MAXROW(), e MAXCOL().

<acColunas> um vetor de expresses caractere contendo os nomes de campos do arquivo de dados ou expresses para utilizar como valores para cada linha exibida. Se este argumento no especificado, DBEDIT() exibe todos os campos presentes na rea corrente como sendo as colunas.

<cFunoUsurio> o nome de uma funo definida pelo usurio que executada quando uma tecla no reconhecvel pressionada ou quando no h nenhuma tecla pendente no buffer do teclado. O nome da funo especificada como sendo uma expresso caractere sem os parnteses ou argumentos. Note que o comportamento da funo DBEDIT() afetado pela presena desses argumentos. Para maiores informaes veja os tpicos discutidos abaixo.

<acMscarasColunas> um vetor paralelo contendo as mscaras de formatao de cada coluna. Especificando <cMscaraColunas> em vez do vetor, este ser assumido para a exibio de todas as colunas com o mesmo formato.

<acCabealhosColunas> um vetor paralelo contendo expresses caractere que definem os cabealhos para cada coluna. Se especificada <cCabealhoColuna> em vez do vetor de cabealhos, assumido o mesmo cabealho para todas as colunas. Para exibir cabealhos em mais de uma linha, inclua um ponto-e-vrgula dentro da expresso de cabealho onde voc deseje que a cadeia seja separada. Caso no seja especificado, os cabealhos das colunas so tomados do vetor <acColunas>, ou so assumidos os nomes dos campos presentes na rea corrente se o argumento <acColunas> no for mencionado.

<acSeparadoresCabealhos> um vetor paralelo contendo expresses do tipo caractere que definem os caracteres que sero utilizados para desenhar as linhas horizontais separando os cabealhos das colunas da rea de exibio dos campos. Especificando a expresso <cSeparadorCabealhos> em vez do vetor utilizado o mesmo separador para todas as colunas. Caso este argumento no seja mencionado, o separador assumido uma linha grfica dupla.

<acSeparadoresColunas> um vetor paralelo contendo expresses caractere que definem os caracteres utilizados para desenhar as linhas verticais que separam as colunas. Especificando a expresso

<cSeparadorColunas> em vez do vetor utilizado o mesmo separador para todas as colunas. Caso este argumento no seja mencionado, o separador assumido uma linha grfica simples.

<acSeparadoresRodaps> um vetor paralelo contendo expresses caractere que definem os caracteres que sero utilizados para desenhar as linhas horizontais que separam os rodaps das colunas da rea de exibio dos campos. Especificando a expresso <cSeparadorRodaps> em vez do vetor utilizado o mesmo separador de rodap para todas as colunas. Caso este argumento no seja mencionado, no exibido nenhum separador para os rodaps.

<acRodapsColunas> um vetor paralelo contendo expresses caractere que definem os rodaps para cada coluna. Especificando a expresso <cRodapColunas> em vez do vetor utilizado o mesmo rodap para todas as colunas. Para exibir rodaps em mais de uma linha, inclua um ponto-e-vrgula na

expresso contendo o rodap onde voc deseje que a cadeia seja separada. Caso este argumento no seja mencionado, no exibido nenhum rodap para as colunas. Retorno

DBEDIT() sempre retorna NIL. Descrio

DBEDIT() alm de ser uma funo de interface com o usurio tambm uma funo de compatibilidade que exibe registros de uma ou mais reas de trabalho na forma de tabela. A janela de visualizao da DBEDIT() uma rea com clulas 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 exibio de cada coluna determinada pela avaliao da expresso da coluna contida no vetor <acColunas> ou pela mscara da coluna especificada no vetor <acMscarasColunas>.

Todas as teclas de movimentao do cursor so manipuladas dentro da DBEDIT(), inclundo PgUp, PgDn, Home, End, as quatro setas de navegao, e todas as combinaes vlidas da tecla Ctrl que realizam a movimentao do cursor. As teclas de navegao s quais a DBEDIT() responde quando o argumento da funo do usurio no especificado estao mostradas na tabela Teclas Ativas na prxima pgina. Tabela 5-8: Teclas Ativas em DBEDIT()

Tecla

Ao

Cursor para cima

Sobe uma linha

Cursor para baixo

Desce uma linha

Cursor para esquerda

Coluna esquerda

Cursor para direita

Coluna direita

Ctrl-Cursor para esquerda

Painel uma coluna para esquerda

Ctrl-Cursor para direita

Painel uma coluna para direita

Home

Coluna mais esquerda na tela

End

Coluna mais direita na tela

Ctrl-Home

Coluna inicial

Ctrl-End

Coluna final

PgUp

Tela anterior

PgDn

Prxima tela

Ctrl-PgUp

Primeira linha da coluna corrente

Ctrl-PgDn

Ultima linha da coluna corrente

Return

Encerra DBEDIT()

Esc

Encerra DBEDIT()

Quando o argumento da funo do usurio (<cFunoUsurio>) especificado, todas as teclas indicadas na tabela Teclas Ativas estao ativas com exceo do Esc e Return. Quando a DBEDIT() chama a funo do usurio, esta passa automaticamente dois argumentos:

O modo corrente passado como um valor numrico

O ndice da coluna corrente com base no vetor <acColunas> passado como um valor numrico

O parmetro modo indica o estado corrente da DBEDIT() dependendo da ltima tecla que foi executada. Os possveis valores dos modos estao mostrados na tabela Modos da DBEDIT().

Tabela 5-9: Modos de DBEDIT()

Status

bedit.ch

escrio

E_IDLE

nativa, todas teclas foram manipuladas e no h teclas pendentes

E_HITTOP

entativa de passar incio de arquivo

E_HITBOTTOM

entativa de passar final de arquivo

E_EMPTY

rquivo vazio na rea corrente

DC_EXCEPT

eclagem exceo

O parmetro ndice aponta para a posio da coluna corrente definida no vetor <acColunas>. Caso o vetor <acColunas> no seja especificado, o parmetro ndice apontar para a posio do campo da estrutura do arquivo de dados corrente. O nome do campo pode ser acessado utilizando a funo FIELD().

Quando a funo do usurio tiver sido chamada, um valor deve ser retornado para instruir DBEDIT() que ao realizar em seguida. A tabela Valores de Retorno da Funo do Usurio sumariza os possveis valores de retorno e as aes correspondentes: Tabela 5-10: Valores de Retorno da Funo de Usurio de DBEDIT()

Valor

bedit.ch

escrio

E_ABORT

Aborta DBEDIT()

E_CONT

ontinua DBEDIT()

E_REFRESH

Fora reler e reescrever a tela e continuar; aps reescrever, processa teclas, e vai para inativa

A funo do usurio chamada nos seguintes casos:

Ocorrncia de uma tecla de exceo. Isto acontece quando a DBEDIT() captura uma tecla pressionada e esta no reconhecida. Quaisquer teclas pendentes permanecem no buffer do teclado at que seja capturada dentro da funo do usurio 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 aps ser efetuado um refresh da tela. Nesta ocorrncia, h uma chamada para a funo do usurio e ento a DBEDIT() espera por uma tecla.

Incio ou final do arquivo encontrado. Esta ocorrncia a mesma que a inatividade da DBEDIT(). Todas as teclas pendentes so executadas, e h uma chamada funo do usurio com a mensagem de status indicadora.

Note que quando a DBEDIT() executada pela primeira vez, todas as teclas pendentes no buffer do teclado so executadas e logo aps a DBEDIT() entra no modo inativo com a chamada funo do usurio. Caso no existam teclas pendentes, o modo inativo imediato.

A estrutura da funo do usurio 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 caracterstica, voc pode ter mltiplas janelas de browse na tela ao mesmo tempo.

DBEDIT() uma funo de compatibilidade e, portanto, no recomendada sua utilizao como dispositivo de browse. Para este propsito, ela est superada pela classe de objeto TBrowse. Exemplos

Este exemplo demonstra como chamar a DBEDIT() com uma funo do usurio:

USE Customer INDEX Customer NEW

USE Sales INDEX Sales NEW

SET 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 alm do ltimo registro lgico em um arquivo de banco de dados; do contrrio, ela retorna falso (.F.). Caso no 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 no possui registros, EOF() retorna verdadeiro (.T.). Descrio

EOF() uma funo de tratamento de banco de dados utilizada para testar uma condio 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 aplicao mais tpica como parte do argumento <lCondicao> de uma construo DO WHILE que processa registros sequencialmente em um arquivo de banco de dados. Neste caso <lCondicao> incluiria um teste para .NOT. EOF(), forando o lao DO WHILE a terminar quando EOF() retornar verdadeiro (.T.).

Tanto EOF() quanto FOUND() so frequentemente utilizados para verificar se um comando SEEK, FIND, ou LOCATE falhou. Com estes comandos, porm, prefervel 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 funo EOF() retorna verdadeiro (.T.), ela retm seu valor at que haja outra tentativa de mover o ponteiro de registros. O padro que EOF() opere na rea de trabalho correntemente selecionada. Pode-se fazer esta funo operar em uma rea de trabalho no selecionada desde que esta seja especificada em uma expresso alias (veja o exemplo abaixo). Exemplos

O exemplo a seguir demonstra o resultado da funo EOF() quando se tenta deliberadamente mover o ponteiro de registros para alm do ltimo registro:

USE Sales

GO BOTTOM

? EOF() // Resulta: .F.

SKIP

? EOF() // Resulta: .T.

Este exemplo utiliza expresses alias para questionar o valor de EOF() em reas de trabalho no selecionadas:

USE Sales NEW

USE Sales NEW

USE Customer NEW

? Sales->(EOF())

? Customer->(EOF())

Este exemplo ilustra como EOF() pode ser utilizada como parte de uma condio para operaes sequenciais em bancos de dados:

USE Sales INDEX CustNum NEW

WHILE !EOF()

nOldCust := Sales->CustNum

nTotalAmount := 0

WHILE nOldCust = Sales->CustNum .AND. (!EOF())

? Sales->CustNum, Sales->Description, Sales->SaleAmount

nTotalAmount += Sales->SaleAmount

SKIP

ENDDO

? "Quantia total: ", nTotalAmount

ENDDO ERRORBLOCK()

Envia um bloco de cdigo a ser avaliado quando ocorre um erro em tempo de execuo Sintaxe

ERRORBLOCK([<bErrorHandler>]) --> bCurrentErrorHandler Argumentos

<bErrorHandler> o bloco de cdigo a ser executado toda vez que ocorrer um erro em tempo de execuo. Quando avaliado, o <bErrorHandler> passado na forma de um objeto erro como um argumento pelo sistema. Retorno

ERRORBLOCK() retorna o bloco de cdigo corrente que tratar o erro. Caso no tenha sido enviado nenhum bloco de tratamento de erro desde que o programa foi invocado, ERRORBLOCK() retorna o bloco de tratamento de erro padro. Descrio

ERRORBLOCK() uma funo de tratamento de erros que define a atuao de um handler de erros sempre que ocorrer um erro em tempo de execuo. O manipulador de erros especificado como um bloco de cdigo da seguinte forma:

{ |<objError>| <lista de expresses>,... }

Onde <objError> um error object que contm informaes sobre o erro. Dentro do bloco de cdigo, podem ser enviadas mensagens ao error object para obter informaes sobre o erro. Se o bloco de tratamento de erros retornar verdadeiro (.T.), a operao que falhou repetida, e se retornar falso (.F.), o processamento recomea.

O bloco de tratamento de erros pode ser especificado como uma lista de expresses ou como uma chamada a uma funo definida por usurio. Uma chamada a uma funo definida por usurio mais til pois voc pode utilizar declaraes de controle do Clipper ao invs de expresses. Este em particular o caso se houver um BEGIN SEQUENCE pendente e voc deseja BREAK para a prxima declarao RECOVER.

Como consequncia, blocos de tratamento de erro podem ser utilizados em combinao com estruturas de controle BEGIN SEQUENCE...END. Dentro de um bloco de tratamento de erros, voc manipula erros comuns, de baixo nvel, e de dispositivos que tm um mecanismo de recuperao geral. Se a operao necessita tratamento de erros especficos, defina um BEGIN SEQUENCE e depois BREAK para a declarao RECOVER, retornando o error object para processamento local. Veja o exemplo abaixo.

Se no foi especificado nenhum <bErrorHandler> utilizando ERRORBLOCK() e ocorrer um erro em tempo de execuo, o bloco de tratamento ao de erros

padro avaliado. Este manipulador de erros exibe uma mensagem descritiva na tela, ajusta a funo ERRORLEVEL() para 1, e depois sai do programa (QUIT).

Como ERRORBLOCK() retorna o bloco de tratamento ao de erros corrente, possvel especificar um bloco de tratamento de erros para uma operao gravando-se o bloco de manipulao de erros corrente e depois recuperando-o aps o final da operao. Alm disso, uma importante consequncia do fato de os blocos de tratamento de erros serem especificados como blocos de cdigo, que eles podem ser passados para rotinas e funes definidas por usurio e depois retornadas como valores. Exemplos

O fragmento de cdigo a seguir ilustra como um bloco de tratamento de erros pode ser enviado e depois chamado quando h um erro dentro de uma construo BEGIN SEQUENCE:

LOCAL bErrorHandler, bLastHandler, objErr

bErrorHandler := { |objError| MyErrorHandler(objError) }

//

bLastHandler := ERRORBLOCK(bErrorHandler) // Salva manipulador corrente

//

BEGIN SEQUENCE

. <declaraes da operao>

RECOVER USING objErrorInfo // Recebe objeto de erro de BREAK

. <declaraes de recuperao>

END

ERRORBLOCK(bLastHandler) // Restaura manipulador

RETURN

FUNCTION MyErrorHandler( objError )

//

BREAK objError // Retorna objeto para RECOVER

RETURN 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 numrico inteiro. Caso no haja nenhum arquivo de banco de dados aberto, FCOUNT() retorna zero. Descrio

FCOUNT() uma funo de tratamento de banco de dados. Ela til em aplicaes que contm 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 relatrios. Normalmente, utiliza-se FCOUNT() para estabelecer o limite superior de um lao FOR...NEXT ou DO WHILE que processa um nico campo por vez.

O padro que a funo FCOUNT() opere na rea de trabalho correntemente selecionada. Pode-se faz-la operar numa rea de trabalho no selecionada se esta for especificada em uma expresso alias. Exemplos

A seguir FCOUNT() retorna a quantidade de campos nas reas detrabalho corrente e no selecionada:

USE Sales NEW

USE Customer NEW

? FCOUNT() // Resulta: 5

? Sales->(FCOUNT()) // Resulta: 8

Este exemplo usa FCOUNT() para declarar um vetor a ser carregado com informaes sobre campos:

LOCAL aFields := ARRAY(FCOUNT())

AFIELDS(aFields)

Este exemplo utiliza a funo FCOUNT() como o limite superior de um lao FOR na lista de campos da rea de trabalho corrente:

LOCAL nField

USE Sales NEW

FOR nField := 1 TO FCOUNT()

? FIELD(nField)

NEXT FOUND()

Determina se a operao de pesquisa anterior foi bem sucedida

Sintaxe

FOUND() --> lSucesso Retorno

FOUND() retorna verdadeiro (.T.) se o ltimo comando de pesquisa foi bem sucedido; do contrrio, ela retorna falso (.F.). Descrio

FOUND() uma funo de tratamento de banco de dados utilizada para determinar se uma operao de pesquisa (isto , FIND, LOCATE, CONTINUE, SEEK, SET RELATION) foi bem sucedida antes que o prximo passo no programa seja executado. Quando qualquer um destes comandos executado, FOUND() retorna verdadeiro (.T.) caso haja correspondncia;

do contrrio, ele retorna falso (.F.).

Se o comando de pesquisa for LOCATE ou CONTINUE, a correspondncia o prximo registro que atender a abrangncia e condio. Caso o comando de pesquisa seja FIND, SEEK ou SET RELATION, a correspondncia 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 contrrio, falso (.F.).

O valor de FOUND() retido at que seja executado outro comando de movimentao de registros. A no 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 secundria, questionando-se FOUND() na rea secundria far a funo retornar

verdadeiro (.T.) caso haja correspondncia.

O padro que a funo FOUND() opere na rea de trabalho correntemente selecionada. Pode-se faz-la operar em uma rea de trabalho no selecionada se esta for especificada em uma expresso alias (veja o exemplo abaixo). Exemplos

O exemplo a seguir ilustra o comportamento da funo FOUND() aps um comando de movimentao de registros:

USE Sales INDEX Sales

? INDEXKEY(0) // Resulta: SALESMAN

SEEK "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 no selecionada atravs de uma expresso alias:

USE Sales INDEX Sales NEW

USE Customer INDEX Customer NEW

SET RELATION TO CustNum INTO Sales

//

SEEK "Smith"

? FOUND(), Sales->(FOUND())

Este fragmento de cdigo processa todos os registros de Customer que tm o valor chave "Smith" usando FOUND() para determinar quando h mudana no valor chave:

USE Customer INDEX Customer NEW

SEEK "Smith"

WHILE FOUND()

. <declaraes>

SKIP

LOCATE REST WHILE Name = "Smith"

ENDDO MEMOEDIT()

Exibe ou edita cadeias de caracteres e campos memo. Sintaxe

MEMOEDIT([<cString>],

[<nTopo>], [<nEsquerda>],

[<nBase>], [<nDireita>],

[<lModoEdio>],

[<cFunoControle>],

[<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 no seja especificado, o buffer de texto fica vazio.

<nTopo>, <nEsquerda>, <nBase>, e <nDireita> so as coordenadas superior esquerda e inferior direita da janela. Valores de linha podem variar de zero a MAXROW(), e posies de coluna podem variar de zero a MAXCOL(). Se no forem especificadas, as coordenadas padro so 0, 0, MAXROW(), e MAXCOL().

<lModoEdio> determina se o buffer de texto pode ser editado ou simplesmente exibido. Especificar verdadeiro (.T.) permite ao usurio fazer alteraes no buffer de texto, enquanto que especificar falso (.F.) permite ao usurio somente a leitura do buffer de texto. Caso no seja especificado, o valor padro verdadeiro (.T.).

<cFunoControle> o nome de uma funo de usurio que executada quando o usurio pressionar uma tecla no reconhecida pela MEMOEDIT() e quando no houver teclas pendentes no buffer de teclado.

<cFunoControle> especificada como um valor caractere sem parnteses ou argumentos. Especificando-se falso (.F.) neste argumento, o <cString> exibido, e a MEMOEDIT() terminada. Caso este argumento seja especificado, o comportamento automtico 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 prxima linha na janela de MEMOEDIT(). Se <nTamanhoLinha> for maior do que o nmero de colunas na janela de MEMOEDIT(), a janela de edio ser deslocada caso o cursor se mova para alm do limite da janela. Se <nTamanhoLinha> no for especificado, o tamanho de linha padro (<nDireita> - <nEsquerda>).

<nTamanhoTab> determina o tamanho de um caractere de tabulao a ser inserido quando o usurio pressionar Tab. Caso <nTamanhoTab> no seja especificado, so inseridos quatro espaos ao invs de um caractere de tabulao.

<nLinhaBufferTexto> e <nColunaBufferTexto> definem a posio de exibio do cursor dentro do buffer de texto quando invocada a MEMOEDIT(). <nLinhaBufferTexto> comea com 1 (um) e <nColunaBufferTexto> comea com zero. Se estes argumentos no forem especificados, o cursor posicionado na linha 1 (um) e coluna zero da janela de MEMOEDIT().

<nLinhaJanela> e <nColunaJanela> definem a posio inicial do cursor dentro da janela da MEMOEDIT(). Posies de linha e coluna comeam com zero. Caso estes argumentos no sejam especificados, a posio inicial na janela linha zero mais a posio de coluna onde o cursor estiver. Retorno

MEMOEDIT() retorna o buffer de texto caso o usurio termine a edio com CtrlW, ou uma cpia de <cString> caso o usurio termine com Esc. Descrio

MEMOEDIT() uma funo de interface com o usurio e de edio de textos, que pode ser utilizada para editar campos memo e cadeias de caracteres longas. A edio ocorre dentro de uma regiao de janela especificada, posicionada em qualquer lugar na tela. Da mesma forma que outras funes de interface com o usurio (ACHOICE(), DBEDIT()), MEMOEDIT() suporta uma srie de modos distintos, e inclui uma funo de See also: LASTKEY() MEMOREAD() MEMOTRAN() MEMOWRIT().

usurio para permitir a reconfigurao de teclas e outras atividades relevantes programao da tarefa de edio 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 usurio realmente edita. Caso no seja especificado <cString>, apresentado ao usurio um buffer de texto vazio para edio.

Quando o usurio sai da MEMOEDIT() pressionando Ctrl-W, o contedo do buffer de texto retornado. Se o usurio sair pressionando Esc, o buffer de texto descartado e o valor original de <cString> retornado. De qualquer maneira, o valor retornado pode ento ser atribuido a uma varivel ou campo memo, ou passado como um argumento para outra funo.

Modos de Edio: MEMOEDIT() suporta dois modos de edio, dependendo do valor de <lModoEdio>. Quando <lModoEdio> verdadeiro (.T.), MEMOEDIT() entra no modo de edio, e ao usurio permitido alterar o contedo do buffer de texto da MEMOEDIT().

Quando <lModoEdio> falso (.F.), MEMOEDIT() entra no modo visualizar, e ao usurio permitido navegar pelo buffer de texto, mas sem editar ou inserir textos. Para facilitar a visualizao para o usurio, 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 usurio pode entrar e editar textos posicionando o cursor, adicionando, ou eliminando caracteres. Para facilitar a edio de textos, h uma srie de teclas de navegao e edio:

Tabela 5-20: Teclas de Navegao e Edio em MEMOEDIT()

Tecla

Ao

Cursor para cima/Ctrl-E

Move para cima uma linha

Cursor para baixo/Ctrl-X

Move para baixo uma linha

Cursor para esquerda/Ctrl-S

Move para esquerda um caractere

Cursor para direita/Ctrl-D

Move para direita um caractere

Ctrl-Cursor para esquerda/Ctrl-A

Move para esquerda uma palavra

Ctrl-Cursor para direita/Ctrl-F

Move para direita uma palavra

Home

Move para o incio da linha corrente

End

Move para o final da linha corrente

Ctrl-Home

Move para o incio da janela corrente

Ctrl-End

Move para o final da janela corrente

PgUp

Move para janela anterior

PgDn

Move para a prxima janela

Ctrl-PgUp

Move para o incio do texto

Ctrl-PgDn

Move para o final do texto

Return

Move para o incio da prxima linha

Del

Elimina caractere onde est o cursor

Backspace

Elimina caractere esquerda do cursor

Tab

Insere tab ou espaos

Caracteres Imprimveis

Insere caractere

Ctrl-Y

Elimina a linha corrente

Ctrl-T

Elimina a palavra direita

Ctrl-B

Reformata pargrafo

Ctrl-V/Ins

Comuta modo de insero

Ctrl-W

Grava e finaliza a edio

Esc

Aborta edio e retorna o original

A tela de edio: Quando MEMOEDIT() exibe, ela sobreescreve a rea especificada da tela e no grava a tela original. Alm disso, ela no exibe bordas nem ttulos. Para fornecer estas ferramentas, voc deve criar uma rotina ou funo de usurio que execute estas aes e depois chame a MEMOEDIT(). Veja o exemplo abaixo.

A funo de controle: A funo de controle especificada no argumento <cFunoControle>, que manipula excees de tecla e reconfigura teclas especiais. A funo de controle chamada vrias vezes pela MEMOEDIT(), muito frequentemente em resposta a teclas que ela no reconhece. Teclas que causam uma exceo so todas as teclas Alt, de funo, e teclas de controle disponveis. Como estas teclas no so processadas pela MEMOEDIT(), elas podem ser reconfiguradas. Algumas destas teclas tm uma ao padro atribuida s mesmas. Na funo de controle, voc executa vrias aes que dependem do modo corrente da MEMOEDIT() e depois Retorna um valor que diz MEMOEDIT() o que fazer.

Quando o argumento funo de controle especificado, MEMOEDIT() define duas classes de teclas: no configurveis e excees de tecla. Quando pressionada uma tecla no configurvel, MEMOEDIT() a executa; caso contrrio gerada uma exceo de tecla e a funo de controle chamada. Quando no houver mais nenhuma tecla pendente no buffer de teclado a ser processada pela MEMOEDIT(), a funo de controle chamada novamente.

Quando a MEMOEDIT() chama a funo de controle, ela automaticamente passa parmetros 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 ao tomada antes da execuo da funo de controle. So possveis os seguintes modos: Tabela 5-21: Modos de MEMOEDIT()

Modo

Memoedit.ch

Descrio

ME_IDLE

Inativo, todas as teclas foram processadas

ME_UNKEY

Tecla desconhecida,memo inalterado

ME_UNKEYX

Tecla desconhecida, memo alterado

ME_INT

Modo de inicializao

Um valor de modo 3 indica que a MEMOEDIT() est em modo de inicializao. Quando voc especifica a <cFunoControle>, MEMOEDIT() faz uma chamada funo de controle imediatamente aps ser invocada. Neste ponto, voc retorna uma solicitao de configurao dos vrios modos de formatao de texto da MEMOEDIT():

Transporte, rolagem, ou inserir. MEMOEDIT() chama a funo de controle repetidamente, permanencendo no modo de inicializao at que voc retorne 0. O buffer de texto ento exibido, e o controle entra no modo de edio configurado por <lModoEdio>. Observe que se o transporte estiver ativo quando MEMOEDIT() mudar do modo de inicializao para o de edio, todo o buffer de texto formatado com <nTamanhoLinha>. Para evitar esta formatao inicial, desligue o transporte durante a inicializao. Observe tambm que a ativao ou no de transporte e rolagem no atribuida a nenhuma tecla, porm isto pode ser feito a partir da funo de controle.

Os modos 1 e 2 indicam que a MEMOEDIT() capturou uma tecla no reconhecida ou configurvel do buffer de teclado. Teclas configurveis so processadas retornando-se 0 para que seja executada a ao padro da MEMOEDIT(). O retorno de um valor diferente executa outra ao de tecla, desta forma redefinindo a tecla. Caso seja uma tecla no reconhecida, voc pode definir uma ao para ela retornando um valor que solicita uma ao de tecla ou executa uma ao 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 funo de controle. Neste ponto, voc geralmente atualiza exibies de nmero de linha e coluna.

Os outros dois parmetros, linha corrente e coluna, indicam a posio corrente do cursor no buffer de texto quando a funo de controle chamada. O parmetro linha comea com posio 1 (um), e coluna comea com posio zero.

Quando o modo 1, 2 ou 3, voc pode retornar um valor que instrui a MEMOEDIT() qual a prxima ao a ser executada. A tabela a seguir See also: LASTKEY() MEMOREAD() MEMOTRAN() MEMOWRIT() resume os valores de retorno possveis e suas consequncias: Tabela 5-22: Valores de Retorno da Funo de Controle de MEMOEDIT()

Valor

Memoedit.ch

Ao

ME_DEFAULT

Executa ao padro

1-31

ME_UNKEY

Processa ao correspondente ao valor da tecla

32

ME_IGNORE

Ignora tecla

33

ME_DATA

Trata tecla como dado

34

ME_TOGGLEWRAP

Comuta modo de transporte

35

ME_TOGGLESCROLL

Comuta modo de rolagem

100

ME_WORDRIGHT

Prxima palavra

101

ME_BOTTOMRIGHT

Base da tela

Arquivos header: Para que os valores de modo e solicitao sejam mais fceis de ser lembrados e utilizados, fornecido o arquivo Memoedit.ch no \CLIPPER5\INCLUDE. Alm disso, Inkey.ch est localizado no mesmo diretrio, e contm constantes para todos os valores INKEY(). Notas

Configurando teclas: Se a <cFunoUsurio> for especificada, as teclas na tabela abaixo so

configurveis. Se a tecla for reconfigurvel, retornar 0 executa a ao padro da MEMOEDIT(). retornar um valor diferente, porm, executa outra ao de tecla, desta forma redefinindo a mesma. Caso a tecla no seja do tipo configurvel reconhecido pela MEMOEDIT(), voc pode definir uma ao para ela tambm retornando um valor que pede uma ao de tecla da tabela abaixo. Tabela 5-23: Teclas Configurveis em MEMOEDIT()

Tecla

Ao Padro

Ctrl-Y

Elimina a linha corrente

Ctrl-T

Elimina a palavra direita

Ctrl-B

Reformata pargrafo

Ctrl-V/Ins

Comuta modo de insero

Ctrl-W

Finaliza edio e grava

Esc

Aborta edio e retorna original

Transporte: Transporte um modo de formatao que voc pode alternar se retornar 34 da funo de usurio. Quando est on (o padro), MEMOEDIT() insere um soft carriage return/line feed (retorno automtico) ao final da palavra mais prxima da borda da janela ou tamanho de linha, valendo o que ocorrer primeiro. Quando transporte est desligado, MEMOEDIT() rola o buffer de texto para alm dos limites da janela at que o cursor atinja o final da linha. Neste ponto, o usurio deve pressionar Return (inserindo um hard carriage return/line feed) para avanar para a prxima linha.

Alterando pargrafos: Pressionar Ctrl-B ou retornar 2 de uma funo de usurio causa a reformatao do buffer de texto at que um hard carriage return (final de pargrafo) ou o final do buffer de texto seja alcanado. Isto acontece sem importar se trabsporte est ligado ou desligado.

Carriage returns automticos: Carriage returns automticos podem interferir na exibio 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 varivel caractere Clipper. Isto pode ser feito com a funo MEMOREAD(). Aps a edio do contedo do arquivo texto contido na varivel caractere, ele pode ser escrita no arquivo novamente com MEMOWRIT().

Exemplos

O exemplo a seguir permite ao usurio visualizar um campo memo, sem deixar que sejam feitas alteraes no buffer de texto:

USE Customer NEW

SET CURSOR OFF

MEMOEDIT(CustNotes, 5, 10, 20, 69, .F.)

SET CURSOR ON

Este exemplo ilustra como permitir ao usurio editar um campo memo, sendo que depois estas alteraes sero atribuidas ao campo memo:

USE Customer NEW

REPLACE CustNotes WITH MEMOEDIT(CustNotes, 5, 10, 20, 69)

Este exemplo demonstra como criar uma cadeia de caracteres usando MEMOEDIT():

LOCAL cNotes

cNotes = MEMOEDIT()

Este exemplo demonstra uma funo definida pelo usurio que edita uma cadeia de caracteres em uma janela com moldura exibida com um ttulo:

FUNCTION MemoEdit( cString, cTtulo, 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 contedo de um arquivo texto para umavarivel caractere, edita, e depois escreve o novo contedo no disco:

LOCAL cString := MEMOREAD("Text.txt")

cString := MEMOEDIT(cString)

IF !MEMOWRIT("Text.txt", cString)

? "Erro de gravacao"

BREAK

ENDIF

RETURN

MEMOREAD()

Retorna o contedo 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 extenso no caso de haver uma, e pode opcionalmente incluir path. Retorno

MEMOREAD() retorna o contedo de um arquivo texto na forma de uma cadeia de caracteres. O arquivo pode ter um tamanho de no mximo 65.535 caracteres (64K)--ou seja, o tamanho mximo de uma cadeia de caracteres. Se <cArq> no puder ser encontrado, MEMOREAD() retorna uma cadeia de caracteres nula (""). Descrio

MEMOREAD() uma funo de tratamento de memos que l um arquivo em disco para a memria, 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 diretrio DOS corrente. Se o arquivo no for encontrado, MEMOREAD() pesquisa o path DOS . MEMOREAD() no utiliza as configuraes 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 atravs de outro processo, MEMOREAD() retorna uma cadeia de caracteres nula ("").

Exemplos

O exemplo a seguir utiliza MEMOREAD() para atribuir o contedo de um arquivo texto ao campo memo Notas e a uma varivel caractere:

REPLACE Notas WITH MEMOREAD("Temp.txt")

cString = MEMOREAD("Temp.txt")

Este exemplo define uma funo que edita um arquivo em disco:

FUNCTION Editor( cArq )

LOCAL cString

IF (cString := MEMOREAD(cArq)) == ""

? "Erro de leitura em " + cArq

RETURN .F.

ELSE

MEMOWRIT(cArq, MEMOEDIT(cString))

RETURN .T.

ENDIF RECNO()

Retorna o nmero do registro corrente de uma rea de trabalho Sintaxe

RECNO() --> nRegistro Retorno

RECNO() retorna o nmero do registro corrente na forma de um valor numrico inteiro. Se a rea de trabalho contm 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 alm do ltimo registro, RECNO() retorna LASTREC() + 1 e EOF() retorna verdadeiro (.T.). Caso seja feita uma tentativa para mover o ponteiro alm do primeiro registro, RECNO() retorna o nmero do primeiro registro lgico no arquivo de banco de dados, e BOF() retorna verdadeiro (.T.). Descrio

RECNO() uma funo de tratamento de banco de dados que retorna o nmero 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 nmero do registro. Cada rea de trabalho, por sua vez, mantm um ponteiro para o registro corrente em seu arquivo de banco de dados aberto. Aquele nmero de registro informado pela funo RECNO(). A ferramenta de numerao de registros permite acesso direto a um registro sem pesquisar sequencialmente o arquivo de banco de dados para atingir a posio do registro especificado.

RECNO() normalmente utilizada para generalizar rotinas que processam os registros atravs do nmero dos mesmos. Isto inclui SET RELATION...TO

RECNO(), que faz a likagem de arquivos de banco de dados por nmero de registro. GO RECNO() tambm usada para fazer um refresh dos dados de registro correntes do disco.

O padro que RECNO() opere na rea de trabalho correntemente selecionada. Pode-se faz-la operar em uma rea de trabalho no selecionada se esta for especificada em uma expresso alias (veja oexemplo abaixo). Exemplos

O exemplo a seguir questiona RECNO() aps mover deliberadamente o ponteiro de registros:

USE Customers NEW

GO 3

? RECNO() // Resulta: 3

GO TOP

? RECNO() // Resulta: 1

nRecord := 3

GO nRecord

? RECNO() // Resulta: 3

GO BOTTOM

SKIP

? RECNO(), LASTREC() // Resulta: 11 10

Este exemplo utiliza expresses alias para questionar o valor de RECNO() em reas de trabalho no selecionadas:

USE Sales NEW

USE Customer NEW

//

? Sales->(RECNO())

? Customer->(RECNO()) Funes 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 dcimo de segundo. Se for especificado zero, o programa pra at que uma tecla seja pressionada. Caso <nSegundos> seja omitido, INKEY() no espera por uma tecla. Retorno

INKEY() retorna um valor numrico inteiro de -39 at 386, que identifica a tecla extrada do buffer de teclado. Caso o buffer de teclado esteja vazio, INKEY() retorna zero. INKEY() retorna valores para todas as combinaes de caracteres ASCII, teclas de funo, Alt-tecla de funo, Ctrl-tecla de funo, Alt-letra, e Ctrlletra. Descrio

INKEY() uma funo de tratamento de teclado que extrai a prxima tecla pendente no buffer de teclado e retorna um valor que representa esta tecla. O valor tambm gravado internamente e pode ser acessado atravs da funo LASTKEY(). Caso o argumento <nSegundos> seja especificado e no haja teclas pendentes no buffer, acontece uma pausa na execuo do programa at que aparea uma tecla no buffer de teclado, ou ento at os <nSegundos> especificados tenham passado. O perodo de tempo que INKEY() espera baseiase no relgio do sistema operacional e no relacionado velocidade do microprocessador. Se <nSegundos> for zero, h uma pausa na execuo do programa at que uma tecla seja colocada no buffer. Observe que INKEY() no um estado de espera e, portanto, as teclas configuradas por SET KEY no so ativas.

INKEY() semelhante funo NEXTKEY(). De forma diferente de INKEY(), porm, NEXTKEY() l mas no extrai a tecla do buffer de teclado. Esta funo til quando voc precisa verificar se uma tecla foi pressionada sem que a mesma seja processada.

INKEY() a funo bsica do sistema Clipper para capturar teclas do buffer de teclado. utilizada para receber o teclado ou parar a execuo do programa at que o usurio pressione uma tecla. Por exemplo, voc pode utilizar INKEY() para terminar comandos com abrangncia de registros tais como LIST, LABEL FORM, e REPORT FORM se ela for includa em uma condio WHILE. Consulte o exemplo

abaixo.

Para uma lista completa de cdigos 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 := 0

DO WHILE LASTKEY() != K_ESC

? "Aperte qualquer tecla: "

nInkeyCode := INKEY(0)

?? "Caractere:", CHR(nInkeyCode),;

"Codigo INKEY():", LTRIM(STR(nInkeyCode))

ENDDO

RETURN

Este exemplo utiliza INKEY() para receber uma tecla de interrupo do usurio durante um REPORT FORM. Se o usurio pressionar Esc durante o processo de impresso, o comando REPORT FORM termina:

#include "Inkey.ch"

//

USE Sales INDEX Salesman NEW

REPORT FORM Monthly FOR MONTH(SalesDate) == MONTH(DATE());

WHILE INKEY() != K_ESC TONE()

Aciona o alto-falante por uma durao e frequncia especificadas. Sintaxe

TONE(<nFrequncia>, <nDurao>) --> NIL Argumentos

<nFrequncia> um valor numrico positivo que indica a frequncia do som a ser produzido.

<nDurao> um valor numrico positivo que indica a durao do som, medida em incrementos de 1/18 de segundo; um segundo, portanto, 18.

Para os dois argumentos, valores no inteiros so truncados--e no arredondados--para sua poro inteira. Retorno

TONE() sempre retorna NIL. Descrio

TONE() uma funo de tratamento de sons utilizada para indicar ao usurio os vrios estados do programa. Por estados entende-se estados de erro, condies 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 usurio atravs de uma mensagem ou dilogo interativo. Um condio de limite pode indicar que o usurio est tentando levar o cursor para alm dos limites superior ou inferior de uma coluna em um objeto TBrowse. Um processo de batch tambm pode indicar que chegou ao seu final atravs de um som para alertar o usurio, caso este tenha se afastado da tela.

TONE() funciona acionando o alto-falante na frequncia especificada, e pela durao especificada. A durao medida em incrementos de 1/18 de segundo. A frequncia medida em hertz (ciclos por segundo).

Frequncias abaixo de 20 so inaudveis. A tabela abaixo demonstra as frequncias de notas musicais padro. Nota

TONE() funciona apenas em IBM-PC e computadores 100% compatveis. Tabela 5-33: Notas Musicais

Nota

Frequncia

Nota

Frequncia

130.80

mid C

261.70

C#

138.60

C#

277.20

146.80

293.70

D#

155.60

D#

311.10

164.80

329.60

174.60

349.20

F#

185.00

F#

370.00

196.00

392.00

G#

207.70

G#

415.30

220.00

440.00

A#

233.10

A#

466.20

B2

46.90

493.90

523.30

Exemplos

O exemplo a seguir uma funo de bip, utilizada para indicar que uma operao de batch terminou:

FUNCTION DoneBeep

TONE(300, 1)

TONE(100, 1)

TONE(300, 1)

TONE(100, 1)

RETURN NIL

Este exemplo uma sequncia de sons usada para indicar teclagens invlidas ou condies de limite:

FUNCTION ErrorBeep

TONE(100, 3)

RETURN NIL 1 Comentrios