Apostila de Clipper

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
CLIPPER Apostila de Linguagem de Programao I
1999
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
Colgio Catanduvas
Prof. Hlio Lemes Costa Jr.
1999
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.
Colgio Catanduvas
1999
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
Colgio Catanduvas
1999
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:
Colgio Catanduvas
1999
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
Colgio Catanduvas
1999
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.
Colgio Catanduvas
1999
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>]
Colgio Catanduvas
1999
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
Colgio Catanduvas
1999
@...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.
Colgio Catanduvas
10
1999
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.
Colgio Catanduvas
11
1999
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
B
C
D
E
R
X
Z
(
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
Colgio Catanduvas
12

!
1999
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
A,N,X,9,#
L
Y
!
$
*
.
,
Ao
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"
@ 2, 1 SAY nNetLoss PICTURE "@)"
@ 3, 1 SAY cPhone PICTURE "@R (999)999-9999"
@ 4, 1 SAY cName PICTURE "@!"
//Resulta: 7,125.50
//Resulta: (125.50)
//Resulta: (213)456-7890
//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
Colgio Catanduvas
13
1999
@...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
Colgio Catanduvas
14
1999
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 re-exibe uma tela
previamente gravada, e utilizada juntamente com o comando SAVE SCREEN para evitar qua a tela
original escrita com os comandos @...SAY, @...GET seja re-escrita.
Este comando opera de duas formas, dependendo se a 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
Colgio Catanduvas
15
1999
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
Colgio Catanduvas
16
1999
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.
Colgio Catanduvas
17
1999
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.
Colgio Catanduvas
18
1999
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
A
B
C
D
E
Tipo
C
N
N
D,N
D,N
K
R
TODOS
C
S<n>
X
Z
(
)
!
N
N
N
N
C
Ao
Permite somente caracteres alfabticos
Exibe nmeros alinhados esquerda
Exibe CR aps nmeros positivos
Exibe datas segundo o formato SET DATE
Exibe datas com o ms e dia invertidos independente do SET DATE
corrente, nmericos com pontos e vrgulas period reverse invertidos
Elimina texto assumido caso a primeira tecla no seja cursor
Caracteres no-template so inseridos na tela mas no so guardados na
varivel
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
A
N
X
9
#
L
Y
!
$
*
.
,
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.
Colgio Catanduvas
19
1999
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
Colgio Catanduvas
20
1999
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
Colgio Catanduvas
21
1999
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
Cursor para cima
Cursor para baixo
Home
End
Ao
Move para o item anterior
Move para o prximo item
Move para o primeiro item
Move para o ltimo item Cursor para esquerda Move para o item
anterior Cursor para direita Move para o prximo item
Colgio Catanduvas
22

PgUp
PgDn
Return
Esc
Primeira letra
1999
Seleciona item de menu, retorna posio

Aborta seleo, retorna zero
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.
Colgio Catanduvas
23
1999
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 ps-condio 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
Cursor para esquerda, Ctrl-S
Cursor para direita, Ctrl-D
Ctrl-Cursor para esquerda, Ctrl-A
Ctrl-Cursor para direita, Ctrl-F
Cursor para cima, Ctrl-E
Cursor para baixo, Ctrl-X,
Home
End ltimo caractere do GET
Ctrl-Home
Ctrl-End
Ao
Caractere esquerda. No move cursor para o GET
anterior
Caractere direita. No move cursor para o prximo GET
Palavra esquerda
Palavra direita
GET anterior
Return, Ctrl-M Prximo GET
Primeiro caractere do GET
Incio do primeiro GET
Incio do ltimo GET
Tabela 4-10: Teclas de Edio de READs

Tecla
Del, Ctrl-G
Backspace, Ctrl-H
Ctrl-T
Ctrl-Y
Ctrl-U
Ao
Elimina caractere onde est o cursor
Backspace
Elimina palavra direita
Elimina do cursor at o final do GET
Retorna o GET ao seu valor original
Tabela 4-11: Teclas Comutativas em um READ

Tecla
Ins, Ctrl-V
Ao
Comuta modo de insero
WAIT*
Suspende a execuo de um programa at que seja pressionada uma tecla
Colgio Catanduvas
24
1999
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
Colgio Catanduvas
25
1999
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
Colgio Catanduvas
26
1999
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
Colgio Catanduvas
27
1999
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
1
2
3
Nome
Field_name
Field_type
Field_len
Tipo
Caractere
Caractere
Numrico
Tamanho
10
1
3
Colgio Catanduvas
Decimais
0
28

4
Field_dec
Numrico
1999
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.
Colgio Catanduvas
29
1999
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.
Colgio Catanduvas
30
1999
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()
GO TOP
? RECNO()
// Resulta: 84
// 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.
Colgio Catanduvas
31
1999
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.
Colgio Catanduvas
32
1999
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")
INDEX ON Branch TO Branch
? TYPE("Amount")
INDEX ON Amount TO Amount
? TYPE("Date")
INDEX ON Date TO Date
// Resulta: C
// Resulta: N
// Resulta: D
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
Colgio Catanduvas
33

Ctrl-W, Ctrl-C, PgUp,
PgDn
Return, Ctrl-M
Esc
Cursor para cima
Cursor para baixo
1999
Encerra um READ gravando GET corrente

Encerra um READ a partir do ltimo GET
Encerra um READ sem gravar o GET corrente
Encerra um READ a partir do primeiro GET se READEXIT()=.T.
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
SEEK cLookup
IF FOUND()
@ 15, 10 GET Salesman
// Adiciona novos GETS a GetList
@ 16, 10 GET Amount
Colgio Catanduvas
34

READ
ENDIF
CLOSE Sales
RETURN .T.
1999
// READ GetList
// 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
Colgio Catanduvas
35
1999
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.
Colgio Catanduvas
36
1999
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
//
Colgio Catanduvas
37
1999
<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
Colgio Catanduvas
38

SKIP -5
? RECNO()
1999
// 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"
Colgio Catanduvas
39
1999
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())
Colgio Catanduvas
40
1999
Comandos para clculos sobre registros

COUNT
Totaliza o nmero de registros e coloca o resultado numa varivel
Sintaxe
COUNT TO <idVar>
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
Colgio Catanduvas
41
1999
SUM
Soma expresses numricas e coloca o valor em variveis
Sintaxe
SUM <nLista expr> TO <idLista var>
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
? nSum2
// Resulta: 151515.00
// Resulta: 150675.00
Comandos para controle do fluxo do programas

DO*
Invoca um procedure
Sintaxe
DO <idProcedure> [WITH <lista argumentos>]
Colgio Catanduvas
42
1999
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
Colgio Catanduvas
43
1999
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:
Colgio Catanduvas
44
1999
@ 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.
Colgio Catanduvas
45
1999
Exemplos
O exemplo a seguir demonstra uma estrutura de controle tpica para um relatrio por grupos:
LOCAL cOldSalesman, nTotalAmount
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]
Colgio Catanduvas
46
1999
<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>...
Colgio Catanduvas
47
1999
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.
Colgio Catanduvas
48
1999
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
Colgio Catanduvas
49
1999
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:
Colgio Catanduvas
50
1999
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.
Colgio Catanduvas
51
1999
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
Colgio Catanduvas
52
1999
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
Colgio Catanduvas
53
1999
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 )
Colgio Catanduvas
54
1999
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>]
[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.
Colgio Catanduvas
55
1999
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
Colgio Catanduvas
56
1999
Sintaxe
REPORT FORM <xcRelatrio>
[TO PRINTER] [TO FILE <xcArquivo>]
[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).
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.
Colgio Catanduvas
57
1999
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"
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
Colgio Catanduvas
58
1999
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
Colgio Catanduvas
59
1999
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 macrosubstituio de uma varivel.
SET COLOR TO sem argumentos restaura as cores padro para W/N,N/W,N,N,N/W.
Descrio
Colgio Catanduvas
60
1999
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
Preto
Azul
Verde
Ciano
Vermelho
Magenta
Marrom
Branco
Cinza
Azul Brilahnte
Verde Brilhante
Ciano Brilhante
Verme lho Brilhante
Magenta Brilhante
Amarelo
Branco Brilhante
Preto
Vdeo Inverso
Incolor
Letra
N,Espao
B
G
BG
R
RB
GR
W
N+
B+
G+
BG+
R+
RB+
GR+
W+
U
I
X
Nmero
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Colgio Catanduvas
Monocromtico
Preto
Sublinhado
Branco
Branco
Branco
Branco
Branco
Branco
Preto
Sublinhado Brilhante
Branco Brilhante
Branco Brilhante
Branco Brilhante
Branco Brilhante
Branco Brilhante
Branco Brilhante
Sublinhado
Vdeo Inverso
Incolor
61
1999
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.
Colgio Catanduvas
62
1999
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
Colgio Catanduvas
63
1999
<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
AMERICAN
ANSI
BRITISH
FRENCH
GERMAN
ITALIAN
JAPAN
USA
Formato
mm/dd/yy
yy.mm.dd
dd/mm/yy
dd/mm/yy
dd.mm.yy
dd-mm-yy
yy/mm/dd
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
Colgio Catanduvas
64
1999
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
? 2/4
? 1/3
SET DECIMALS TO 4
? 2/4
? 1/3
// O padro
// Resulta: 0.50
// Resulta: 0.33
// Resulta: 0.5000
// 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.
Colgio Catanduvas
65
1999
<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.
Colgio Catanduvas
66
1999
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:
@ 2,10 SAY "Alo pessoal"
EJECT
Este exemplo, por outro lado, envia comandos @...SAYs a um arquivo:
SET PRINTER TO Output.txt
@ 10, 10 SAY "Arquivo: Output.txt"
@ 11, 10 SAY DATE()
SET PRINTER TO
// Fecha o arquivo
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
Colgio Catanduvas
67
1999
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
Colgio Catanduvas
68
1999
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 invoc-lo.
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
CLEAR GETS
BREAK
KEYBOARD Ctrl-W
KEYBOARD Esc
Ao
Encerra o READ sem gravar o GET corrente
Encerra o READ e grava 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
Colgio Catanduvas
69
1999
@ 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
Colgio Catanduvas
70
1999
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
Colgio Catanduvas
71
1999
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 PRINTER ON
@ 0, 0 SAY "Isto vai para Prnfile.txt"
? "Assim como isto!"
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>
Colgio Catanduvas
72
1999
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
Colgio Catanduvas
73
1999
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
? ABS(nNum1 - nNum2)
? ABS(nNum2 - nNum1)
? ABS(-12)
? ABS(0)
// Resulta: -50
// Resulta: 50
// Resulta: 50
// Resulta: 12
// Resulta: 0
Colgio Catanduvas
74
1999
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)
SET DECIMALS TO 10
? EXP(1)
? LOG(EXP(1))
// Resulta: 2.72
// Resulta: 2.7182818285
// 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.
Colgio Catanduvas
75
1999
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)
? LOG(10 * 2)
? EXP(LOG(1))
? LOG(2.71)
// Resulta: 2.30
// Resulta: 3.00
// Resulta: 1.00
// Resulta: 1.00
Colgio Catanduvas
76
1999
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()
3
3
-3
-3
-1
-2
2
1
0
-2
2
0
3
3
-3
-3
Erro
1
-1
Erro
-1
-2
2
1
Erro
-1
1
Erro
2
1
-1
-2
Funo MOD() no
dBASE III Plus
3
-1
1
-3
2
1
-1
-2
Notas
Colgio Catanduvas
77
1999
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)
? ROUND(10.5, 0)
? ROUND(10.51, 0)
? ROUND(10.49999999999999, 2)
Colgio Catanduvas
// Resulta: 10.00
// Resulta: 11.00
// Resulta: 11.00
// Resulta: 10.50
78
1999
Estes exemplos utilizam um argumento <nDecimais> negativo para arredondar valores numricos
para valores numricos inteiros:
? ROUND(101.99, -1)
? ROUND(109.99, -1)
? ROUND(109.99, -2)
// Resulta: 100.00
// Resulta: 110.00
// 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
Colgio Catanduvas
79
1999
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:
Colgio Catanduvas
80
1999
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("")
? LEN(CHR(0))
// Resulta: 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().
Colgio Catanduvas
81
1999
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)
? LEN(STR(nNumber))
? LTRIM(STR(nNumber))
? LEN(LTRIM(STR(nNumber)))
// Resulta: 18
// Resulta: 10
// Resulta: 18
// 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)
? REPLICATE("Oi ", 2)
? REPLICATE(CHR(42), 5)
// Resulta: *****
// Resulta: Oi Oi
// Resulta: *****
Este exemplo utiliza REPLICATE() para preencher o teclado com vrias teclas Cursor para baixo:
#include "Inkey.ch"
Colgio Catanduvas
82
1999
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.
Colgio Catanduvas
83
1999
<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
Varivel
Expresses/constantes
VAL()
MONTH()/DAY()
YEAR()
RECNO()
Tamanho do Valor de Retorno

Campo Tamanho do campo mais decimais
Mnimo de 10 dgitos mais decimais
Mnimo de 3 dgitos
3 dgitos
5 dgitos
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
Colgio Catanduvas
84

? STR(nNumber)
? STR(nNumber, 4)
? STR(nNumber, 2)
? STR(nNumber * 10, 7, 2)
? STR(nNumber * 10, 12, 4)
? STR(nNumber, 10, 1)
1999
// Resulta:123.45
// Resulta: 123
// Resulta: **
// Resulta: 1234.50
// Resulta: 1234.5000
// 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:
Colgio Catanduvas
85

cName := "Biff Styvesent"
? SUBSTR(cNome, 1, 4)
? SUBSTR(cNome, 6)
? SUBSTR(cNome, LEN(cNome) + 2)
? SUBSTR(cNome, -9)
? SUBSTR(cNome, -9, 3)
1999
// Resulta: Biff
// Resulta: Styvesent
// Resulta: null string
// Resulta: Styvesent
// 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")
? UPPER("123 char = <>")
// Resulta: A STRING
// Resulta: 123 CHAR = <>
Colgio Catanduvas
86
1999
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.
Colgio Catanduvas
87
1999
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")
? VAL("12.1256")
? VAL("12A12")
? VAL("A1212")
? VAL(SPACE(0))
? VAL(SPACE(1))
? VAL(" 12.12")
? VAL("12 .12")
// Resulta: 12.12
// Resulta: 12.13
// Resulta: 12.00
// Resulta: 0.00
// Resulta: 0.00
// Resulta: 0.00
// Resulta: 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
Colgio Catanduvas
88
1999
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()
? DATE() + 30
// Resulta: 09/01/90
// Resulta: 10/01/90
Colgio Catanduvas
89

? DATE() - 30
dDate = DATE()
? CMONTH(dDate)
1999
// Resulta: 08/02/90
// 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()
? DTOC(DATE())
? "Hoje e " + DTOC(DATE())
// Resulta: 09/01/90
// Resulta: 09/01/90
// Resulta: Hoje e 09/01/90
DTOS()
Converte um valor data para uma cadeia de caracteres com formato aaaammdd
Sintaxe
DTOS(<dData>) --> cData
Argumentos
Colgio Catanduvas
90
1999
<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()
? DTOS(DATE())
? LEN(DTOS(CTOD("")))
// Resulta: 09/01/90
// Resulta: 19900901
// 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
Colgio Catanduvas
91
1999
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
Colgio Catanduvas
92
1999
(.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
Cursor para cima
Ao
Vai para o item anterior
Colgio Catanduvas
93

Cursor para baixo
Home
End
Ctrl-Home
Ctrl-End
PgUp
PgDn
Ctrl-PgUp
Ctrl-PgDn
Return
Esc
Cursor para esquerda
Cursor para direita
Primeira letra
1999
Vai para o prximo item

Vai para o primeiro item do menu
Vai para o ltimo item do menu
Vai para o primeiro item da janela
Vai para o ltimo item da janela
Vai para a pgina anterior
Vai para a prxima pgina
Seleciona item corrente
Aborta seleo
Aborta seleo
Aborta seleo
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
Cursor para cima
Cursor para baixo
Ctrl-Home
Ctrl-End
PgUp
PgDn
Ctrl-PgUp
Ctrl-PgDn
Ao
Vai para o item anterior
Vai para o prximo item
Vai para o primeiro item da janela
Vai para o ltimo item da janela
Vai para a pgina anterior
Vai para a prxima pgina
Quando ACHOICE() executa a funo de usurio, ela passa automaticamente os trs parmetros a
seguir:
Colgio Catanduvas
94
1999
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
0
1
2
3
4
Achoice.ch
AC_IDLE
AC_HITTOP
AC_HITBOTTOM
AC_EXCEPT
AC_NOITEM
Descrio
Inativo
Tentativa de passar incio da lista
Tentativa de passasr final da lista
Teclagemn exceo
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
0
1
2
3
Achoice.ch
AC_ABORT
AC_SELECT
AC_CONT
AC_GOTO
Ao
Aborta seleo
Executa seleo
Continua ACHOICE()
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"
Colgio Catanduvas
95
1999
//
alSelectableItens[1] := .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
<new>
<bof>
<delete>
Record
Significado
Modo de Append
Incio de arquivo
Registro corrente est marcado para eliminao
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.
Colgio Catanduvas
96
1999
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
Colgio Catanduvas
97
1999
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
Cursor para cima
Cursor para baixo
Cursor para esquerda
Cursor para direita
Ctrl-Cursor para esquerda
Ao
Sobe uma linha
Desce uma linha
Coluna esquerda
Coluna direita
Painel uma coluna para esquerda
Colgio Catanduvas
98

Ctrl-Cursor para direita
Home
End
Ctrl-Home
Ctrl-End
PgUp
PgDn
Ctrl-PgUp
Ctrl-PgDn
Return
Esc
1999
Painel uma coluna para direita

Coluna mais esquerda na tela
Coluna mais direita na tela
Coluna inicial
Coluna final
Tela anterior
Prxima tela
Primeira linha da coluna corrente
Ultima linha da coluna corrente
Encerra DBEDIT()
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
0
1
2
3
4
bedit.ch
E_IDLE
E_HITTOP
E_HITBOTTOM
E_EMPTY
DC_EXCEPT
escrio
nativa, todas teclas foram manipuladas e no h teclas pendentes
entativa de passar incio de arquivo
entativa de passar final de arquivo
rquivo vazio na rea corrente
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
0
1
2
bedit.ch
E_ABORT
E_CONT
E_REFRESH
escrio
Aborta DBEDIT()
ontinua DBEDIT()
Fora reler e reescrever a tela e continuar; aps reescrever, processa
teclas, e vai para inativa
A funo do usurio chamada nos seguintes casos:
Colgio Catanduvas
99
1999
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
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.).
Colgio Catanduvas
100
1999
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()
SKIP
? EOF()
// Resulta: .F.
// 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
Colgio Catanduvas
101
1999
? "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).
Colgio Catanduvas
102
1999
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
RETURN NIL
// Retorna objeto para RECOVER
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.
Colgio Catanduvas
103
1999
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()
? Sales->(FCOUNT())
// Resulta: 5
// 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.).
Colgio Catanduvas
104
1999
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 fazla 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)
SEEK "1000"
? FOUND()
SEEK "100"
? FOUND()
SKIP
? FOUND()
// Resulta: SALESMAN
// Resulta: .F.
// Resulta: .T.
// Resulta: .F.
Este exemplo demonstra como acessar um valor FOUND() em uma rea de trabalho no selecionada
atravs de uma expresso alias:
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:
SEEK "Smith"
WHILE FOUND()
.
. <declaraes>
.
SKIP
LOCATE REST WHILE Name = "Smith"
Colgio Catanduvas
105
1999
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.
Colgio Catanduvas
106
1999
<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 Ctrl-W, 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
Cursor para cima/Ctrl-E
Ao
Move para cima uma linha
Colgio Catanduvas
107

Cursor para baixo/Ctrl-X
Cursor para esquerda/Ctrl-S
Cursor para direita/Ctrl-D
Ctrl-Cursor para esquerda/Ctrl-A
Ctrl-Cursor para direita/Ctrl-F
Home
End
Ctrl-Home
Ctrl-End
PgUp
PgDn
Ctrl-PgUp
Ctrl-PgDn
Return
Del
Backspace
Tab
Caracteres Imprimveis
Ctrl-Y
Ctrl-T
Ctrl-B
Ctrl-V/Ins
Ctrl-W
Esc
1999
Move para baixo uma linha

Move para esquerda um caractere
Move para direita um caractere
Move para esquerda uma palavra
Move para direita uma palavra
Move para o incio da linha corrente
Move para o final da linha corrente
Move para o incio da janela corrente
Move para o final da janela corrente
Move para janela anterior
Move para a prxima janela
Move para o incio do texto
Move para o final do texto
Move para o incio da prxima linha
Elimina caractere onde est o cursor
Elimina caractere esquerda do cursor
Insere tab ou espaos
Insere caractere
Elimina a linha corrente
Elimina a palavra direita
Reformata pargrafo
Grava e finaliza a edio
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
Colgio Catanduvas
108

0
1
2
3
ME_IDLE
ME_UNKEY
ME_UNKEYX
ME_INT
1999
Inativo, todas as teclas foram processadas

Tecla desconhecida,memo inalterado
Tecla desconhecida, memo alterado
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
0
1-31
32
33
34
35
100
101
Memoedit.ch
ME_DEFAULT
ME_UNKEY
ME_IGNORE
ME_DATA
ME_TOGGLEWRAP
ME_TOGGLESCROLL
ME_WORDRIGHT
ME_BOTTOMRIGHT
Ao
Executa ao padro
Processa ao correspondente ao valor da tecla
Ignora tecla
Trata tecla como dado
Comuta modo de transporte
Comuta modo de rolagem
Prxima palavra
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().
Colgio Catanduvas
109
1999
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
Ctrl-Y
Ctrl-T
Ctrl-B
Ctrl-V/Ins
Ctrl-W
Esc
Ao Padro
Elimina a linha corrente
Elimina a palavra direita
Reformata pargrafo
Finaliza edio e grava
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
Colgio Catanduvas
110
1999
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 ("").
Colgio Catanduvas
111
1999
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.).
Colgio Catanduvas
112
1999
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()
GO TOP
? RECNO()
nRecord := 3
GO nRecord
? RECNO()
GO BOTTOM
SKIP
? RECNO(), LASTREC()
// Resulta: 3
// Resulta: 1
// Resulta: 3
// 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
Colgio Catanduvas
113
1999
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 Ctrl-letra.
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 baseia-se 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)
Colgio Catanduvas
114
1999
?? "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"
//
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).
Colgio Catanduvas
115
1999
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
C
C#
D
D#
E
F
F#
G
G#
A
A#
B2
C
Frequncia
130.80
138.60
146.80
155.60
164.80
174.60
185.00
196.00
207.70
220.00
233.10
46.90
523.30
Nota
mid C
C#
D
D#
E
F
F#
G
G#
A
A#
B
-
Frequncia
261.70
277.20
293.70
311.10
329.60
349.20
370.00
392.00
415.30
440.00
466.20
493.90
-
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
Colgio Catanduvas
116

Apostila de Clipper

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Apostila de Clipper

Enviado por

Direitos autorais:

Formatos disponíveis

Introduo

Compilando Programas do Clipper

Chamando o Compilador do Clipper

CLIPPER <nome do arquivo>

CLIPPER Apostila de Linguagem de Programao I

Criando Arquivos Executveis com o EXOSPACE

EXOSPACE FILE Sample

Como o EXOSPACE encontra Arquivos da Biblioteca

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

LOCAL dWhen := DATE()

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Comandos para apresentao de dados

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

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

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Converte caracteres alfabticos para maisculas

Templates: Smbolos de template seguem as funes no string de PICTURE se forem especificados.

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

Outros caracteres especificados no template sobreescrevem o caractere na mesma posio no stream

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Os comandos e funes SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), e RESTSCREEN()

Comandos para entrada e edio de dados

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Funes: Uma funo PICTURE um smbolo precedido do smbolo @. Um smbolo de template

Tabela 4-1: Formatos de PICTURE para um GET

Templates: Smbolos de template seguem as funes no string de PICTURE se forem especificados.

Tabela 4-2: Smbolos Template para PICTURES de GETs

Outros caracteres especificados no template sobreescrevem o caractere localizado na mesma posio no

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

WHEN e VALID: Um objeto GET tambm possui expresses de pr condio e ps condio

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I

Atribuindo <idVar>: Devido s propriedades de refresh automtico e exibio de um objeto GET

Prof. Hlio Lemes Costa Jr.

CLIPPER Apostila de Linguagem de Programao I