Escolar Documentos
Profissional Documentos
Cultura Documentos
Apostila I - ADVPL Básico PDF
Apostila I - ADVPL Básico PDF
Introduo programao e
ADVPL bsico
(Capacitao Interna)
OBJETIVOS DO CURSO................................................................................................................................. 6
MDULO 01: Introduo programao...................................................................................................... 7
1. Lgica de Programao e Algoritmos .................................................................................................. 7
1.1. Lgica de Programao............................................................................................................... 7
1.2. Desenvolvendo algoritmos.......................................................................................................... 8
1.2.1. Estudando algoritmos..................................................................................................................9
1.2.2. Teste de mesa.......................................................................................................................... 11
2. Estruturas de programao ............................................................................................................... 12
2.1. Diagrama de bloco .................................................................................................................... 12
2.2. Estruturas de deciso e repetio ............................................................................................. 15
2.2.1. Estruturas de deciso ................................................................................................................ 15
2.2.2. Estruturas de repetio ............................................................................................................. 18
MDULO 02: A linguagem ADVPL .............................................................................................................. 20
3. Estrutura de um Programa ADVPL..................................................................................................... 22
3.1. reas de um Programa ADVPL .................................................................................................. 24
4. Declarao e Atribuio de Variveis ................................................................................................ 27
4.1. Tipo de Dados ........................................................................................................................... 27
4.2. Declarao de variveis ............................................................................................................ 28
4.3. Escopo de variveis................................................................................................................... 29
4.4. Entendendo a influncia do escopo das variveis...................................................................... 33
4.5. Operaes com Variveis .......................................................................................................... 34
4.5.1. Atribuio de variveis .............................................................................................................. 34
4.5.2. Operadores da linguagem ADVPL ................................................................................................ 35
4.5.3. Operao de Macro Substituio ................................................................................................. 40
4.5.4. Funes de manipulao de variveis .......................................................................................... 41
5. Estruturas bsicas de programao................................................................................................... 47
5.1. Estruturas de repetio............................................................................................................. 47
5.1.1. Influenciando o fluxo de repetio .............................................................................................. 50
5.2. Estruturas de deciso ............................................................................................................... 52
6. Arrays e Blocos de Cdigo ................................................................................................................. 56
6.1. Arrays ....................................................................................................................................... 56
6.1.1. Inicializando arrays ................................................................................................................... 58
6.1.2. Funes de manipulao de arrays.............................................................................................. 59
6.1.3. Cpia de arrays ........................................................................................................................ 61
6.2. Listas de Expresses e Blocos de Cdigo................................................................................... 63
6.2.1. Premissas para utilizao de Blocos de Cdigo.............................................................................. 63
6.2.2. Lista de expresses................................................................................................................... 64
6.2.3. Blocos de Cdigo ...................................................................................................................... 66
6.2.4. Funes para manipulao de blocos de cdigo ............................................................................ 68
7. Funes............................................................................................................................................. 69
7.1. Tipos e escopos de funes....................................................................................................... 70
7.2. Passagem de parmetros entre funes ................................................................................... 73
8. Diretivas de compilao .................................................................................................................... 79
MDULO 03: Desenvolvendo pequenas customizaes.............................................................................. 84
9. ADVPL e o ERP Microsiga Protheus.................................................................................................... 84
9.1. O Ambiente Protheus ................................................................................................................ 84
9.2. Organizao e configurao inicial do ambiente Protheus ........................................................ 88
-2-
-3-
-4-
-5-
-6-
Com foco nesta necessidade, este tpico ir descrever resumidamente os conceitos envolvidos
no processo de desenvolvimento de um programa atravs dos conceitos relacionados :
Lgica de programao
Algoritmos
Diagramas de blocos
Lgica
Seqncia Lgica
Estes pensamentos, podem ser descritos como uma seqncia de instrues, que devem ser
seguidas para se cumprir uma determinada tarefa.
Instrues
Por exemplo, se quisermos fazer uma omelete de batatas, precisaremos colocar em prtica
uma srie de instrues: descascar as batatas, bater os ovos, fritar as batatas, etc. evidente
que essas instrues tm que ser executadas em uma ordem adequada no se pode
descascar as batatas depois de frit-las.
-7-
Algoritmo
Um algoritmo formalmente uma seqncia finita de passos que levam a execuo de uma
tarefa. Podemos pensar em algoritmo como uma receita, uma seqncia de instrues que do
cabo de uma meta especfica. Estas tarefas no podem ser redundantes nem subjetivas na sua
definio, devem ser claras e precisas.
Como exemplos de algoritmos podemos citar os algoritmos das operaes bsicas (adio,
multiplicao, diviso e subtrao) de nmeros reais decimais. Outros exemplos seriam os
manuais de aparelhos eletrnicos, como um videocassete, que explicam passo-a-passo como,
por exemplo, gravar um evento.
At mesmo as coisas mais simples, podem ser descritas por seqncias lgicas, tais como:
Pseudocdigo
O algoritmo deve ser fcil de interpretar e fcil de codificar. Ou seja, ele deve ser o
intermedirio entre a linguagem falada e a linguagem de programao.
-8-
Fases
Mascar um chiclete
Utilizar um telefone pblico carto
Fritar um ovo
Trocar lmpadas
Descascar batatas
Jogar o jogo da forca
Calcular a mdia de notas
Jogar o jogo da velha contra o algoritmo
Mascar um chiclete
1. Pegar o chiclete
2. Retirar o papel
3. Mastigar
4. Jogar o papel no lixo
-9-
Trocar lmpadas
Descascar batatas
1. Escolher a palavra
2. Montar o diagrama do jogo
3. Enquanto houver lacunas vazias e o corpo estiver incompleto:
3.1. Se acertar a letra: escrever na lacuna correspondente
3.2. Se errar a letra: desenhar uma parte do corpo na forca
- 10 -
Aps desenvolver um algoritmo ele dever sempre ser testado. Este teste chamado de
TESTE DE MESA, que significa seguir as instrues do algoritmo de maneira precisa para
verificar se o procedimento utilizado est correto ou no.
Teste de mesa:
ID Nota
2. Ao trmino das notas, a tabela dever conter todas as notas informadas, como abaixo:
ID Nota
1 8.0
2 7.0
3 8.0
4 8.0
5 7.0
6 7.0
- 11 -
O diagrama de blocos uma forma padronizada e eficaz para representar os passos lgicos de
um determinado processamento.
Com o diagrama podemos definir uma seqncia de smbolos, com significado bem definido,
portanto, sua principal funo a de facilitar a visualizao dos passos de um processamento.
Simbologia
Smbolo Funo
Processamento em geral.
Processamento
- 12 -
- 13 -
- 14 -
Estruturas de deciso
o IF...ELSE
o DO CASE ... CASE
Estruturas de repetio
o WHILE...END
o FOR...NEXT
IF...ELSE
DO CASE ... CASE
IF...ELSE
A estrutura IF...ELSE (Se/Seno) permite a anlise de uma condio e a partir da qual ser
executada uma de duas aes possveis: se a anlise da condio resultar em um valor
verdadeiro ou se a anlise da condio resultar em um valor falso.
- 15 -
Aes anteriores
...
Anlise da Falso
condio
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo aps a
tomada da
deciso
- 16 -
Aes anteriores
...
Falso
Falso
Falso
Falso
Continuao do
fluxo aps a
tomada da
deciso
- 17 -
WHILE...END
FOR...TO...NEXT
WHILE...END
Nesta estrutura, o conjunto de aes ser executado enquanto a anlise de uma condio de
referncia resultar em um valor verdadeiro. importante verificar que o bloco somente ser
executado, inclusive se na primeira anlise a condio resultar em um valor verdadeiro.
Representao: WHILE...END
Aes anteriores
...
Anlise da Falso
condio
Loop Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo
...
- 18 -
Nesta estrutura, o conjunto de aes ser executado uma quantidade de vezes definida,
normalmente referenciada como passo.
Para cada passo realizado pela estrutura FOR...TO...NEXT, ser avaliada uma condio que
verificar se foi atingido o nmero de execues previamente definido. Desta forma a
estrutura compreende um controle de nmero de passos executados, o qual incrementado
na anlise da expresso NEXT.
Representao: FOR...TO...NEXT
Em ADVPL pode ser utilizada a instruo STEPS para alterar o valor a ser
adicionado no contador de passos a cada execuo da instruo NEXT, sendo
que este valor poder ser at negativo, viabilizando uma contagem
decrescente.
- 19 -
Podem-se criar rotinas para a customizao do sistema ERP Microsiga Protheus, desde
processos adicionais at mesmo relatrios. A grande vantagem aproveitar todo o ambiente
montado pelos mdulos do ERP Microsiga Protheus. Porm, com o ADVPL possvel at
mesmo criar toda uma aplicao, ou mdulo, do comeo.
As rotinas criadas sem interface so consideradas nesta categoria porque geralmente tm uma
utilizao mais especfica do que um processo adicional ou um relatrio novo. Tais rotinas no
tm interface com o usurio atravs do Protheus Remote, e qualquer tentativa nesse sentido
- 20 -
Rotinas escritas em ADVPL podem ser iniciadas como processos individuais (sem interface) no
Protheus Server atravs de duas maneiras: Iniciadas por outra rotina ADVPL atravs da
chamada de funes como StartJob() ou CallProc() ou iniciadas automaticamente na
inicializao do Protheus Server (quando propriamente configurado).
Programao de RPC
O servidor Protheus tambm pode executar rotinas em ADVPL em outros servidores Protheus
atravs de conexo TCP/IP direta utilizando o conceito de RPC. Do mesmo modo, aplicaes
externas podem requisitar a execuo de rotinas escritas em ADVPL atravs de conexo
TCP/IP direta.
Programao Web
O Protheus Server pode tambm ser executado como um servidor Web, respondendo a
requisies HTTP. No momento destas requisies, pode executar rotinas escritas em ADVPL
como processos individuais, enviando o resultado das funes como retorno das requisies
para o cliente HTTP (como por exemplo, um Browser de Internet). Qualquer rotina escrita em
ADVPL que no contenha comandos de interface pode ser executada atravs de requisies
HTTP. O Protheus permite a compilao de arquivos HTML contendo cdigo ADVPL embutido.
So os chamados arquivos ADVPL ASP, para a criao de pginas dinmicas.
Programao TelNet
TelNet parte da gama de protocolos TCP/IP que permite a conexo a um computador remoto
atravs de uma aplicao cliente deste protocolo. O PROTHEUS Server pode emular um
terminal TelNet, atravs da execuo de rotinas escritas em ADVPL. Ou seja, pode-se escrever
rotinas ADVPL cuja interface final ser um terminal TelNet ou um coletor de dados mvel.
- 21 -
Erros de execuo so aqueles que acontecem depois da compilao, quando o programa est
sendo executado. Podem ocorrer por inmeras razes, mas geralmente se referem as funes
no existentes, ou variveis no criadas ou inicializadas, etc.
Linhas de Programa
As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser linhas de
comando, linhas de comentrio ou linhas mistas.
Linhas de Comando
Linhas de comando possuem os comandos ou instrues que sero executadas. Por exemplo:
Local nCnt
Local nSoma := 0
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Linhas de Comentrio
- 22 -
/*
Programa para clculo do total
Autor: Microsiga Software S.A.
Data: 2 de outubro de 2001
*/
Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento
(indicada pelos caracteres */) considerado como comentrio.
Linhas Mistas
O ADVPL tambm permite que existam linhas de comando com comentrio. Isto possvel
adicionando-se as duas barras transversais (//) ao final da linha de comando e adicionando-se
o texto do comentrio:
Local nCnt
Local nSoma := 0 // Inicializa a varivel com zero para a soma
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Tamanho da Linha
Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser digitado no
editor de textos utilizado, existe uma linha considerada linha lgica. A linha lgica, aquela
considerada para a compilao como uma nica linha de comando.
A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento da tecla
<Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm algumas vezes, por
limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha lgica em mais de
uma linha fsica no arquivo texto. Isto efetuado utilizando-se o sinal de ponto-e-vrgula (;).
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
- 23 -
Apesar de no ser uma linguagem de padres rgidos com relao estrutura do programa,
importante identificar algumas de suas partes. Considere o programa de exemplo abaixo:
#include protheus.ch
/*
+===========================================+
| Programa: Clculo do Fatorial |
| Autor : Microsiga Software S.A. |
| Data : 02 de outubro de 2001 |
+===========================================+
*/
Local nCnt
Local nResultado := 1 // Resultado do fatorial
Local nFator := 5 // Nmero para o clculo
// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
// Termina o programa
Return
rea de Identificao
Declarao dos includes
Declarao da funo
Identificao do programa
Corpo do Programa
Preparao para o processamento
Processamento
rea de Encerramento
- 24 -
O formato para esta rea no definido. Pode-se colocar qualquer tipo de informao
desejada e escolher a formatao apropriada.
#include protheus.ch
/*
+==========================================+
| Programa: Clculo do Fatorial |
| Autor : Microsiga Software S.A. |
| Data : 02 de outubro de 2001 |
+==========================================+
*/
Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto funcionamento
do programa. Entre os ajustes se encontram declaraes de variveis, inicializaes, abertura
de arquivos, etc. Apesar do ADVPL no ser uma linguagem rgida e as variveis poderem ser
declaradas em qualquer lugar do programa, aconselhvel faz-lo nesta rea visando tornar o
cdigo mais legvel e facilitar a identificao de variveis no utilizadas.
Local nCnt
Local nResultado := 0 // Resultado do fatorial
Local nFator := 10 // Nmero para o clculo
Corpo do Programa
nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a tarefa
necessria atravs da organizao lgica destas linhas de comando. Espera-se que as linhas de
comando estejam organizadas de tal modo que no final desta rea o resultado esperado seja
obtido, seja ele armazenado em um arquivo ou em variveis de memria, pronto para ser
exibido ao usurio atravs de um relatrio ou na tela.
// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
- 25 -
// Clculo do fatorial
nFator := GetFator()
// GetFator funo ilustrativa na qual a varivel recebe a informao do usurio.
If nFator <= 0
Alert(Informao invlida)
Return
Endif
rea de Encerramento
// Termina o programa
Return
- 26 -
O ADVPL no uma linguagem de tipos rgidos (strongly typed), o que significa que variveis
de memria podem receber diferentes tipos de dados durante a execuo do programa.
As 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 podem-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).
Caractere
Strings ou cadeias de caracteres so identificadas em ADVPL por blocos de texto entre aspas
duplas (") ou aspas simples ('):
"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"
Uma varivel do tipo caractere 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.
- 27 -
Arrays 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.
A partir do momento que uma varivel criada, no necessrio mais se referenciar ao seu
contedo, e sim ao seu nome.
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 atribudo 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 substitudo pelo de 300.
- 28 -
Local nNumero := 10
Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence seu
escopo local.
Local
Static
Private
Public
nNumero2 := 15
Devido a essa caracterstica, quando se pretende fazer uma atribuio a uma varivel
declarada previamente mas escreve-se o nome da varivel de forma incorreta, o ADVPL no
gerar nenhum erro de compilao ou de execuo. Pois compreender o nome da varivel
escrito de forma incorreta como se fosse a criao de uma nova varivel. Isto alterar a lgica
do programa, e um erro muitas vezes difcil de identificar.
- 29 -
Variveis de escopo local so pertencentes apenas ao escopo da funo onde foram declaradas
e devem ser explicitamente declaradas com o identificador LOCAL, como no exemplo:
Function Pai()
Local nVar := 10, aMatriz := {0,1,2,3}
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10. Quando a
funo Filha executada, nVar ainda existe mas no pode ser acessada. Quando a execuo
da funo Pai terminar, a varivel nVar destruda. Qualquer varivel com o mesmo nome no
programa que chamou a funo Pai no afetada.
Variveis de escopo local so criadas automaticamente cada vez que a funo onde forem
declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da ativao da
funo (ou seja, at que a funo retorne o controle para o cdigo que a executou). Se uma
funo chamada recursivamente (por exemplo, chama a si mesma), cada chamada em
recurso cria um novo conjunto de variveis locais.
Variveis de escopo static funcionam basicamente como as variveis de escopo local, mas
mantm seu valor atravs da execuo e devem ser declaradas explicitamente no cdigo com
o identificador STATIC.
O escopo das variveis static depende de onde so declaradas. Se forem declaradas dentro do
corpo de uma funo ou procedimento, seu escopo ser limitado quela rotina. Se forem
declaradas fora do corpo de qualquer rotina, seu escopo afeta a todas as funes declaradas
no fonte.
- 30 -
Function Pai()
Static nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada. Diferente
de variveis declaradas como LOCAL ou PRIVATE, nVar continua a existir e mantm seu valor
atual quando a execuo da funo Pai termina. Entretanto, somente pode ser acessada por
execues subseqentes da funo Pai.
A declarao opcional para variveis privadas. Mas podem ser declaradas explicitamente com
o identificador PRIVATE.
possvel criar uma nova varivel privada com o mesmo nome de uma varivel j existente.
Entretanto, a nova (duplicada) varivel pode apenas ser criada em um nvel de ativao
inferior ao nvel onde a varivel foi declarada pela primeira vez (ou seja, apenas em uma
funo chamada pela funo onde a varivel j havia sido criada). A nova varivel privada ir
esconder qualquer outra varivel privada ou pblica (veja a documentao sobre variveis
pblicas) com o mesmo nome enquanto existir.
Uma vez criada, uma varivel privada visvel em todo o programa enquanto no for
destruda automaticamente quando a rotina que a criou terminar ou uma outra varivel
privada com o mesmo nome for criada em uma subfuno chamada (neste caso, a varivel
existente torna-se inacessvel at que a nova varivel privada seja destruda).
Em termos mais simples, uma varivel privada visvel dentro da funo de criao e todas as
funes chamadas por esta, a menos que uma funo chamada crie sua prpria varivel
privada com o mesmo nome.
- 31 -
Function Pai()
Private nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)
Neste exemplo, a varivel nVar criada com escopo private e inicializada com o valor 10.
Quando a funo Filha executada, nVar ainda existe e, diferente de uma varivel de escopo
local, pode ser acessada pela funo Filha. Quando a funo Pai terminar, nVar ser destruda
e qualquer declarao de nVar anterior se tornar acessvel novamente.
No ambiente ERP Protheus, existe uma conveno adicional a qual deve ser
respeitada que variveis em uso pela aplicao no sejam incorretamente
manipuladas. Por esta conveno deve ser adicionado o caracter _ antes
do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o
tpico: Boas Prticas de Programao.
possvel criar uma varivel de escopo private com o mesmo nome de uma varivel de escopo
public existente, entretanto, no permitido criar uma varivel de escopo public com o mesmo
nome de uma varivel de escopo private existente.
Uma vez criada, uma varivel de escopo public visvel em todo o programa onde foi
declarada at que seja escondida por uma varivel de escopo private criada com o mesmo
nome. A nova varivel de escopo private criada esconde a varivel de escopo public existente,
e esta se tornar inacessvel at que a nova varivel private seja destruda. Por exemplo:
Function Pai()
Public nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)
- 32 -
Diferentemente dos outros identificadores de escopo, quando uma varivel declarada como
pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).
No ambiente ERP Protheus, existe uma conveno adicional a qual deve ser
respeitada que variveis em uso pela aplicao no sejam incorretamente
manipuladas. Por esta conveno deve ser adicionado o caracter _ antes
do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o
tpico: Boas Prticas de Programao.
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:
ou
- 33 -
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 caractere 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:
Excetuando-se o caso do valor nulo, para os demais devem ser utilizadas funes de
converso quando necessrio concatenar tipos de dados diferentes (por exemplo, nas linhas
07 e 17.
- 34 -
If xVariavel
o mesmo que
If xVariavel = .T.
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:
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
+ Adio
- Subtrao
* Multiplicao
/ Diviso
** ou ^ Exponenciao
% Mdulo (Resto da Diviso)
Operadores de String
- 35 -
Operadores Lgicos
.And. E lgico
.Or. OU lgico
.Not. ou ! NO lgico
Operadores de Atribuio
:= Atribuio Simples
+= Adio e Atribuio em Linha
-= Subtrao e Atribuio em Linha
*= Multiplicao e Atribuio em Linha
/= Diviso e Atribuio em Linha
**= ou Exponenciao e Atribuio em Linha
^=
%= Mdulo (resto da diviso) e Atribuio em Linha
Atribuio Simples
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 aplica a atribuio s variveis. Com ele
pode-se atribuir mais de uma varivel ao mesmo tempo.
- 36 -
O operador de atribuio em linha tambm pode ser utilizado para substituir valores de
campos em um banco de dados.
Atribuio Composta
Operadores de Incremento/Decremento
++ Incremento Ps ou Pr-fixado
-- Decremento Ps ou Pr-fixado
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 entanto:
Local nA := 10
Local nB := ++nA + nA
- 37 -
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
& Macro substituio
@ Passagem de parmetro por referncia
|| Passagem de parmetro por valor
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.
O smbolo || utilizado para indicar que durante a passagem de uma varivel para
uma funo ou procedimento ela seja tomada como um e valor no como referncia.
- 38 -
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.
1. Exponenciao
2. Multiplicao e Diviso
3. Adio e Subtrao
Considere o exemplo:
Alterao da Precedncia
- 39 -
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"
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
execuo, 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.
- 40 -
Alm de atribuir, controlar o escopo e macro executar o contedo das variveis necessrio
manipular seu contedo atravs de funes especficas da linguagem para cada situao.
As funes mais utilizadas nas operaes entre converso entre tipos de variveis so:
CTOD()
CVALTOCHAR()
DTOC()
DTOS()
STOD()
STR()
STRZERO()
VAL()
CTOD()
Sintaxe CTOD(cData)
Realiza a converso de uma informao do tipo caracter no formato
Descrio DD/MM/AAAA para uma varivel do tipo data.
CVALTOCHAR()
Sintaxe CVALTOCHAR(nValor)
Realiza a converso de uma informao do tipo numrico em uma string,
Descrio sem a adio de espaos a informao.
- 41 -
Sintaxe DTOC(dData)
Realiza a converso de uma informao do tipo data para em caracter, sendo
Descrio o resultado no formato DD/MM/AAAA.
DTOS()
Sintaxe DTOS(dData)
Realiza a converso de uma informao do tipo data em um caracter, sendo
Descrio o resultado no formato AAAAMMDD.
STOD()
Sintaxe STOD(sData)
Realiza a converso de uma informao do tipo caracter com contedo no
Descrio
formato AAAAMMDD em data.
STR()
Sintaxe STR(nValor)
Realiza a converso de uma informao do tipo numrico em uma string,
Descrio
adicionando espaos direita.
STRZERO()
VAL()
Sintaxe VAL(cValor)
- 42 -
ALLTRIM()
ASC()
AT()
CHR()
CSTUFF()
LEN()
RAT()
SUBSTR()
ALLTRIM()
Sintaxe ALLTRIM(cString)
Retorna uma string sem os espaos direita e esquerda, referente ao
contedo informado como parmetro.
Descrio
A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e
LTRIM (left trim).
ASC()
Sintaxe ASC(cCaractere)
Converte uma informao caractere em seu valor de acordo com a tabela
Descrio ASCII.
AT()
- 43 -
Sintaxe CHR(nASCII)
Converte um valor nmero referente a uma informao da tabela ASCII no
Descrio caractere que esta informao representa.
LEN()
Sintaxe LEN(cString)
LOWER()
Sintaxe LOWER(cString)
Retorna uma string com todos os caracteres minsculos, tendo como base a
Descrio
string passada como parmetro.
RAT()
STUFF()
SUBSTR()
- 44 -
Sintaxe UPPER(cString)
Retorna uma string com todos os caracteres maisculos, tendo como base a
Descrio
string passada como parmetro.
ABS()
INT()
NOROUND()
ROUND()
ABS()
Sintaxe ABS(nValor)
Retorna um valor absoluto (independente do sinal) com base no valor
Descrio especificado no parmetro.
INT()
Sintaxe INT(nValor)
NOROUND()
ROUND()
- 45 -
TYPE()
VALTYPE()
TYPE()
Sintaxe TYPE(cVariavel)
Determina o tipo do contedo de uma varivel, a qual no foi definida na
Descrio funo em execuo.
VALTYPE()
Sintaxe VALTYPE(cVarivel)
Determina o tipo do contedo de uma varivel, a qual foi definida na funo
Descrio em execuo.
- 46 -
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.
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.
Estruturas de repetio
Estruturas de deciso
Estruturas de repetio so designadas para executar uma seo de cdigo mais de uma vez.
Por exemplo, imaginando-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, que so os comandos
FOR...NEXT e o comando WHILE...ENDDO.
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
- 47 -
- 48 -
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
Este exemplo imprime a soma dos 100 primeiros nmeros pares. A soma obtida 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
Sintaxe
WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO
Parmetros
- 49 -
LOOP
EXIT
LOOP
A instruo LOOP utilizada para forar um desvio no fluxo do programa de volta a anlise da
condio de repetio. Desta forma, todas as operaes que seriam realizadas dentro da
estrutura de repetio aps o LOOP sero desconsideradas.
Exemplo:
aItens:= ListaProdutos() // funo ilustrativa que retorna um array com dados dos produtos
nQuantidade := Len(aItens)
nItens := 0
nItens++
IF BLOQUEADO(aItens [nItens]) // funo ilustrativa que verifica se o produto est
LOOP // bloqueado.
ENDIF
IMPRIME() // funo ilustrativa que realiza a impresso de um item liberado para uso
End
- 50 -
A instruo EXIT utilizada para forar o trmino de uma estrutura de repetio. Desta forma,
todas as operaes que seriam realizadas dentro da estrutura de repetio aps o EXIT sero
desconsideradas, e o programa ir continuar a execuo a partir da prxima instruo
posterior ao trmino da estrutura (END ou NEXT).
Exemplo:
While .T.
MSGINFO(Final de Jogo)
- 51 -
Em ADVPL existem dois comandos para execuo de sees de cdigo de acordo com
avaliaes lgicas, que so os comandos IF...ELSE...ENDIF e o comando DO
CASE...ENDCASE.
O Comando IF...ELSE...ENDIF
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
Parmetros
Exemplo:
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
Endif
Return
- 52 -
Sintaxe
IF lExpressao1
Comandos
[ELSEIF lExpressaoX
Comandos]
[ELSE
Comandos...]
ENDIF
Parmetros
- 53 -
O Comando DO CASE...ENDCASE
Sintaxe
DO CASE
CASE lExpressao1
Comandos
[CASE lExpressao2
Comandos
...
CASE lExpressaoN
Comandos]
[OTHERWISE
Comandos]
ENDCASE
Parmetros
- 54 -
Exemplo:
DO CASE
CASE nMes <= 3
cPeriodo := "Primeiro Trimestre"
CASE nMes >= 4 .And. nMes <= 6
cPeriodo := "Segundo Trimestre"
CASE nMes >= 7 .And. nMes <= 9
cPeriodo := "Terceiro Trimestre"
OTHERWISE
cPeriodo := "Quarto Trimestre"
ENDCASE
Return
- 55 -
6.1. Arrays
Arrays ou matrizes, so colees de valores, semelhantes a uma lista. Uma matriz pode ser
criada atravs de diferentes maneiras.
Cada item em um array referenciado pela indicao de sua posio numrica na lista,
iniciando pelo nmero 1.
O exemplo a seguir declara uma varivel, atribui um array de trs elementos a ela, e ento
exibe um dos elementos e o tamanho do array:
Uma caracterstica interessante do ADVPL que um array pode conter qualquer tipo de dado:
nmeros, datas, lgicos, caracteres, objetos, etc., e ao mesmo tempo. Em outras palavras, os
elementos de um array no precisam ser necessariamente do mesmo tipo de dado, em
contraste com outras linguagens como C e Pascal.
aFunct1 := {"Pedro",32,.T.}
Este array 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 de um array:
#define FUNCT_NOME 1
#define FUNCT_IDADE 2
#define FUNCT_CASADO 3
- 56 -
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 um outro array,
do mesmo modo que muitos registros so agrupados em uma tabela de banco de dados:
aFuncts um array com 3 linhas por 3 colunas. Uma vez que as variveis separadas foram
combinadas em um array, os nomes podem ser exibidos assim:
Local nCount
For nCount := 1 To Len(aFuncts)
Alert(aFuncts[nCount, FUNCT_NOME])
// O acesso a elementos de um array 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.
A facilidade da utilizao de arrays, 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.
- 57 -
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
08 Next nCnt
Este cdigo preenche o array 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 um array de tamanho conhecido
no momento da criao do cdigo.
1. Na linha 02 o array criada usando aX[10]. Isto indica ao ADVPL para alocar espao
para 10 elementos no array. Os colchetes [ e ] so utilizados para indicar o tamanho
necessrio.
3. 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.
4. A linha 07 demonstra como um valor pode ser atribudo para uma posio existente em
uma matriz especificando o ndice entre colchetes.
- 58 -
01 Local nCnt
02 Local aX[0]
03 Local aY := Array(0)
04 Local aZ := {}
05
06 For nCnt := 1 To nSize
07 AADD(aX, nCnt*nCnt)
08 Next nCnt
1. A linha 02 utiliza os colchetes para criar um array vazio. Apesar de no ter nenhum
elemento, seu tipo de dado array.
2. Na linha 03 a chamada da funo array cria uma matriz sem nenhum elemento.
Porque cada uma destes arrays no contm elementos, a linha 07 utiliza a funo AADD() para
adicionar elementos sucessivamente at o tamanho necessrio (especificado por exemplo na
varivel nSize).
ARRAY()
AADD()
ACLONE()
ADEL()
ASIZE()
AINS()
ASORT()
ASCAN()
- 59 -
AADD()
ACLONE()
Sintaxe AADD(aArray)
A funo ACLONE() realiza a cpia dos elementos de um array para outro
Descrio
array integralmente.
ADEL()
ASIZE()
ASORT()
- 60 -
AINS()
Conforme comentado anteriormente, um array uma rea na memria, o qual possui uma
estrutura permite que as informaes sejam armazenadas e organizadas das mais diversas
formas.
Com base nesse conceito, o array pode ser considerado apenas como um mapa ou um guia
de como as informaes esto organizadas e de como elas podem ser armazenadas ou
consultadas. Para se copiar um array deve-se levar este conceito em considerao, pois caso
contrrio o resultado esperado no ser o obtido na execuo da cpia.
Para copiar o contedo de uma varivel, utiliza-se o operador de atribuio :=, conforme
abaixo:
nPessoas := 10
nAlunos := nPessoas
Isto porque o comando de atribuio copia o contedo da rea de memria representada pelo
nome nPessoas para a rea de memria representada pelo nome nAlunos. Mas ao utilizar o
operador de atribuio := da mesma forma que utilizado em variveis simples para se copiar
um array o efeito diferente:
- 61 -
Desta forma ao atribuir o contedo representado pela varivel aPessoas a varivel aAlunos no
est se copiando as informaes e sim o mapa das reas de memria onde as informaes
esto realmente armazenadas.
Por esta razo deve ser utilizado o comando ACLONE() quando deseja-se obter um array com
a mesma estrutura e informaes que compe outro array j existente.
- 62 -
Primeira premissa
Pode-se escrever:
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 caractere, e em seguida para a
funo alert para a exibio. Por causa desta regra de precedncia possvel atribuir um valor
a mais de uma varivel ao mesmo tempo:
Z := Y := X := 0
Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:
Z := ( Y := (X := 0) )
Apesar de o 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
- 63 -
Segunda premissa
Em ADVPL pode-se juntar diversas linhas de cdigo em uma nica linha fsica de comando. Por
exemplo, o cdigo:
If lAchou
Alert("Cliente encontrado!")
Endif
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.
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.
Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento impresso.
Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:
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.
- 64 -
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 ) )
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:
- 65 -
E a linha de exemplo com a lista de expresses pode ser substituda, tendo o mesmo
resultado, por:
( X := 10 , Y := 20 ) // Lista de Expresses
{|| X := 10 , Y := 20 } // Bloco de Cdigo
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.
Ou seja, podem ser executados. Para a execuo, ou avaliao, de um bloco de cdigo, deve-
se utilizar a funo Eval():
Essa funo recebe como parmetro um bloco de cdigo e avalias todas as expresses
contidas neste bloco de cdigo, retornando o resultado da ltima expresso avaliada.
Passando Parmetros
B := {| N | X := 10, Y := 20 + N}
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
- 66 -
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.
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:
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
bloco de cdigo no conhece que elementos est comparando - a funo asort seleciona os
elementos (talvez utilizando o algoritmo QuickSort) e passa-os para o bloco de cdigo. O bloco
de cdigo compara-os e retorna verdadeiro (.T.) 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 ordem descendente, pode-se
utilizar o seguinte bloco de cdigo:
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:
Finalmente, para ordenar um sub-elemento (coluna) de uma matriz por exemplo, pode-se
utilizar o seguinte bloco de cdigo:
- 67 -
A linguagem ADVPL possui diversas funes que auxiliam na manipulao de blocos de cdigo,
dentre as quais podemos citar as mais utilizadas:
EVAL()
DBEVAL()
AEVAL()
EVAL()
DBEVAL()
AEVAL()
- 68 -
Para tornar uma funo mais flexvel, ao cham-la pode-se passar parmetros, o quais contm
os dados e informaes que definem o processamento da funo.
Return ...
A funo tambm tem a faculdade de retornar uma varivel, podendo inclusive ser um Array.
Para tal encerra-se a funo com:
Return(campo)
- 69 -
Nos tpicos a seguir sero detalhados os tipos de funes disponveis na linguagem ADVPL,
suas formas de utilizao e respectivas diferenas.
Function()
User Function()
Static Function()
Main Function()
Function()
O interpretador ADVPL distingue nomes de funes do tipo Function() com at dez caracteres.
A partir do dcimo caracter, apesar do compilador no indicar quaisquer tipos de erros, o
interpretador ignorar os demais caracteres.
Exemplo:
// Fonte MATA100INCL.PRW
#INCLUDE "protheus.ch"
Function MATA100INCL01()
ALERT("01")
Return
Function MATA100INCL02()
ALERT("02")
Return
- 70 -
As User Defined Functions ou funes definidas pelos usurios, so tipos especiais de funes
implementados pelo ADVPL para garantir que desenvolvimentos especficos no realizados pela
Inteligncia Protheus da Microsiga sobreponham as funes padres desenvolvidas para o ERP.
O interpretador ADVPL considera que o nome de uma User Function composto pelo nome
definido para a funo precedido dos caracteres U_. Desta forma a User Function XMAT100I
ser tratada pelo interpretador como U_XMAT100I.
Static Function()
Funes ADVPL tradicionais, cuja visibilidade est restrita as funes descritas no mesmo
arquivo de cdigo fonte no qual esto definidas.
Exemplo:
//Fonte FINA010.PRW
Function FINA010()
CriaSx1(FIN010)
Return
Function FINA020()
CriaSx1(FIN020)
Return
- 71 -
Este recurso permite isolar funes de uso exclusivo de um arquivo de cdigo fonte, evitando a
sobreposio ou duplicao de funes na aplicao.
1. Padronizar o nome de uma determinada funo, que possui a mesma finalidade, mas
que sua implementao pode variar de acordo com a necessidade de funo principal /
aplicao.
Main Function()
Main Function() outro tipo de funo especial do ADVPL incorporado para permitir
tratamentos diferenciados na aplicao ERP.
Uma Main Function() tem a caracterstica de poder ser executada atravs da tela inicial de
parmetros do client do ERP (Microsiga Protheus Remote), da mesma forma que uma User
Function, com a diferena que as Main Functions somente podem ser desenvolvidas com o uso
da autorizao de compilao, tornando sua utilizao restrita a Inteligncia Protheus da
Microsiga.
Na aplicao ERP comum o uso das Main Functions() nas seguintes situaes:
- 72 -
Complementando esta definio, podem ser utilizadas duas formas distintas de passagens de
parmetros para funes descritas na linguagem ADVPL:
Local nCnt
Local nResultado := 0
Return
Avaliando a funo CalcFator() descrita anteriormente podemos verificar que a mesma recebe
como parmetro para sua execuo a varivel nFator.
Com base nesta funo podemos descrever duas forma de passagem de parmetros por
contedo:
Local nResultado := 0
nResultado := CalcFator(5)
- 73 -
Como a linguagem ADVPL trata os parmetros de forma posicional, o contedo 5 ser atribudo
diretamente a varivel definida como primeiro parmetro da funo chamado, no nosso caso
nFator.
Por ser uma atribuio de parmetros por contedo, o interpretador da linguagem basicamente
executa uma operao de atribuio normal, ou seja, nFator := 5.
Local nResultado := 0
Local nFatorUser := 0
nFatorUser := GetFator() // Funo ilustrativa na qual o usurio informa o fator a ser utilizado.
nResultado := CalcFator(nFatorUser)
- 74 -
Por ser uma atribuio de parmetros por contedo, o interpretador da linguagem basicamente
executa uma operao de atribuio normal, ou seja, nFator := nFatorUser.
nResultado := CalcFator(nFatorUser)
...
Function CalcFator(nFator)
...
A passagem de parmetros por referncia uma tcnica muito comum nas linguagens de
programao a qual permite que variveis de escopo LOCAL tenham seu contedo manipulado
por funes especficas, mantendo o controle destas variveis restrito a funo que as definiu e
as funes desejadas pela aplicao.
A passagem de parmetros por referncia utiliza o conceito de que uma varivel uma rea
de memria e portanto passar um parmetro por referncia nada mais do que ao invs de
passar o contedo para a funo chamada, passar qual a rea de memria utilizada pela
varivel passada.
- 75 -
Passagem de parmetros por referncia Duas variveis x uma nica rea de memria
- 76 -
O tratamento de contedos padres para parmetros de funes muito utilizado nas funes
padres da aplicao ERP, de forma a garantir a correta execuo destas funes por qualquer
funo chamadora, evitando situaes de ocorrncias de erros pela falta da definio de
parmetros necessrios a correta utilizao da funo.
Exemplo:
Local nCnt
Local nResultado := 0
Default nFator := 1
Return nResultado
- 77 -
Exemplo:
Local nCnt
Local nResultado := 0
For nCnt := nFator To 1 Step -1 // nFator est como Nulo, portando nCnt nulo
nResultado *= nCnt
Next nCnt // Ao efetuar o Next, o interpretador realiza a ao nCnt += 1.
Return nResultado
- 78 -
#INCLUDE
#DEFINE
#IFDEF
#IFNDEF
#ELSE
#ENDIF
#COMMAND
Diretiva: #INCLUDE
A diretiva #INCLUDE indica em que arquivo de extenso CH (padro ADVPL) esto os UDCs
a serem utilizados pelo pr-processador.
A aplicao ERP possui diversos includes, os quais devem ser utilizados segundo a aplicao
que ser desenvolvida, o que permitir a utilizao de recursos adicionais definidos para a
linguagem, implementados pela rea de Tecnologia da Microsiga.
Os includes mais utilizados nas aplicaes ADVPL desenvolvidas para o ERP so:
- 79 -
o DIALOG.CH
o FONT.CH
o INI.CH
o PTMENU.CH
o PRINT.CH
o TCQUERY
o CREATE RPCCONN
o CLOSE RPCCONN
o PREPARE ENVIRONMENT
o RESET ENVIRONMENT
o OPEN REMOTE TRANSACTION
o CLOSE REMOTE TRANSACTION
o CALLPROC IN
o OPEN REMOTE TABLES
o CREATE XMLSTRING
o CREATE XMLFILE
o SAVE XMLSTRING
o SAVE XMLFILE
- 80 -
Diretiva: #DEFINE
A diretiva #DEFINE permite que o desenvolvedor crie novos termos para serem utilizadas no
cdigo fonte. Este termo tem o efeito de uma varivel de escopo PUBLIC, mas que afeta
somente o fonte na qual o #DEFINE est definido, com a caracterstica de no permitir a
alterao de seu contedo.
Desta forma um termo definido atravs da diretiva #DEFINE pode ser considerado como uma
constante.
Por esta razo a aplicao ERP possui trs repositrios distintos para cada
uma das bases de dados homologadas pela Microsiga, pois cada compilao
utiliza uma diretiva referente ao seu idioma.
- 81 -
Atravs destas diretivas, podem ser verificados parmetros do sistema, tais como o idioma
com o qual est parametrizado e a base de dados utilizada para armazenar e gerenciar as
informaes do ERP.
Desta forma, ao invs de escrever dois ou mais cdigos fontes que realizam a mesma funo,
mas utilizando recursos distintos para cada base de dados ou exibindo mensagem para cada
um dos idiomas tratados pela aplicao, o desenvolvedor pode preparar seu cdigo fonte para
ser avaliado pelo pr-processador, o qual ir gerar um cdigo compilado de acordo com a
anlise dos parmetros de ambiente.
#IFDEF SPANISH
#DEFINE STR0001 Hola !!!
#ELSE
#IFDEF ENGLISH
#DEFINE STR0001 Hello !!!
#ELSE
#DEFINE STR0001 Ol !!!
#ENDIF
#ENDIF
PORTUGUESE
SPANISH
ENGLISH
- 82 -
#IFDEF TOP
#ELSE
DbSelectArea(SA1)
#ENDIF
Diretiva: #COMMAND
Esta diretiva permite que o desenvolvedor defina para o compilador como uma expresso
dever ser interpretada.
- 83 -
O PROTHEUS, por outro lado, uma plataforma tecnolgica que engloba um Servidor de
Aplicao, um Dicionrio de Dados e as Interfaces para conexo com o usurio. o Protheus
que executa o cdigo ADVPL e o devido acesso base da dados.
O Protheus composto pelo ERP (que engloba, alm das funcionalidades descritas nos
captulos anteriores, mais de trinta verticais aplicadas a reas especficas de negcios) e
pelo Configurador (programa que permite customizar o sistema s necessidades do usurio
de forma fcil).
Para executar um programa desenvolvido em ADVPL, preciso antes de mais nada escrev-lo
e compil-lo. Este procedimento feito atravs da ferramenta TOTVS DevStudio do
Protheus (Totvs Development Studio).
- 84 -
Proteger o programa fonte, evitando que seja alterado indevidamente, pois somente os
objetos so distribudos com uma execuo mais rpida em funo da compilao no
DEV-Studio;
Que o sistema cresa de forma ilimitada, pois os objetos ficam fora do executvel;
- 85 -
- 86 -
Protheus Monitor / TOTVS Monitor: Programa de anlise que verifica quem est
usando o sistema e possibilita o envio de mensagens ou mesmo derrubar conexes
(TOTVSMONITOR.EXE).
Caso exista algum Firewall ou Proxy entre o WEB Server e o Browser que vai acessar o
SmartClient ActiveX, eles devero ser configurados para permitir o seu download.
- 87 -
- 88 -
Apesar da estrutura ilustrada anteriormente indicar que as pastas esto subordinadas pasta
PROTHEUS, possvel que algumas delas possam estar em mquinas diferentes ou at mesmo
em ambientes computacionais diferentes.
- 89 -
- 90 -
c:\protheus\bin\appserver\totvsappserver.exe
Destino:
Iniciar em:
- console
c:\protheus\bin\appserver
-Console ou -Debug
Executado como uma JanelaConsole, as informaes recebidas das conexes com o TOTVS
Application Server conectados so exibidas diretamente na tela do console do TOTVS
Application Server, bem como informaes de No Conformidades.
-Install
-Remove
Para remov-lo da Lista de Servios do NT, pode-se execut-lo com a opo de Linha de
Comando.
c:\protheus\bin\smartclient\totvssmartcliente.exe
Destino:
Iniciar em:
M
c:\protheus\bin\smartclient
-Q (Quiet)
Indica que o TOTVS Smart Client, no dever mostrar o Splash (Imagem de Apresentao) e a
tela de identificao de Parmetros Iniciais, necessita ser acompanhada da (Clusula P).
-P (Main Program)
-E (Environment)
Nome da Seo de Environment, no (Ini do Server), que ser utilizada, para definies gerais.
-C (Connection)
Nome da Seo de Conexo, que ser utilizada, para a conexo ao TOTVS Application Server.
-M (AllowMultiSession)
Permite mltiplas instncias (Cpias) do TOTVS Smart Client, na mesma mquina, o que por
Default no permitido.
- 91 -
RootPath: Aponta para a pasta raiz (inicial), a partir da qual sero localizados os dados
(no caso de ISAM), bem como o prprio Dicionrio de Dados (Exemplo:
RootPath=C:\PROTHEUS\PROTHEUS_DATA)
[ENVIRONMENT]
SOURCEPATHC:\PROTHEUS\APO
ROOTPATH= C:\MP811\PROTHEUS_DATA
STARTPATH=\ PROTHEUS\
RPODB=TOP
RPOLANGUAGE=PORTUGUESE
RPOVERSION=101
LOCALFILES=ADS
TRACE=0
LOCALDBEXTENSION=.DBF
PICTFORMAT=DEFAULT
DATEFORMAT=DEFAULT
[DRIVERS]
ACTIVE=TCP
[TCP]
TYPE=TCPIP
PORT=1234
- 92 -
[DRIVERS]
ACTIVE=TCP
[TCP]
SERVER=172.16.72.41
PORT=1234
Port: Indica o nmero da porta a ser utilizada para a comunicao entre o Protheus
Server e o Protheus Remote. necessrio que a porta utilizada na comunicao seja a
mesma em ambos (no TOTVSAPPSERVER.INI e no TOTVSSMARTCLIENT.INI). Vale
ressaltar que a porta 80 reservada para a Internet e pode causar conflitos caso seja
utilizada na comunicao do Protheus.
Server: Aponta para o endereo do servidor que pode ser a prpria mquina
(localhost) ou o nome da mquina (Server= Servidor_01) ou mesmo um endereo IP
(exemplo Server=172.16.72.41).
Exemplo:
- 93 -
Para contextualizar a estrutura da aplicao ERP, no tpico a seguir detalhada a forma como
as tabelas de dados do sistema esto divididas entre os diversos mdulos que compe o
PROTHEUS.
Arquivo Descrio
SIGAMAT Cadastro de empresas e filiais do sistema
SIGAPSS Arquivo de usurios, grupos e senhas do sistema
SIX ndices dos arquivos
SX1 Perguntas e respostas
SX2 Mapeamento de tabelas
SX3 Dicionrio de Dados
SX4 Agenda do Schedule de processos
SX5 Tabelas
SX6 Parmetros
SX7 Gatilhos de Interface
SX8 Fora de uso
SX9 Relacionamentos entre tabelas
SXA Pastas cadastrais apontadas no SX3
SXB Consulta por meio da tecla F3 (Consulta Padro)
SXD Controle do Schedule de processos
SXE Seqncia de documentos (+1)
SXF Seqncia de documentos (Prximo)
SXG Tamanho padro para campos apontado pelo SX3
SXK Resposta de Perguntas (SX1) por usurios
SXO Controle de LOGs por tabela
SXP Histrico de Logs cadastrados no SXO
Cadastro de filtros inteligentes da mbrowse (contm as
SXQ informaes necessrias para a criao do filtro).
Cadastro de relacionamento entre programa x filtro
SXR (utilizada internamente pelo Protheus para verificar em
quais programas os filtros podero ser utilizados).
- 94 -
Ambientes e tabelas
Na aplicao PROTHEUS as tabelas de dados podem ter uma estrutura mais simples e
econmica, com tabelas em DBF/ADS, do fabricante Extended System ou CTREE do fabricante
FAIRCOM ou uma estrutura mais robusta e complexa, em bases SQL (SQLSERVER da
Microsoft, ORACLE, DB II da IBM, SYBASE, MYSQL, POSTGREE, etc.).
Para permitir uma utilizao adequada das tabelas de dados do sistema por cada um dos
ambientes da aplicao ERP, as tabelas foram divididas em grupos denominados famlias.
Cada mdulo pode utilizar uma ou mais famlias de tabelas especificas para suas atividades, e
ainda compartilhar informaes com outros mdulos atravs de famlias comuns a todas as
operaes realizadas no sistema.
A tabela a seguir demonstra alguns dos mdulos que compe a aplicao ERP PROTHEUS
atualmente:
Ambiente Identificao
SIGAATF ATIVO FIXO
SIGACOM COMPRAS
SIGACON CONTABILIDADE
SIGAEST ESTOQUE E CUSTOS
SIGAFAT FATURAMENTO
SIGAFIN FINANCEIRO
SIGAFIS LIVROS FISCAIS
SIGAPCP PLANEJAMENTO E CONTROLE DA PRODUO
SIGAGPE GESTO DE PESSOAL
SIGAFAS FATURAMENTO DE SERVIOS
SIGAVEI VECULOS
SIGALOJ CONTROLE DE LOJAS/AUTOMAO COMERCIAL
SIGATMK CALL CENTER
SIGAOFI OFICINAS
SIGAPON PONTO ELETRNICO
SIGAEIC EASY IMPORT CONTROL
SIGATCF TERMINAL
SIGAMNT MANUTENO DE ATIVOS
SIGARSP RECRUTAMENTO E SELEO DE PESSOAL
SIGAQIE INSPEO DE ENTRADA QUALIDADE
SIGAQMT METODOLOGIA QUALIDADE
O nome de cada tabela no Protheus constitudo de seis dgitos, os quais so utilizados para
formar a seguinte representao:
F X X E E 0
- 95 -
A tabela a seguir demonstra algumas das principais famlias de tabelas utilizadas pela
aplicao ERP Protheus:
Famlia Descrio
S - Tabelas pertencentes ao sistema bsico, tambm chamado Classic
Cadastros de entidades compartilhadas entre os ambientes
S A
(Clientes, Fornecedores, Bancos entre outros).
Cadastros dos ambientes de Materiais (Produtos, Saldos entre
S B
outros).
Arquivos de movimentaes diversas utilizados pelos ambientes de
Materiais (Solicitao ao Almoxarifado, Solicitao de Compras,
S C
Pedido de Compras, Pedido de Vendas, Ordens de Produo entre
outros).
Arquivos de movimentaes de estoque (Itens de notas fiscais de
S D
entrada e sada, movimentos internos de estoque entre outros).
S E Cadastros e movimentaes do ambiente Financeiro.
Cadastros e movimentaes Fiscais (Cabealhos das notas fiscais
S F de entrada e sada, cadastro de tipos de entrada e sada, livros
fiscais, entre outros).
S G Cadastros do ambiente de Planejamento e Controle de Produo
S H Movimentos do ambiente de Planejamento e Controle de Produo
S I Cadastros e movimentos do ambiente Contbil (descontinuado)
S N Cadastros e movimentos do ambiente Ativo Fixo
S R Cadastros e movimentos do ambiente Gesto de Pessoal
S X Tabelas de configurao do sistema
S Z Tabelas livres para utilizao e projetos especficos em clientes.
A - Gesto de Projetos
C - Contabilidade Gerencial
C T Contabilidade Gerencial
C V Contabilidade Gerencial
C W Contabilidade Gerencial
D - Transportadoras e derivados
E - Comrcio exterior e derivados
G - Gesto Hospitalar
J - Gesto Educacional
N - Servios Pblicos
P - Reservado para projetos da fbrica de software
Q - Qualidade e derivados
R - Recursos Humanos e derivados
T - Plano de Sade
W - Workflow
Z - Tabelas livres para utilizao e projetos especficos em clientes em
adio a famlia SZ.
- 96 -
Cada tabela do sistema possui seus ndices definidos no arquivo de configurao SIX, o qual
pode ser atualizado atravs do mdulo Configurador.
Os arquivos de ndices das tabelas de sistema sero criados de acordo com o banco de dados
utilizado (ISAM ou conexo via TOPCONNECT).
Para bancos de dados ISAM, ser gerados arquivos com a mesma nomenclatura da tabela de
dados, mas com uma extenso diferenciada (atualmente .CDX). No caso da utilizao de um
banco de dados, cada ndice ser uma numerao seqencial em funo do nome da tabela
original.
As especificaes das chaves de ndices de cada um das tabelas est disponvel no arquivo de
sistema SIX, e a chave nica da tabela utilizada para banco de dados est descrita na tabela
SX2.
Menus
Cada mdulo da aplicao ERP possui um menu padro com todas as funcionalidades
disponveis para o ambiente, menu este definido atravs de sintaxe XML (arquivos .XNU).
Os menus possuem uma estrutura padro que permite ao usurio localizar e identificar
facilmente cada uma das funcionalidades oferecidas pelo ambiente.
Para executar o mdulo Configurador necessrio que a aplicao Protheus Server esteja em
execuo e atravs da aplicao Protheus Remote dever ser informada como programa inicial
a opo SIGACFG.
- 97 -
- 98 -
- 99 -
- 100 -
A idia do Dicionrio de Dados permitir que o usurio possa incluir ou inibir campos, ou
mesmo alterar as propriedades dos campos existentes. Pode, ainda, criar novas tabelas. Ou
seja, os programas ao invs de terem os campos definidos em seu cdigo original, lem o
Dicionrio em tempo de execuo, montando arrays com as propriedades de cada um. A partir
da, sua utilizao normal, atravs do uso de funes do ADVPL que tornam o trabalho do
desenvolvedor transparente a esta arquitetura.
O objetivo do Dicionrio de Dados permitir que o prprio usurio crie novas tabelas ou altere
os campos nas tabelas existentes quanto ao seu uso, sua ordem de apresentao, legenda
(nos trs idiomas), validao, help, obrigatoriedade de preenchimento, inicializao etc.
Procedimento
1. Para adicionar uma tabela ao dicionrio de dados de uma empresa, selecione a opo
Dicionrio de Dados abaixo da empresa que ser atualizada. (rvore de opes da parte
esquerda da interface visual do Gerenciador de Bases de Dados).
- 101 -
boto Incluir ( ). Ao utilizar esta opo ser exibida a tela para definio dos dados
referentes nova tabela que ser criada:
- 102 -
( ).
O Path refere-se pasta que conter efetivamente os dados das tabelas, quando ISAM,
nas verses com banco de dados relacional no so utilizadas. Essa pasta ser criada
dentro da pasta indicada na configurao do sistema como ROOTTPATH.
- 103 -
Procedimento
e selecione a tabela que ser atualizada, e utilize o boto Editar ( ). Ao utilizar esta
opo ser exibida a tela de manuteno de campos da tabela selecionada:
- 104 -
- 105 -
opo Incluir ( ). Ao utilizar esta opo ser exibida a tela para definio dos dados
referentes ao novo campo que ser criado:
boto Confirmar ( ).
- 106 -
Nome do campo: Todos os campos tm como prefixo o prprio nome da tabela, sendo
que para tabelas da famlia S, o prefixo do campo composto apenas pelos prximos
dois dgitos. No caso das demais tabelas, o prefixo do campo sero os trs dgitos
identificadores da tabela.
Tipo do campo: Indica se caractere, numrico, lgico, data ou memo. claro que a
mudana do tipo de campo deve ser feita com muito cuidado, pois, se tivermos um
campo numrico usado em clculos e ele for alterado para caractere, certamente
teremos um erro.
Formato de edio: Define como o campo aparece nas telas e nos relatrios.
Contexto: Pode ser real ou virtual. O contexto virtual cria o campo somente na
memria e no na tabela armazenada no disco. Isso necessrio porque os
programas de cadastramento e de consulta genrica apresentam somente uma tabela
de cada vez. Assim, se quisermos apresentar um campo de uma outra tabela, ou
mesmo o resultado de um clculo, sem que tal informao ocupe espao fsico no HD,
utilizamos o contexto virtual. Campos virtuais normalmente so alimentados por
gatilhos.
Guia: Campo
- 107 -
Ttulo: a legenda que aparece nas telas/relatrios. H inclusive trs campos para
esta finalidade: em portugus, espanhol e ingls. Esta propriedade pode ser alterada
vontade, pois no interfere em nenhum processamento.
Guia: Opes
Guia: Validaes
Guia: Uso
Guia: Mdulos
- 108 -
Conforme mencionado anteriormente, no ambiente Protheus uma tabela pode ter vrios
ndices, os quais sero gerados de acordo com o banco de dados configurado para o sistema.
Procedimento
e selecione a tabela que ser atualizada, e utilize o boto Editar ( ). Ao utilizar esta
opo ser exibida a tela de manuteno de campos da tabela selecionada:
- 109 -
5. Aps a visualizao dos ndices j cadastrados no SIX para a tabela selecionada, utilize
a opo Incluir ( ). Ao utilizar esta opo ser exibida a tela para definio dos
dados referentes ao novo ndice que ser criado:
- 110 -
Confirmar ( ).
- 111 -
O Nickname uma identificao complementar do ndice o qual pode ser utilizada para
auxiliar o desenvolvedor na utilizao desta ordem em uma aplicao, a qual pode ser
padro do sistema ou especfica de um cliente.
Para selecionar os campos j cadastrados na tabela, pode ser utilizado o boto Campos
O campo relativo filial sempre faz parte dos ndices, com exceo do SM2, para que
os registros nas tabelas estejam agrupados por filiais, independente desta tabela ser
compartilhada entre as filiais.
Procedimento
- 112 -
Confirmar ( ).
Pode haver vrios gatilhos para o mesmo campo. A ordem de execuo determinada
pelo campo Seqncia.
A regra pode ser uma expresso que resulta em um valor a ser preenchido no Contra
Domnio.
- 113 -
Procedimento
1. Para adicionar uma tabela genrica, selecione os menus Ambiente, Cadastros, Tabelas.
- 114 -
Confirmar ( ).
Procedimento
utilize o boto Incluir ( ) para realizar o cadastro de uma nova tabela no sistema:
- 115 -
boto Confirmar ( ).
- 116 -
A ferramenta TOTVS Development Studio um programa que faz parte do Protheus e permite
o trabalho de edio, compilao e depurao de programas escritos em ADVPL.
Projeto
Um programa para ser compilado deve ser vinculado a um projeto. Normalmente, programas
que fazem parte de um determinado mdulo ou ambiente esto em um mesmo projeto.
A vinculao dos programas a um projeto feita por meio dos arquivos do tipo PRW. Na
verdade, um projeto pode ser constitudo de um ou mais arquivos deste tipo, que por sua vez,
podem ter uma ou mais funes, conforme ilustra o diagrama a seguir:
- 117 -
Uma vez adicionado a um projeto e compilado sem incidncias de erros de cdigo, o objeto
resultante ser cadastrado no RPO (Repositrio de Objetos) e poder ser utilizado pela
aplicao ERP.
A compilao dos itens de um projeto pode ser realizada individualmente, por grupo de fontes
(pastas) ou ainda selecionando-o inteiramente. Cada uma dos fontes ser processado e
compilado separadamente, permitindo a visualizao do progresso da operao e das
mensagens de aviso (warnings) ou erros (critical errors) na guia Mensagens.
Execuo
Para que os objetos compilados e disponveis n RPO sejam utilizados, devem ser observadas as
seguintes regras:
Para identificar as causas de erros, a ferramenta DEV-Studio possui diversos recursos que
auxiliam o DEBUG.
Variveis Locais
Variveis Privates
Variveis Publics
Variveis Statics
Janela da Watchs
Janela de Tabelas e Campos
Pilha de Chamadas
Atravs da Janela de Watchs possvel determinar quais variveis devem ser exibidas;
- 118 -
Interface da aplicao
- 119 -
Desta forma a linguagem possui dois grupos de funes distintos para atuar com os bancos de
dados:
As funes de manipulao de dados ditas como genricas permitem que uma aplicao ADVPL
seja escrita da mesma forma, independente se a base de dados configurada para o sistema
ERP for do tipo ISAM ou padro SQL.
Muitas destas funes foram inicialmente herdadas da linguagem CLIPPER, e mediante novas
implementaes da rea de Tecnologia da Microsiga foram melhoradas e adequadas s
necessidades do ERP. Por esta razo possvel encontrar em documentaes da linguagem
CLIPPER informaes sobre funes de manipulao de dados utilizadas na ferramenta ERP.
Estas funes permitem que o desenvolvedor ADVPL execute comandos em sintaxe SQL
diretamente de um cdigo fonte da aplicao, disponibilizando recursos como execuo de
queries de consulta, chamadas de procedures e comunicao com outros bancos de dados
atravs de ODBCs.
- 120 -
Como a aplicao ERP pode ser configurada para utilizar diferentes tipos de bases de dados
importante mencionar as principais diferenas entre estes recursos, o que pode determinar a
forma como o desenvolvedor ir optar por escrever sua aplicao.
O acesso direto feito atravs de ndices que so tabelas paralelas s tabelas de dados e que
contm a chave e o endereo do registro, de forma anloga ao ndice de um livro. Para cada
chave, criado um ndice prprio.
Nas bases de dados padro ISAM os ndices so armazenados em um nico arquivo do tipo
CDX, j nos bancos de dados padro SQL cada ndice criado com uma numerao seqencial
tendo como base o nome da tabela ao qual ele est relacionado.
Nas bases de dados padro ISAM, cada registro possui um identificador nativo ou ID
seqencial e ascendente que funciona como o endereo base daquela informao.
Este ID, mas conhecido como RECNO ou RECNUMBER gerado no momento de incluso do
registro na tabela e somente ser alterado caso a estrutura dos dados desta tabela sofra
alguma manuteno. Dentre as manutenes que uma tabela de dados ISAM pode sofrer
pode-se citar a utilizao do comando PACK, o qual ir apagar fisicamente os registros
deletados da tabela forando uma renumerao dos identificadores de todos os registros. Esta
situao tambm torna necessria a recriao de todos os ndices vinculados quela tabela.
Isto ocorre nas bases de dados ISAM devido ao conceito de excluso lgica de registros que as
mesmas possuem. J os bancos de dados padro SQL nativamente utilizam apenas o conceito
de excluso fsica de registros, o que para outras aplicaes seria transparente, mas no o
caso do ERP Protheus.
Para manter a compatibilidade das aplicaes desenvolvidas para bases de dados padro
ISAM, a rea de Tecnologia e Banco de Dados da Microsiga implementou nos bancos de dados
padro SQL o conceito de excluso lgica de registros existente nas bases de dados ISAM
atravs da criao de campos de controle especficos: R_E_C_N_O_, D_E_L_E_T_ e
R_E_C_D_E_L.
Estes campos permitem que a aplicao ERP gerencie as informaes do banco de dados da
mesma forma que as informaes em bases de dados ISAM.
- 121 -
O campo D_E_L_E_T_ tratado internamente pela aplicao ERP como um flag ou marca de
excluso. Desta forma os registros que estiverem com este campo marcado sero
considerados como excludos logicamente. A execuo do comando PACK em uma tabela de
um banco de dados padro SQL visa excluir fisicamente os registros com o campo D_E_L_E_T_
marcado, mas no causar o efeito de renumerao de RECNO (no caso R_E_C_N_O_) que
ocorre nas tabela de bases de dados ISAM.
Dentre as funes ADVPL disponveis para acesso e manipulao de informaes, este material
ir detalhar as seguintes opes:
SELECT()
DBSELECTAREA()
DBSETORDER()
DBSEEK() E MSSEEK()
DBSKIP()
DBGOTO()
DBGOTOP()
DBGOBOTTON()
DBSETFILTER()
RECLOCK()
SOFTLOCK()
MSUNLOCK()
DBDELETE()
DBUSEAREA()
DBCLOSEAREA()
- 122 -
Sintaxe DBRLOCK(xIdentificador)
Funo de base de dados, que efetua o lock (travamento) do registro
identificado pelo parmetro xIdentificador. Este parmetro pode ser o
Recno() para tabelas em formado ISAM, ou a chave primria para bancos de
dados relacionais.
Descrio
Se o parmetro xIdentificador no for especificado, todos os locks da rea de
trabalho sero liberados, e o registro posicionado ser travado e adicionado
em uma lista de registros bloqueados.
DBCLOSEAREA()
Sintaxe DbCloseArea()
Permite que um alias presente na conexo seja fechado, o que viabiliza seu
reuso em outro operao. Este comando tem efeito apenas no alias ativo na
Descrio
conexo, sendo necessria sua utilizao em conjunto com o comando
DbSelectArea().
DBCOMMIT()
Sintaxe DBCOMMIT()
DBCOMMITALL()
Sintaxe DBCOMMITALL()
Efetua todas as atualizaes pendentes em todas as rea de trabalho em uso
Descrio
pela thread (conexo) ativa.
DBDELETE()
Sintaxe DbDelete()
Efetua a excluso lgica do registro posicionado na rea de trabalho ativa,
Descrio sendo necessria sua utilizao em conjunto com as funes RecLock() e
MsUnLock().
DBGOTO()
Sintaxe DbGoto(nRecno)
Move o cursor da rea de trabalho ativa para o record number (recno)
Descrio especificado, realizando um posicionamento direto, sem a necessidade uma
busca (seek) prvio.
- 123 -
Sintaxe DbGoTop()
Descrio Move o cursor da rea de trabalho ativa para o primeiro registro lgico.
DBGOBOTTON()
Sintaxe DbGoBotton()
Descrio Move o cursor da rea de trabalho ativa para o ltimo registro lgico.
DBRLOCKLIST()
Sintaxe DBRLOCKLIST()
Retorna um array contendo o record number (recno) de todos os registros
Descrio
travados da rea de trabalho ativa.
DBSEEK() E MSSEEK()
DBSKIP()
Sintaxe DbSkip(nRegistros)
Move o cursor do registro posicionado para o prximo (ou anterior
Descrio dependendo do parmetro), em funo da ordem ativa para a rea de
trabalho.
DBSELECTAREA()
- 124 -
DBSETORDER()
Sintaxe DbSetOrder(nOrdem)
Define qual ndice ser utilizada pela rea de trabalho ativa, ou seja, pela
rea previamente selecionada atravs do comando DbSelectArea(). As
Descrio
ordens disponveis no ambiente Protheus so aquelas definidas no SINDEX
/SIX, ou as ordens disponibilizadas por meio de ndices temporrios.
DBORDERNICKNAME()
Sintaxe DbOrderNickName(NickName)
Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os
Descrio seus prprios ndices e no momento da incluso deve criar o NICKNAME para
o mesmo.
DBUNLOCK()
Sintaxe DBUNLOCK()
Mesma funcionalidade da funo UNLOCK(), s que recomendada para
ambientes de rede nos quais os arquivos so compartilhados.
Descrio
Libera o travamento do registro posicionado na rea de trabalho ativa e
confirma as atualizaes efetuadas naquele registro.
DBUNLOCKALL()
Sintaxe DBUNLOCKALL()
Libera o travamento de todos os registros de todas as reas de trabalho
Descrio
disponveis na thread (conexo) ativa.
DBUSEAREA()
MSUNLOCK()
Sintaxe MsUnLock()
Libera o travamento (lock) do registro posicionado confirmando as
Descrio
atualizaes efetuadas neste registro.
- 125 -
Sintaxe RecLock(cAlias,lInclui)
Efetua o travamento do registro posicionado na rea de trabalho ativa,
Descrio
permitindo a incluso ou alterao das informaes do mesmo.
RLOCK()
SELECT()
Sintaxe Select(cArea)
Determina o nmero de referncia de um determinado alias em um
ambiente de trabalho. Caso o alias especificado no esteja em uso no
Descrio
ambiente, ser retornado o valor 0 (zero).
SOFTLOCK()
Sintaxe SoftLock(cAlias)
Permite a reserva do registro posicionado na rea de trabalho ativa de forma
que outras operaes, com exceo da atual, no possam atualizar este
registro. Difere da funo RecLock() pois no gera uma obrigao de
atualizao, e pode ser sucedido por ele.
Descrio
Na aplicao ERP Protheus, o SoftLock() utilizado nos browses, antes da
confirmao da operao de alterao e excluso, pois neste momento a
mesma ainda no foi efetivada, mas outras conexes no podem acessar
aquele registro pois o mesmo est em manuteno, o que implementa da
integridade da informao.
UNLOCK()
Sintaxe UNLOCK()
Libera o travamento do registro posicionado na rea de trabalho ativa e
Descrio
confirma as atualizaes efetuadas naquele registro.
- 126 -
Muitas vezes uma varivel pode ter o mesmo nome que um campo de um arquivo ou de uma
tabela aberta no momento. Neste caso, o ADVPL privilegiar o campo, de forma que 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.
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
- 127 -
Semforos
Com isso, mesmo que tenhamos vrios processos solicitando numeraes seqenciais para
uma mesma tabela, como por exemplo incluses simultneas de pedidos de vendas, teremos
para cada pedido um nmero exclusivos e sem o intervalos e numeraes no utilizadas.
A linguagem ADVPL permite a utilizao das seguintes funes para o controle das numeraes
seqenciais utilizadas nas tabelas da aplicao ERP:
GETSXENUM()
CONFIRMSXE()
ROLLBACKSXE()
GETSXENUM()
- 128 -
Sintaxe CONFIRMSXE(lVerifica)
ROLLBACKSXE()
Sintaxe ROLLBACKSXE()
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(),
Descrio
retornando a numerao disponvel para outras conexes.
Neste tpico sero abordas as formas pelas quais a aplicao ERP Protheus pode ser
customizada com a utilizao da linguagem ADVPL.
- 129 -
Com base nesta premissa, a utilizao de validaes no Dicionrio de Dados (SX3) ou nas
Perguntas de Processos e Relatrios (SX1) dever focar sempre na utilizao de funes ou
expresses que resultem em um retorno lgico.
Dentre as funes que a linguagem ADVPL em conjunto com os recursos desenvolvidos pela
aplicao ERP para validao de campos e perguntas sero detalhadas:
VAZIO()
NAOVAZIO()
EXISTCPO()
EXISTCHAV()
PERTENCE()
POSITIVO()
NEGATIVO()
TEXTO()
EXISTCHAV()
- 130 -
NAOVAZIO()
Sintaxe NaoVazio()
Retorna .T. ou .F. se o contedo do campo posicionado no momento no
Descrio
est vazio.
NEGATIVO()
Sintaxe Negativo()
PERTENCE()
Sintaxe Pertence(cString)
Retorna .T. ou .F. se o contedo digitado para o campo est contido na
string definida como parmetro da funo. Normalmente utilizada em
Descrio
campos com a opo de combo, pois caso contrrio seria utilizada a funo
ExistCpo().
POSITIVO()
Sintaxe Positivo()
TEXTO()
Sintaxe Texto()
Retorna .T. ou .F. se o contedo digitado para o campo contm apenas
Descrio
nmeros ou alfanumricos.
VAZIO()
Sintaxe Vazio()
Retorna .T. ou .F. se o contedo do campo posicionado no momento est
Descrio
vazio.
- 131 -
Funes
Contedo Funcionalidade
A Permite apenas caracteres alfabticos.
C Exibe CR depois de nmeros positivos.
E Exibe numrico com o ponto e vrgula invertidos (formato Europeu).
R Insere caracteres diferentes dos caracteres de template na exibio, mas no os
insere na varivel do GET.
S<n> Permite rolamento horizontal do texto dentro do GET, <n> um nmero inteiro
que identifica o tamanho da regio.
X Exibe DB depois de nmeros negativos.
Z Exibe zeros como brancos.
( Exibe nmeros negativos entre parnteses com os espaos em branco iniciais.
) Exibe nmeros negativos entre parnteses sem os espaos em branco iniciais.
! Converte caracteres alfabticos para maisculo.
Templates
Contedo Funcionalidade
X Permite qualquer caractere.
9 Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos.
# Permite dgitos, sinais e espaos em branco para qualquer tipo de dado.
! Converte caracteres alfabticos para maisculo.
* Exibe um asterisco no lugar dos espaos em branco iniciais em nmeros.
. Exibe o ponto decimal.
, Exibe a posio do milhar.
A1_NOME Caracter - 40
Picture: @!
- 132 -
Funes
Contedo Funcionalidade
C Exibe CR depois de nmeros positivos
E Exibe numrico com o ponto e a vrgula invertidos (formato Europeu)
R Insere caracteres diferentes dos caracteres de template
X Exibe DB depois de nmeros negativos
Z Exibe zeros como brancos
( Envolve nmeros negativos entre parnteses
! Converte todos os caracteres alfabticos para maisculo
Templates
Contedo Funcionalidade
X Exibe dgitos para qualquer tipo de dado
9 Exibe dgitos para qualquer tipo de dado
# Exibe dgitos para qualquer tipo de dado
! Converte caracteres alfabticos para maisculo
* Exibe asterisco no lugar de espaos em branco inicias em nmeros
. Exibe a posio do ponto decimal
, Exibe a posio do milhar
- 133 -
A aplicao ERP utiliza o recurso de gatilhos em campo com a finalidade de auxiliar o usurio
no preenchimento de informaes durante a digitao de informaes. As funes que podem
ser utilizadas no gatilho esto diretamente relacionadas a definio da expresso de retorno
que ser executada na avaliao do gatilho do campo.
Na definio da chave de busca do gatilho deve ser avaliada qual filial dever ser
utilizada como parte da chave: a filial da tabela de origem do gatilho ou a filial da
tabela que ser consultada. O que normalmente determina a filial que ser utilizada
como parte da chave justamente a informao que ser consultada, aonde:
Exemplos:
Exemplos:
Exemplos:
Na definio da regra de retorno deve ser considerado o tipo do campo que ser
atualizado, pois este campo que determina qual tipo do retorno ser considerado
vlido para o gatilho.
- 134 -
o GETMV()
o SUPERGETMV()
o GETNEWPAR()
GETMV()
SUPERGETMV()
GETNEWPAR()
PUTMV()
GETMV()
Sintaxe GETMV(cParametro)
Retorna o contedo do parmetro especificado no arquivo SX6, considerando
Descrio a filial parametrizada na conexo. Caso o parmetro no exista ser exibido
um help do sistema informando a ocorrncia.
- 135 -
PUTMV()
SUPERGETMV()
Desta forma, quaisquer alterao na base realizada por uma rotina configurada em um
parmetro pode ocasionar a perda da integridade das informaes do sistema.
- 136 -
Conceitos
Um ponto de entrada uma User Function desenvolvida com a finalidade de interagir com uma
rotina padro da aplicao ERP.
Premissas e Regras
Um ponto de entrada no deve ser utilizado para outras finalidades seno para as quais
o mesmo foi pr-definido, sob pena de causar a perda da integridade das informaes
da base de dados ou provocar eventos de erro durante a execuo da rotina padro.
Um ponto de entrada deve ser transparente para o processo padro, de forma que
todas as tabelas acessadas pelo ponto de entrada e que sejam utilizadas pela rotina
padro, devero ter sua situao imediatamente anterior execuo do ponto
restaurada ao trmino do mesmo, e para isto recomenda-se o uso das funes
GETAREA() e RESTAREA().
- 137 -
A linguagem ADVPL possui duas formas distintas para definio de interfaces visuais no
ambiente ERP: sintaxe convencional, nos padres da linguagem CLIPPER e a sintaxe orientada
a objetos.
Alm das diferentes sintaxes disponveis para definio das interfaces visuais o ERP Protheus
possui funcionalidades pr-definidas, as quais j contm todos os tratamentos necessrios a
atender as necessidades bsicas de acesso e manuteno das informaes do sistema.
Neste tpico sero abordadas as sintaxes convencionais para definio das interfaces visuais
da linguagem ADVPL e as interfaces de manuteno disponveis no ambiente ERP Protheus.
Para ilustrar a diferena na utilizao destes dois includes, segue abaixo as diferentes
definies para o componentes Dialog e MsDialog:
#include rwmake.ch
#include protheus.ch
DEFINE MSDIALOG oDlg TITLE "Janela em sintaxe ADVPL "FROM 000,000 TO 400,600 PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
- 138 -
MSDIALOG()
MSGET()
SAY()
BUTTON()
SBUTTON()
BUTTON()
MSDIALOG()
MSGET()
SAY()
SBUTTON()
- 139 -
Abaixo segue um cdigo completo de interface, utilizado todos os elementos da interface visual
descritos anteriormente:
@ 010,050 MSGET cCGC SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()
- 140 -
AxCadastro
Mbrowse
Ambos os modelos utilizam como premissa que a estrutura da tabela a ser utilizada esteja
definida no dicionrio de dados do sistema (SX3).
13.2.1. AxCadastro()
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Parmetros
Exemplo:
#include "protheus.ch"
dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)
Return
- 141 -
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Parmetros
nLin1, nCol1, Coordenadas dos cantos aonde o browse ser exibido. Para seguir o
nLin2, nCol2 padro da AXCADASTRO() use 6,1,22,75 .
Alias padro do sistema para utilizao, o qual deve estar definido no
cAlias
dicionrio de dados SX3.
- 142 -
AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
aRotina
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir" ,"AxInclui" ,0,3})
AADD(aRotina,{"Alterar" ,"AxAltera",0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta",0,5})
Exemplo:
#include "protheus.ch"
AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir" ,"AxInclui",0,3})
AADD(aRotina,{"Alterar" ,"AxAltera",0,4})
AADD(aRotina,{"Excluir" ,"AxDeleta",0,5})
dbSelectArea(cAlias)
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
- 143 -
1 Pesquisar
2 Visualizar
3 Incluir
4 Alterar
5 Excluir
6 Livre
- 144 -
#include "protheus.ch"
dbSelectArea(cAlias)
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
RETURN
- 145 -
AXPESQUI()
AXVISUAL()
AXINCLUI()
AXALTERA()
AXDELETA()
AXALTERA()
AXDELETA()
AXINCLUI()
AXPESQUI()
Sintaxe AXPESQUI()
Funo de pesquisa padro em registros exibidos pelos browses do sistema,
a qual posiciona o browse no registro pesquisado. Exibe uma tela que
Descrio
permite a seleo do ndice a ser utilizado na pesquisa e a digitao das
informaes que compe a chave de busca.
- 146 -
- 147 -
obrigatria a utilizao da identao, pois torna o cdigo muito mais legvel. Veja os
exemplos abaixo:
A utilizao da identao seguindo as estruturas de controle de fluxo (while, if, caso etc) torna
a compreenso do cdigo muito mais fcil:
Para identar o cdigo utilize a tecla <TAB> e na ferramenta DEV-Studio, a qual pode ser
configurada atravs da opo Preferncias:
- 148 -
dbSeek()
dbSelectArea()
- 149 -
Constantes:
#define NUMLINES 60 #define NUMPAGES 1000
Variveis de memria:
M-> CT2_CRCONV M->CT2_MCONVER := CriaVar("CT2_CONVER")
Campos:
SC6->C6_NUMPED
Querys:
SELECT * FROM...
- 150 -
- 151 -
- 152 -
- 153 -
- 154 -
Desenvolver uma rotina que capture vrios CNPJs de clientes informados pelo
usurio, e verifique para cada um deles se o mesmo existe ou no na base de
09
dados. Ao final informar quais CNPJs foram informados, e de acordo com a
seleo do usurio, exibir os dados principais de um destes clientes.
- 155 -
- 156 -
- 157 -
Colaboradores
- 158 -
CTOD()
Realiza a converso de uma informao do tipo caracter no formato DD/MM/AAAA para uma
varivel do tipo data.
Sintaxe: CTOD(cData)
Parmetros
Exemplo:
cData := 31/12/2006
dData := CTOD(cData)
CVALTOCHAR()
Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de
espaos a informao.
Sintaxe: CVALTOCHAR(nValor)
Parmetros
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
- 160 -
Guia de Referncia Rpida
ADVPL Bsico
DTOC()
Realiza a converso de uma informao do tipo data para em caracter, sendo o resultado no
formato DD/MM/AAAA.
Sintaxe: DTOC(dData)
Parmetros
Exemplo:
DTOS()
Sintaxe: DTOS(dData)
Parmetros
Exemplo:
STOD()
Sintaxe: STOD(sData)
Parmetros
Exemplo:
sData := LERSTR(01,08) // Funo que realiza a leitura de uma string de um txt previamente
// aberto
dData := STOD(sData)
- 161 -
Guia de Referncia Rpida
ADVPL Bsico
STR()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos
direita.
Sintaxe: STR(nValor)
Parmetros
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
STRZERO()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando zeros
esquerda do nmero convertido, de forma que a string gerada tenha o tamanho especificado
no parmetro.
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
- 162 -
Guia de Referncia Rpida
ADVPL Bsico
VAL()
Sintaxe: VAL(cValor)
Parmetros
Exemplo:
- 163 -
Guia de Referncia Rpida
ADVPL Bsico
Matemticas
ACOS()
Sintaxe: ACOS(nValor)
Parmetros:
Retorno:
CEILING()
Funo utilizada para calcular o valor mais prximo possvel de um valor nMax informado como
parmetro para a funo.
Sintaxe: CELLING(nMax)
Parmetros
Retorno:
Numrico
Valor do tipo double, representando o menor inteiro que maior ou igual ao
valor de nMax. No h retorno de erro na funo.
COS()
Sintaxe: COS(nAngulo)
Parmetros:
Retorno:
- 164 -
Guia de Referncia Rpida
ADVPL Bsico
Situaes invlidas:
LOG10()
Funo utilizada para calcular o logaritmo natural de um valor numrico, em base 10.
LOG10() uma funo numrica que calcula o logaritmo natural de um nmero. O logaritmo
natural tem como base o valor 10. Devido ao arredondamento matemtico, os valores
retornados por LOG() podem no coincidir exatamente.
Sintaxe: LOG10(nNatural)
Parmetros:
Retorno:
SIN()
Funo utilizada para calcular o valor do seno ou seno hiperblico. Devemos informar como
parmetro para a funo um valor que representa o angulo em radianos.
Sintaxe: SIN(nAngulo)
Parmetros:
Retorno:
Situaes invlidas:
- 165 -
Guia de Referncia Rpida
ADVPL Bsico
SQRT()
Sintaxe: SQRT(nValor)
Parmetros:
Retorno:
TAN()
Sintaxe: TAN(nAngulo)
Parmetros:
Retorno:
Situaes invlidas:
- 166 -
Guia de Referncia Rpida
ADVPL Bsico
Verificao de tipos de variveis
TYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.
Sintaxe: TYPE(cVariavel)
Parmetros
Exemplo:
IF TYPE(dDataBase) == D
MSGINFO(Database do sistema: +DTOC(dDataBase))
ELSE
MSGINFO(Varivel indefinida no momento)
ENDIF
VALTYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.
Sintaxe: VALTYPE(cVariavel)
Parmetros
Exemplo:
LOCAL cTexto :=
LOCAL nColF := 0
LOCAL nLargGet := 0
PRIVATE oDlg
cTexto := Space(nTamanho)
nLargGet := Round(nTamanho * 2.5,0)
nColf := Round(195 + (nLargGet * 1.75) ,0)
- 167 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo (continuao):
cTexto := IIF(nOpca==1,cTexto,"")
RETURN cTexto
Manipulao de arrays
ARRAY()
A funo Array() utilizada na definio de variveis de tipo array, como uma opo a sintaxe
utilizando chaves ({}).
Parmetros
Exemplo:
aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.
- 168 -
Guia de Referncia Rpida
ADVPL Bsico
AADD()
A funo AADD() permite a insero de um item em um array j existente, sendo que este
item podem ser um elemento simples, um objeto ou outro array.
Exemplo:
aDados := {} // Define que a varivel aDados um array, sem especificar suas dimenses.
aItem := {} // Define que a varivel aItem um array, sem especificar suas dimenses.
// Neste ponto o array a Item possui 03 elementos os quais podem ser acessados com:
// aItem[1] -> corresponde ao contedo de cVariavel1
// aItem[2] -> corresponde ao contedo de cVariavel2
// aItem[3] -> corresponde ao contedo de cVariavel3
Exemplo (continuao):
// Neste ponto, o array a aDados possui apenas um elemento, que tambm um array
// contendo 03 elementos:
// aDados [1][1] -> corresponde ao contedo de cVariavel1
// aDados [1][2] -> corresponde ao contedo de cVariavel2
// aDados [1][3] -> corresponde ao contedo de cVariavel3
AADD(aDados, aItem)
AADD(aDados, aItem)
// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros
// 03 elementos, sendo:
- 169 -
Guia de Referncia Rpida
ADVPL Bsico
// Desta forma, o array aDados montando com uma estrutura de 03 linhas e 03 colunas, com
// o contedo definido por variveis externas, mas com a mesma forma obtida com o uso do
// comando: aDados := ARRAY(3,3).
ACLONE()
A funo ACLONE() realiza a cpia dos elementos de um array para outro array integralmente.
Sintaxe: AADD(aArray)
Parmetros
aArray Array pr-existente que ter seu contedo copiado para o array especificado.
Exemplo:
// Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array
// aDados.
ADEL()
Exemplo:
- 170 -
Guia de Referncia Rpida
ADVPL Bsico
// aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito da excluso do item 1.
// aItens[3] -> contedo nulo, por se tratar do item excludo.
ASIZE()
nTamanho Tamanho com o qual deseja-se redefinir o array. Se o tamanho for menor do
que o atual, sero removidos os elementos do final do array, j se o
tamanho for maior do que o atual sero inseridos itens nulos ao final do
array.
Exemplo:
// Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo ADEL()
ASIZE(aItens,Len(aItens-1))
// Neste ponto o array aItens possui 02 elementos, ambos com contedos vlidos.
ASORT()
A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio
pr-estabelecido.
aArray Array pr-existente que ter seu contedo ordenado atravs de um critrio
estabelecido.
nInicio Posio inicial do array para incio da ordenao. Caso no seja informado, o
array ser ordenado a partir de seu primeiro elemento.
nItens Quantos itens, a partir da posio inicial devero ser ordenados. Caso no
seja informado, sero ordenados todos os elementos do array.
bOrdem Bloco de cdigo que permite a definio do critrio de ordenao do array.
Caso bOrdem no seja informado, ser utilizado o critrio ascendente.
- 171 -
Guia de Referncia Rpida
ADVPL Bsico
Um bloco de cdigo basicamente uma funo escrita em linha. Desta forma
sua estrutura deve suportar todos os requisitos de uma funo, os quais so
atravs da anlise e interpretao de parmetros recebidos, executar um
processamento e fornecer um retorno.
Com base nesse requisito, pode-se definir um bloco de cdigo com a estrutura
abaixo:
aSort(aAlunos)
// Durante a execuo da funo aSort(), a varivel x receber o contedo do item que est
// posicionado. Como o item que est posicionado a posio aAlunos[x] e aAlunos[x] ->
// string contendo o nome de um aluno, pode-se substituir x por cNomeAtu.
// A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma
// analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de cdigo
// bOrdem pode ser re-escrito como:
aSort(aAlunos,,bOrdem)
- 172 -
Guia de Referncia Rpida
ADVPL Bsico
ASCAN()
A funo ASCAN() permite que seja identificada a posio do array que contm uma
determinada informao, atravs da anlise de uma expresso descrita em um bloco de
cdigo.
Exemplo:
Sempre opte por analisar como o bloco de cdigo ser utilizado e ao invs de
x, y e similares, defina os parmetros com nomes que representem seu
contedo. Ser mais simples o seu entendimento e o entendimento de outros
que forem analisar o cdigo escrito.
- 173 -
Guia de Referncia Rpida
ADVPL Bsico
AINS()
Exemplo:
AINS(aAlunos,3)
- 174 -
Guia de Referncia Rpida
ADVPL Bsico
Manipulao de blocos de cdigo
EVAL()
Exemplo:
nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
DBEVAL()
A funo DBEval() permite que todos os registro de uma determinada tabela sejam analisados
e para cada registro ser executado o bloco de cdigo definido.
bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada registro do alias ativo.
bFor Condio para continuao da anlise dos registros, com o efeito de uma
estrutura For ... Next.
bWhile Condio para continuao da anlise dos registros, com o efeito de uma
estrutura While ... End
- 175 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo 01
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
nCnt++
dbSkip()
End
Exemplo 02
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
Exemplo 02 (continuao):
- 176 -
Guia de Referncia Rpida
ADVPL Bsico
AEVAL()
A funo AEVAL() permite que todos os elementos de um determinada array sejam analisados
e para cada elemento ser executado o bloco de cdigo definido.
bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada elemento do array informado.
Exemplo 01:
AADD(aCampos,A1_FILIAL)
AADD(aCampos,A1_COD)
SX3->(dbSetOrder(2))
For nX:=1 To Len(aCampos)
SX3->(dbSeek(aCampos[nX]))
AADD(aTitulos,AllTrim(SX3->X3_TITULO))
Next nX
- 177 -
Guia de Referncia Rpida
ADVPL Bsico
Manipulao de strings
ALLTRIM()
Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado
como parmetro.
A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left
trim).
Sintaxe: ALLTRIM(cString)
Parmetros
cString String que ser avaliada para remoo dos espaos a direita e a esquerda.
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
ASC()
Converte uma informao caractere em seu valor de acordo com a tabela ASCII.
Sintaxe: ASC(cCaractere)
Parmetros
Exemplo:
- 178 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo (continuao):
EndCase
cRet := cRet+cLetra
Next
Return UPPER(cRet)
AT()
Exemplo:
STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)
RETURN cNoMascara
- 179 -
Guia de Referncia Rpida
ADVPL Bsico
BITON()
Funo utilizada para ligar determinados bits de uma String passada por parametro para a
funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico
que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem
alterados(ligados) e o tamanho da string passada.
Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )
Parmetros
CHR()
Converte um valor nmero referente a uma informao da tabela ASCII no caractere que esta
informao representa.
Sintaxe: CHR(nASCII)
Parmetros
Exemplo:
DESCEND()
Retorno:
- 180 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo:
// Este exemplo utiliza DESCEND() em uma expresso INDEX para criar um ndice de datas de
// ordem descendente:
// Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice
// descendente:
DbSEEK(DESCEND(DTOS(dFindDate)))
GETDTOVAL()
Funo utilizada para retornar um numero formatado, de acordo com o valor passado por
parmetro, sendo que ir apenas manter os valores numricos contidos na string passada por
parmetro, verificando se existe algum caractere '.' retornando um numero fracionrio, na
ordem dos nmeros contidos na string.
A funo muito til quando desejamos utilizar o valor numrico de uma data que est
contida em uma string.
Parmetros:
cDtoVal Representa uma string contendo um valor numrico no qual ser convertido.
Retorno:
Exemplo:
- 181 -
Guia de Referncia Rpida
ADVPL Bsico
ISALPHA()
Parmetros:
Retorno:
ISDIGIT()
Parmetros:
Retorno:
Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um digto
entre zero e nove; caso contrrio, retorna falso (.F.).
ISLOWER()
Funo utilizada para determinar se o caractere mais esquerda uma letra minscula,
permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio
de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula.
ISLOWER() e ISUPPER() ambas sao relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.
Parmetros:
Retorno:
Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo ,
caso contrrio, retorna falso (.F.).
- 182 -
Guia de Referncia Rpida
ADVPL Bsico
ISUPPER()
Funo utilizada para determinar se o caractere mais esquerda uma letra maicula,
permitindo avaliar se o primeiro caractere de um string uma letra maicula. o contrrio de
ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula.
ISLOWER() e ISUPPER() ambas sao relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.
Parmetros:
Retorno:
Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo ,
caso contrrio, retorna falso (.F.).
LEN()
Sintaxe: LEN(cString)
Parmetros
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
- 183 -
Guia de Referncia Rpida
ADVPL Bsico
LOWER()
Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.
Sintaxe: LOWER(cString)
Parmetros
Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
LTRIM()
Funo para 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().
Retorno:
Caracter 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 ("").
- 184 -
Guia de Referncia Rpida
ADVPL Bsico
MATHC()
Funo utilizada para realizar operaes matemticas com strings que contm um valor
numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao, Diviso,
Multiplicao e Exponenciao.
A funo ir retornar uma string contendo o resultado da operao matemtica, com uma
especificao de at 18 casas de preciso no numero.
Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )
Parmetros:
Retorno:
OEMTOANSI()
Funo que transforma uma string no Formato OEM / MS-DOS Text para uma string ANSI
Text ( formato do Windows ).
Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de dados , os
acentos e caracteres especiais so gravados como texto OEM . Para tornar possvel a correta
visualizao destes dados em uma interface Windows , utilizamos a funo OemToAnsi() para
realizar a converso.
Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados , o texto
capturado no formato ANSI Text . Caso este texto seja utilizado para alimentar uma base de
dados a ser acessada atravs de um programa MS-DOS , devemos converter o dado para OEM
antes de grav-lo , atravs da funo AnsiToOem().
Retorno:
- 185 -
Guia de Referncia Rpida
ADVPL Bsico
PADL() / PADR() / PADC()
PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e
esquerda.
PADL() adiciona caracteres de preenchimento esquerda.
PADR() adiciona caracteres de preenchimento direita.
PADC(), PADL(), e PADR() so utilizadas para exibir cadeias de caracteres de tamanho varivel
em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para assegurar o
alinhamento com comandos ?? consecutivos. Outra utilizao exibir textos em uma tela de
tamanho fixo, para certificar-se de que o texto anterior foi completamente sobrescrito.
Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench ] )
Parmetros
Retorno:
RAT()
- 186 -
Guia de Referncia Rpida
ADVPL Bsico
RTRIM()
Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
contenham espaos em branco direita. Ela til quando voc deseja eliminar espaos em
branco direita ao se concatenar cadeias de caracteres. o caso tpico com campos de banco
de dados que so armazenados em formato de tamanho fixo. Por exemplo, voc pode usar
RTRIM() para concatenar o primeiro e o ltimo campos de nome para formar uma cadeia de
caracteres de nome.
Parmetros:
Retorno:
Caracter RTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
direita foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou totalmente composta por espaos, RTRIM() retorna uma cadeia
de caracteres nula ("").
SPACE()
Parmetros:
Retorno:
- 187 -
Guia de Referncia Rpida
ADVPL Bsico
STRTOKARR()
Funo utilizada para retornar um array, de acordo com os dados passados como parmetro
para a funo. Esta funo recebe uma string <cValue> e um caracter <cToken> que
representa um separador, e para toda ocorrncia deste separador em <cValue> adicionado
um item no array.
Parmetros:
Retorno:
Exemplo:
STRTRAN()
Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.
Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [
nCount ] )
Parmetros:
Retorno:
- 188 -
Guia de Referncia Rpida
ADVPL Bsico
STUFF()
Parmetros:
Retorno:
Exemplo:
SUBSTR()
Retorna parte do contedo de uma string especificada, de acordo com a posio inicial deste
contedo na string e a quantidade de caracteres que dever ser retornada a partir daquele
ponto (inclusive).
Exemplo:
cCampo := A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_
- 189 -
Guia de Referncia Rpida
ADVPL Bsico
TRANSFORM()
Funo de converso que formata valores caractere, data, lgicos e numricos conforme um
string de mscara especificado, a qual inclui uma combinao de strings de template e funes
de picture. Ela faz o mesmo que a clusula PICTURE do comando @...SAY, sendo normalmente
utilizada para formatar dados a serem enviados tela ou impressora.
Parmetros:
cExp O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
cSayPicture Uma string de caracteres de mscara e template usado para descrever o
formato da cadeia de caracteres a ser retornada.
Retorno:
UPPER()
Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.
Sintaxe: UPPER(cString)
Parmetros
Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
- 190 -
Guia de Referncia Rpida
ADVPL Bsico
Manipulao de data / hora
CDOW()
Retorno:
cDayWeek Nome do dia da semana como uma cadeia de caracteres. A primeira letra
maiscula e as demais minsculas.
Exemplo:
CMONTH()
Funo de converso de datas que retorna uma cadeia de caracteres com o nome do ms em
ingls.
Retorno:
Exemplo:
- 191 -
Guia de Referncia Rpida
ADVPL Bsico
DATE()
Funo que retorna a data do atual sistema. O formato de sada controlado pelo comando
SET DATE, sendo que o formato padro mm/dd/yy.
Sintaxe: DATE()
Parmetros:
Nenhum .
Retorno:
Exemplo:
DAY()
Funo de converso de datas usada para converter o valor data em um nmero inteiro que
representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR()
para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas.
Retorno:
Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
dData := DATE() // Resultado: 09/01/01
nDia := DAY(DATE()) // Resultado: 1
nDia := DAY(DATE()) + 1 // Resultado: 2
nDia := DAY(CTOD("12/01/94")) // Resultado: 1
// Este exemplo mostra a funo DAY() usada em conjunto com CMONTH() e
YEAR() para formatar o valor da data:
dData := Date()
cData := CMONTH(dData) + STR(DAY(dData)) + "," + STR(YEAR(dData)) // Resultado: June
15, 2001
- 192 -
Guia de Referncia Rpida
ADVPL Bsico
DOW()
Funo que converte uma data para o valor numrico que representa o dia da semana. til
quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o dia da
semana como uma cadeia de caracteres.
Retorno:
Exemplo:
DTOC()
Funo para converso de uma data para uma cadeia de caracteres formatada segundo o
padro corrente, definido pelo comando SET DATE. Se for necessria a utilizao de
formatao especial, use a funo TRANSFORM().
Em expresses de ndices de arquivo, use DTOS() no lugar de DTOC() para converter datas
para cadeia de caracteres.
Retorno:
Exemplo:
- 193 -
Guia de Referncia Rpida
ADVPL Bsico
DTOS()
Funo para converso de uma data que pode ser usada para criar expresses de ndice. O
resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia).
Retorno:
sData Retorna uma cadeia de caracteres com oito byte de tamanho no formato
yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia
de caracteres com oito espaos. O valor retornado no afetado pela
formato da data corrente.
Exemplo:
ELAPTIME()
Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no formato
hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.
Retorno:
Exemplo:
- 194 -
Guia de Referncia Rpida
ADVPL Bsico
MONTH()
Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que
retorna o nome do ms a partir do valor de dData.
Retorno:
Exemplo:
SECONDS()
Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a hora do
sistema. Est relacionada funo TIME() que retorna a hora do sistema como uma cadeia de
caracteres no formato hh:mm:ss.
Sintaxe: SECONDS()
Parmetros:
Nenhum .
Retorno:
Exemplo:
- 195 -
Guia de Referncia Rpida
ADVPL Bsico
TIME()
Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada
com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a
meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos.
Sintaxe: TIME()
Parmetros:
Nenhum .
Retorno:
Exemplo:
YEAR()
YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR()
membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui
DAY() e MONTH() que retornam o dia e o ms como valores numricos.
Retorno:
Exemplo 01:
- 196 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo 02:
// Este exemplo cria uma funo de usurio que usa a funo YEAR() para formatar o valor da
// data:
ABS()
Sintaxe: ABS(nValor)
Parmetros
Exemplo:
nPessoas := 20
nLugares := 18
INT()
Sintaxe: INT(nValor)
Parmetros
Exemplo:
- 197 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo (continuao):
RETURN nQuantidade
NOROUND()
Exemplo:
nBase := 2.985
nValor := NOROUND(nBase,2) 2.98
ROUND()
Exemplo:
nBase := 2.985
nValor := ROUND(nBase,2) 2.99
- 198 -
Guia de Referncia Rpida
ADVPL Bsico
Manipulao de arquivos
SELECT()
Sintaxe: Select(cArea)
Parmetros
Exemplo:
nArea := Select(SA1)
DBGOTO()
Move o cursor da rea de trabalho ativa para o record number (recno) especificado, realizando
um posicionamento direto, sem a necessidade uma busca (seek) prvio.
Sintaxe: DbGoto(nRecno)
Parmetros
Exemplo:
DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro 100
- 199 -
Guia de Referncia Rpida
ADVPL Bsico
DBGOTOP()
Sintaxe: DbGoTop()
Parmetros
Nenhum .
Exemplo:
DBGOBOTTON()
Sintaxe: DbGoBotton()
Parmetros
Nenhum .
Exemplo:
- 200 -
Guia de Referncia Rpida
ADVPL Bsico
DBSELECTAREA()
Define a rea de trabalho especificada com sendo a rea ativa. Todas as operaes
subseqentes que fizerem referncia a uma rea de trabalho a utilizao, a menos que a rea
desejada seja informada explicitamente.
DBSETORDER()
Define qual ndice ser utilizada pela rea de trabalho ativa, ou seja, pela rea previamente
selecionada atravs do comando DbSelectArea(). As ordens disponveis no ambiente Protheus
so aquelas definidas no SINDEX /SIX, ou as ordens disponibilizadas por meio de ndices
temporrios.
Sintaxe: DbSetOrder(nOrdem)
Parmetros
Nmero de referncia da ordem que deseja ser definida como ordem ativa
nOrdem
para a rea de trabalho.
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // De acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
- 201 -
Guia de Referncia Rpida
ADVPL Bsico
DBORDERNICKNAME()
Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os seus prprios
ndices e no momento da incluso deve criar o NICKNAME para o mesmo.
Sintaxe: DbOrderNickName(NickName)
Parmetros
Exemplo:
DbSelectArea(SA1)
DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO
NickName: Tipo
DBSEEK() E MSSEEK()
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
Else
MsgAlert(Cliente no encontrado, Consulta por cliente)
Endif
- 202 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo 02 Busca aproximada
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DBSKIP()
Move o cursor do registro posicionado para o prximo (ou anterior dependendo do parmetro),
em funo da ordem ativa para a rea de trabalho.
Sintaxe: DbSkip(nRegistros)
Parmetros
DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGotop() // Posiciona o cursor no incio da rea de trabalho ativa
While !EOF() // Enquanto o cursor da rea de trabalho ativa no indicar fim de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip()
End
- 203 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo 02 Retrocedendo registros
DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGoBotton() // Posiciona o cursor no final da rea de trabalho ativa
While !BOF() // Enquanto o cursor da rea de trabalho ativa no indicar incio de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip(-1)
End
DBSETFILTER()
Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de um bloco
de cdigo ou atravs de uma expresso simples.
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
- 204 -
Guia de Referncia Rpida
ADVPL Bsico
DBSTRUCT()
Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura ser um
array bidimensional conforme abaixo:
*ndice do array
Sintaxe: DbStruct()
Parmetros
Nenhum .
Exemplo:
cCampos :=
DbSelectArea(SA1)
aStructSA1 := DbStruct()
FOR nX := 1 to Len(aStructSA1)
cCampos += aStructSA1[nX][1] + /
NEXT nX
ALERT(cCampos)
RECLOCK()
Sintaxe: RecLock(cAlias,lInclui)
Parmetros
Exemplo 01 - Incluso
DbSelectArea(SA1)
RecLock(SA1,.T.)
SA1->A1_FILIAL := xFilial(SA1) // Retorna a filial de acordo com as configuraes do ERP
SA1->A1_COD := 900001
SA1->A1_LOJA := 01
MsUnLock() // Confirma e finaliza a operao
- 205 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo 02 - Alterao
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
RLOCK()
DBRLOCK()
MSUNLOCK()
Sintaxe: MsUnLock()
Parmetros
Nenhum .
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
- 206 -
Guia de Referncia Rpida
ADVPL Bsico
A linguagem ADVPL possui variaes da funo MsUnlock(), as quais so:
UNLOCK()
DBUNLOCK()
DBUNLOCKALL()
SOFTLOCK()
Permite a reserva do registro posicionado na rea de trabalho ativa de forma que outras
operaes, com exceo da atual, no possam atualizar este registro. Difere da funo
RecLock() pois no gera uma obrigao de atualizao, e pode ser sucedido por ele.
Sintaxe: SoftLock(cAlias)
Parmetros
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(cChave)
IF Found()
SoftLock() // Reserva o registro localizado
lConfirma := AlteraSA1() // Funo ilustrativa que exibe os dados do registro
// posicionado e pemite a alterao dos mesmos.
IF lConfirma
RecLock(SA1,.F.)
GravaSA1() // Funo ilustrativa que altera os dados conforme a AlertaSA1()
MsUnLock() // Liberado o RecLock() e o SoftLock() do registro.
Endif
Endif
- 207 -
Guia de Referncia Rpida
ADVPL Bsico
DBDELETE()
Efetua a excluso lgica do registro posicionado na rea de trabalho ativa, sendo necessria
sua utilizao em conjunto com as funes RecLock() e MsUnLock().
Sintaxe: DbDelete()
Parmetros
Nenhum .
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found()
RecLock(SA1,.F.) // Define que ser realizada uma alterao no registro posicionado
DbDelete() // Efetua a excluso lgica do registro posicionado.
MsUnLock() // Confirma e finaliza a operao
ENDIF
DBUSEAREA()
Define um arquivo de base de dados como uma rea de trabalho disponvel na aplicao.
Parmetros
Exemplo:
- 208 -
Guia de Referncia Rpida
ADVPL Bsico
DBCLOSEAREA()
Permite que um alias presente na conexo seja fechado, o que viabiliza seu reuso em outro
operao. Este comando tem efeito apenas no alias ativo na conexo, sendo necessria sua
utilizao em conjunto com o comando DbSelectArea().
Sintaxe: DbCloseArea()
Parmetros
Nenhum .
Exemplo:
GETSXENUM()
CONFIRMSXE()
Sintaxe: CONFIRMSXE(lVerifica)
Parmetros
- 209 -
Guia de Referncia Rpida
ADVPL Bsico
ROLLBACKSXE()
Sintaxe: ROLLBACKSXE()
Parmetros
Nenhum .
Validao
EXISTCHAV()
Retorna .T. ou .F. se o contedo especificado existe no alias especificado. Caso exista ser
exibido um help de sistema com um aviso informando da ocorrncia.
EXISTCPO()
Retorna .T. ou .F. se o contedo especificado no existe no alias especificado. Caso no exista
ser exibido um help de sistema com um aviso informando da ocorrncia.
- 210 -
Guia de Referncia Rpida
ADVPL Bsico
NAOVAZIO()
Sintaxe: NaoVazio()
Parmetros
Nenhum .
NEGATIVO()
Sintaxe: Negativo()
Parmetros
Nenhum .
PERTENCE()
Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida como
parmetro da funo. Normalmente utilizada em campos com a opo de combo, pois caso
contrrio seria utilizada a funo ExistCpo().
Sintaxe: Pertence(cString)
Parmetros
POSITIVO()
Sintaxe: Positivo()
Parmetros
Nenhum .
TEXTO()
Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou
alfanumricos.
Sintaxe: Texto()
Parmetros
Nenhum .
- 211 -
Guia de Referncia Rpida
ADVPL Bsico
VAZIO()
Sintaxe: Vazio()
Parmetros
Nenhum .
Parmetros
GETMV()
Sintaxe: GETMV(cParametro)
Parmetros
GETNEWPAR()
Difere do SuperGetMV() pois considera que o parmetro pode no existir na verso atual do
sistema, e por conseqncia no ser exibida a mensagem de help.
cPadrao Contedo padro que ser utilizado caso o parmetro no exista no SX6.
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
cFilial
corrente da conexo.
- 212 -
Guia de Referncia Rpida
ADVPL Bsico
PUTMV()
SUPERGETMV()
cPadrao Contedo padro que ser utilizado caso o parmetro no exista no SX6.
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
cFilial
corrente da conexo.
- 213 -
Guia de Referncia Rpida
ADVPL Bsico
Componentes da interface visual
MSDIALOG()
Define o componente MSDIALOG(), o qual utilizado como base para os demais componentes
da interface visual, pois um componente MSDIALOG() uma janela da aplicao.
Sintaxe:
Parmetros
oObjetoDLG Posio do objeto Say em funo da janela em que ele ser definido.
Exemplo:
- 214 -
Guia de Referncia Rpida
ADVPL Bsico
MSGET()
Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis
na tela da interface.
Sintaxe:
Parmetros
cF3 String que define a consulta padro que ser vinculada ao campo.
Exemplo:
@ 010,050 MSGET cCGC SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()
- 215 -
Guia de Referncia Rpida
ADVPL Bsico
SAY()
Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de
interface.
Sintaxe:
Parmetros
nLinha, nColuna Posio do objeto Say em funo da janela em que ele ser definido.
Exemplo:
BUTTON()
Define o componente visual Button, o qual permite a incluso de botes de operao na tela
da interface, os quais sero visualizados somente com um texto simples para sua identificao.
Sintaxe: BUTTON()
Parmetros
- 216 -
Guia de Referncia Rpida
ADVPL Bsico
Exemplo:
SBUTTON()
Define o componente visual SButton, o qual permite a incluso de botes de operao na tela
da interface, os quais sero visualizados dependendo da interface do sistema ERP utilizada
somente com um texto simples para sua identificao, ou com uma imagem (BitMap) pr-
definido.
Sintaxe: SBUTTON()
Parmetros
Exemplo:
DEFINE SBUTTON FROM 020, 120 TYPE 2 ACTION (nOpca := 2,oDlg:End());
ENABLE OF oDlg
- 217 -
Guia de Referncia Rpida
ADVPL Bsico
Interfaces de cadastro
AXCADASTRO()
MBROWSE()
AXPESQUI()
Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o
browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado
na pesquisa e a digitao das informaes que compe a chave de busca.
Sintaxe: AXPESQUI()
Parmetros
Nenhum .
- 218 -
Guia de Referncia Rpida
ADVPL Bsico
AXVISUAL()
Parmetros
AXINCLUI()
Parmetros
- 219 -
Guia de Referncia Rpida
ADVPL Bsico
Funo de validao de confirmao da tela. No deve ser passada
como Bloco de Cdigo, mas pode ser passada como uma lista de
expresses, desde que a ltima ao efetue um retorno lgico:
cTudoOk
(Func1(), Func2(), ...,FuncX(), .T. )
AXALTERA()
Parmetros
- 220 -
Guia de Referncia Rpida
ADVPL Bsico
AXDELETA()
Parmetros
aCpos Vetor com nome dos campos que podero ser editados
Botes adicionais para a EnchoiceBar, no formato:
aArray[n][1] -> Imagem do boto
aButtons
aArray[n][2] -> bloco de cdigo contendo a ao do boto
aArray[n][3] -> ttulo do boto
Funes para execuo em pontos pr-definidos da AxFunction(),
conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da exibio
da interface.
aParam[2] := Bloco de cdigo para processamento na validao da
aParam
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao
da AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da transao da
AxFunction().
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser
executada a funo EnchAuto().
aAuto aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as
validaes do SX3
lMaximized Indica se a janela dever ser ou no maximizada
- 221 -
Guia de Referncia Rpida
ADVPL Bsico
Funes visuais para aplicaes
ALERT()
Sintaxe: AVISO(cTexto)
Parmetros
AVISO()
Parmetros
- 222 -
Guia de Referncia Rpida
ADVPL Bsico
FORMBACTH()
- 223 -
Guia de Referncia Rpida
ADVPL Bsico
MSGFUNCTIONS()
Parmetros
MSGALERT
MSGINFO
MSGSTOP
MSGYESNO
- 224 -
Guia de Referncia Rpida
ADVPL Bsico
Funes ADVPL para aplicaes
GETAREA()
Sintaxe: GETAREA()
Retorno: Array contendo {Alias(),IndexOrd(),Recno()}
Parmetros
Nenhum .
RESTAREA()
Funo utilizada para devolver a situao do ambiente salva atravs do comando GETAREA().
Deve-se observar que a ltima rea restaurada a rea que ficar ativa para a aplicao.
Sintaxe: RESTAREA(aArea)
Parmetros
Exemplo:
LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.
cVar := &(ReadVar())
dbSelectArea("SX5")
IF !dbSeek(xFilial()+"Z1"+cVar)
ENDIF
RestArea(aArea)
Return( lRet )
- 225 -
Guia de Referncia Rpida
ADVPL Bsico