Apostila

Advpl

Criao de Variveis
Na criao de uma varivel deve-se ter em mente alguns pontos fundamentais:

A declarao
O tipo de varivel
A funo CRIAVAR()
A inicializao
Padronizao de variveis

A Declarao
Deve ser feita sempre no incio da rotina que for utiliz-la, como no exemplo:
Function a910VerCod()
Local cCod910 := 001
Return

O Tipo de Varivel
O tipo de varivel serve para identificar a utilizao que a mesma ter no decorrer da rotina.
Toda varivel deve estar tipada durante sua criao. Quando programamos nativamente em
C, isto se torna obrigatrio. Devemos fazer o mesmo no AP5, pois isto demonstra que a
varivel foi conscientemente declarada.

Tipos Existentes
PUBLIC: Esta varivel ser inicializada em um valor lgico falso (.F.) at que seja
atribudo um valor especfico a ela. Esta varivel permanece definida por toda a durao da
aplicao e pode ser vista (assim como usada, alterada e avaliada) por qualquer funo.
Esta varivel gera um token (indicao) na tabela de smbolos, isto significa que o mdulo
principal conter smbolos para esta classe de varivel, o que, por sua vez, ocupa mais
espao de memria. Deve-se evitar a utilizao deste tipo, a no ser em casos extremos.
PRIVATE: Esta varivel ser inicializada em valor nulo (NIL) e uma vez declarada,
permanecer assim durante toda a durao do fluxo da funo, at que este volte ao
procedimento inicial que a chamou. Em essncia, uma varivel de memria PRIVATE
inicializada logo no incio do Protheus, agir como um varivel PUBLIC. Esta varivel
pode ser vista por uma sub-rotina da funo e modificada de maneira correspondente. Esta
varivel tambm gera um token na tabela de smbolos comentada acima.

Apostila
Advpl
LOCAL: Esta varivel de memria ser inicializada com valor nulo (NIL) e s visvel
dentro da funo que a inicializa, mesmo que esta ltima, contenha funes incorporadas a
seu contedo. Este tipo de varivel o mais adequado a ser utilizado em funes, pois no
gera smbolos na tabela de smbolos, por conseqncia ocupa pouco espao de memria e,
o compilador avalia as variveis LOCAL e STATIC mais rapidamente que os outros tipos
(PUBLIC e PRIVATE). Cuidado para no sucumbir teoria de que se pode obter economia
de memria, mudando qualquer referncia PRIVATE para uma referncia LOCAL. Se
voc fizer isso, as funes podem no funcionar corretamente, embora funcionassem na
verso anterior s alteraes.
STATIC: A varivel STATIC idntica classe de armazenamento LOCAL, com uma
exceo. Uma varivel STATIC retida dentro de sua sub-rotina, mesmo depois que o
fluxo da funo a tenha deixado. Isto particularmente til para funes independentes tipo
caixa-preta, que contm seu prprio conjunto de variveis exclusivas e devem manter
esses valores de interao em interao.

Inicializao
Quando no atribumos nenhum valor a uma varivel no momento de sua declarao,
corremos o risco de utiliz-la com valor NIL e causar erros fatais. Por isso, a
inicializao de uma varivel de extrema importncia.

Padronizao de Variveis
importante que ao lermos o nome de uma varivel, possamos saber se o seu tipo
numrico, caracter, data ou lgico. O nome da varivel de get no deve coincidir com uma
varivel de outro programa, pois toda varivel de get possui um help especfico.
Exemplo:
a varivel DBaixa (get da baixa no programa de Ttulos a Receber), j possui um texto help
que indica seu conteudo e no dever ser criada outra varivel para outra finalidade com
este mesmo nome.
Para tanto, definimos a seguinte padronizao :
N -> Numricas
L -> Lgicas
D -> Data
C -> Caracter

Apostila
Advpl
A -> Array (matriz)
O -> Objeto
U -> Sem definio

Criando uma Varivel Utilizando a Funo CRIAVAR()

Esta funo cria uma varivel, retornando o valor do campo, de acordo com o dicionrio de
dados. Avalia o inicializador padro e retorna o contedo de acordo com o tipo de dado
definido no dicionrio.
Sintaxe
uRet := CriaVar(cCampo,lIniPad,cLado)
Onde :
Uret -> tipo de retorno de acordo com o dicionrio de dados, considerando inicializador
padro.
cCampo -> Nome do campo
LiniPad -> Indica se considera (.T.) ou no (.F.) o inicializador padrao (X3_RELACAO)
Clado -> Lado para inicializao padro

Variveis de Relatrios
Na criao de um relatrio algumas variveis e seus tipos so convencionados para a
utilizao da biblioteca de funes de relatrio.
Varivel
wnRel
cbCont
Cabec1
Cabec2
Cabec3

Tipo
Local
Local
Local
Local
Local

Tamanho

Local

cDesc1
cDesc2

Local
Local

Contedo
Nome default do relatrio em disco
Contador
1 linha do cabealho do relatrio
2 linha do cabealho do relatrio
3 linha do cabealho do relatrio
Tamanho do Relatrio (P = Pequeno 80 colunas, M = Mdio 132
colunas, G = Grande, 220 colunas)
1 linha da descrio do relatrio
2 linha da descrio do relatrio

Apostila
Advpl
cDesc3
Limite
Titulo
aReturn
Nomeprog
cString

Local
Local
Local
Private
Private
Private

Li

Private

m_pag

Private

aOrd

Private

nLastKey
cPerg

Private
Private

aLinha

Private

3 linha da descrio do relatrio

Quantidade de colunas no relatrio (80,132,220)
Ttulo do Relatrio
Matriz com as informaes para a tela de configurao de impresso
Nome do programa do relatrio
Alias do arquivo principal do relatrio para o uso de filtro
Controle das linhas de impresso. Seu valor inicial a quantidade
mxima de linhas por pgina utilizada no relatrio
Controle do nmero de pginas do relatrio
Matriz contendo as ordens de layout para a impresso. Caso no
existam vrias ordens esta matriz deve estar vazia. Ex.: aOrd :=
{"Cdigo", "Descrio", "Telefone"} -> O layout do relatrio vai
depender da ordem selecionada na tela de configurao de
impresso
Utilizado para controlar o cancelamento da impresso do relatrio
Nome da pergunta a ser exibida para o usurio
Matriz que contem informaes para impresso de relatrios
cadastrais

Apostila
Advpl

Tipos de Dados
O AdvPl no uma linguagem de tipos rgidos (strongly typed), o que significa que
variveis de memria podem diferentes tipos de dados durante a execuo do programa.
Variveis podem tambm conter objetos, mas os tipos primrios da linguagem so:

Numrico
O AdvPl no diferencia valores inteiros de valores com ponto flutuante, portanto pode-se
criar variveis numricas com qualquer valor dentro do intervalo permitido. Os seguintes
elementos so do tipo de dado numrico:

2
43.53
0.5
0.00001
1000000

Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos
incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E308 at
1.7976931348623158 E+308.

Lgico
Valores lgicos em AdvPl so identificados atravs de .T. ou .Y. para verdadeiro e .F. ou
.N. para falso (independentemente se os caracteres estiverem em maisculo ou minsculo).

Caracter
Strings ou cadeias de caracteres so identificadas em AdvPl por blocos de texto entre aspas
duplas (") ou aspas simples ('):

Apostila
Advpl
"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"

Uma varivel do tipo caracter pode conter strings com no mximo 1 Mb, ou seja, 1048576
caracteres.

Data
O AdvPl tem um tipo de dados especfico para datas. Internamente as variveis deste tipo
de dado so armazenadas como um nmero correspondente a data Juliana.
Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs da
utilizao de funes especficas como por exemplo ctod que converte uma string para data.

Matriz (Array)
Matrizes so um tipo de dado especial. a disposio de outros elementos em colunas e
linhas. O AdvPl suporta matrizes uni ou multidimensionais. Os elementos de uma matriz
so acessados atravs de ndices numricos iniciados em 1, identificando a linha e coluna
para quantas dimenes existirem.
Uma matriz pode conter no mximo 100000 elementos, independentemente do nmero de
dimenses.
Matrizes devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a
memria do servidor.

Bloco de Cdigo
O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues
escritas em AdvPl que podero ser executadas posteriormente.

Apostila
Advpl

Criao e Atribuio de Variveis

Variveis de memria so um dos recursos mais importantes de uma linguagem. So reas
de memria criadas para armazenar informaes utilizadas por um programa para a
execuo de tarefas. Por exemplo, quando o usurio digita uma informao qualquer, como
o nome de um produto, em uma tela de um programa esta informao armazenada em
uma varivel de memria para posteriormente ser gravada ou impressa.
A partir do momento que uma varivel criada, no necessrio mais se referenciar ao seu
contedo, e sim ao seu nome. O nome de uma varivel um identificador nico que segue
duas regras regras:
Mximo de 10 caracteres. O AdvPl no impede a criao de uma varivel de memria
cujo nome contenha mais de 10 caracteres, porm apenas os 10 primeiros sero
considerados para a localizao do contedo armazenado. Portanto se forem criadas duas
variveis cujos 10 primeiros caracteres forem iguais, como nTotalGeralAnual e
nTotalGeralMensal, as referncias a qualquer uma delas no programa resultaro o mesmo.
Ou seja, sero a mesma varivel:

nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))

Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300. Isso
acontece porque no momento que esse valor foi atribuido varivel nTotalGeralAnual, o
AdvPl considerou apenas os 10 primeiros caracteres (assim como o faz quando deve exibir
o valor da varivel nTotalGeralMensal), ou seja, considerou-as como a mesma varivel.
Assim o valor original de 100 foi substituido pelo de 300.
Limitao de caracteres no nome. Os nomes das variveis devem sempre comear por
uma letra ou o caracter de sublinhado ( _ ). No restante, pode conter letras, nmeros e o
caracter de sublinhado. Qualquer outro caracter, incluindo espaos em branco, no so
permitidos.
7

Apostila
Advpl
O AdvPl permite a criao ilimitada de variveis, dependendo apenas da memria
disponvel. A seguir esto alguns nomes vlidos para variveis:

TOT01
cNumero
VAR_QUALQUER
M_CARGO
A11

E alguns invlidos:

1CODIGO (Inicia por um nmero)

M CARGO (contm um espao em branco)
LOCAL (palavra reservada do AdvPl)

O AdvPl no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio

informar o tipo de dados que determinada varivel ir conter no momento de sua
declarao, e o seu valor pode mudar durante a execuo do programa. Tambm no h
necessidade de declarar variveis em uma seo especfica do seu cdigo fonte, embora
seja aconselhvel declarar todas as variveis necessrias no comeo, tornando a
manuteno mais fcil e evitando a declarao de variveis desnecessrias.
Para declarar uma varivel deve-se utilizar um identificador de escopo, seguido de uma
lista de variveis separadas por vrgula (,). Um identificador de escopo uma palavra chave
que indica a que contexto do programa a varivel declarada pertence. O contexto de
variveis pode ser local (visualizadas apenas dentro do programa atual), pblico
(visualizadas por qualquer outro programa), entre outros. Os diferentes tipos de contexto de
variveis so explicados na documentao sobre escopo de variveis.
Considere as linhas de cdigo de exemplo:

Apostila
Advpl

nResultado := 250 * (1 + (nPercentual / 100))

Se esta linha for executada em um programa AdvPl, ocorrer um erro de execuo com a
mensagem "variable does not exist: nPercentual", pois esta varivel est sendo utilizada em
uma expresso de clculo sem ter sido declarada. Para solucionar este erro, deve-se declarar
a varivel previamente:

Local nPercentual, nResultado

nResultado := 250 * (1 + (nPercentual / 100))

Neste exemplo, as variveis so declaradas previamente utilizando o identificador de

escopo local. Quando a linha de clculo for executada, o erro de varivel no existente no
mais ocorrer. Porm variveis no inicializadas tm sempre o valor default nulo (Nil) e
este valor no pode ser utilizado em um clculo pois tambm gerar erros de execuo
(nulo no pode ser dividido por 100). A resoluo deste problema efetuada inicializandose a varivel atravs de uma das formas:

Local nPercentual,nResultado
Store 10 To nPercentual
nResultado := 250 * (1 + (nPercentual / 100))

ou

Local nPercentual, nResultado

nPercentual := 10
nResultado := 250 * (1 + (nPercentual / 100))
9

Apostila
Advpl

ou

Local nPercentual := 10, nResultado

nResultado := 250 * (1 + (nPercentual / 100))

A diferena entre o ltimo exemplo e os dois anteriores que a varivel inicializada no

momento da declarao. Nos dois primeiros exemplos, a varivel primeiro declarada e
ento inicializada em uma outra linha de cdigo. O comando store existe apenas por
compatibilidade com verses anteriores e outras linguagens xBase, mas obsoleto. Deve-se
utilizar o operador de atribuio (:= ou somente =). aconselhvel optar pelo operador de
atribuio composto de dois pontos e sinal de igual, pois o operador de atribuio
utilizando somente o sinal de igual pode ser facilmente confundido com o operador
relacional (para comparao) durante a criao do programa.
Uma vez que um valor lhe seja atribudo, o tipo de dado de uma varivel igual ao tipo de
dado do valor atribudo. Ou seja, uma varivel passa a ser numrica se um nmero lhe
atribudo, passa a ser caracter se uma string de texto lhe for atribuda, etc. Porm mesmo
que uma varivel seja de determinado tipo de dado, pode-se mudar o tipo da varivel
atribuindo outro tipo a ela:

01 Local xVariavel // Declara a varivel inicialmente com valor nulo

02
03 xVariavel := "Agora a varivel caracter..."
04 Alert("Valor do Texto: " + xVariavel)
05
06 xVariavel := 22 // Agora a varivel numrica
07 Alert(cValToChar(xVariavel))
08

10

Apostila
Advpl
09 xVariavel := .T. // Agora a varivel lgica
10 If xVariavel
11

Alert("A varivel tem valor verdadeiro...")

12 Else
13

Alert("A varivel tem valor falso...")

14 Endif
15
16 xVariavel := Date() // Agora a varivel data
17 Alert("Hoje : " + DtoC(xVariavel))
18
19 xVariavel := nil // Nulo novamente
20 Alert("Valor nulo: " + xVariavel)
21
22 Return

No programa de exemplo anterior, a varivel xVariavel utilizada para armazenar diversos

tipos de dados. A letra "x" em minsculo no comeo do nome utilizada para indicar uma
varivel que pode conter diversos tipos de dados, segundo a Notao Hngara (consulte
documentao especfica para detalhes). Este programa troca os valores da varivel e exibe
seu contedo para o usurio atravs da funo alert. Essa funo recebe um parmetro que
deve ser do tipo string de caracter, por isso dependendo do tipo de dado da varivel
xVariavel necessrio fazer uma converso antes.
Apesar dessa flexibilidade de utilizao de variveis, deve-se tomar cuidados na passagem
de parmetros para funes ou comandos, e na concatenao (ou soma) de valores. Note a
linha 20 do programa de exemplo. Quando esta linha executada, a varivel xVariavel
contem o valor nulo. A tentativa de soma de tipos de dados diferentes gera erro de
execuo do programa. Nesta linha do exemplo, ocorrer um erro com a mensagem "type
mismatch on +". Excetuando-se o caso do valor nulo, para os demais deve-se sempre

11

Apostila
Advpl
utilizar funes de converso quando necessita-se concatenar tipos de dados diferentes (por
exemplo, nas linhas 07 e 17.
Note tambm que quando uma varivel do tipo de dado lgico, ela pode ser utilizada
diretamente para checagem (linha 10):

If xVariavel

o mesmo que

If xVariavel = .T.

A declarao de variveis para os demais tipos de dados, matrizes e blocos de cdigo,

exatamente igual ao descrito at agora. Apenas existem algumas diferenas quanto a
inicializao, que podem ser consultadas na documentao de inicializao de matrizes e
blocos de cdigo.

12

Apostila
Advpl

Matrizes
Matrizes, ou arrays, so colees de valores. Ou, de uma maneira mais fcil de entender,
uma lista. Uma matriz pode ser criada atravs de diferentes maneiras. Consulte a
documentao sobre Inicializao de Matrizes para maiores detalhes.
Cada item em uma matriz referenciado pela indicao de sua posio numrica na lista,
iniciando pelo nmero 1. O exemplo a seguir declara uma varivel, atribui uma matriz de
trs elementos a ela, e ento exibe um dos elementos e o tamanho da matriz:

Local aLetras

// Declarao da varivel

aLetras := {"A", "B", "C"} // Atribuio da matriz varivel

Alert(aLetras[2])

// Exibe o segundo elemento da matriz

Alert(cValToChar(Len(aLetras))) // Exibe o tamanho da matriz

O AdvPl permite a manipulao de matrizes facilmente. Enquanto que em outras

linguagens como C ou Pascal necessrio alocar memria para cada elemento de uma
matriz (o que tornaria a utilizao de "pointeiros" necessria), o AdvPl se encarrega de
gerenciar a memria e torna simples adicionar elementos a uma matriz, utilizando a funo
aAdd:

aAdd(aLetras,"D") // Adiciona o quarto elemento ao final da matriz

13

Apostila
Advpl
Alert(aLetras[4]) // Exibe o quarto elemento
Alert(aLetras[5]) // Erro! No h um quinto elemento na matriz

Matrizes como Estruturas

Uma caracterstica interessante do AdvPl que uma matriz pode conter qualquer coisa:
nmeros, datas, lgicos, caracteres, objetos, etc. E ao mesmo tempo. Em outras palavras, os
elementos de uma matriz no precisam ser necessariamente do mesmo tipo de dado, em
contraste com outras linguagens como C e Pascal.

aFunct1 := {"Pedro",32,.T.}

Esta matriz contem uma string, um nmero e um valor lgico. Em outras linguagens como
C ou Pascal, este "pacote" de informaes pode ser chamado como um "struct" (estrutura
em C, por exemplo) ou um "record" (registro em Pascal, por exemplo). Como se fosse na
verdade um registro de um banco de dados, um pacote de informaes construdo com
diversos campos. Cada campo tendo um pedao diferente de dado.
Suponha que no exemplo anterior, o array aFunct1 contenha informaes sobre o nome de
uma pessoa, sua idade e sua situao matrimonial. Os seguintes #defines podem ser criados
para indicar cada posio dos valores dentro da matriz:

#define FUNCT_NOME 1
#define FUNCT_IDADE 2
#define FUNCT_CASADO 3

E considere mais algumas matrizes para representar mais pessoas:

aFunct2 := {"Maria" , 22, .T.}

aFunct3 := {"Antnio", 42, .F.}

14

Apostila
Advpl

Os nomes podem ser impressos assim:

Alert(aFunct1[FUNCT_NOME])
Alert(aFunct2[FUNCT_NOME])
Alert(aFunct3[FUNCT_NOME])

Agora, ao invs de trabalhar com variveis individuais, pode-se agrup-las em uma outra
matriz, do mesmo modo que muitos registros so agrupados em uma tabela de banco de
dados:

aFuncts := {aFunct1, aFunct2, aFunct3}

Que equivalente a isso:

aFuncts := { {"Pedro" , 32, .T.}, ;

{"Maria" , 22, .T.}, ;
{"Antnio", 42, .F.} }

aFuncts uma matriz com 3 linhas por 3 colunas. Uma vez que as variveis separadas
foram combinadas em uma matriz, os nomes podem ser exibidos assim:

Local nCount
For nCount := 1 To Len(aFuncts)

15

Apostila
Advpl
Alert(aFuncts[nCount,FUNCT_NOME])
// O acesso a elementos de uma matriz multidimensional
// pode ser realizado tambm desta forma:
// aFuncts[nCount][FUNCT_NOME]
Next nCount

A varivel nCount seleciona que funcionrio (ou que linha) de interesse. Ento a
constante FUNCT_NOME seleciona a primeira coluna daquela linha.

Cuidados com Matrizes

Matrizes so listas de elementos, portanto memria necessria para armazenar estas
informaes. Como as matrizes podem ser multidimensionais, a memria necessria ser a
multiplicao do nmero de itens em cada dimenso da matriz, considerando-se o tamanho
do contedo de cada elemento contido nesta. Portanto o tamanho de uma matriz pode variar
muito.
A facilidade da utilizao de matrizes, mesmo que para armazenar informaes em pacotes
como descrito anteriormente, no compensada pela utilizao em memria quando o
nmero de itens em um array for muito grande. Quando o nmero de elementos for muito
grande deve-se procurar outras solues, como a utilizao de um arquivo de banco de
dados temporrio.
No h limitao para o nmero de dimenses que uma matriz pode ter, mas o nmero de
elementos mximo (independentes das dimenses onde se encontram) de 100000.

16

Apostila
Advpl

Inicializando Matrizes
Algumas vezes o tamanho da matriz conhecido previamente. Outras vezes o tamanho da
matriz s ser conhecido em tempo de execuo.

Se o tamanho da matriz conhecido

Se o tamanho da matriz conhecido no momento que o programa escrito, h diversas
maneiras de implementar o cdigo.

01 Local nCnt
02 Local aX[10]
03 Local aY := Array(10)
04 Local aZ := {0,0,0,0,0,0,0,0,0,0}
05
06 For nCnt := 1 To 10
07

aX[nCnt] := nCnt * nCnt

17

Apostila
Advpl
08 Next nCnt

Este cdigo preenche a matriz com uma tabela de quadrados. Os valores sero 1, 4, 9, 16 ...
81, 100. Note que a linha 07 se refere varivel aX, mas poderia tambm trabalhar com aY
ou aZ. O objetivo deste exemplo demonstrar trs modos de criar uma matriz de tamanho
conhecido no momento da criao do cdigo.
Na linha 02 a matriz criada usando aX[10]. Isto indica ao AdvPl para alocar espao para
10 elementos na matriz. Os colchetes [ e ] so utilizados para indicar o tamanho necessrio.
Na linha 03 utilizada a funo array com o parmetro 10 para criar a matriz, e o retorno
desta funo atribudo varivel aY.
Na linha 03 efetuado o que se chama "desenhar a imagen da matriz". Como pode-se notar,
existem dez 0s na lista encerrada entre chaves ({}). Claramente, este mtodo no o
utilizado para criar uma matriz de 1000 elementos. O terceiro mtodo difere dos anteriores
porque inicializa a matriz com os valores definitivos. Nos dois primeiros mtodos, cada
posio da matriz contm um valor nulo (Nil) e deve ser inicializado posteriormente.
A linha 07 demonstra como um valor pode ser atribudo para uma posio existente em
uma matriz especificando o ndice entre colchetes.

Se o tamanho da matriz no conhecido

Se o tamanho da matriz no conhecido at o momento da execuo do programa, h
algumas maneiras de criar uma matriz e adicionar elementos a ela. O exemplo a seguir
ilustra a idia de criao de uma matriz vazia (sem nenhum elemento) e adio de
elementos dinamicamente.

01 Local nCnt
02 Local aX[0]
03 Local aY := Array(0)
04 Local aZ := {}
05
06 For nCnt := 1 To nSize

18

Apostila
Advpl
07

aAdd(aX,nCnt*nCnt)

08 Next nCnt

A linha 02 utiliza os colchetes para criar uma matriz vazia. Apesar de no ter nenhum
elemento, seu tipo de dado matriz.
Na linha 03 a chamada da funo array cria uma matriz sem nenhum elemento.
Na linha 04 est declarada a representao de uma matriz vazia em AdvPl. Mais uma vez,
esto sendo utilizadas as chaves para indicar que o tipo de dados da varivel matriz. Note
que {} uma matriz vazia (tem o tamanho 0), enquanto {Nil} uma matriz com um nico
elemento nulo (tem tamanho 1).
Porque cada uma destas matrizes no contem elementos, a linha 07 utiliza a funo aadd
para adicionar elementos sucessivamente at o tamanho necessrio (especificado por
exemplo na varivel nSize).

Blocos de Cdigo
Blocos de cdigo so um conceito existente h muito tempo em linguagens xBase. No
como algo que apareceu da noite para o dia, e sim uma evoluo progressiva utilizando a
combinao de muitos conceitos da linguagem para a sua implementao.

Um Primeiro Lembrete
O AdvPl uma linguagem baseada em funes. Funes tm um valor de retorno. Assim
como o operador de atribuio :=.
Assim, ao invs de escrever:

x := 10 // Atribui o valor 10 varivel chamada X

Alert("Valor de x: " + cValToChar(x))

Posde-se escrever:

19

Apostila
Advpl

// Atribui e ento exibe o valor da varivel X

Alert("Valor de x: " + cValtoChar(X := 10))

A expresso x:=10 avaliada primeiro, e ento seu resultado (o valor de X, que agora 10)
passada para a funo cvaltochar para a converso para caracter, e em seguida para a
funo alert para a exibio. Por causa desta regra de precedncia possvel atribuir um
valor a mais de uma varavel ao mesmo tempo:

Z := Y := X := 0

Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:

Z := ( Y := (X := 0) )

Apesar do AdvPl avaliar expresses da esquerda para a direita, no caso de atribuies isso
acontece ao contrrio, da direita para a esquerda. O valor atribudo varivel X, que
retorna o valor para ser atribudo varivel Y e assim sucessivamente. Pode-se dizer que o
zero foi "propagado atravs da expresso".

Outro Lembrete
Em AdvPl pode-se juntar diversas linhas de cdigo em uma nica linha fscia do arquivo.
Por exemplo, o cdigo:

If lAchou
Alert("Cliente encontrado!")
Endif

20

Apostila
Advpl

pode ser escrito assim:

If lAchou ; Alert("Cliente encontrado!") ; Endif

O ponto-e-vrgula indica ao AdvPl que a nova linha de cdigo est para comear. Pode-se
ento colocar diversas linhas lgicas de cdigo na mesma linha fsica atravs do editor de
texto utilizado.

Apesar da possibilidade de se escrever todo o programa assim, em uma nica linha fsica,
isto no recomendado pois dificulta a legibilidade do programa e, conseqentemente, a
manuteno.

Lista de Expresses
A evoluo dos blocos de cdigo comea com as listas de expresses. Nos exemplos a
seguir, o smbolo ==> indicar o retorno da expresso aps sua avaliao (seja para atribuir
em uma varivel, exibir para o usurio ou imprimir em um relatrio), que ser impresso em
um relatrio por exemplo.

Duas Linhas de Cdigo

@00,00 PSAY x := 10

==>

10

@00,00 PSAY y := 20

==>

20

Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento impresso.

Duas Linha de Cdigo em Uma , Utilizando Ponto-e-Vrgula

Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:

Alert( cValToChar( x := 10 ; y := 20 ) ) ==>

10
21

Apostila
Advpl

Apesar desse cdigo se encontrar em uma nica linha fsica, existem duas linhas lgicas
separadas pelo ponto e vrgula. Ou seja, esse cdigo equivalente a:

Alert( cValToChar( x := 10 ) )
y := 20

Portanto apenas o valor 10 da varivel x ser passado para as funes cvaltochar e alert
para ser exibido. E o valor 20 apenas ser atribudo varivel y.

Convertendo para uma Lista de Expresses

Quando parnteses so colocados ao redor do cdigo e o sinal de ponto-e-vrgula
substitudo por uma vrgula apenas, o cdigo torna-se uma lista de expresses:

Alert( cValToChar ( ( X := 10 , Y := 20 ) ) ) ==> 20

O valor de retorno resultante de uma lista de expresses o valor resultante da ltima

expresso ou elemento da lista. Funciona como se fosse um pequeno programa ou funo,
que retorna o resultado de sua ltima avaliao (efetuadas da esquerda para a direita).
Neste exemplo, a expresso x := 10 avaliada, e ento a expresso y := 20, cujo valor
resultante passado para a funo alert e cvaltochar, e ento exibido. Depois que essa linha
de cdigo executada, o valor de X igual a 10 e o de y igual a 20, e 20 ser exibido.
Teoricamente, no h limitao para o nmero de expresses que podem ser combinadas
em uma lista de expresses. Na prtica, o nmero mximo por volta de 500 smbolos.
Debugar listas de expresses difcil oprque as expresses no esto divididas em linhas de
cdigo fonte, o que torna todas as expresses associadas a uma mesma linha de cdigo. Isto
pode tornar muito difcil determinar onde um erro ocorreu.

Onde Pode-se Utilizar uma Lista de Expresses?

22

Apostila
Advpl
O propsito principal de uma lista de expresses agrup-las em uma nica unidade. Em
qualquer lugar do cdigo AdvPl que uma expresso simples pode ser utilizada, pode-se
utilizar uma lista de expresses. E ainda, pode-se fazer com que vrias coisas aconteam
onde normalmente apenas uma aconteceria.

X := 10 ; Y := 20

If X > Y
Alert("X")
Z := 1
Else
Alert("Y")
Z := -1
Endif

Aqui temos o mesmo conceito, escrito utilizando listas de expresses na funo iif:

X := 10 ; Y := 20

iif( X > Y , ;
( Alert("X"), Z := 1 ) , ;
( Alert("Y"), Z := -1 ) )

De Listas de Expresses para Blocos de Cdigo

Considere a seguinte lista de expresses:

23

Apostila
Advpl

Alert( cValToChar( ( x := 10, y := 20 ) ) ) ==> 20

O AdvPl permite criar funes, que so pequenos pedaos de cdigo, como se fosse um
pequeno programa, utilizados para diminuir partes de tarefas mais complexas e reaproveitar
cdigo em mais de um lugar num programa. Para maiores detalhes consulte a
documentao sobre a criao de funes em AdvPl. Porm, a idia neste momento que a
lista de expresses utilizada na linha anterior pode ser criada como uma funo:

Function Lista()
X := 10
Y := 20
Return Y

E a linha de exemplo com a lista de expresses pode ser substituda, tendo o mesmo
resultado, por:

Alert( cValToChar( Lista() ) ) ==> 20

Como mencionado anteriormente, uma lista de expresses como um pequeno programa

ou funo. Com poucas mudanas, uma lista de expresses pode se tornar um bloco de
cdigo:

( X := 10 , Y := 20 ) // Lista de Expresses
{|| X := 10 , Y := 20 } // Bloco de Cdigo

24

Apostila
Advpl
Note as chaves {} utilizadas no bloco de cdigo. Ou seja, um bloco de cdigo uma
matriz. Porm na verdade, no uma lista de dados, e sim uma lista de comandos, uma lista
de cdigo.

// Isto uma matriz de dados

A := {10, 20, 30}

// Isto um bloco de cdigo, porm funciona como

// se fosse uma matriz de comandos
B := {|| x := 10, y := 20}

Executando um Bloco de Cdigo

Diferentemente de uma matriz, no se pode acessar elementos de um bloco de cdigo
atravs de um ndice numrico. Porm blocos de cdigo so semelhantes a uma lista de
expresses, e a uma pequena funo. Ou seja, podem ser executados. Para a execuo, ou
avaliao, de um bloco de cdigo, deve-se utilizar a funo eval:

nRes := Eval(B) ==> 20

Essa funo recebe como parmero um bloco de cdigo e avalias todas as expresses
contidas neste bloco de cdigo, retornando o resultado da ltima expresso avaliada.

Passando Parmetros
J que blocos de cdigo so como pequenas funes, tambm possvel a passagem de
parmetros para um bloco de cdigo. Os parmetros devem ser informados entre as barras
verticais (||) separados por vrgulas, assim como em uma funo.

B := {| N | X := 10, Y := 20 + N}

25

Apostila
Advpl

Porm deve-se notar que j que o bloco de cdigo recebe um parmetro, um valor deve ser
passado quando o bloco de cdigo for avaliado.

C := Eval(B, 1) ==> 21

Utilizando Blocos de Cdigo

Blocos de cdigo podem ser utilizados em diversas situaes. Geralmente so utilizados
para executar tarefas quando eventos de objetos so acionados ou para modificar o
comportamento padro de algumas funes.
Por exemplo, considere a matriz abaixo:

A := {"GARY HALL", "FRED SMITH", "TIM JONES"}

Esta matriz pode ser ordenada pelo primeiro nome, utilizando-se a chamada da funo
asort(A), resultado na matriz com os elementos ordenados dessa forma:

{"FRED SMITH", "GARY HALL", "TIM JONES"}

A ordem padro para a funo asort ascendente. Este comportamento pode ser modificado
atravs da informao de um bloco de cdigo que ordena a matriz de forma descendente:

B := { |X, Y| X > Y }
aSort(A, B)

O bloco de cdigo (de acordo com a documentao da funo asort) deve ser escrito para
aceitar dois parmetros que so os dois elementos da matriz para comparao. Note que o
26

Apostila
Advpl
bloco de cdigo no conhece que elementos est comparando - a funo asort seleciona os
elementos (talvez utilizando o algortmo QuickSort) e passa-os para o bloco de cdigo. O
bloco de cdigo compara-os e retorna verdadeiro (.T.) se se encontram na ordem correta, ou
falso (.F.) se no. Se o valor de retorno for falso, a funo asort ir ento trocar os valores
de lugar e seguir comparando o prximo par de valores.
Ento, no bloco de cdigo anterior, a comparao X > Y verdadeira se os elementos esto
em ordem descendente, o que significa que o primeiro valor maior que o segundo.
Para ordenar a mesma matriz pelo ltimo nome, tambm em orden descendente, pode-se
utilizar o seguinte bloco de cdigo:

B := { |X, Y| Substr(X,At(" ",X)+1) > Substr(Y,At(" ",Y)+1) }

Note que este bloco de cdigo procura e compara as partes dos caracteres imediatamente
seguinte a um espao em branco. Depois de utilizar esse bloco de cdigo para a funo
asort, a matriz conter:

{"GARY HALL", "TIM JONES", "FRED SMITH"}

Finalmente, para ordenar um sub-elemento (coluna) de uma matriz por exemplo, pode-se
utilizar o seguinte bloco de cdigo:

B := { |X, Y| X[1] > Y[1] }

27

Apostila
Advpl

Diferenciao entre variveis e nomes de

campos
Muitas vezes uma varivel pode ter o mesmo nome que um campo de um arquivo ou tabela
aberto no momento. Neste caso, o AdvPl privilegiar o campo. Assim uma referncia a um
nome que identifique tanto uma varivel como um campo, resultar no contedo do campo.
Para especificar qual deve ser o elemento referenciado, deve-se utilizar o operador de
identificao de apelido (->) e um dos dois identificadores de referncia, MEMVAR ou
FIELD.

28

Apostila
Advpl

cRes := MEMVAR->NOME

Esta linha de comando identifica que o valor atribudo varivel cRes deve ser o valor da
varivel de memria chamada NOME.

cRes := FIELD->NOME

Neste caso, o valor atribudo varivel cRes ser o valor do campo NOME existente no
arquivo ou tabela aberto na rea atual.
O identificador FIELD pode ser substitudo pelo apelido de um arquivo ou tabela aberto,
para evitar a necessidade de selecionar a rea antes de acessar o contedo de terminado
campo.

cRes := CLIENTES->NOME

Para maiores detalhes sobre abertura de arquivos com atribuio de apelidos, consulte a
documentao sobre acesso a banco de dados ou a documentao da funo dbUseArea.

Operadores Comuns
Na documentao sobre variveis h uma breve demonstrao de como atribuir valores a
uma varivel da forma mais simples. O AdvPl amplia significativamente a utilizao de
variveis atravs do uso de expresses e funes. Uma expresso um conjunto de
operadores e operandos cujo resultado pode ser atribudo a uma varivel ou ento analisado
para a tomada de decises. Por exemplo:

Local nSalario := 1000, nDesconto := 0.10

29

Apostila
Advpl
Local nAumento, nSalLiquido
nAumento := nSalario * 1.20
nSalLiquido := nAumento * (1-nDesconto)

Neste exemplo so utilizadas algumas expresses para calcular o salrio lquido aps um
aumento. Os operandos de uma expresso podem ser uma varivel, uma constante, um
campo de arquivo ou uma funo.

Operadores Matemticos
Os operadores utilizados em AdvPl para clculos matemticos so:
+
*
/
** ou ^
%

Adio
Subtrao
Multiplicao
Diviso
Exponenciao
Mdulo (Resto da Diviso)

Operadores de String
Os operadores utilizados em AdvPl para tratamento de caracteres so:
+ Concatenao de strings (unio)
- Concatenao de strings com eliminao dos brancos finais das strings intermedirias
$ Comparao de Substrings (contido em)

Operadores Relacionais
Os operadores utilizados em AdvPl para operaes e avaliaes relacionais so:
<
>
=
==
<=

Comparao Menor
Comparao Maior
Comparao Igual
Comparao Exatamente Igual (para caracteres)
Comparao Menor ou Igual
30

Apostila
Advpl
>= Comparao Maior ou Igual
<> Comparao Diferente
ou
#
ou
!=

Operadores Lgicos
Os operadores utilizados em AdvPl para operaes e avaliaes lgicas so:
.And.
E lgico
.Or.
OU lgico
.Not. ou ! NO lgico

Operadores de Atribuio
Os operadores utilizados em AdvPl para atribuio de valores a variveis de memria so:
=
:=
+=
-=
*=
/=
**= ou ^=
%=

Atribuio Simples
Atribuio em Linha
Adio e Atribuio em Linha
Subtrao e Atribuio em Linha
Multiplicao e Atribuio em Linha
Diviso e Atribuio em Linha
Exponenciao e Atribuio em Linha
Mdulo (resto da diviso) e Atribuio em Linha

31

Apostila
Advpl

Atribuio Simples
O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.

nVariavel = 10

Atribuio em Linha
O operador de atribuio em linha caracterizado por dois pontos e o sinal de igualdade.
Tem a mesma funo do sinal de igualdade sozinho, porm aplia a atribuio s variveis.
Com ele pode-se atribuir mais de uma varivel ao mesmo tempo.

nVar1 := nVar2 := nVar3 := 0

Quando diversas variveis so inicializadas em uma mesma linha, a atribuio comea da

direita para a esquerda, ou seja, nVar3 recebe o valro zero inicialmente, nVar2 recebe o
contedo de nVar3 e nVar1 recebe o contedo de nVar2 por final.
Com o operador de atribuio em linha, pode-se substituir as inicializaes individuais de
cada varivel por uma inicializao apenas:

Local nVar1 := 0, nVar2 := 0, nVar3 := 0

por

Local nVar1 := nVar2 := nVar3 := 0

32

Apostila
Advpl
O operador de atribuio em linha tambm pode ser utilizado para substituir valores de
campos em um banco de dados.

Atribuio Composta
Os operadores de atribuio composta so uma facilidade da linguagem AdvPl para
expresses de clculo e atribuio. Com eles pode-se economizar digitao:
Operador
+=
-=
*=
/=
**= ou ^=
%=

Exemplo
X += Y
X -= Y
X *= Y
X /= Y
X **= Y
X %= Y

Equivalente a
X=X+Y
X=X-Y
X=X*Y
X=X/Y
X = X ** Y
X=X%Y

Operadores de Incremento/Decremento
A linguagem AdvPl possui operadores para realizar incremento ou decremento de
variveis. Entende-se por incremento aumentar o valor de uma varivel numrica em 1 e
entende-se por decremento diminuir o valor da varivel em 1. Os operadores so:
++ Incremento Ps ou Pr-fixado
-- Decremento Ps ou Pr-fixado

Os operadores de decremento/incremento podem ser colocados tanto antes (pr-fixado)

como depois (ps-fixado) do nome da varivel. Dentro de uma expresso, a ordem do
operador muito importante, podendo alterar o resultado da expresso. Os operadores
incrementais so executados da esquerda para a direita dentro de uma expresso.

33

Apostila
Advpl

Local nA := 10
Local nB := nA++ + nA

O valor da varivel nB resulta em 21, pois a primeira referncia a nA (antes do ++)

continha o valor 10 que foi considerado e imediatamente aumentado em 1. Na segunda
referncia a nA, este j possua o valor 11. O que foi efetuado foi a soma de 10 mais 11,
igual a 21. O resultado final aps a execuo destas duas linhas a varivel nB contendo 21
e a varivel nA contendo 11.
No entando:

Local nA := 10
Local nB := ++nA + nA

Resulta em 22, pois o operador incremental aumentou o valor da primeira nA antes que seu
valor fosse considerado.

Operadores Especiais
Alm dos operadores comuns, o AdvPl possui alguns outros operadores ou identificadores.
Estas so suas finalidades:
()
[]
{}
->
&
@

Agrupamento ou Funo
Elemento de Matriz
Definio de Matriz, Constante ou Bloco de Cdigo
Identificador de Apelido
Macrosubstituio
Passagem de parmetro por referncia

34

Apostila
Advpl
Os parnteses so utilizados para agrupar elementos em uma expresso mudando a ordem
de precedncia da avaliao da expresso (segundo as regras matemticas por exemplo).
Tambm servem para envolver os argumentos de uma funo. Veja a documentao sobre
precedncia de operadores para maiores detalhes.
Os colchetes so utilizados para especificar um elemento especfico de uma matriz. Por
exemplo, A[3,2], refere-se ao elemento da matriz A na linha 3, coluna 2.
As chaves so utilizadas para a especificao de matrizes literais ou blocos de cdigo. Por
exemplo, A:={10,20,30} cria uma matriz chamada A com trs elementos.
O smbolo -> identifica um campo de um arquivo diferenciando-o de uma varivel. Por
exemplo, FUNC->nome refere-se ao campo nome do arquivo FUNC. Mesmo que exista
uma varivel chamada nome, o campo nome que ser acessado.
O smbolo & identifica uma avaliao de expresso atravs de macro e visto em detalhes
na documentao sobre macrossubstituio.
O smbolo @ utilizado para indicar que durante a passagem de uma varivel para uma
funo ou procedimento ela seja tomada como uma referncia e no como valor.

Ordem de Precedncia dos Operadores

Dependendo do tipo de operador, existe uma ordem de precedncia para a avaliao dos
operandos. Em princpio, todas as operaes com os operadores so realizadas da esquerda
para a direita se eles tiverem o mesmo nvel de prioridade.
A ordem de precedncia, ou nvel de prioridade de execuo, dos operadores em AdvPl :
1.
2.
3.
4.
5.
6.
7.

Operadores de Incremento/Decremento pr-fixado

Operadores de String
Operadores Matemticos
Operadores Relacionais
Operadores Lgicos
Operadores de Atribuio
Operadores de Incremento/Decremento ps-fixado
35

Apostila
Advpl
Em expresses complexas com diferentes tipos de operadores, a avaliao seguir essa
sequncia. Caso exista mais de um operador do mesmo tipo (ou seja, de mesmo nvel), a
avaliao se d da esquerda para direita. Para os operadores matemticos entretanto h uma
precedncia a seguir:
1. Exponenciao
2. Multiplicao e Diviso
3. Adio e Subtrao
Considere o exemplo:

Local nResultado := 2+10/2+5*3+2^3

O resultado desta expresso 30, pois primeiramente calculada a exponenciao 2^3(=8),

ento so calculadas as multiplicaes e divises 10/2(=5) e 5*3(=15), e finalmente as
adies resultando em 2+5+15+8(=30).

Alterao da Precedncia
A utilizao de parnteses dentro de uma expresso altera a ordem de precedncia dos
operadores. Operandos entre parnteses so analisados antes dos que se encontram fora dos
parnteses. Se existirem mais de um conjunto de parnteses no-aninhados, o grupo mais a
esquerda ser avaliado primeiro e assim sucessivamente.

Local nResultado := (2+10)/(2+5)*3+2^3

No exemplo acima primeiro ser calculada a exponenciao 2^3(=8). Em seguida

2+10(=12) ser calculado, 2+5(=7) calculado, e finalmente a diviso e a multiplicao
sero efetuadas, o que resulta em 12/7*3+8(=13.14).
Se existirem vrios parnteses aninhados, ou seja, colocados um dentro do outro, a
avaliao ocorrer do parnteses mais intero em direo ao mais externo.

36

Apostila
Advpl

Macro Substituio
O operador de macro substituio, simbolizado pelo "e" comercial (&), utilizado para a
avaliao de expresses em tempo de execuo. Funciona como se uma expresso
armazenada fosse compilada em tempo de execuo, antes de ser de fato executada.
Considere o exemplo:

01 X := 10
02 Y := "X + 1"
37

Apostila
Advpl
03 B := &Y // O contedo de B ser 11

A varivel X atribuda com o valor 10, enquanto a varivel Y atribuda com a string de
caracteres contendo "X + 1".
A terceira linha utiliza o operador de macro. Esta linha faz com que o nmero 11 seja
atribudo varivel B. Pode-se perceber que esse o valor resultante da expresso em
formato de caractere contida na varivel Y.
Utilizando-se uma tcnica matemtica elementar, a substituio, temos que na segunda
linha, Y definido como "X + 1", ento pode-se substituir Y na terceira linha:

03 B := &"X + 1"

O operador de macro cancela as aspas:

03 B := X + 1

Pode-se perceber que o operador de macro remove as aspas, o que deixa um pedao de
cdigo para ser executado. Deve-se ter em mente que tudo isso acontece em tempo de
eecuo, o que torna tudo muito dinmico. Uma utilizao interessante criar um tipo de
calculadora, ou avaliador de frmulas, que determina o resultado de algo que o usurio
digita.

O operador de macro tem uma limitao: variveis referenciadas dentro da string de

caracteres (X nos exemplos anteriores) no podem ser locais.

38

Apostila
Advpl

Controlando o Fluxo
O AdvPl suporta vrias estruturas de controle que permitem mudar a seqncia de fluxo de
execuo de um programa. Estas estruturas permitem a execuo de cdigo baseado em
condies lgica e a repetio da execuo de pedaos de cdigo qualquer nmero de
vezes.
Em AdvPl, todas as estruturas de controle podem ser "aninhadas" dentro de todas as demais
estruturas contanto que estejam aninhadas propriamente. Estruturas de controle tm um
identificador de incio e um de fim, e qualquer estrutura aninhada deve se encontrar entre
estes identificadores.

39

Apostila
Advpl
Tambm existem estruturas de controle para determinar que elementos, comandos, etc em
um programa sero compilados. Estas so as diretivas do pr-processador #ifdef...#endif e
#ifndef...#endif. Consulte a documentao sobre o pr-processador para maiores detalhes.
As estruturas de controle em AdvPl esto divididas em Estruturas de Repetio e Estruturas
de Deciso.

Repetio de Comandos
Estruturas de repetio so deseginadas para executar uma seo de cdigo mais de uma
vez. Por exemplo, imagiando-se a existncia de uma funo para imprimir um relatrio,
pode-se desejar imprimi-lo quatro vezes. Claro, pode-se simplesmente chamar a funo de
impresso quatro vezes em seqncia, mas isto se tornaria pouco profissional e no
resolveria o problema se o nmero de relatrios fosse varivel.
Em AdvPl existem dois comandos para a repetio de sees de cdigo. O comando
FOR...NEXT e o comando WHILE...ENDDO.

40

Apostila
Advpl

O Comando FOR...NEXT
A estrutura de controle FOR...NEXT, ou simplesmente o loop FOR, repete uma seo de
cdigo em um nmero determinado de vezes.
Sintaxe
FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento]
Comandos...
[EXIT]
[LOOP]
NEXT
Parmetros
Variavel

nValorInicial TO
nValorFinal
STEP
nIncremento

Comandos
EXIT

LOOP

Especifica uma varivel ou um elemento de uma matriz para atuar como

um contador. A varivel ou o elemento da matriz no precisa ter sido
declarado antes da execuo do comando FOR...NEXT. Se a varivel no
existir, ser criada como uma varivel privada.
nValorInicial o valor inicial para o contador; nValorFinal o valor final
para o contador. Pode-se utilizar valores numricos literais, variveis ou
expresses, contanto que o resultado seja do tipo de dado numrico.
nIncremento a quandidade que ser incrementada ou decrementada no
contador aps cada execuo da seo de comandos. Se o valor de
nIncremento for negativo, o contador ser decrementado. Se a clusula
STEP for omitida, o contador ser incrementado em 1. Pode-se utilizar
valores numricos literais, variveis ou expresses, contanto que o
resultado seja do tipo de dado numrico.
Especifica um ou mais instrues de comando AdvPl que sero
executadas.
Transfere o controle de dentro do comando FOR...NEXT para o comando
imediatamente seguinte ao NEXT, ou seja, finaliza a repetio da seo
de comandos imediatamente. Pode-se colocar o comando EXIT em
qualquer lugar entre o FOR e o NEXT.
Retorna o controle diretamente para a clusula FOR sem executar o
restante dos comandos entre o LOOP e o NEXT. O contador
incrementadou ou decrementado normalmente, como se o NEXT tivesse
41

Apostila
Advpl
sido alcanado. Pode-se colocar o comando LOOP em qualquer lugar
entre o FOR e o NEXT.
Comentrios
Uma varivel ou um elemento de uma matriz utilizado como um contador para especificar
quantas vezes os comandos AdvPl dentro da estrutura FOR...NEXT so executados. Os
comandos AdvPl depois do FOR so executados at que o NEXT seja alcanado. O
contador (Variavel) ento incrementado ou decremantado com o valor em nIncremento
(se a clusula STEP for omitida, o contador incrementado em 1). Ento, o contador
comparado com o valor em nValorFinal. Se for menor ou igual ao valor em nValorFinal, os
comandos seguintes ao FOR so executados novamente. Se o valor for maior que o contido
em nValorFinal, a estrutura FOR...NEXT terminada e o programa continua a execuo no
primeiro comando aps o NEXT.
Os valores de nValorInicial, nValorFinal e nIncremento so apenas considerados
inicialmente. Entretanto, mudar o valor da varivel utilizada como contador dentro da
estrutura afetar o nmero de vezes que a repetio ser executada. Se o valor de
nIncremento negativo e o valor de nValorInicial maior que o de nValorFinal, o contador
ser decrementado a cada repetio.
Exemplo
Local nCnt
Local nSomaPar := 0

For nCnt := 0 To 100 Step 2

nSomaPar += nCnt
Next

Alert( "A soma dos 100 primeiros nmeros pares : " + ;

cValToChar(nSomaPar) )

Return

42

Apostila
Advpl

Este exemplo imprime a soma dos 100 primerios nmeros pares. A soma obitida atravs
da repetio do clculo utilizando a prpria varivel de contador. Como a clusula STEP
est sendo utilizada, a varivel nCnt ser sempre incrementada em 2. E como o contador
comea com 0, seu valor sempre ser um nmero par.

O Comando WHILE...ENDDO
A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma
seo de cdigo enquanto uma determinada expresso resultar em verdadeiro (.T.).
Sintaxe
WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO
Parmetros
lExpressao Especifica uma expresso lgica cujo valor determina quando os
comandos entre o WHILE e o ENDDO so executados. Enquanto o
resultado de lExpressao for avaliado como verdadeiro (.T.), o conjunto de
comandos so executados.
Comandos
Especifica um ou mais instrues de comando AdvPl que sero
executadas enquanto lExpressao for avaliado como verdadeiro (.T.).
EXIT
Transfere o controle de dentro do comando WHILE...ENDDO para o
comando imediatamente seguinte ao ENDDO, ou seja, finaliza a repetio
da seo de comandos imediatamente. Pode-se colocar o comando EXIT
em qualquer lugar entre o WHILE e o ENDO.
LOOP
Retorna o controle diretamente para a clusula WHILE sem executar o
restante dos comandos entre o LOOP e o ENDDO. A expresso em
lExpressao reavaliada para a deciso se os comandos continuaro sendo

43

Apostila
Advpl
executados.
Comentrios
Os comandos entre o WHILE e o ENDDO so executados enquanto o resultado da
avaliao da expresso em lExpressao permanecer verdadeiro (.T.). Cada palavra chave
WHILE deve ter uma palavra chave ENDDO correspondente.
Exemplo
Local nNumber := nAux := 350

nAux := Int(nAux / 2)

While nAux > 0

nSomaPar += nCnt
Next

Alert( "A soma dos 100 primeiros nmeros pares : " + ;

cValToChar(nSomaPar) )

Return

Desviando a Execuo
Estruturas de desvio so deseginadas para executar uma seo de cdigo se determinada
condio lgica resultar em verdadeiro (.T.). Em AdvPl existem dois comandos para

44

Apostila
Advpl
execuo de sees de cdigo de acordo com avaliaes lgicas. O comando IF...ENDIF e
o comando DO CASE...ENDCASE.

O Comando IF...ENDIF
Executa um conjunto de comandos baseado no valor de uma expresso lgica.
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
Parmetros
lExpressao Especifica uma expresso lgica que avaliada. Se lExpressao resultar em
verdadeiro (.T.), qualquer comando seguinte ao IF e antecedente ao ELSE
ou ENDIF (o que ocorrer primeiro) ser executado.

Comandos

Se lExpressao resultar em falso (.F.) e a clusula ELSE for definida,

qualquer comando aps essa clusula e anterior ao ENDIF ser executada.
Se a clusula ELSE no for definida, todos os comandos entre o IF e o
ENDIF so ignorados. Neste caso, a execuo do programa continua com
o primeiro comando seguinte ao ENDIF.
Conjunto de comandos AdvPl que sero executados dependendo da
avaliao da expresso lgica em lExpressao.

Comentrios
Pode-se aninhar um bloco de comando IF...ENDIF dentro de outro bloco de comando
IF...ENDIF. Porm, para a avaliao de mais de uma expresso lgica, deve-se utilizar o
comando DO CASE...ENDCASE.
Exemplo

45

Apostila
Advpl
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
Endif
Return

O Comando DO CASE...ENDCASE
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em
verdadeiro (.T.).
Sintaxe
DO CASE
CASE lExpressao1
Commandos
[CASE lExpressao2
Commandos
...
CASE lExpressaoN
Commandos]
[OTHERWISE
Commandos]
ENDCASE
46

Apostila
Advpl
Parmetros
CASE
lExpressao1
Comandos...

Quando a primeira expresso CASE resultante em verdadeiro (.T.)

for encontrada, o conjunto de comandos seguinte executado. A
execuo do conjunto de comandos continua at que a prxima
clusula CASE, OTHERWISE ou ENDCASE seja encontrada. Ao
terminar de executar esse conjunto de comandos, a execuo continua
com o primeiro comando seguinte ao ENDCASE.
Se uma expresso CASE resultar em falso (.F.), o conjunto de
comandos seguinte a esta at a prxima clusula ignorado.
Apenas um conjunto de comandos executado. Estes so os
primeiros comandos cuja expresso CASE avaliada como
verdadeiro (.T.). Aps a execuo, qualquer outra expresso CASE
posterior ignorada (mesmo que sua avaliao resultasse em
verdadeiro).
Se todas as expresses CASE forem avaliadas como falso (.F.), a
clusula OTHERWISE determina se um conjunto adicional de
comandos deve ser executado. Se essa clusula for incluida, os
comandos seguintes sero executados e ento o programa continuar
com o primeiro comando seguinte ao ENDCASE. Se a clusula
OTHERWISE for omitida, a execuo continuar normalmente aps
a clusula ENDCASE.

OTHERWISE
Commandos

Comentrios
O Comando DO CASE...ENDCASE utilizado no lugar do comando IF...ENDIF quando
um nmero maior do que uma expresso deve ser avaliada, substituindo a necessidade de
mais de um comando IF...ENDIF aninhados.
Exemplo
Local nMes

:= Month(Date())

Local cPeriodo := ""

DO CASE
CASE nMes <= 3
cPeriodo := "Primeiro Trimestre"

47

Apostila
Advpl
CASE nMes >= 4 .And. nMes <= 6
cPeriodo := "Segundo Trimestre"
CASE nMes >= 7 .And. nMes <= 9
cPeriodo := "Terceiro Trimestre"
OTHERWISE
cPeriodo := "Quarto Trimestre"
ENDCASE

Return

tFont
48

Apostila
Advpl
Classe que encapsula fonte de edio.

Hierarquia
tFontAbs -> tFont

Descrio
Utilize objeto tFont para modificar a fonte padro de controles visuais.

Mtodos
New
Descrio
Construtor do objeto.
Sintaxe
New([acName], [nPar2], [anHeight], [lPar4], [alBold], [nPar6], [lPar7], [nPar8], [alItalic],
[alUnderline])
Parmetros
acName
nPar2
anHeight
lPar4
alBold
nPar6
lPar7
nPar8
alItalic
alUnderline

Caractere, opcional. Nome da fonte, o padro Arial.

Reservado.
Numrico, opcional. Tamanho da fonte. O padro -11.
Reservado.
Lgico, opcional. Se .T. o estilo da fonte ser negrito.
Reservado.
Reservado.
Reservado.
Lgico, opcional. Se .T. o estilo da fonte ser itlico.
Lgico, opcional. Se .T. o estilo da fonte ser sublinhado.

Retorno
O objeto criado.

Exemplo
49

Apostila
Advpl
#include protheus.ch

User Function Teste()

Local oDlg, oSay, oFont:= TFont():New(Courier New,,-14,.T.)

DEFINE MSDIALOG oDlg FROM 0,0 TO 200,200 TITLE My dialog PIXEL
// apresenta o tSay com a fonte Courier New //
oSay:= tSay():New(10,10,{||para exibir},oDlg,,oFont,,;
,,.T.,CLR_WHITE,CLR_RED,100,20)
oSay:lTransparent:= .T.
ACTIVATE MSDIALOG oDlg CENTERED

Return

MSDialog
50

Apostila
Advpl
Classe de dilogo de entrada de dados.

Hierarquia
tSrvObject -> tWindow -> tDialog -> MSDialog

Caractersticas
MSDialog deve ser utilizada como padro de janela para entrada de dados. MSDialog um
tipo de janela dilogo modal, isto , no permite que outra janela ativa receba dados
enquanto esta estiver ativa.

Propriedades
Vide classes ancestrais.

Mtodos
New
Descrio
Mtodo construtor da classe.
Sintaxe
New([anTop], [anLeft], [anBottom], [anRight], [acCaption], [cPar6], [nPar7],
[lPar8], [nPar9], [anClrText], [anClrBack], [oPar12], [aoWnd], [alPixel], [oPar15],
[oPar16], [lPar17])
Parmetros
Numrico, opcional. Coordenada vertical superior em pixels ou
caracteres.
Numrico, opcional. Coordenada horizontal esquerda em pixels ou
anLeft
caracteres.
Numrico, opcional. Coordenada vertical inferior em pixels ou
anBottom
caracteres.
Numrico, opcional Coordenada horizontal direita em pixels ou
anRight
caracteres.
acCaption
Caractere, opcional. Ttulo do dilogo.
cPar6
Reservado.
anTop

51

Apostila
Advpl
nPar7
lPar8
nPar9
anClrText
anClrBack
oPar12
aoWnd
alPixel
oPar15
oPar16
lPar17

Reservado.
Reservado.
Reservado.
Cor do texto.
Cor do fundo.
Reservado.
Objeto, opcional. Janela pai do dilogo, geralmente a janela principal
do programa.
Se .T. considera as coordenadas informadas em pixels, se .F. considera
as coordenadas em caracteres.
Reservado.
Reservado.
Reservado.

Retorno
O dilogo construdo.
Exemplo
#include protheus.ch

User Function Teste()

// cria dilogo
Local oDlg:=MSDialog():New(10,10,300,300,Meu dialogo;
,,,,,CLR_BLACK,CLR_WHITE,,,.T.)

// ativa dilogo centralizado

oDlg:Activate(,,,.T.,{||msgstop(validou!),.T.},;
,{||msgstop(iniciando) )

52

Apostila
Advpl
Return

53

Apostila
Advpl

MsGetDados
Objeto tipo lista com uma ou mais colunas para cadastramento de dados baseado em um
vetor.
Caractersticas
A MsGetDados precisa que sejam declaradas as variveis abaixo sendo tipo Private:
aRotina.

Vetor com as rotinas que sero executadas na MBrowse e que definira o tipo de operao
que esta sendo executada (incluso, alterao, excluso, visualizao, pesquisa, ...) no
formato:
Elemento
1
2
3
4
5

Contedo
Ttulo
Rotina
Reservado
Operao (1 - pesquisa; 2 - visualizao; 3 - incluso; 4 - alterao; 5 excluso)
Acesso relacionado a rotina, se esta posio no for informada nenhum acesso
ser validado

aHeader
Vetor com informaes das colunas no formato:
Elemento
1
2
3
4
5
6

Contedo
Ttulo
Campo
Mscara
Tamanho
Decimal
Validao

54

Apostila
Advpl
7
8
9
10

Reservado
Tipo
Reservado
Reservado

aCols
Vetor com as linhas a serem editadas. As colunas devem ser construdas com base no
aHeader mais uma ultima com valor lgico que determina se a linha foi excluda.

lRefresh
Varivel tipo lgica para uso reservado.
A MsGetDados cria a varivel publica n que indica qual a linha posicionada do aCols.
As funes passadas como parmetro para a MsGetDados (cLinhaOk, cTudoOk, ...) no
podero ser declaradas como Static Function.
A consulta padro, validao do usurio e gatilhos estaro habilitados se o campo estiver
cadastrado no Dicionrio de Dados (SX3/SX7) e apresentar estas opes disponveis.
Mtodos
New
Descrio
Cria o objeto MsGetDados.
Sintaxe
MSGETDADOS():NEW( nSuperior, nEsquerda, nInferior, nDireita, nOpc, [ cLinhaOk ], [
cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter ], [ uPar1 ], [ lVazio ], [ nMax ], [ cCampoOk
], [ cSuperApagar ], [ uPar2 ], [ cApagaOk ], [ oWnd ] ) -> objeto
Argumentos

Descrio

55

Apostila
Advpl
Distancia entre a MsGetDados e o extremidade superior do objeto
que a contm.
Distancia entre a MsGetDados e o extremidade esquerda do objeto
nEsquerda
que a contm.
Distancia entre a MsGetDados e o extremidade inferior do objeto
nInferior
que a contm.
Distancia entre a MsGetDados e o extremidade direita do objeto que
nDireita
a contm.
Posio do elemento do vetor aRotina que a MsGetDados usar
nOpc
como referencia.
cLinhaOk
Funo executada para validar o contexto da linha atual do aCols.
Funo executada para validar o contexto geral da MsGetDados
cTudoOk
(todo aCols).
Nome dos campos do tipo caracter que utilizaro incremento
cIniCpos
automtico. Este parmetro deve ser no formato +<nome do
primeiro campo>+<nome do segundo campo>+....
lApagar
Habilita deletar linhas do aCols. Valor padro falso.
aAlter
Vetor com os campos que podero ser alterados.
uPar1
Parmetro reservado.
Habilita validao da primeira coluna do aCols para esta no poder
lVazio
estar vazia. Valor padro falso.
nMax
Nmero mximo de linhas permitidas. Valor padro 99.
cCampoOk
Funo executada na validao do campo.
cSuperApagar Funo executada quando pressionada as teclas <Ctrl>+<Delete>.
uPar2
Parmetro reservado.
cApagaOk
Funo executada para validar a excluso de uma linha do aCols.
oWnd
Objeto no qual a MsGetDados ser criada.
nSuperior

Retorno
Objeto.

ForceRefresh
Descrio
Atualiza a MsGetDados com o aCols e posiciona na primeira linha.

56

Apostila
Advpl

Sintaxe

oObjeto:ForceRefresh()

Hide
Descrio
Esconde a MsGetDados.

Sintaxe

oObjeto:Hide()

Show
Descrio
Mostra a MsGetDados.

Sintaxe

oObjeto:Show()
Exemplo
User Function Exemplo()
57

Apostila
Advpl
Local nI
Local oDlg
Local oGetDados
Local nUsado := 0
Private lRefresh := .T.
Private aHeader := {}
Private aCols := {}
Private aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluir", "AxDeleta", 0, 5}}
DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")
While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
Aadd(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
58

Apostila
Advpl
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
EndIf
DbSkip()
End
Aadd(aCols,Array(nUsado+1))
For nI := 1 To nUsado
aCols[1][nI] := CriaVar(aHeader[nI][2])
Next
aCols[1][nUsado+1] := .F.
DEFINE MSDIALOG oDlg TITLE "Exemplo" FROM 00,00 TO 300,400 PIXEL
oGetDados := MSGETDADOS():NEW(05, 05, 145, 195, 4, "U_LINHAOK",
"U_TUDOOK", "+A1_COD", .T., {"A1_NOME"}, , .F., 200, "U_FIELDOK",
"U_SUPERDEL", , "U_DELOK", oDlg)
ACTIVATE MSDIALOG oDlg CENTERED
Return

User Function LINHAOK()

ApMsgStop("LINHAOK")
Return .T.

59

Apostila
Advpl
User Function TUDOOK()
ApMsgStop("LINHAOK")
Return .T.

User Function DELOK()

ApMsgStop("DELOK")
Return .T.

User Function SUPERDEL()

ApMsgStop("SUPERDEL")
Return .T.

User Function FIELDOK()

ApMsgStop("FIELDOK")
Return .T.

MXsGetDb
60

Apostila
Advpl
Objeto tipo lista com uma ou mais colunas para cadastramento de dados baseado em uma
tabela temporria.
Caractersticas
A MsGetDB precisa que sejam declaradas as variveis abaixo sendo tipo Private:
aRotina.

Vetor com as rotinas que sero executadas na MBrowse e que definira o tipo de operao
que esta sendo executada (incluso, alterao, excluso, visualizao, pesquisa, ...) no
formato:
Elemento
1
2
3
4
5

Contedo
Ttulo
Rotina
Reservado
Operao (1 - pesquisa; 2 - visualizao; 3 - incluso; 4 - alterao; 5 excluso)
Acesso relacionado a rotina, se esta posio no for informada nenhum acesso
ser validado

aHeader
Vetor com informaes das colunas no formato:
Elemento
1
2
3
4
5
6
7
8
9
10

Contedo
Ttulo
Campo
Mscara
Tamanho
Decimal
Validao
Reservado
Tipo
Reservado
Reservado

61

Apostila
Advpl

lRefresh
Varivel tipo lgica para uso reservado.
A tabela temporria utilizada pela MsGetDB dever ser criada com base no aHeader mais
um ltimo campo tipo lgico que determina se a linha foi excluda.
A MsGetDB cria a varivel publica nBrLin que indica qual a linha posicionada do aCols.
As funes passadas como parmetro para a MsGetDB (cLinhaOk, cTudoOk, ...) no
podero ser declaradas como Static Function.
A consulta padro, validao do usurio e gatilhos estaro habilitados se o campo estiver
cadastrado no Dicionrio de Dados (SX3/SX7) e apresentar estas opes disponveis.
Mtodos
New
Descrio
Cria o objeto MsGetDB.
Sintaxe
MSGETDB():NEW( nSuperior, nEsquerda, nInferior, nDireita, nOpc, [ cLinhaOk ], [
cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter ], [ nCongelar ], [ lVazio ], [ uPar1 ], cTRB, [
cCampoOk ], [ lCondicional ], [ lAdicionar ], [ oWnd ], [ lDisparos ], [ uPar2 ], [
cApagarOk ], [ cSuperApagar ] ) -> objeto
Argumentos
Descrio
Distancia entre a MsGetDB e o extremidade superior do objeto que a
nSuperior
contm.
Distancia entre a MsGetDB e o extremidade esquerda do objeto que
nEsquerda
a contm.
Distancia entre a MsGetDB e o extremidade inferior do objeto que a
nInferior
contm.
Distancia entre a MsGetDB e o extremidade direita do objeto que a
nDireita
contm.
Posio do elemento do vetor aRotina que a MsGetDB usar como
nOpc
referncia.
cLinhaOk
Funo executada para validar o contexto da linha atual do aCols.

62

Apostila
Advpl
Funo executada para validar o contexto geral da MsGetDB (todo
aCols).
Nome dos campos do tipo caracter que utilizaro incremento
cIniCpos
automtico. Este parmetro deve ser no formato +<nome do
primeiro campo>+<nome do segundo campo>+....
lApagar
Habilita a opo de deletar linhas do aCols. Valor padro falso.
aAlter
Vetor com os campos que podero ser alterados.
nCongelar
Indica qual coluna no ficara congelada na exibio.
Habilita validao da primeira coluna do aCols para esta no poder
lVazio
estar vazia. Valor padro falso.
uPar1
Parmetro reservado.
cTRB
Alias da tabela temporria.
cCampoOk
Funo executada na validao do campo.
lConditional
Reservado
Indica se a MsGetDB ira criar uma linha em branco
lAdacionar
automaticamente quando for incluso.
oWnd
Objeto no qual a MsGetDB ser criada.
Indica se ser utilizado o Dicionrio de Dados para consulta padro,
lDisparos
inicializao padro e gatilhos.
uPar2
Parmetro reservado.
cApagarOk
Funo executada para validar a excluso de uma linha do aCols.
cSuperApagar -Funo executada quando pressionada as teclas <Ctrl>+<Delete>.
cTudoOk

Retorno
Objeto.

ForceRefresh
Descrio
Atualiza a MsGetDB com a tabela e posiciona na primeira linha.
Sintaxe
ForceRefresh()
Exemplo

63

Apostila
Advpl
User Function Exemplo()
Local nI
Local oDlg
Local oGetDB
Local nUsado := 0
Local aStruct := {}
Private lRefresh := .T.
Private aHeader := {}
Private aCols := {}
Private aRotina := {{"Pesquisar", "AxPesqui", 0, 1},;
{"Visualizar", "AxVisual", 0, 2},;
{"Incluir", "AxInclui", 0, 3},;
{"Alterar", "AxAltera", 0, 4},;
{"Excluit", "AxDeleta", 0, 5}}
DbSelectArea("SX3")
DbSetOrder(1)
DbSeek("SA1")
While !Eof() .and. SX3->X3_ARQUIVO == "SA1"
If X3Uso(SX3->X3_USADO) .and. cNivel >= SX3->X3_NIVEL
nUsado++
Aadd(aHeader,{Trim(X3Titulo()),;
SX3->X3_CAMPO,;
SX3->X3_PICTURE,;
64

Apostila
Advpl
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL,;
SX3->X3_VALID,;
"",;
SX3->X3_TIPO,;
"",;
"" })
Aadd(aStruct,{SX3->X3_CAMPO,;
SX3->X3_TIPO,;
SX3->X3_TAMANHO,;
SX3->X3_DECIMAL})
EndIf
DbSkip()
End
Aadd(aStruct,{"FLAG","L",1,0})
cCriaTrab := CriaTrab(aStruct,.T.)
DbUseArea(.T.,__LocalDriver,cCriaTrab,,.T.,.F.)
DEFINE MSDIALOG oDlg TITLE "Exemplo" FROM 00,00 TO 300,400 PIXEL
oGetDB := MSGETDB():NEW(05, 05, 145, 195, 3, "U_LINHAOK", "U_TUDOOK",
"+A1_COD", .T., {"A1_NOME"}, 1, .F., , cCriaTrab, "U_FIELDOK", , .T., oDlg,
.T., ,"U_DELOK", "U_SUPERDEL")
ACTIVATE MSDIALOG oDlg CENTERED
DbSelectArea(cCriaTrab)
DbCloseArea()
65

Apostila
Advpl
Return

User Function LINHAOK()

ApMsgStop("LINHAOK")
Return .T.

User Function TUDOOK()

ApMsgStop("LINHAOK")
Return .T.

User Function DELOK()

ApMsgStop("DELOK")
Return .T.

User Function SUPERDEL()

ApMsgStop("SUPERDEL")
Return .T.

User Function FIELDOK()

ApMsgStop("FIELDOK")
Return .T.

66

Apostila
Advpl

MsmGet
Conjunto de objetos tipo MsGet/MsCombo para cadastramento de dados baseado no
Dicionrio de Dados.
Caractersticas

67

Apostila
Advpl
A MsMGet tambm poder criada a partir da funo Enchoice a qual recebe os mesmos
parmetros do mtodo New porm no retorna o objeto criado.
A MsMGet se baseia no Dicionrio de Dados para verificar campos obrigatrios,
validaes, gatilhos, consulta padro etc. assim como para a criao das Pastas de Cadastro.
A MsMGet pode usar tanto variveis de memria do tipo Private como diretamente os
campos da tabela a que se refere.
Mtodos
New
Descrio
Cria o objeto MsMGet.
Sintaxe
MSMGET():NEW( cAlias, nReg, nOpc, [ uPar1 ], [ uPar2 ], [ uPar3 ], [ aACho ], [ aPos ],
[ aCpos ], [ uPar4 ], [ uPar5 ], [ uPar6 ], [ uPar7 ], [ oWnd ], [ uPar8 ], [ lMemoria ], [
lColuna ], [ uPar9 ], [ lSemPastas ] ) -> objeto
Argumentos
cAlias
nReg
uPar1
uPar2
uPar3
aAcho
aPos
aCpos
uPar4
uPar5
uPar6
uPar7
oWnd

Descrio
Alias do dados a serem cadastrados.
Nmero do registro da tabela a ser editado.
Parmetro reservado.
Parmetro reservado.
Parmetro reservado.
Vetor com os campos que sero apresentados pela MsMGet.
Vetor com as coordenadas onde a MsMGet ser criada no formato
{coord. superior, coord. esquerda, coord. direita, coord.
inferior}.Funo executada para validar o contexto da linha atual do
aCols.
Vetor com os campos que podero ser alterados.
Parmetro reservado. Nome dos campos do tipo caracter que utilizaro
incremento automtico. Este parmetro deve ser no formato +<nome
do primeiro campo>+<nome do segundo campo>+....
Parmetro reservado.
Parmetro reservado.
Parmetro reservado.
Objeto no qual a MsMGet ser criada.

68

Apostila
Advpl
uPar8
lMemoria
lColuna
uPar9
lSemPastas

Parmetro reservado.
Indica se ser usado variveis de memria ou os campos da tabela para
cadastramento dos dados. Valor padro falso.
Indica se a MsMGet sera apresentada com um objeto por linha (uma
coluna). Valor padro falso. Parmetro reservado.
Parmetro reservado.
Indica se no ser usado as Pastas de Cadastro na MsMGet. Funo
executada para validar a excluso de uma linha do aCols.

Retorno
Objeto.

Refresh
Descrio
Atualiza os objetos contidos na MsMGet.
Sintaxe
Refresh()

Hide
Descrio
Esconde a MsMGet.
Sintaxe
Hide()

Show
69

Apostila
Advpl
Descrio
Mostra a MsMGet.
Sintaxe
Show()

Exemplo
User Function Exemplo()
Local i
Local oDlg
Local oMsMGet
Local lInit
Local cCampo
DbSelectArea("SA1")
For i := 1 To FCount()
cCampo := Field(i)
lInit := .F.
If ExistIni(cCampo)
lInit := .t.
M->&(cCampo) := InitPad(SX3->X3_RELACAO)
If ValType(M->&(cCampo)) = "C"
M->&(cCampo) := Padr(M->&(cCampo),SX3->X3_TAMANHO)
EndIf
If M->&(cCampo) == NIL
70

Apostila
Advpl
lInit := .F.
EndIf
EndIf
If !lInit
M->&(cCampo) := FieldGet(i)
If ValType(M->&(cCampo)) = "C"
M->&(cCampo) := Space(Len(M->&(cCampo)))
ElseIf ValType(M->&(cCampo)) = "N"
M->&(cCampo) := 0
ElseIf ValType(M->&(cCampo)) = "D"
M->&(cCampo) := CtoD(" / / ")
ElseIf ValType(M->&(cCampo)) = "L"
M->&(cCampo) := .F.
EndIf
EndIf
Next
DEFINE MSDIALOG oDlg TITLE "Exemplo" FROM 00,00 TO 19,80
MSMGET():NEW("SA1",0,3,,,,,,,,,,,,,.T.)
ACTIVATE MSDIALOG oDlg CENTERED ON INIT EnchoiceBar(oDlg,{|| oDlg:End()},
{|| oDlg:End()})
Return

71

Apostila
Advpl

MBrowse
Monta um Browse com menu de opes.
Sintaxe

72

Apostila
Advpl
MBROWSE( [ uPar1 ], [ uPar2 ], [ uPar3 ], [ uPar4 ], cAlias, [ aFixos ], [ cCpo ], [
uPar5 ], [ cFun ], [ nPadrao ], [ aCores ], [ cExpIni ], [ cExpFim ], [ nCongela ] ) ->
nil
Argumento Obrigat.

Tipo

Descrio

uPar1
uPar2
uPar3
uPar4
cAlias

No
No
No
No
Sim

N
N
N
N
C

aFixos

No

cCpo

No

uPar5

No

cFun

No

nPadrao

No

aCores

No

cExpIni

No

cExpFim

No

nCongela

No

Parmetro reservado.
Parmetro reservado.
Parmetro reservado.
Parmetro reservado.
Alias do arquivo a ser visualizado no browse.
Contendo os nomes dos campos fixos pr-definidos pelo
programador, obrigando a exibio de uma ou mais colunas.
Campo a ser validado se est vazio ou no para exibio do bitmap
de status.
Parmetro reservado.
Funo que retornar um valor lgico para exibio do bitmap de
status.
Nmero da rotina a executada quando for efetuado um duplo clique
em um registros do browse. Caso no seja informado o padro ser
executada visualizao ou pesquisa.
Este vetor possui duas dimenses, a primeira a funo de validao
para exibio do bitmap de status, e a segunda o bitmap a ser
exibido.
Funo que retorna o contedo inicial do filtro baseada na chave de
ndice selecionada.
Funo que retorna o contedo final do filtro baseada na chave de
ndice selecionada.
Coluna a ser congelado no browse.

Descrio
As variveis cCadastro e aRotina (*) precisam ser declarados como private acima da
chamada da funo.
Apenas um dos parmetros ( cCpo, cFun, aColors ) deve ser informado.
(*) vetor com as rotinas que sero executadas, nele ser definido o tipo de operao a ser
executada (incluso, alterao, excluso, visualizao, pesquisa, ...) sua estrutura
composta de 5 (cinco) dimenses: 1 - Ttulo; 2 Rotina; 3 Reservado; 4 Operao (1
- pesquisa; 2 - visualizao; 3 - incluso; 4 - alterao; 5 - excluso); 5 Acesso
relacionado a rotina, se esta posio no for informada no validar os acessos.
Exemplo
Private cCadastro := 'Cadastro de Clientes'
Private aRotina := { { 'Pesquisar' , 'AxPesqui' , 0, 1 },;
{ 'Visualizar' , 'AxVisual' , 0, 2 },;

73

Apostila
Advpl
{ 'Incluir' , 'AxInclui' , 0, 3 },;
{ 'Alterar' , 'AxAltera' , 0, 4 },;
{ 'Excluir' , 'AxExcluir', 0, 5 }}
MBROWSE( ,,,, 'SA1',, '!A1_COD',,, 4 )

IncProc
Incrementa rgua de progresso.
Sintaxe

74

Apostila
Advpl
INCPROC() -> nil
Descrio
Para incrementar a rgua criada pela funo Processa(), utilizamos a funo IncProc()
Exemplo
User Function <nome-da-funo>( )
Local bAcao := {|lFim| Exemplo(@lFim) }
Local cTitulo := ''
Local cMsg := 'Processando'
Local lAborta := .T.
Processa( bAcao, cTitulo, cMsg, lAborta )
Return

Static Function Exemplo(lFim)

Local nI
ProcRegua(10000)
For nI := 1 To 10000
If lFim
Exit
EndIf
INCPROC()
Next nI
Return

75

Apostila
Advpl

25/11/2003

EXERCCIOS
76

Apostila
Advpl
Analisar a situao e verificar a possibilidade da utilizao de Pontos de Entrada,
validaes de usurio ou gatilhos.
1) Necessito limitar o nmero de Itens no Pedido de Venda, de modo que o
usurio informe apenas 6 Itens por Pedido, nao mais que isso. Dever ser
mostrada uma mensagem informando a limitao ao usurio.

2) No Documento de Entrada as NFs com valores maiores que R$ 5.000,00

(cinco mil reais) devero ser incluidas apenas aps a digitao de um usurio
e senha de validao (usurio: Master // senha: teste).

3) No Pedido de Vendas o Valor Unitrio dever ser alterado apenas pelo

usurio Administrador.

77