Apostila Advpl1 p10

ADVPL 1
Todos os direitos reservados.
0800 709 8100

totvs.com
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 ...................................................................9
1.2.1. Estudando algoritmos ................................................................................................................................10

1.2.2. Teste de mesa..............................................................................................................................................13
2.
ESTRUTURAS DE PROGRAMAO...........................................................15
2.1.
Diagrama de bloco .............................................................................15
2.2.
Estruturas de deciso e repetio........................................................20
2.2.1. Estruturas de deciso .................................................................................................................................20

2.2.2. Estruturas de repetio ..............................................................................................................................25
MDULO 02: A LINGUAGEM ADVPL ...............................................................29

3.
3.1.
4.
ESTRUTURA DE UM PROGRAMA ADVPL.................................................32

reas de um Programa ADVPL............................................................36
DECLARAO E ATRIBUIO DE VARIVEIS ..........................................42
4.1.
Tipo de Dados ....................................................................................42
4.2.
Declarao de variveis.......................................................................44
4.3.
Escopo de variveis.............................................................................46
4.4.
Entendendo a influncia do escopo das variveis................................55
4.5.
Operaes com Variveis ....................................................................57
4.5.1. Atribuio de variveis ...............................................................................................................................57

4.5.2. Operadores da linguagem ADVPL............................................................................................................59
4.5.3. Operao de Macro Substituio .............................................................................................................69
4.5.4. Funes de manipulao de variveis......................................................................................................71
5.
5.1.
ESTRUTURAS BSICAS DE PROGRAMAO ...........................................80

Estruturas de repetio .......................................................................80
5.1.1. Influenciando o fluxo de repetio...........................................................................................................85
5.2.
Pgina 2
Estruturas de deciso ..........................................................................87
ADVPL 1
6.
ARRAYS E BLOCOS DE CDIGO ...............................................................96

Arrays .................................................................................................96
6.1.
6.1.1.
6.1.2.
6.1.3.
Inicializando arrays ..................................................................................................................... 100

Funes de manipulao de arrays .......................................................................................... 103
Cpia de arrays ........................................................................................................................... 106
Listas de Expresses e Blocos de Cdigo .......................................... 110
6.2.
6.2.1.
6.2.2.
6.2.3.
6.2.4.
7.
8.
Premissas para utilizao de Blocos de Cdigo ..................................................................... 110

Lista de expresses..................................................................................................................... 112
Blocos de Cdigo........................................................................................................................ 116
Funes para manipulao de blocos de cdigo................................................................... 119
FUNES................................................................................................. 121
7.1.
Tipos e escopos de funes .............................................................. 123
7.2.
Passagem de parmetros entre funes............................................ 128
DIRETIVAS DE COMPILAO ................................................................. 138
MDULO 03: DESENVOLVENDO PEQUENAS CUSTOMIZAES.................. 151

9.
ADVPL E O ERP MICROSIGA PROTHEUS ............................................... 151

9.1.
O Ambiente Protheus ....................................................................... 152
9.2.
Organizao e configurao inicial do ambiente Protheus ................ 157
9.3.
O Configurador do Protheus............................................................. 166
9.3.1.
9.3.2.
9.3.3.
Funcionalidades Abordadas ...................................................................................................... 166

Estruturas bsicas da aplicao ERP Protheus ........................................................................ 166
Acessando o mdulo Configurador ......................................................................................... 174
Funcionalidades do Configurador ..................................................... 176
9.4.
9.4.1.
9.4.2.
9.4.3.
9.4.4.
9.4.5.
9.4.6.
9.4.7.
Dicionrio de Dados da aplicao ERP .................................................................................... 178

Adio de tabelas ao Dicionrio de Dados ............................................................................. 179
Adio de campos s tabelas do Dicionrio de Dados ......................................................... 183
Adio de ndices para as tabelas do Dicionrio de Dados .................................................. 190
Adio de gatilhos para os campos das tabelas do Sistema ................................................ 195
Criao de Tabelas Genricas ................................................................................................... 199
Criao de Parmetros............................................................................................................... 201
10. TOTVS DEVELOPMENT STUDIO ............................................................. 203

DESENVOLVIMENTO DE PEQUENAS CUSTOMIZAES ................................ 207
11. ACESSO E MANIPULAO DE BASES DE DADOS EM ADVPL ............... 207
11.1.
Diferenas e compatibilizaes entre bases de dados ....................... 209

11.2.
Funes de acesso e manipulao de dados .................................... 211
Ttulo ADVPL 1
Pgina 3
11.3.
Diferenciao entre variveis e os nomes de campos........................ 219
11.4.
Controle de numerao sequencial................................................... 221
12. CUSTOMIZAES PARA A APLICAO ERP ......................................... 223

12.1.
Customizao de campos Dicionrio de Dados .............................. 223
12.1.1.
12.1.2.
Validaes de campos e perguntas..................................................................................... 224

Pictures de formao disponveis ........................................................................................ 227
12.2.
Customizao de gatilhos Configurador......................................... 231
12.3.
Customizao de parmetros Configurador ................................... 232
12.3.1.
12.3.2.
12.4.
Funes para a manipulao de parmetros ..................................................................... 233

Cuidados na utilizao de um parmetro........................................................................... 235
Pontos de Entrada Conceitos, Premissas e Regras .......................... 236
13. INTERFACES VISUAIS ............................................................................. 238

13.1.
Sintaxe e componentes das interfaces visuais ................................... 238
13.2.
Interfaces padres para atualizaes de dados ................................. 242
13.2.1.
13.2.2.
13.2.3.
AxCadastro() ........................................................................................................................... 242

MBrowse() ............................................................................................................................... 244
AxFunctions() .......................................................................................................................... 250
APNDICES ..................................................................................................... 254

BOAS PRTICAS DE PROGRAMAO ........................................................... 254
14. UTILIZAO DE IDENTAO ................................................................ 254
15. CAPITULAO DE PALAVRAS-CHAVE................................................... 256
15.1.
Palavras em maisculo...................................................................... 257
16. UTILIZAO DA NOTAO HNGARA................................................. 257

17. PALAVRAS RESERVADAS ....................................................................... 259
GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL ..................... 261
Converso entre tipos de dados ................................................................... 261
Verificao de tipos de variveis ................................................................... 267
Manipulao de arrays.................................................................................. 270
Manipulao de blocos de cdigo ................................................................ 282
Manipulao de strings ................................................................................ 287
Pgina 4
ADVPL 1
Manipulao de variveis numricas............................................................. 294

Manipulao de arquivos.............................................................................. 299
Controle de numerao sequencial............................................................... 319
Validao...................................................................................................... 320
Parmetros ................................................................................................... 323
Componentes da interface visual .................................................................. 327
Interfaces de cadastro .................................................................................. 333
Funes visuais para aplicaes .................................................................... 340
Funes ADVPL para aplicaes.................................................................... 345
REFERNCIAS BIBLIOGRFICAS .................................................................... 347
Ttulo ADVPL 1
Pgina 5
OBJETIVOS DO CURSO
Objetivos especficos do curso:
Ao final do curso o treinando dever ter desenvolvido os seguintes conceitos, habilidades e
atitudes:
a) Conceitos a serem aprendidos

Fundamentos e tcnicas de programao;

Princpios bsicos da linguagem ADVPL;
Comandos e funes especficas da Microsiga.
b) Habilidades e tcnicas a serem aprendidas

Resoluo de algoritmos atravs de sintaxes orientadas a linguagem ADVPL;

Anlise de fontes de baixa complexidade da aplicao ERP Protheus;
Desenvolvimento de pequenas customizaes para o ERP Protheus.
c) Atitudes a serem desenvolvidas

Pgina 6
Adquirir conhecimentos atravs da anlise das funcionalidades disponveis no

ERP Protheus;
Embasar a realizao de outros cursos relativos linguagem ADVPL.
ADVPL 1
MDULO 01: INTRODUO PROGRAMAO

1. LGICA DE PROGRAMAO E ALGORITMOS
No aprendizado de qualquer linguagem de programao essencial desenvolver os
conceitos relacionados lgica e tcnica da escrita de um programa.
Com foco nesta necessidade, este tpico descrever resumidamente os conceitos envolvidos
no processo de desenvolvimento de um programa, atravs dos conceitos relacionados a:
Lgica de programao
Algoritmos
Diagramas de blocos
1.1. Lgica de Programao
Lgica
A lgica de programao necessria para pessoas que desejam trabalhar com

desenvolvimento de sistemas e programas. Ela permite definir a sequncia lgica para o
desenvolvimento. Ento o que lgica?
Lgica de programao a tcnica de encadear pensamentos para atingir determinado

objetivo.
Sequncia Lgica
Estes pensamentos podem ser descritos como uma sequncia de instrues, que devem ser
seguidas para que seja cumprida determinada tarefa.
Ttulo ADVPL 1
Pgina 7
Sequncia Lgica so passos executados at atingir um objetivo, ou soluo de um

problema.
Instrues
Na linguagem comum entende-se por instrues como um conjunto de regras, ou normas

definidas para a realizao, ou emprego de algo. Em informtica, porm, instruo a
informao que indica a um computador uma ao elementar a executar. Convm ressaltar
que uma ordem isolada no permite realizar o processo completo, para isso necessrio um
conjunto de instrues colocadas em ordem seqencial lgica.
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 devem ser executadas em uma ordem adequada no se podem
descascar as batatas depois de frit-las.
Dessa maneira, uma instruo tomada isoladamente no tem muito sentido para obtermos o
resultado. Precisamos colocar em prtica o conjunto de todas as instrues, e na ordem
correta.
Instrues um conjunto de regras, ou normas definidas para a realizao ou emprego

de algo. Em informtica, o que indica a um computador uma ao elementar a
executar.
Algoritmo
Um algoritmo formalmente uma sequncia finita de passos que levam execuo de uma
tarefa. Podemos pensar em algoritmo como uma receita, uma sequncia 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 possvel citar os algoritmos das operaes bsicas (adio,
multiplicao, diviso e subtrao) de nmeros reais decimais. Outros exemplos seriam os
Pgina 8
ADVPL 1
manuais de aparelhos eletrnicos que explicam passo-a-passo como, por exemplo, gravar um
evento.
At mesmo as coisas mais simples podem ser descritas por sequncias lgicas, tais como:
Chupar uma bala

1. Pegar a bala;
2. Retirar o papel;
3. Chupar a bala;
4. Jogar o papel no lixo.
Somar dois nmeros quaisquer
1. Escreva o primeiro nmero no retngulo A;

2. Escreva o segundo nmero no retngulo B;
3. Some o nmero do retngulo A com nmero do retngulo B e coloque o
resultado no retngulo C.
1.2. Desenvolvendo algoritmos

Pseudocdigo
Os algoritmos so descritos em uma linguagem chamada pseudocdigo. Este nome uma

aluso posterior implementao em uma linguagem de programao, ou seja, quando for
utilizada a linguagem de programao propriamente dita como, por exemplo, ADVPL.
Por isso os algoritmos so independentes das linguagens de programao, sendo que ao

contrrio de uma linguagem de programao, no existe um formalismo rgido de como deve
ser escrito o algoritmo.
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.
Ttulo ADVPL 1
Pgina 9
Regras para a construo do Algoritmo
Para escrever um algoritmo precisamos descrever a sequncia de instrues, de maneira

simples e objetiva. Para isso utilizaremos algumas tcnicas:
1. Usar somente um verbo por frase;

2. Imaginar que voc est desenvolvendo um algoritmo para pessoas que no trabalham
com Informtica;
3. Usar frases curtas e simples;
4. Ser objetivo;
5. Procurar usar palavras que no tenham duplo sentido.
Fases
Para implementar um algoritmo de simples interpretao e codificao necessrio

inicialmente dividir o problema apresentado em trs fases fundamentais:
ENTRADA: so os dados de entrada do algoritmo;

PROCESSAMENTO: so os procedimentos utilizados para chegar ao resultado final;
SADA: so os dados j processados.
11..22..11..
EEssttuuddaannddoo aallggoorriittm
mooss
Neste tpico sero demonstrados alguns algoritmos do cotidiano que foram implementados
utilizando os princpios descritos nos tpicos anteriores.

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
Pgina 10
ADVPL 1
Mascar um chiclete
1.
2.
3.
4.
Pegar o chiclete.
Retirar o papel.
Mastigar.
Jogar o papel no lixo.
Utilizar um telefone pblico - carto
1.
2.
3.
4.
5.
6.
Retirar o telefone do gancho.

Esperar o sinal.
Colocar o carto.
Discar o nmero.
Falar no telefone.
Colocar o telefone no gancho.
Fritar um ovo
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Pegar frigideira, ovo, leo e sal.

Colocar leo na frigideira.
Ascender o fogo.
Colocar a frigideira no fogo.
Esperar o leo esquentar.
Quebrar o ovo na frigideira.
Jogar a casca no lixo.
Retirar a frigideira do fogo quando o ovo estiver no ponto.
Desligar o fogo.
Colocar sal a gosto.
Trocar lmpadas
1.
2.
3.
4.
5.
Se a lmpada estiver fora do alcance, pegar uma escada.

Pegar a lmpada nova.
Se a lmpada queimada estiver quente, pegar um pano.
Tirar a lmpada queimada.
Colocar a lmpada nova.
Ttulo ADVPL 1
Pgina 11
Descascar batatas
1. Pegar faca, bacia e batatas.

2. Colocar a gua na bacia.
3. Descascar todas as batatas.
3.1.
Colocar as batatas descascadas na bacia.
Jogar o jogo da forca
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.
Calcular a mdia de notas
1. Enquanto houver notas a serem recebidas:

1.1.
Receber a nota.
2. Some todas as notas recebidas.

3. Divida o total obtido pela quantidade de notas recebidas.
4. Exiba a mdia das notas.
Jogar o jogo da velha contra o algoritmo

1. Enquanto existir um quadrado livre e ningum ganhou ou perdeu o jogo:
1.1.
Espere a jogada do adversrio, continue depois.
1.2.
Se o centro estiver livre: jogue no centro.
1.3.
Seno, se o adversrio possuir dois quadrados em linha com um quadrado
livre jogue neste quadrado.
1.4.
Seno, se h algum canto livre, jogue neste canto.
Pgina 12
ADVPL 1
11..22..22..
TTeessttee ddee m
meessaa
Todo algoritmo desenvolvido, deve ser testado. Este teste chamado TESTE DE MESA, que
significa seguir as instrues do algoritmo de maneira precisa para verificar se o
procedimento utilizado est correto ou no.
Para avaliar a aplicao do teste de mesa, utilizaremos o algoritmo de calcular a mdia de

notas:
Algoritmo: Calcular a mdia de notas

a. Receber a nota.

Teste de mesa:
1. Para cada nota informada, receber e registrar na tabela abaixo:
ID
Nota
2. Ao trmino das notas, a tabela dever conter todas as notas informadas, como abaixo:
ID
Nota
8.0
7.0
3
8.0
Ttulo ADVPL 1
Pgina 13
8.0
7.0
7.0
3. Some todas as notas: 45

4. Divida a soma das notas, pelo total de notas informado: 45/6 7.5
5. Exiba a mdia obtida: Mensagem (Mdia: 7.5)
Exerccio 01
Vamos aprimorar os seguintes algoritmos descritos na apostila:
1)
Usar telefone pblico carto.
2)
Fritar um ovo.
3)
Mascar um chiclete
4)
Trocar lmpadas.
5)
Descascar batatas.
6)
Usar telefone pblico carto
7)
Jogar o Jogo da Forca
Pgina 14
ADVPL 1
2. ESTRUTURAS DE PROGRAMAO
2.1. Diagrama de bloco
O diagrama de blocos uma padronizao que
determinado processamento.
representa os passos lgicos de um
Com o diagrama definimos uma sequncia de smbolos com significado bem definido.
Portanto, sua principal funo a de facilitar a visualizao dos passos de um processamento.
Simbologia
Existem diversos smbolos em um diagrama de bloco. No quadro abaixo esto representados

alguns dos smbolos mais utilizados:
Smbolo
Funo
Indica o incio e o fim de um
processamento.
Terminador
Processamento em geral.
Processame
nto
Ttulo ADVPL 1
Pgina 15
Indica a entrada de dados atravs

do teclado.
Entrada
Manual
Indica um ponto no qual dever
ser efetuada uma escolha entre
duas situaes possveis.
Deciso
Mostra os resultados obtidos com
um processamento.
Exibio
Indica um documento utilizado pelo
processamento, seja para entrada de
informaes ou para exibio dos dados
disponveis aps um processamento.
Documento
Cada smbolo ir conter uma descrio pertinente forma com o

qual o mesmo foi utilizado no fluxo, indicando o processamento
ou a informao que o mesmo representa.
Pgina 16
ADVPL 1
Representao de algoritmos atravs de diagramas de bloco
Algoritmo 01: Fritar um ovo
1. Pegar frigideira, ovo, leo e sal.

2. Colocar leo na frigideira.
3. Acender o fogo.
4. Colocar a frigideira no fogo.
5. Esperar o leo esquentar.
6. Quebrar o ovo na frigideira.
7. Jogar a casca no lixo.
8. Retirar a frigideira do fogo quando o ovo estiver no ponto.
9. Desligar o fogo.
10. Colocar sal a gosto.
Ttulo ADVPL 1
Pgina 17
Pgina 18
ADVPL 1
Algoritmo 02: Calcular a mdia de notas

a. Receber a nota.

Ttulo ADVPL 1
Pgina 19
2.2. Estruturas de deciso e repetio

A utilizao de estruturas de deciso e repetio em um algoritmo permite a realizao de
aes relacionadas s situaes que influenciam na execuo e na soluo do problema.
Como foco na utilizao da linguagem ADVPL, sero ilustradas as seguintes estruturas:
Estruturas de deciso
o
o
IF...ELSE
DO CASE ... CASE
Estruturas de repetio
o
o
22..22..11..
WHILE...END
FOR...NEXT
EEssttrruuttuurraass ddee ddeecciissoo
Os comandos de deciso so utilizados em algoritmos cuja soluo no obtida atravs da

utilizao de aes meramente sequenciais, permitindo que estes comandos de deciso
avaliem as condies necessrias para optar por uma ou outra maneira de continuar seu
fluxo.
As estruturas de deciso que sero analisadas so:
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.
Representao 01: IF...ELSE com aes para ambas as situaes
Pgina 20
ADVPL 1
Esta estrutura permite ainda que seja executada apenas uma ao, na situao em que a
anlise da condio resultar em um valor verdadeiro.
Representao 02: IF...ELSE somente com ao para situao verdadeira
Aes anteriores
...
Anlise da
condio
Falso
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo aps a
tomada da
deciso
Apesar das linguagens de programao possurem variaes para

a estrutura IF...ELSE, conceitualmente todas as representaes
podem ser descritas com base no modelo apresentado.
Ttulo ADVPL 1
Pgina 21
A linguagem ADVPL possui uma variao para a estrutura

IF...ELSE, descrita como IF...ELSEIF...ELSE.
Com esta estrutura possvel realizar a anlise de diversas
condies em sequncia, para as quais ser avaliada somente a
ao da primeira expresso cujo anlise resultar em um valor
verdadeiro.
Pgina 22
ADVPL 1
DO CASE...CASE
A estrutura DO CASE...ENDCASE (Caso) permite a anlise de diversas condies consecutivas,

para as quais somente a condio para a primeira condio verdadeira ser sua ao
vinculada e executada.
O recurso de anlise de mltiplas condies necessrio para soluo de problemas mais

complexos, nos quais as possibilidades de soluo superam a mera anlise de um nico
resultado verdadeiro, ou falso.
Aes anteriores
...
Falso
Anlise da
condio 1
Verdadeiro
Ao vinculada a
condio 1
Verdadeiro
Ao vinculada a
condio 2
Verdadeiro
Ao vinculada a
condio N
Falso
Anlise da
condio 2
Falso
Anlise da
condio N
Falso
Continuao do
fluxo aps a
tomada da
deciso
Ttulo ADVPL 1
Pgina 23
Apesar das linguagens de programao possurem variaes para

a estrutura DO CASE...CASE, conceitualmente todas as
representaes podem ser descritas com base no modelo
apresentado.
Pgina 24
ADVPL 1
22..22..22..
EEssttrruuttuurraass ddee rreeppeettiioo
Os comandos de repetio so utilizados em algoritmos nas situaes em que necessrio

realizar uma determinada ao, ou um conjunto de aes para um nmero definido ou
indefinido de vezes, ou ainda enquanto uma determinada condio for verdadeira.
As estruturas de deciso que sero analisadas so:
WHILE...END
FOR...TO...NEXT
WHILE...END
Nessa estrutura, o conjunto de aes 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
condio
Loop
Falso
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo
...
Ttulo ADVPL 1
Pgina 25
Existem diversas variaes para a estrutura WHILE...END, na qual

existe a possibilidade da primeira execuo ser realizada sem a
anlise da condio, a qual valer apenas a partir da segunda
execuo.
A linguagem ADVPL aceita a sintaxe DO WHILE...ENDDO que em
outras linguagens representa a situao descrita anteriormente
(anlise da condio somente a partir da segunda execuo), mas
em ADVPL esta sintaxe tem o mesmo efeito do WHILE...END.
Pgina 26
ADVPL 1
FOR...TO...NEXT
Nessa estrutura, o conjunto de aes executado em uma quantidade de vezes definida,

normalmente referenciada como passo.
Para cada passo realizado pela estrutura FOR...TO...NEXT, avaliada uma condio que
verifica se foi atingido o nmero de execues previamente definido. Dessa forma, a estrutura
compreende um controle de nmero de passos executados e incrementado na anlise da
expresso NEXT.
Semelhante a estrutura WHILE...END, a primeira ao somente ser realizada mediante um

resultado verdadeiro na anlise da condio.
Representao: FOR...TO...NEXT
Ttulo ADVPL 1
Pgina 27
A estrutura FOR...TO...NEXT, dependendo da linguagem de

programao, permite a realizao de um incremento simples a
cada execuo da instruo NEXT, ou a adio de outro valor ao
contador que dever especificado de acordo com a sintaxe da
linguagem.
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.
Exerccio 02
Vamos montar os diagramas de blocos para os algoritmos desenvolvidos no
exerccio anterior:
1. Usar telefone pblico carto.
2. Fritar um ovo.
3. Mascar um chiclete.
4. Trocar lmpadas.
5. Descascar batatas.
6. Jogar o Jogo da Forca
Pgina 28
ADVPL 1
MDULO 02: A LINGUAGEM ADVPL

A Linguagem ADVPL teve seu incio em 1994, sendo na verdade uma evoluo na utilizao
de linguagens no padro xBase pela Microsiga Software S.A. (Clipper, Visual Objects e depois
FiveWin). Com a criao da tecnologia Protheus era necessrio criar uma linguagem que
suportasse o padro xBase para a manuteno de todo o cdigo existente do sistema de ERP
Siga Advanced. Foi ento criada a linguagem chamada Advanced Protheus Language.
O ADVPL uma extenso do padro xBase de comandos e funes, operadores, estruturas de

controle de fluxo e palavras reservadas, contando tambm com funes e comandos
disponibilizados pela Microsiga que a torna uma linguagem completa para a criao de
aplicaes ERP prontas para a Internet. Tambm uma linguagem orientada a objetos e
eventos, permitindo ao programador desenvolver aplicaes visuais e criar suas prprias
classes de objetos.
Quando compilados, todos os arquivos de cdigo tornam-se unidades de inteligncia bsicas,

chamados APOs (de Advanced Protheus Objects). Tais APOs so mantidos em um repositrio
e carregados dinamicamente pelo PROTHEUS Server para a execuo. Como no existe a
linkedio, ou unio fsica do cdigo compilado a um determinado mdulo ou aplicao,
funes criadas em ADVPL podem ser executadas em qualquer ponto do Ambiente Advanced
Protheus.
O compilador e o interpretador da linguagem ADVPL o prprio servidor PROTHEUS

(PROTHEUS Server), e existe um Ambiente visual para o desenvolvimento integrado
(PROTHEUSIDE), em que o cdigo pode ser criado, compilado e depurado.
Os programas em ADVPL podem conter comandos, ou funes de interface com o usurio.

De acordo com tal caracterstica, tais programas so subdivididos nas seguintes categorias:
Programao Com Interface Prpria com o Usurio
Nessa categoria, so classificados os programas desenvolvidos para execuo atravs do

terminal remoto do Protheus, o Protheus Remote. O Protheus Remote a aplicao
encarregada da interface e da interao com o usurio, sendo que todo o processamento do
cdigo em ADVPL, o acesso ao banco de dados e o gerenciamento de conexes efetuado
no Protheus Server. O Protheus Remote o principal meio de acesso execuo de rotinas
escritas em ADVPL no Protheus Server. Por isso permite executar qualquer tipo de cdigo,
tenha ele interface com o usurio, ou no. Porm, nessa categoria so considerados apenas
os programas que realizem algum tipo de interface remota, utilizando o protocolo de
comunicao do Protheus.
Ttulo ADVPL 1
Pgina 29
Podero ser criadas 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.
Todo o cdigo do sistema ERP Microsiga Protheus escrito em ADVPL.
Programao Sem Interface Prpria com o Usurio
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 (como a criao de uma janela padro) ocasionar uma exceo em tempo de
execuo. Essas rotinas so apenas processos, ou Jobs executados no Protheus Server.
Algumas vezes, a interface dessas rotinas fica a cargo de aplicaes externas, desenvolvidas
em outras linguagens que so responsveis por iniciar os processos no servidor Protheus, por
meio dos meios disponveis de integrao e conectividade no Protheus.
De acordo com a utilizao e com o meio de conectividade utilizado, estas rotinas so

subcategorizadas assim:
Programao por Processos
Rotinas escritas em ADVPL podem ser iniciadas como processos individuais (sem interface),
no Protheus Server atravs de duas maneiras: Iniciadas por outra rotina ADVPL por meio da
chamada de funes como StartJob() ou CallProc(), ou iniciadas automaticamente, na
inicializao do Protheus Server (quando propriamente configurado).
Programao de RPC
Com a utilizao de uma biblioteca de funes disponvel no Protheus (uma API de

comunicao) so executadas as rotinas escritas em ADVPL diretamente no Protheus Server,
por aplicaes externas escritas em outras linguagens. Assim, o que se chama de RPC (de
Remote Procedure Call, ou Chamada de Procedimentos Remota).
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,
Pgina 30
ADVPL 1
as aplicaes externas podem requisitar a execuo de rotinas escritas em ADVPL, pela

conexo TCP/IP direta.
Programao Web
O Protheus Server pode tambm ser executado como um servidor Web, respondendo a
requisies HTTP. No momento dessas 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, utilizando uma aplicao cliente desse protocolo. O PROTHEUS Server pode emular
um terminal pela execuo de rotinas escritas em ADVPL. Ou seja, possvel escrever rotinas
ADVPL cuja interface final ser um terminal TelNet, ou um coletor de dados mvel.
Ttulo ADVPL 1
Pgina 31
3. ESTRUTURA DE UM PROGRAMA ADVPL

Um programa de computador nada mais do que um grupo de comandos logicamente
dispostos, com o objetivo de executar determinada tarefa. Esses comandos so gravados em
um arquivo texto que transformado em uma linguagem executvel por um computador,
utilizando o processo de compilao. A compilao substitui os comandos de alto nvel (que
os humanos compreendem) por instrues de baixo nvel (compreendida pelo sistema
operacional em execuo no computador). No caso do ADVPL, no o sistema operacional
de um computador que executar o cdigo compilado, mas sim o Protheus Server.
Dentro de um programa, os comandos e funes utilizados devem seguir as regras de sintaxe

da linguagem utilizada, pois caso contrrio, o programa ser interrompido por erros. Os erros
podem ser de compilao, ou de execuo.
Erros de compilao so aqueles encontrados na sintaxe que no permitem que o arquivo de

cdigo do programa seja compilado. Podem ser comandos especificados de forma errnea,
utilizao invlida de operadores, etc.
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 s
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
Pgina 32
ADVPL 1
Linhas de Comentrio
Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem apenas

para a documentao e para tornar mais fcil o entendimento do programa. Existem trs
formas de se comentar linhas de texto. A primeira delas utilizar o sinal de * (asterisco) no
comeo da linha:
* Programa para clculo do total

* Autor: Microsiga Software S.A.
* Data: 2 de outubro de 2001
Ttulo ADVPL 1
Pgina 33
Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio.

possvel utilizar a palavra NOTE, ou dois smbolos da letra "e" comercial (&&) para realizar a
funo do sinal de asterisco. Porm todas essas formas de comentrio de linhas so obsoletas
e existem apenas para a compatibilizao com o padro xBase. A melhor maneira de
comentar linhas em ADVPL utilizar duas barras transversais:
// Programa para clculo do total

// Autor: Microsiga Software S.A.
// Data: 2 de outubro de 2001
Outra forma de documentar textos utilizando as barras transversais juntamente com o

asterisco. possvel comentar todo um bloco de texto sem precisar comentar linha a linha:
/*
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
Pgina 34
ADVPL 1
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, possvel "quebrar" a linha lgica em mais
de uma linha fsica no arquivo texto. Isso efetuado utilizando-se o sinal de ponto-e-vrgula
(;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter>

!Empty(cTel) .And. !Empty(cFax) .And. ; <enter>
!Empty(cEmail)
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
Nesse exemplo existe uma linha de comando para a checagem das variveis utilizadas. Como
a linha torna-se muito grande, possvel dividi-la em mais de uma linha fsica, utilizando o
sinal de ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas duas primeiras
linhas, durante a execuo do programa ocorrer um erro, pois a segunda linha fsica ser
considerada como uma segunda linha de comando na compilao. E durante a execuo esta
linha no ter sentido.
Ttulo ADVPL 1
Pgina 35
3.1. reas de um Programa ADVPL

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
+===========================================+
*/
User Function CalcFator()
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
// Exibe o resultado na tela, atravs da funo alert

Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))
// Termina o programa
Return
A estrutura de um programa ADVPL composta pelas seguintes reas:

Pgina 36
ADVPL 1
rea de Identificao
Declarao dos includes
Declarao da funo
Identificao do programa
rea de Ajustes Iniciais

Declarao das variveis
Corpo do Programa
Preparao para o processamento
Processamento
rea de Encerramento
rea de Identificao
Esta uma rea que no obrigatria e dedicada a documentao do programa. Quando

existente, contm apenas comentrios explicando a sua finalidade, data de criao, autor, etc.,
e aparece no comeo do programa, antes de qualquer linha de comando.
O formato para esta rea no definido. possvel escrever qualquer tipo de informao
desejada e ainda, escolher a formatao apropriada.
Ttulo ADVPL 1
Pgina 37
/*
+==========================================+
| Programa: Clculo do Fatorial
| Autor : Microsiga Software S.A.
| Data
: 02 de outubro de 2001
+==========================================+
*/
User Function CalcFator()
Opcionalmente, possvel incluir definies de constantes utilizadas no programa ou incluso

de arquivos de cabealho nesta rea.
rea de Ajustes Iniciais
Nessa rea geralmente so feitos

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
nessa rea. Assim, possvel tornar o cdigo 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
Nessa rea encontram-se as linhas de cdigo do programa. Nela realiza a tarefa necessria
por meio da organizao lgica dessas linhas de comando. Espera-se que as linhas de
comando estejam organizadas de tal modo que no final da mesma, o resultado esperado seja
Pgina 38
ADVPL 1
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.
nResultado *= nCnt
Next nCnt
Ttulo ADVPL 1
Pgina 39
A preparao para o processamento formada pelo conjunto de validaes e

processamentos necessrios antes da realizao do processamento em si.
Avaliando o processamento do clculo do fatorial descrito anteriormente, possvel definir

que a validao inicial a ser realizada o contedo da varivel nFator, pois a mesma
determinar a correta execuo do cdigo.
nFator := GetFator()
// GetFator funo ilustrativa na qual a varivel recebe a informao do usurio.
If nFator <= 0
Alert(Informao invlida)
Return
Endif

nResultado *= nCnt
Next nCnt
Pgina 40
ADVPL 1
rea de Encerramento
nesta rea onde as finalizaes so efetuadas. onde os arquivos abertos so fechados, e o

resultado da execuo do programa utilizado. possvel exibir o resultado armazenado em
uma varivel, ou em um arquivo. Ainda, finalizar, se a tarefa j tiver sido toda completada no
corpo do programa. nessa rea que se encontra o encerramento do programa. Todo
programa em ADVPL deve sempre terminar com a palavra chave return.
// Exibe o resultado na tela, atravs da funo alert

// Termina o programa
Return
Ttulo ADVPL 1
Pgina 41
4. DECLARAO E ATRIBUIO DE VARIVEIS

4.1. Tipo de Dados
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, possvel
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).
Pgina 42
ADVPL 1
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 desse tipo de
dado so armazenadas como um nmero correspondente data Juliana.
Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim com a
utilizao de funes especficas como, por exemplo, CTOD() que converte uma string para
data.
Ttulo ADVPL 1
Pgina 43
Array
O Array um tipo de dado especial. a disposio de outros elementos em colunas e linhas.

O ADVPL suporta arrays unidimensionais (vetores) ou multidimensionais (matrizes). Os
elementos de um array so acessados atravs de ndices numricos iniciados em 1,
identificando a linha e coluna para quantas dimenses existirem.
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.
4.2. Declarao de variveis
Variveis de memria so um dos recursos mais importantes de uma linguagem. So reas de

memria criadas para armazenar informaes utilizadas por um programa para a execuo de
tarefas. Por exemplo, quando o usurio digita uma informao qualquer, como o nome de um
produto, em uma tela de um programa esta informao armazenada em uma varivel de
memria para posteriormente ser gravada, ou impressa.
A partir do momento que uma varivel criada, no mais necessrio referenciar ao seu
contedo, e sim, seu nome.
Pgina 44
ADVPL 1
O nome de uma varivel um identificador nico que deve respeitar um nmero mximo de
10 caracteres. O ADVPL no impede a criao de uma varivel de memria cujo nome
contenha mais de 10 caracteres, porm apenas os 10 primeiros sero considerados para a
localizao do contedo armazenado. Portanto, se forem criadas duas variveis cujos 10
primeiros caracteres forem iguais, como nTotalGeralAnual e nTotalGeralMensal, as referncias
a qualquer uma delas no programa resultaro o mesmo, ou seja, sero a mesma varivel:
nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))
Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300. Isso
acontece porque no momento em 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.
Ttulo ADVPL 1
Pgina 45
4.3. Escopo de variveis
O ADVPL no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio

informar o tipo de dados que determinada varivel ir conter no momento de sua declarao,
e o seu valor pode mudar durante a execuo do programa.
Tambm no h necessidade de declarar variveis em uma seo especfica do seu cdigo

fonte, embora seja aconselhvel declarar todas as variveis necessrias no comeo, tornando
a manuteno mais fcil, e evitando a declarao de variveis desnecessrias.
Para declarar uma varivel necessrio utilizar um identificador de escopo. Um identificador

de escopo uma palavra chave que indica a que contexto do programa a varivel declarada
pertence. O contexto de variveis pode ser local (visualizadas apenas dentro do programa
atual), pblico (visualizadas por qualquer outro programa), entre outros.
O Contexto de Variveis dentro de um Programa
As variveis declaradas em um programa ou funo so visveis de acordo com o escopo

onde so definidas. Como tambm do escopo depende o tempo de existncia das variveis. A
definio do escopo de uma varivel efetuada no momento de sua declarao.
Local nNmero := 10
Esta linha de cdigo declara uma varivel chamada nNmero, indicando que aonde pertence
seu escopo local.
Os identificadores de escopo so:

Local
Static
Private
Public
O ADVPL no rgido em relao declarao de variveis no comeo do programa. A

incluso de um identificador de escopo no necessrio para a declarao de uma varivel,
contanto que um valor lhe seja atribudo.
nNumero2 := 15
Pgina 46
ADVPL 1
Quando um valor atribudo a uma varivel em um programa ou funo, o ADVPL criar a

varivel se ela no tiver sido declarada anteriormente. A varivel ento criada como se
tivesse sido declarada como Private.
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. Assim, compreender o nome da varivel
escrito de forma incorreta como se fosse a criao de uma nova varivel. Dessa forma, ser
alterada a lgica do programa, e um erro muitas vezes difcil de identificar.
Ttulo ADVPL 1
Pgina 47
Variveis de escopo local
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.
A visibilidade de variveis de escopo locais idntica ao escopo de sua declarao, ou seja, a

varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se uma funo
chamada recursivamente, apenas as variveis de escopo local criadas na mais recente ativao
so visveis.
Pgina 48
ADVPL 1
Variveis de escopo static
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.
Ttulo ADVPL 1
Pgina 49
Neste exemplo, a varivel nVar declarada como static e inicializada com o valor 10:
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.
Variveis de escopo private
A declarao opcional para variveis privadas. Mas podem ser declaradas explicitamente
com o identificador PRIVATE.
Adicionalmente, a atribuio de valor a uma varivel no criada anteriormente, de forma

automtica cria-se a varivel como privada. Uma vez criada, uma varivel privada continua a
existir e mantm seu valor at que o programa ou funo onde foi criada termine (ou seja, at
que a funo onde foi feita retorne para o cdigo que a executou). Neste momento,
automaticamente destruda.
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
esconder qualquer outra varivel privada ou pblica (veja a documentao sobre variveis
pblicas) com o mesmo nome enquanto existir.
Pgina 50
ADVPL 1
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.
Ttulo ADVPL 1
Pgina 51
Por exemplo:
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 que

fala sobre as variveis, em uso pela aplicao, no sejam
incorretamente manipuladas. Por esta conveno deve ser
adicionado o caractere _ antes do nome das variveis PRIVATE e
PUBLIC. Para ,maiores informaes avaliar o tpico: Boas
Prticas de Programao.
Exemplo: Private _dData
Pgina 52
ADVPL 1
Variveis de escopo public
possvel criar variveis de escopo public dinamicamente, no cdigo com o identificador

PUBLIC. As variveis desse escopo continuam a existir e mantm seu valor at o fim da
execuo da thread (conexo). Tambm 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 em que 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.)
Nesse exemplo, nVar criada como public e inicializada com o valor 10. Quando a funo
Filha executada, nVar ainda existe e pode ser acessada. Diferente de variveis locais ou
privates, nVar ainda existe aps o trmino da a execuo da funo Pai.
Diferentemente dos outros identificadores de escopo, quando uma varivel declarada como
pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).
Ttulo ADVPL 1
Pgina 53
No ambiente ERP Protheus, existe uma conveno adicional que

deve ser respeitada. Essa conveno diz que as variveis em uso
pela aplicao no sejam incorretamente manipuladas. Por essa
conveno deve ser adicionado o caractere _ antes do nome de
variveis PRIVATE e PUBLIC. Para Maiores informaes avalier o
tpico: Boas Prticas de Programao.
Exemplo: Public _cRotina
Pgina 54
ADVPL 1
4.4. Entendendo a influncia do escopo das variveis
Considere as linhas de cdigo de exemplo:
nResultado := 250 * (1 + (nPercentual / 100))
Se esta linha for executada em um programa ADVPL ocorrer um erro de execuo com a
mensagem "variable does not exist: nPercentual", pois esta varivel est sendo utilizada em
uma expresso de clculo sem ter sido declarada. Para solucionar esse erro, deve-se declarar
a varivel previamente:
Local nPercentual, nResultado

No exemplo acima, as variveis so declaradas previamente, utilizando o identificador de

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

nPercentual := 10
ou
Local nPercentual := 10, nResultado

Ttulo ADVPL 1
Pgina 55
A diferena, entre o ltimo exemplo e os dois anteriores, que a varivel inicializada no

momento da declarao. Nos dois exemplos, a varivel primeiro declarada e ento
inicializada em uma outra linha de cdigo.
aconselhvel optar pelo operador de atribuio composto de dois pontos e sinal de igual,
pois o operador de atribuio, utilizando somente o sinal de igual, pode ser facilmente
confundido com o operador relacional (para comparao), durante a criao do programa.
Pgina 56
ADVPL 1
4.5. Operaes com Variveis
44..55..11..
A
Attrriibbuuiioo ddee vvaarriivveeiiss
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, possvel mudar o tipo de varivel
atribuindo outro tipo a ela:
01 Local xVariavel // Declara a varivel inicialmente com valor nulo

02
03 xVariavel := "Agora a varivel caractere..."
04 Alert("Valor do Texto: " + xVariavel)
05
06 xVariavel := 22 // Agora a varivel numrica
07 Alert(cValToChar(xVariavel))
08
09 xVariavel := .T. // Agora a varivel lgica
10 If xVariavel
11
Alert("A varivel tem valor verdadeiro...")
12 Else
13
Alert("A varivel tem valor falso...")
14 Endif
15
16 xVariavel := Date() // Agora a varivel data
17 Alert("Hoje : " + DtoC(xVariavel))
18
19 xVariavel := nil // Nulo novamente
20 Alert("Valor nulo: " + xVariavel)
21
22 Return
Ttulo ADVPL 1
Pgina 57
No programa de exemplo anterior, a varivel xVariavel utilizada para armazenar diversos

tipos de dados. A letra "x", em minsculo no comeo do nome, utilizada para indicar uma
varivel que pode conter diversos tipos de dados, segundo a Notao Hngara (consulte
documentao especfica para detalhes). Este programa troca os valores da varivel e exibe
seu contedo para o usurio atravs da funo ALERT(). Essa funo recebe um parmetro
que deve ser do tipo string de caractere. Por isso, dependendo do tipo de dado da varivel
xVariavel, necessrio fazer uma converso antes.
Apesar dessa flexibilidade de utilizao de variveis, devem-se tomar cuidados na passagem

de parmetros para funes ou comandos, e na concatenao (ou soma) de valores. Note a
linha 20 do programa de exemplo. Quando esta linha executada, a varivel xVariavel contm
o valor nulo. A tentativa de soma de tipos de dados diferentes gera erro de execuo do
programa. Nesta linha do exemplo, ocorrer um erro com a mensagem "type mismatch on
+".
Excetuando-se o caso do valor nulo, para os demais devem ser utilizadas funes de
converso, quando necessrio concatenar tipos de dados diferentes (por exemplo, nas
linhas 07 e 17).
Note tambm que quando uma varivel do tipo de dado lgico, ela pode ser utilizada
diretamente para checagem (linha 10):
If xVariavel
o mesmo que
If xVariavel = .T.
Pgina 58
ADVPL 1
44..55..22..
O
Oppeerraaddoorreess ddaa lliinngguuaaggeem
mA
AD
DV
VPPLL
Operadores comuns
Na documentao sobre variveis h uma breve demonstrao de como atribuir valores a

uma varivel da forma mais simples. O ADVPL amplia significativamente a utilizao de
variveis, atravs do uso de expresses e funes.
Uma expresso um conjunto de operadores e operandos, cujo resultado pode ser atribudo
a uma varivel ou ento analisado para a tomada de decises. Por exemplo:
Local nSalario := 1000, nDesconto := 0.10

Local nAumento, nSalLiquido
nAumento := nSalario * 1.20
nSalLiquido := nAumento * (1-nDesconto)
Nesse 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.
Ttulo ADVPL 1
Pgina 59
Operadores Matemticos
Os operadores utilizados em ADVPL para clculos matemticos so:
Adio
Subtrao
Multiplicao
Diviso
** ou ^
Exponenciao
Mdulo (Resto da Diviso)
Operadores de String
Os operadores utilizados em ADVPL para tratamento de caracteres so:
Concatenao de strings (unio).
Concatenao de strings com eliminao dos brancos finais das strings

intermedirias.
Comparao de Substrings (contido em).
Pgina 60
ADVPL 1
Operadores Relacionais
Os operadores utilizados em ADVPL para operaes e avaliaes relacionais so:
<
Comparao Menor
>
Comparao Maior
Comparao Igual
==
Comparao Exatamente Igual (para caracteres)
<=
Comparao Menor ou Igual
>=
Comparao Maior ou Igual
<> ou # Comparao Diferente

ou !=
Operadores Lgicos
Os operadores utilizados em ADVPL para operaes e avaliaes lgicas so:
.And.
E lgico
.Or.
OU lgico
.Not. ou !
NO lgico
Ttulo ADVPL 1
Pgina 61
Operadores de Atribuio
Os operadores utilizados em ADVPL para atribuio de valores a variveis de memria so:
:=
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
O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.

nVariavel := 10
Pgina 62
ADVPL 1
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 possvel atribuir mais de uma varivel ao mesmo tempo.
nVar1 := nVar2 := nVar3 := 0
Quando diversas variveis so inicializadas em uma mesma linha, a atribuio comea da

direita para a esquerda, ou seja, nVar3 recebe o valor zero inicialmente, nVar2 recebe o
contedo de nVar3 e nVar1 recebe o contedo de nVar2 por final.
Com o operador de atribuio em linha, possvel substituir as inicializaes individuais de

cada varivel por uma inicializao apenas:
Local nVar1 := 0, nVar2 := 0, nVar3 := 0

por
Local nVar1 := nVar2 := nVar3 := 0
O operador de atribuio em linha tambm pode ser utilizado para substituir valores de
campos em um banco de dados.
Ttulo ADVPL 1
Pgina 63
Atribuio Composta
Os operadores de atribuio composta so uma facilidade da linguagem ADVPL para

expresses de clculo e atribuio. Dessa forma possvel economizar digitao:
Operador
Exemplo
Equivalente a
+=
X += Y
X=X+Y
-=
X -= Y
X=X-Y
*=
X *= Y
X=X*Y
/=
X /= Y
X=X/Y
**= ou ^=
X **= Y
X = X ** Y
%=
X %= Y
X=X%Y
Operadores de Incremento/Decremento
A linguagem ADVPL possui operadores para realizar incremento ou decremento de variveis.

Entende-se por incremento aumentar o valor de uma varivel numrica em 1 e entende-se
por decremento diminuir o valor da varivel em 1. Os operadores so:
++
Incremento Ps ou Pr-fixado
--
Decremento Ps ou Pr-fixado
Os operadores de decremento/incremento podem ser colocados tanto antes (pr-fixado)

como depois (ps-fixado) do nome da varivel. Dentro de uma expresso, a ordem do
operador muito importante, podendo alterar o resultado da expresso. Os operadores
incrementais so executados da esquerda para a direita dentro de uma expresso.
Local nA := 10
Local nB := nA++ + nA
Pgina 64
ADVPL 1
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 dessas duas linhas a varivel nB contendo 21 e a varivel nA
contendo 11.
No entanto:
Local nA := 10
Local nB := ++nA + nA
Resulta em 22 pois o operador incremental aumentou o valor da primeira nA antes que seu
valor fosse considerado.
Operadores Especiais
Alm dos operadores comuns, o ADVPL possui alguns outros operadores, ou identificadores.
Estas so suas finalidades:
()
Agrupamento ou Funo
[]
Elemento de Matriz
{}
Definio de Matriz, Constante ou Bloco de Cdigo
->
Identificador de Apelido
&
Macro substituio
Passagem de parmetro por referncia
||
Passagem de parmetro por valor

Os parnteses so utilizados para agrupar elementos em uma expresso, mudando a
ordem de precedncia da avaliao da expresso (segundo as regras matemticas, por
exemplo). Tambm servem para envolver os argumentos de uma funo.
Os colchetes so utilizados para especificar um elemento especfico de uma matriz.

Por exemplo, A[3,2] refere-se ao elemento da matriz A na linha 3, coluna 2.
Ttulo ADVPL 1
Pgina 65

As chaves so utilizadas para a especificao de matrizes literais, ou blocos de cdigo.
Por exemplo, A:={10,20,30} cria uma matriz chamada A com trs elementos.

O smbolo -> identifica um campo de um arquivo, diferenciando-o de uma varivel.
Por exemplo, FUNC->nome refere-se ao campo nome do arquivo FUNC. Mesmo que exista
uma varivel chamada nome, o campo nome que ser acessado.

O smbolo & identifica uma avaliao de expresso atravs de macro e visto em
detalhes na documentao sobre macro substituio.

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.
Pgina 66
ADVPL 1
Ordem de Precedncia dos Operadores
Dependendo do tipo de operador, existe uma ordem de precedncia para a avaliao dos
operandos. Em princpio, todas as operaes, com os operadores, so realizadas da esquerda
para a direita, se eles tiverem o mesmo nvel de prioridade.
A ordem de precedncia, ou nvel de prioridade de execuo dos operadores em ADVPL :
1.
2.
3.
4.
5.
6.
7.
Operadores de Incremento/Decremento pr-fixado

Operadores de String
Operadores Matemticos
Operadores Relacionais
Operadores Lgicos
Operadores de Atribuio
Operadores de Incremento/Decremento ps-fixado
Em expresses complexas com diferentes tipos de operadores, a avaliao seguir essa

sequncia. Caso exista mais de um operador do mesmo tipo (ou seja, de mesmo nvel), a
avaliao se d da esquerda para direita. Para os operadores matemticos entretanto, h uma
precedncia a seguir:
1.
2.
3.
Exponenciao
Multiplicao e Diviso
Adio e Subtrao
Considere o exemplo:
Local nResultado := 2+10/2+5*3+2^3
O resultado desta expresso 30, pois primeiramente calculada a exponenciao 2^3(=8),

ento so calculadas as multiplicaes e divises 10/2(=5) e 5*3(=15), e finalmente as adies
resultando em 2+5+15+8(=30).
Alterao da Precedncia
A utilizao de parnteses dentro de uma expresso altera a ordem de precedncia dos

operadores. Operandos entre parnteses so analisados antes dos que se encontram
Ttulo ADVPL 1
Pgina 67
fora dos parnteses. Se existirem mais de um conjunto de parnteses no-aninhados, o grupo

mais a esquerda ser avaliado primeiro e assim sucessivamente.
Local nResultado := (2+10)/(2+5)*3+2^3
No exemplo acima, primeiro ser calculada a exponenciao 2^3(=8). Em seguida 2+10(=12)

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

ocorrer do parnteses mais interno em direo ao mais externo.
Pgina 68
ADVPL 1
44..55..33..
O
Oppeerraaoo ddee M
Maaccrroo SSuubbssttiittuuiioo
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. possvel 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 possvel substituir Y na terceira linha:
03 B := &"X + 1"
O operador de macro cancela as aspas:
03 B := X + 1
O operador de macro remove as aspas, o que deixa uma parte do 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, um avaliador
de frmulas, que determina o resultado de algo que o usurio digita.
O operador de macro tem uma limitao: variveis referenciadas dentro da string de

caracteres (X nos exemplos anteriores) no podem ser locais.
Ttulo ADVPL 1
Pgina 69
Pgina 70
ADVPL 1
44..55..44..
FFuunneess ddee m
maanniippuullaaoo ddee vvaarriivveeiiss
Alm de atribuir, controlar o escopo e a macro executar o contedo das variveis,

necessrio manipular seu contedo atravs de funes especficas da linguagem para cada
situao.
As operaes de manipulao de contedo mais comuns em programao so:

Converses entre tipos de variveis.

Manipulao de strings.
Manipulao de variveis numricas.
Verificao de tipos de variveis.
Manipulao de arrays.
Execuo de blocos de cdigo.
Neste tpico sero abordadas as converses entre tipos de variveis e as funes de

manipulao de strings e variveis numricas.
Converses entre tipos de variveis
As funes mais utilizadas nas operaes entre converso entre tipos de variveis so:
CTOD()
CVALTOCHAR()
DTOC()
DTOS()
STOD()
STR()
STRZERO()
VAL()
Ttulo ADVPL 1
Pgina 71
CTOD()
Sintaxe
CTOD(cData)
Descrio
Realiza a converso de uma informao do tipo caractere no formato

DD/MM/AAAA, para uma varivel do tipo data.
CVALTOCHAR()
Sintaxe
CVALTOCHAR(nValor)
Descrio
Realiza a converso de uma informao do tipo numrico em uma string, sem a

adio de espaos a informao.
DTOC()
Sintaxe
DTOC(dData)
Descrio
Realiza a converso de uma informao do tipo data para em caractere, sendo o

resultado no formato DD/MM/AAAA.
Pgina 72
ADVPL 1
DTOS()
Sintaxe
DTOS(dData)
Descrio
Realiza a converso de uma informao do tipo data em um caractere, sendo o

resultado no formato AAAAMMDD.
STOD()
Sintaxe
STOD(sData)
Descrio
Realiza a converso de uma informao do tipo caractere, com contedo no

formato AAAAMMDD, em data.
STR()
Sintaxe
STR(nValor)
Descrio
Realiza a converso de uma informao do tipo numrico em uma string,

adicionando espaos direita.
Ttulo ADVPL 1
Pgina 73
STRZERO()
Sintaxe
STRZERO(nValor, nTamanho)
Descrio
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.
VAL()
Sintaxe
VAL(cValor)
Descrio
Realiza a converso de uma informao do tipo caractere em numrica.
Manipulao de strings
As funes mais utilizadas nas operaes de manipulao do contedo de strings so:
ALLTRIM()
ASC()
AT()
CHR()
CSTUFF()
LEN()
RAT()
SUBSTR()
Pgina 74
ADVPL 1
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
Descrio
ASC(cCaractere)
Converte uma informao caractere em seu valor, de acordo com a tabela ASCII.
AT()
Sintaxe
AT(cCaractere, cString )
Descrio
Retorna a primeira posio de um caractere ou string, dentro de outra string

especificada.
Ttulo ADVPL 1
Pgina 75
CHR()
Sintaxe
CHR(nASCII)
Descrio
Converte um valor nmero referente a uma informao da tabela ASCII, no

caractere que esta informao representa.
LEN()
Sintaxe
LEN(cString)
Descrio
Retorna o tamanho da string especificada no parmetro.
LOWER()
Sintaxe
LOWER(cString)
Descrio
Retorna uma string com todos os caracteres minsculos, tendo como base a
string passada como parmetro.
RAT()
Sintaxe
RAT(cCaractere, cString)
Descrio
Retorna a ltima posio de um caractere ou string, dentro de outra string

especificada.
Pgina 76
ADVPL 1
STUFF()
Sintaxe
STUFF(cString, nPosInicial, nExcluir, cAdicao)
Descrio
Permite substituir um contedo caractere em uma string j existente,

especificando a posio inicial para esta adio e o nmero de caracteres que
sero substitudos.
SUBSTR()
Sintaxe
SUBSTR(cString, nPosInicial, nCaracteres)
Descrio
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).
UPPER()
Sintaxe
UPPER(cString)
Descrio
Retorna uma string com todos os caracteres maisculos, tendo como base a
string passada como parmetro.
Manipulao de variveis numricas
As funes mais utilizadas nas operaes de manipulao do contedo de strings so:
ABS()
INT()
NOROUND()
ROUND()
Ttulo ADVPL 1
Pgina 77
ABS()
Sintaxe
ABS(nValor)
Descrio
Retorna um valor absoluto (independente do sinal) com base no valor

especificado no parmetro.
INT()
Sintaxe
INT(nValor)
Descrio
Retorna a parte inteira de um valor especificado no parmetro.
NOROUND()
Sintaxe
NOROUND(nValor, nCasas)
Descrio
Retorna um valor, truncando a parte decimal do valor especificado no

parmetro de acordo com a quantidade de casas decimais solicitadas.
ROUND()
Sintaxe
ROUND(nValor, nCasas)
Descrio
Retorna um valor, arredondando a parte decimal do valor especificado no

parmetro, de acordo com as quantidades de casas decimais solicitadas,
utilizando o critrio matemtico.
Pgina 78
ADVPL 1
Verificao de tipos de variveis
As funes de verificao permitem a consulta ao tipo do contedo da varivel, durante a

execuo do programa.
TYPE()
VALTYPE()
TYPE()
Sintaxe
TYPE(cVariavel)
Descrio
Determina o tipo do contedo de uma varivel que no foi definida na funo

em execuo.
VALTYPE()
Sintaxe
VALTYPE(cVarivel)
Descrio
Determina o tipo do contedo de uma varivel que foi definida na funo em

execuo.
Ttulo ADVPL 1
Pgina 79
5. ESTRUTURAS BSICAS DE PROGRAMAO

O ADVPL suporta vrias estruturas de controle que permitem mudar a sequncia de fluxo de
execuo de um programa. Essas estruturas permitem a execuo de cdigo baseado em
condies lgicas e a repetio da execuo de pedaos de cdigo em 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.
As estruturas de controle em ADVPL esto divididas em:

Estruturas de repetio.
Estruturas de deciso.
5.1. Estruturas de repetio

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, digamos
que preciso imprimi-lo quatro vezes. possvel simplesmente chamar a funo de
impresso quatro vezes em sequncia, 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.
Pgina 80
ADVPL 1
Sintaxe
FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento]

Comandos...
[EXIT]
[LOOP]
NEXT
Parmetros
Varivel
Especifica uma varivel, ou um elemento de uma matriz para atuar

como um contador. A varivel, ou o elemento da matriz no
precisa ter sido declarado antes da execuo do comando
FOR...NEXT. Se a varivel no existir, ser criada como uma varivel
privada.
nValorInicial TO nValorInicial o valor inicial para o contador; nValorFinal o valor

nValorFinal
final para o contador. possvel utilizar valores numricos literais,
variveis ou expresses, contanto que o resultado seja do tipo
dado numrico.
STEP
nIncremento
nIncremento a quantidade que ser incrementada, ou

decrementada no contador aps cada execuo da seo de
comandos. Se o valor de nIncremento for negativo, o contador ser
decrementado. Se a clusula STEP for omitida, o contador ser
incrementado em 1. possvel utilizar os valores numricos literais,
variveis ou expresses, contanto que o resultado seja do tipo de
dado numrico.
Comandos
Especifica uma, ou mais instrues de comando ADVPL que sero

executadas.
EXIT
Transfere
comando
repetio
adicionar
NEXT.
LOOP
Retorna o controle diretamente para a clusula FOR sem executar

o restante dos comandos entre o LOOP e o NEXT. O contador
incrementado ou decrementado normalmente, como se o NEXT
tivesse sido alcanado. possvel posicionar o comando LOOP em
qualquer lugar, entre o FOR e o NEXT.
o controle de dentro do comando FOR...NEXT para o

imediatamente seguinte ao NEXT. Ou seja, finaliza a
da seo de comandos imediatamente. possvel
o comando EXIT em qualquer lugar entre o FOR e o
Ttulo ADVPL 1
Pgina 81
Uma varivel, ou um elemento de uma matriz utilizado como

um contador para especificar quantas vezes os comandos ADVPL
dentro da estrutura FOR...NEXT so executados.
Os comandos ADVPL depois do FOR so executados at que o

NEXT seja alcanado. O contador (Varivel) ento
incrementado, ou decrementado com o valor em nIncremento (se
a clusula STEP for omitida, o contador incrementado em 1).
Ento, o contador comparado com o valor em nValorFinal. Se for
menor ou igual ao valor em nValorFinal, os comandos seguintes
ao FOR so executados novamente.
Se o valor for maior que o contido em nValorFinal, a estrutura

FOR...NEXT terminada e o programa continua a execuo no
primeiro comando aps o NEXT.
Os valores de nValorInicial, nValorFinal e nIncremento so apenas

considerados inicialmente. Entretanto, mudar o valor da varivel
utilizada como contador dentro da estrutura afetar o nmero de
vezes que a repetio ser executada. Se o valor de nIncremento
negativo e o valor de nValorInicial maior que o de nValorFinal,
o contador ser decrementado a cada repetio.
Exemplo:
Local nCnt
Local nSomaPar := 0
For nCnt := 0 To 100 Step 2
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros nmeros pares : " + ;
cValToChar(nSomaPar) )
Return
Pgina 82
ADVPL 1
Esse 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
A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma seo de

cdigo enquanto uma determinada expresso resultar em verdadeiro (.T.).
Sintaxe
WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO
Parmetros
lExpressao
Especifica uma expresso lgica cujo valor determina quando os

comandos entre o WHILE e o ENDDO so executados. Enquanto o
resultado de lExpressao for avaliado como verdadeiro (.T.), o conjunto de
comandos so executados.
Comandos
Especifica uma ou mais instrues de comando ADVPL, que sero

executadas enquanto lExpressao for avaliado como verdadeiro (.T.).
EXIT
Transfere o controle de dentro do comando WHILE...ENDDO para o

comando imediatamente seguinte ao ENDDO, ou seja, finaliza a
repetio da seo de comandos imediatamente. possvel posicionar o
comando EXIT em qualquer lugar entre o WHILE e o ENDO.
LOOP
Retorna o controle diretamente para a clusula WHILE sem executar o

restante dos comandos entre o LOOP e o ENDDO. A expresso em
lExpressao reavaliada para a deciso se os comandos continuarem
sendo executados.
Ttulo ADVPL 1
Pgina 83
Exemplo :
Local nNumber := nAux := 350

nAux := Int(nAux / 2)
While nAux > 0
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros nmeros pares : " + ;
cValToChar(nSomaPar) )
Return
Os comandos entre o WHILE e o ENDDO so executados enquanto

o resultado da avaliao da expresso em lExpressao permanecer
verdadeiro (.T.). Cada palavra chave WHILE deve ter uma palavra
chave ENDDO correspondente.
Pgina 84
ADVPL 1
55..11..11..
IInnfflluueenncciiaannddoo oo fflluuxxoo ddee rreeppeettiioo
A linguagem ADVPL permite a utilizao de comandos que influem diretamente em um

processo de repetio, sendo eles:
LOOP
EXIT
LOOP
A instruo LOOP utilizada para forar um desvio no fluxo do programa de volta a anlise
da condio de repetio. Dessa 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
While nItens < nQuantidade
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
// Se o produto estiver bloqueado, o mesmo no ser impresso, pois a execuo da //

instruo LOOP far o fluxo do programa retornar a partir da anlise da condio.
Ttulo ADVPL 1
Pgina 85
EXIT
A instruo EXIT utilizada para forar o trmino de uma estrutura de repetio. Dessa forma,
todas as operaes que seriam realizadas dentro da estrutura de repetio aps o EXIT sero
desconsideradas, e o programa continuar a execuo a partir da prxima instruo posterior
ao trmino da estrutura (END ou NEXT).
Exemplo:
While .T.
IF MSGYESNO(Deseja jogar o jogo da forca?)

JFORCA() // Funo ilustrativa que implementa o algoritmo do jogo da forca.
ELSE
EXIT
ENDIF
End
MSGINFO(Final de Jogo)
// Enquanto no for respondido No para a pergunta: Deseja jogar o jogo da

// forca, ser executada a funo do jogo da forca.
// Caso seja selecionada a opo No, ser executada a instruo EXIT que provocar
o trmino do LOOP, permitindo a execuo da mensagem de Final de Jogo.
Pgina 86
ADVPL 1
5.2. Estruturas de deciso

As Estruturas de desvio so designadas para executar uma seo de cdigo se determinada
condio lgica resultar em verdadeiro (.T.).
Em ADVPL existem dois comandos para execuo de sees de cdigo, de acordo com as
avaliaes lgicas, que so os comandos IF...ELSE...ENDIF e o comando DO
CASE...ENDCASE.
O Comando IF...ELSE...ENDIF
Executa um conjunto de comandos baseado no valor de uma expresso lgica.
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
Parmetros
LExpressao
Especifica uma expresso lgica que avaliada. Se lExpressao resultar

em verdadeiro (.T.), qualquer comando seguinte ao IF e antecedente ao
ELSE ou ENDIF (o que ocorrer primeiro) ser executado.
Se lExpressao resultar em falso (.F.) e a clusula ELSE for definida,
qualquer comando aps essa clusula e anterior ao ENDIF ser
executada. Se a clusula ELSE no for definida, todos os comandos
entre o IF e o ENDIF sero ignorados. Nesse caso, a execuo do
programa continua com o primeiro comando seguinte ao ENDIF.
Comandos
Conjunto de comandos ADVPL que sero executados dependendo da

avaliao da expresso lgica em lExpressao.
Ttulo ADVPL 1
Pgina 87
possvel aninhar um bloco de comando IF...ELSE...ENDIF dentro

de outro bloco de comando IF...ELSE...ENDIF. Porm, para a
avaliao de mais de uma expresso lgica, deve-se utilizar o
comando DO CASE...ENDCASE, ou a verso estendida da
expresso IF...ELSE...ENDIF denominada IF...ELSEIF...ELSE...ENDIF.
Exemplo:
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
Endif
Return
Pgina 88
ADVPL 1
O Comando IF...ELSEIF...ELSE...ENDIF
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro

(.T.).
Sintaxe
IF lExpressao1
Comandos
[ELSEIF lExpressaoX
Comandos]
[ELSE
Comandos...]
ENDIF
Parmetros
lExpressao1
Especifica uma expresso lgica que avaliada. Se lExpressao resultar

em verdadeiro (.T.), executar os comandos compreendidos entre o IF e
a prxima expresso da estrutura (ELSEIF ou IF).
Se lExpressao resultar em falso (.F.), ser avaliada a prxima expresso
lgica vinculada ao comando ELSEIF, ou se o mesmo no existir, ser
executada a ao definida no comando ELSE.
lExpressaoX Especifica uma expresso lgica que ser avaliada para cada comando
ELSEIF. Esta expresso somente ser avaliada se a expresso lgica,
especificada no comando IF, resultar em falso (.F.).
Se a lExpressaoX avaliada resulte em falso (.F.) ser avaliada a prxima
expresso lExpressaoX, vinculada ao prximo comando ELSEIF, ou se o
mesmo no existir ser executada a ao definida para o comando
ELSE.
Comandos
Conjunto de comandos ADVPL que sero executados, dependendo da

avaliao da expresso lgica em lExpressao.
Ttulo ADVPL 1
Pgina 89
O campo IF...ELSE...ELSEIF...ENDIF possui a mesma estruturao de

deciso que pode ser obtida com a utilizao do comando DO
CASE...ENDCASE.
Pgina 90
ADVPL 1
Exemplo:
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
ElseIf Date() == dVencto
Alert("Vencimento na data!")
Else
Alert("Vencimento dentro do prazo!")
Endif
Return
O Comando DO CASE...ENDCASE
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro

(.T.).
Sintaxe
DO CASE
CASE lExpressao1
Comandos
[CASE lExpressao2
Comandos
...
CASE lExpressaoN
Comandos]
[OTHERWISE
Comandos]
ENDCASE
Ttulo ADVPL 1
Pgina 91
Parmetros
CASE
lExpressao1
Comandos...
Quando a primeira expresso CASE, resultante em verdadeiro (.T.), for

encontrada, o conjunto de comandos seguinte executado. A execuo
do conjunto de comandos continua at que a prxima clusula CASE,
OTHERWISE ou ENDCASE for encontrada. Ao terminar de executar esse
conjunto de comandos, a execuo continua com o primeiro comando
seguinte ao ENDCASE.
Se uma expresso CASE resultar em falso (.F.), o conjunto de comandos
seguinte a esta at a prxima clusula ignorado.
Apenas um conjunto de comandos executado. Estes so os primeiros
comandos cuja expresso CASE avaliada como verdadeiro (.T.). Aps a
execuo, qualquer outra expresso CASE posterior ignorada (mesmo
que sua avaliao resultasse em verdadeiro).
OTHERWISE
Comandos
Pgina 92
Se todas as expresses CASE forem avaliadas como falso (.F.), a clusula

OTHERWISE determina se um conjunto adicional de comandos deve ser
executado. Se essa clusula for includa, os comandos seguintes sero
executados e ento o programa continuar com o primeiro comando
seguinte ao ENDCASE. Se a clusula OTHERWISE for omitida, a
execuo continuar normalmente aps a clusula ENDCASE.
ADVPL 1
O Comando DO CASE...ENDCASE utilizado no lugar do comando

IF...ENDIF, quando um nmero maior do que uma expresso deve
ser avaliada, substituindo a necessidade de mais de um comando
IF...ENDIF aninhados.
Exemplo:
Local nMes
:= Month(Date())
Local cPeriodo := ""
DO CASE
CASE nMes <= 3
cPeriodo := "Primeiro Trimestre"
CASE nMes >= 4 .And. nMes <= 6
cPeriodo := "Segundo Trimestre"
CASE nMes >= 7 .And. nMes <= 9
cPeriodo := "Terceiro Trimestre"
OTHERWISE
cPeriodo := "Quarto Trimestre"
ENDCASE
Return
Ttulo ADVPL 1
Pgina 93
Exerccio 04
Desenvolver um programa que implemente o algoritmo de descascar batatas,
utilizando a estrutura de repetio FOR, demonstrando quantas batatas foram
descascadas:
Exerccio 05
Desenvolver um programa que implemente o algoritmo de descascar batatas,
utilizando a estrutura de repetio FOR, demonstrando quantas batatas faltam para
serem descascadas:
Exerccio 06
Desenvolver um programa que implemente o algoritmo do Jogo da Forca:
Exerccio 07
Desenvolver um programa que implemente o algoritmo do Jogo da Velha:
Pgina 94
ADVPL 1
Ttulo ADVPL 1
Pgina 95
6. ARRAYS E BLOCOS DE CDIGO

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:
Local aLetras
// Declarao da varivel
aLetras := {"A", "B", "C"} // Atribuio do array a varivel

Alert(aLetras[2])
// Exibe o segundo elemento do array
Alert(cValToChar(Len(aLetras))) // Exibe o tamanho do array
O ADVPL permite a manipulao de arrays facilmente. Enquanto que em outras linguagens

como C ou Pascal necessrio alocar memria para cada elemento de um array (o que
tornaria a utilizao de "ponteiros" necessria), o ADVPL se encarrega de gerenciar a memria
e torna simples adicionar elementos a um array, utilizando a funo AADD():
AADD(aLetras,"D") // Adiciona o quarto elemento ao final do array.

Alert(aLetras[4]) // Exibe o quarto elemento.
Alert(aLetras[5]) // Erro! No h um quinto elemento no array.
Arrays como Estruturas
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.}
Pgina 96
ADVPL 1
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 uma parte diferente de um 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
Ttulo ADVPL 1
Pgina 97
E considere mais alguns arrays para representar mais pessoas:
aFunct2 := {"Maria" , 22, .T.}

aFunct3 := {"Antnio", 42, .F.}
Os nomes podem ser impressos assim:
Alert(aFunct1[FUNCT_NOME])
Agora, ao invs de trabalhar com variveis individuais, possvel agrup-las em um outro

array, do mesmo modo que muitos registros so agrupados em uma tabela de banco de
dados:
aFuncts := {aFunct1, aFunct2, aFunct3}
Que equivalente a isso:
aFuncts := { {"Pedro" , 32, .T.}, ;

{"Maria" , 22, .T.}, ;
{"Antnio", 42, .F.} }
aFuncts 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
Pgina 98
ADVPL 1
A varivel nCount seleciona que funcionrio (ou que linha) de interesse. Ento a constante
FUNCT_NOME seleciona a primeira coluna daquela linha.
Cuidados com Arrays
Arrays so listas de elementos, portanto memria necessria para armazenar estas

informaes. Como estes arrays podem ser multidimensionais, a memria necessria ser a
multiplicao do nmero de itens em cada dimenso do array, considerando-se o tamanho
do contedo de cada elemento contido nesta. Portanto o tamanho de um array pode variar
muito.
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.
Ttulo ADVPL 1
Pgina 99
66..11..11..
IInniicciiaalliizzaannddoo aarrrraayyss
Algumas vezes o tamanho da matriz conhecido previamente. Outras vezes, o tamanho do

array somente ser conhecido em tempo de execuo.
Se o tamanho do array conhecido
Se o tamanho do array conhecido no momento que o programa escrito, h diversas

maneiras de implementar o cdigo:
01 Local nCnt
02 Local aX[10]
03 Local aY := Array(10)
04 Local aZ := {0,0,0,0,0,0,0,0,0,0}
05
06 For nCnt := 1 To 10
07
aX[nCnt] := nCnt * nCnt
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 criado 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.
2.
Na linha 03 utilizada a funo array com o parmetro 10 para criar o array, e o
retorno desta funo atribudo varivel aY. Na linha 03 efetuado o que se chama
"desenhar a imagen do array". Como se pode notar, existem dez 0s na lista encerrada entre
chaves ({}). Claramente, este mtodo no o utilizado para criar uma matriz de 1000
elementos.
Pgina 100
ADVPL 1
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.
Ttulo ADVPL 1
Pgina 101
Se o tamanho do array no conhecido
Se o tamanho do array no conhecido at o momento da execuo do programa, h

algumas maneiras de criar um array e adicionar elementos a ele. O exemplo a seguir ilustra a
idia da criao de um array vazio (sem nenhum elemento), e adio de elementos
dinamicamente.
01 Local nCnt
02 Local aX[0]
03 Local aY := Array(0)
04 Local aZ := {}
05
06 For nCnt := 1 To nSize
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.
3.
Na linha 04 est declarada a representao de um array vazio em ADVPL. Mais uma
vez, esto sendo utilizadas as chaves para indicar que o tipo de dados da varivel array.
Note que {} um array vazio (tem o tamanho 0), enquanto {Nil} um array com um nico
elemento nulo (tem tamanho 1).
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).
Pgina 102
ADVPL 1
66..11..22..
FFuunneess ddee m
maanniippuullaaoo ddee aarrrraayyss
A linguagem ADVPL possui diversas funes que auxiliam na manipulao de arrays, dentre
as quais podemos citar as mais utilizadas:
ARRAY()
AADD()
ACLONE()
ADEL()
ASIZE()
AINS()
ASORT()
ASCAN()
Ttulo ADVPL 1
Pgina 103
ARRAY()
Sintaxe
ARRAY(nLinhas, nColunas)
Descrio
A funo Array() utilizada na definio de variveis de tipo array, como uma

opo a sintaxe, utilizando chaves ({}).
AADD()
Sintaxe
AADD(aArray, xItem)
Descrio
A funo AADD() permite a insero de um item em um array j existente, sendo

que este item pode ser um elemento simples, um objeto, ou outro array.
ACLONE()
Sintaxe
AADD(aArray)
Descrio
A funo ACLONE() realiza a cpia dos elementos de um array para outro array
integralmente.
ADEL()
Sintaxe
ADEL(aArray, nPosio)
Descrio
A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a

excluso de um elemento, todos os demais so reorganizados de forma que a
ultima posio do array passar a ser nula.
ASIZE()
Sintaxe
ASIZE(aArray, nTamanho)
Descrio
A funo ASIZE permite a redefinio da estrutura de um array pr-existente,
Pgina 104
ADVPL 1
adicionando ou removendo itens do mesmo.
ASORT()
Sintaxe
ASORT(aArray, nInicio, nItens, bOrdem)
Descrio
A funo ASORT() permite que os itens de um array sejam ordenados, a partir de

um critrio pr-estabelecido.
Ttulo ADVPL 1
Pgina 105
ASCAN()
Sintaxe
ASCAN(aArray, bSeek)
Descrio
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.
AINS()
Sintaxe
Descrio
66..11..33..
AINS(aArray, nPosicao)
A funo AINS() permite a insero de um elemento, no array especificado, em
qualquer ponto da estrutura do mesmo, diferindo desta forma da funo
AADD(), a qual sempre insere um novo elemento ao final da estrutura j
existente.
CCppiiaa ddee aarrrraayyss
Conforme comentado anteriormente, um array uma rea na memria, o qual possui uma
estrutura que permite as informaes serem 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 obtido na execuo da cpia.
Pgina 106
ADVPL 1
Para copiar o contedo de uma varivel, utiliza-se o operador de atribuio :=, conforme
abaixo:
nPessoas := 10
nAlunos := nPessoas
Ao executar a atribuio de nAlunos com o contedo de nPessoas, o contedo de nPessoas

atribudo a varivel nAlunos, causando o efeito de cpia do contedo de uma varivel para
outra.
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:
aPessoas := {Ricardo, Cristiane, Andr, Camila}

aAlunos := aPessoas
A varivel aPessoas representa uma rea de memria que contm a estrutura de um array
(mapa), no as informaes do array, pois cada informao est em sua prpria rea de
memria.
Ttulo ADVPL 1
Pgina 107
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, em que as
informaes esto realmente armazenadas.
Como foi copiado o mapa e no as informaes, qualquer ao utilizando o rtulo aAlunos

afetar as informaes do rtulo aPessoas. Com isso ao invs de se obter dois arrays distintos,
tem-se o mesmo array com duas formas de acesso (rtulos) diferentes.
Por esta razo deve ser utilizado o comando ACLONE(), quando se deseja obter um array com
a mesma estrutura e informaes que compe outro array j existente.
Pgina 108
ADVPL 1
Ttulo ADVPL 1
Pgina 109
6.2. Listas de Expresses e Blocos de Cdigo

Bloco de cdigo um conceito existente h muito tempo em linguagens xBase. No como
algo que apareceu da noite para o dia, e sim uma evoluo progressiva utilizando a
combinao de muitos conceitos da linguagem para a sua implementao.
66..22..11..
PPrreem
miissssaass ppaarraa uuttiilliizzaaoo ddee B
Bllooccooss ddee CCddiiggoo
Primeira premissa
O ADVPL uma linguagem baseada em funes. Funes tm um valor de retorno. Assim

como o operador de atribuio :=.
Assim, ao invs de escrever:
x := 10 // Atribui o valor 10 varivel chamada X

Alert("Valor de x: " + cValToChar(x))
Escreve-se:
// Atribui e ento exibe o valor da varivel X

Alert("Valor de x: " + cValtoChar(X := 10))
A expresso x:=10 avaliada primeiro, e ento seu resultado (o valor de X, que agora 10)
passada para a funo cvaltochar para a converso para caractere, e em seguida para a
funo alert para a exibio. Por causa dessa 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) )
Pgina 110
ADVPL 1
Apesar de o ADVPL avaliar expresses da esquerda para a direita, no caso de atribuies,

acontece ao contrrio, ou seja, da direita para a esquerda. O valor atribudo varivel X, que
retorna o valor para ser atribudo varivel Y e assim sucessivamente. O zero foi "propagado
atravs da expresso".
Segunda premissa
Em ADVPL junta-se 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. possvel
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, consequentemente, a sua
manuteno.
Ttulo ADVPL 1
Pgina 111
66..22..22..
LLiissttaa ddee eexxpprreesssseess
A evoluo dos blocos de cdigo comea com as listas de expresses. Nos exemplos a seguir,
o smbolo ==> indicar o retorno da expresso aps a sua avaliao (seja para atribuir em
uma varivel, exibir para o usurio ou imprimir em um relatrio), que ser impressa em um
relatrio, por exemplo.
Duas Linhas de Cdigo
@00,00 PSAY x := 10
==>
10
@00,00 PSAY y := 20
==>
20
Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento impresso.
Duas linhas de cdigo em uma , utilizando -se ponto-e-vrgula
Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:
Alert( cValToChar( x := 10 ; y := 20 ) )
==>
10
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.
Pgina 112
ADVPL 1
Convertendo para uma lista de expresses
Quando parnteses so colocados ao redor do cdigo e o sinal de ponto-e-vrgula

substitudo por uma vrgula apenas, o cdigo torna-se uma lista de expresses:
Alert( cValToChar ( ( X := 10 , Y := 20 ) ) ) ==> 20
O valor de retorno resultante de uma lista de expresses o valor resultante da ltima

expresso ou elemento da lista. Funciona como se fosse um pequeno programa ou funo,
que retorna o resultado de sua ltima avaliao (efetuadas da esquerda para a direita).
Nesse exemplo, a expresso x := 10 avaliada, e ento a expresso y := 20, cujo valor

resultante passado para a funo alert e cvaltochar, e ento exibido. Depois que essa linha
de cdigo executada, o valor de X igual a 10 e o de y igual a 20, e 20 ser exibido.
Teoricamente, no h limitao para o nmero de expresses que podem ser combinadas em

uma lista Na prtica, o nmero mximo por volta de 500 smbolos.
Debugar listas de expresses difcil porque as expresses no esto divididas em linhas de
cdigo fonte, o que torna todas as expresses associadas a uma mesma linha de cdigo. Isto
pode tornar muito difcil determinar onde um erro ocorreu.
Onde utilizar uma lista de expresses?

O propsito principal de uma lista de expresses agrup-las em uma nica unidade. Em
qualquer lugar do cdigo ADVPL, em que uma expresso simples pode ser utilizada, pode-se
utilizar uma lista de expresses. E ainda, fazer com que vrias coisas aconteam onde
normalmente apenas uma aconteceria.
X := 10 ; Y := 20
If X > Y
Alert("X")
Z := 1
Else
Alert("Y")
Z := -1
Endif
Ttulo ADVPL 1
Pgina 113
Aqui temos o mesmo conceito, escrito utilizando listas de expresses na funo IIF():
X := 10 ; Y := 20
iif( X > Y , ;
( Alert("X"), Z := 1 ) , ;
( Alert("Y"), Z := -1 ) )
De listas de expresses para blocos de cdigo
Considere a seguinte lista de expresses:
Alert( cValToChar( ( x := 10, y := 20 ) ) ) ==> 20
O ADVPL permite criar funes, que so pequenas partes de um cdigo, como se fosse um
pequeno programa, utilizados para diminuir em partes de tarefas mais complexas e
reaproveitar cdigo em mais de um lugar num programa. Para maiores detalhes consulte a
documentao sobre a criao de funes em ADVPL. Porm, a idia neste momento que a
lista de expresses, utilizada na linha anterior, pode ser criada como uma funo:
Function Lista()
X := 10
Y := 20
Return Y
E a linha de exemplo, com a lista de expresses, pode ser substituda, tendo o mesmo
resultado, por:
Alert( cValToChar( Lista() ) ) ==> 20
Como mencionado anteriormente, uma lista de expresses como um pequeno programa ou

funo. Com poucas mudanas, uma lista de expresses pode se tornar um bloco de cdigo:
( X := 10 , Y := 20 ) // Lista de Expresses
{|| X := 10 , Y := 20 } // Bloco de Cdigo
Pgina 114
ADVPL 1
Note as chaves {} utilizadas no bloco de cdigo. Ou seja, um bloco de cdigo uma matriz.
Porm na verdade, no uma lista de dados, e sim uma lista de comandos, uma lista de
cdigo.
// Isto uma matriz de dados

A := {10, 20, 30}
// Isto um bloco de cdigo, porm funciona como // se fosse uma matriz de comandos
B := {|| x := 10, y := 20}
Ttulo ADVPL 1
Pgina 115
66..22..33..
B
Bllooccooss ddee CCddiiggoo
Diferentemente de uma matriz, no se pode acessar elementos de um bloco de cdigo,

atravs de um ndice numrico. Porm blocos de cdigo so semelhantes a uma lista de
expresses, e a uma pequena funo.
Ou seja, podem ser executados. Para a execuo, ou avaliao de um bloco de cdigo, devese utilizar a funo Eval():
nRes := Eval(B) ==> 20
Essa funo recebe como parmetro um bloco de cdigo e avalia todas as expresses
contidas neste bloco de cdigo, retornando o resultado da ltima expresso avaliada.
Passando Parmetros
J que os blocos de cdigo so como pequenas funes, tambm possvel a passagem de

parmetros para um bloco de cdigo. Os parmetros devem ser informados entre as barras
verticais (||), separados por vrgulas, assim como em uma funo.
B := {| N | X := 10, Y := 20 + N}
Porm deve-se notar que j que o bloco de cdigo recebe um parmetro, um valor deve ser
passado quando o bloco de cdigo for avaliado.
C := Eval(B, 1) ==> 21
Utilizando Blocos de Cdigo
Blocos de cdigo podem ser utilizados em diversas situaes. Geralmente so utilizados para
executar tarefas quando os eventos de objetos so acionados ou, para modificar o
comportamento padro de algumas funes. Como no exemplo, considere a matriz abaixo:
A := {"GARY HALL", "FRED SMITH", "TIM JONES"}
Pgina 116
ADVPL 1
Esta matriz pode ser ordenada pelo primeiro nome, utilizando-se a chamada da funo
asort(A), resultado na matriz com os elementos ordenados dessa forma:
{"FRED SMITH", "GARY HALL", "TIM JONES"}
A ordem padro para a funo asort ascendente. Este comportamento pode ser modificado
atravs da informao de um bloco de cdigo que ordena a matriz de forma descendente:
B := { |X, Y| X > Y }
aSort(A, B)
O bloco de cdigo (de acordo com a documentao da funo asort) deve ser escrito para
aceitar dois parmetros que so os dois elementos da matriz para comparao. Note que o
bloco de cdigo no conhece que elementos esto 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 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, possvel
utilizar o seguinte bloco de cdigo:
B := { |X, Y| SUBSTR(X, At(" ",X)+1) > SUBSTR(Y, At(" ",Y)+1) }
Note que este bloco de cdigo procura e compara as partes dos caracteres, imediatamente
seguinte a um espao em branco. Depois de utilizar esse bloco de cdigo para a funo asort,
a matriz conter:
{"GARY HALL", "TIM JONES", "FRED SMITH"}
Ttulo ADVPL 1
Pgina 117
Finalmente, para ordenar um sub-elemento (coluna) de uma matriz por exemplo, utiliza-se o
seguinte bloco de cdigo:
B := { |X, Y| X[1] > Y[1] }
Pgina 118
ADVPL 1
66..22..44..
FFuunneess ppaarraa m
maanniippuullaaoo ddee bbllooccooss ddee ccddiiggoo
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()
Sintaxe
EVAL(bBloco, xParam1, xParam2, xParamZ)
Descrio
A funo EVAL() utilizada para a avaliao direta de um bloco de cdigo,

utilizando as informaes disponveis no momento de sua execuo. Esta funo
permite a definio e passagem de diversos parmetros que sero considerados
na interpretao do bloco de cdigo.
DBEVAL()
Sintaxe
Array(bBloco, bFor, bWhile)
Descrio
A funo DBEval() permite que todos os registros, de uma determinada tabela,

sejam analisados e para cada registro ser executado o bloco de cdigo
definido.
AEVAL()
Sintaxe
AEVAL(aArray, bBloco, nInicio, nFim)
Descrio
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.
Ttulo ADVPL 1
Pgina 119
Pgina 120
ADVPL 1
7. FUNES
A maior parte das rotinas escritas em programas so compostas de um conjunto de
comandos. Essas rotinas se repetem ao longo de todo o desenvolvimento. Uma funo
nada mais do que um conjunto de comandos que para ser utilizada, basta cham-la pelo
seu nome.
Para tornar uma funo mais flexvel, ao cham-la possvel a passagem de parmetros, que
contm os dados e as informaes que definem o processamento da funo.
Os parmetros das funes descritas utilizando a linguagem ADVPL so posicionais, ou seja,

na sua passagem no importa o nome da varivel e sim a sua posio dentro da lista de
parmetros, que permite executar uma funo escrevendo:
Calcula(parA, parB, parC) // Chamada da funo em uma rotina
E a funo deve estar escrita assim:
User Function Calcula(x, y, z)
... Comandos da Funo
Return ...
Neste caso, x assume o valor de parA, y de parB e z de parC.
A funo tambm tem a faculdade de retornar uma varivel, podendo inclusive ser um Array.
Para tal, encerra-se a funo com:
Return(campo)
Assim A := Calcula(parA,parB,parC) atribui a A o contedo do retorno da funo

Calcula.
Ttulo ADVPL 1
Pgina 121
No ADVPL existem milhares de funes escritas pela equipe de Tecnologia Microsiga,

pelos analistas de suporte e pelos prprios usurios.
Existe um ditado que diz:
Vale mais um programador que conhece todas as funes

disponveis em uma linguagem do que aquele que, mesmo sendo
gnio, reinventa a roda a cada novo programa.
No TDN (TOTVS Developer Network) mais de 500 esto documentadas, e este nmero
tende a aumentar exponencialmente com os novos processos de documentao que esto
em implantao na Tecnologia e Inteligncia Protheus.
O objetivo do curso apresentar, demonstrar e fixar a utilizao das principais funes,

sintaxes e estruturas utilizadas em ADVPL.
No ADVPL at os programas chamados pelo menu so funes, sendo que em um repositrio

no pode haver funes com o mesmo nome e para permitir que os usurios e analistas
possam desenvolver suas prprias funes sem que as mesmas conflitem com as j
disponveis no ambiente ERP, foi implementada pela Tecnologia Microsiga um tipo especial
de funo denominado User Function.
Nos tpicos a seguir sero detalhados os tipos de funes disponveis na linguagem ADVPL,
suas formas de utilizao e respectivas diferenas.
Pgina 122
ADVPL 1
20
7.1. Tipos e escopos de funes

Em ADVPL podem ser utilizados os seguintes tipos de funes:

Function()
User Function()
Static Function()
Main Function()
Function()
Funes ADVPL convencionais, restritas ao desenvolvimento da rea de Inteligncia Protheus

da Microsiga.
O interpretador ADVPL distingue os 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
Ttulo ADVPL 1
Pgina 123
Ao executar a funo MATA100INCL01() ser exibida a mensagem 01, mas ao executar a

funo MATA100INCL02() tambm ser exibida a mensagem 01, pois o interpretador
considera o nome da funo como MATA100INC.
Funes do tipo Function() somente podem ser executadas atravs

dos mdulos do ERP.
Somente podero ser compiladas funes do tipo Function() se o

MP-IDE possuir uma autorizao especial fornecida pela
Microsiga.
Funes do tipo Function() so acessveis por quaisquer outras

funes em uso pela aplicao.
User Function()
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.
Como ocorre o acrscimo dos caracteres U_ no nome da funo

e o interpretador considera apenas os dez primeiros caracteres da
funo, para sua diferenciao recomendado que os nomes das
User Functions tenham apenas oito caracteres, evitando
Pgina 124
ADVPL 1
resultados indesejados durante a execuo da aplicao.

Funes do tipo User Function so acessveis por quaisquer outras
funes em uso pela aplicao, desde que em sua chamada sejam
utilizados os caracteres U_, em conjunto com o nome da funo.
As User Functions podem ser executadas a partir da tela inicial do client

do ERP (Microsiga Protheus Remote), mas as aplicaes que pretendem
disponibilizar esta opo devem possuir um preparo adicional de
ambiente.
Para maiores informaes consulte no TDN o tpico sobre preparao de

ambiente e a documentao sobre a funo RpcSetEnv().
Ttulo ADVPL 1
Pgina 125
Static Function()
Funes ADVPL tradicionais, cuja visibilidade est restrita s funes descritas no mesmo
arquivo de cdigo fonte no qual esto definidas.
Exemplo:
//Fonte FINA010.PRW
Function FINA010()
CriaSx1(FIN010)
Return
Static Function CRIASX1()

//Fonte FINA020.PRW
Function FINA020()
CriaSx1(FIN020)
Return
Static Function CRIASX1()
No exemplo acima, existem duas funes denominadas CRIASX1(), definidas em arquivos de

cdigo fonte distintos: FINA010.PRW e FINA020.PRW.
A funo FINA010() ter visibilidade apenas da funo CRIASX1(), definida no arquivo de

cdigo fonte FINA010.PRW, sendo que o mesmo ocorre com a funo FINA020().
Este recurso permite isolar funes de uso exclusivo de um arquivo de cdigo fonte, evitando
a sobreposio ou a duplicao de funes na aplicao.
Neste contexto as Static Functions() so utilizadas para:
Pgina 126
ADVPL 1
1. Padronizar o nome de uma determinada funo, que possui a mesma finalidade, mas
que sua implementao pode variar de acordo com a necessidade da funo principal
/ aplicao.
2. Redefinir uma funo padro da aplicao, adequando-a s necessidades especficas

de uma funo principal / aplicao.
3. Proteger as funes de uso especfico de um arquivo de cdigo fonte / funo

principal.
O Ambiente de desenvolvimento utilizado na aplicao ERP (MPIDE) valida se existem Functions(), Main Functions() ou User
Functions() com o mesmo nome, mas em arquivos de cdigos
fontes distintos, evitando a duplicidade ou sobreposio de
funes.
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 Inteligncia Protheus da
Totvs.
Na aplicao ERP comum o uso das Main Functions(), nas seguintes situaes:
1. Definio dos mdulos da aplicao ERP: Main Function Sigaadv()
2. Definio de atualizaes e updates: AP710TOMP811()
3. Atualizaes especficas de mdulos da aplicao ERP: UpdateATF()

Ttulo ADVPL 1
Pgina 127
7.2. Passagem de parmetros entre funes

Como mencionado anteriormente os parmetros das funes descritas, utilizando a
linguagem ADVPL so posicionais, ou seja, na sua passagem no importa o nome da varivel
e sim a sua posio dentro da lista de parmetros.
Complementando esta definio, podem ser utilizadas duas formas distintas de passagens de
parmetros para funes descritas na linguagem ADVPL:
Passagem de parmetros por contedo.

Passagem de parmetros por referncia.
Passagem de parmetros por contedo
A passagem de parmetros por contedo a forma convencional de definio dos

parmetros recebidos pela funo chamada, na qual a funo recebe os contedos passados
pela funo chamadora, na ordem com os quais so informados.
User Function CalcFator(nFator)
Local nCnt
Local nResultado := 0

nResultado *= nCnt
Next nCnt

Return
Pgina 128
ADVPL 1
Avaliando a funo CalcFator() descrita anteriormente, podemos verificar que a mesma recebe
como parmetro para a sua execuo varivel nFator.
Com base nesta funo, podemos descrever duas formas de passagem de parmetros por
contedo:
Passagem de contedos diretos.

Passagem de variveis como contedos.
Exemplo 01 Passagem de contedos diretos
User Function DirFator()
nResultado := CalcFator(5)
A passagem de contedos diretos implica na definio explcita do valor do parmetro, na

execuo da chamada da funo. Nesse caso foi informado o contedo 5 (numrico) como
contedo para o primeiro parmetro da funo CalcFator.
Como a linguagem ADVPL trata os parmetros de forma posicional, o contedo 5 ser

atribudo diretamente varivel, definida como primeiro parmetro da funo chamada. 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.
Ttulo ADVPL 1
Pgina 129
Duas caractersticas da linguagem ADVPL tornam necessria uma

ateno especial na chamada de funes:
A linguagem ADVPL no uma linguagem tipada, de forma

que as variveis no tem um tipo previamente definido, aceitando
o contedo que lhes for imposto por meio de uma atribuio.
Os parmetros de uma funo so atribudos de acordo com a

ordem em que tais parmetros so definidos na chamada desta
ordem. No realizado nenhum tipo de consistncia em relao
aos tipos dos contedos, e a obrigatoriedade de parmetros nesta
ao.
Os parmetros de uma funo so caracterizados como variveis de

escopo LOCAL para efeito de execuo.
Dessa forma os mesmos no devem ser definidos novamente como LOCAL,

na rea de definio e inicializao de variveis, pois se isso ocorrer
haver a perda dos valores recebidos pela redefinio das variveis na
funo.
Se for necessrio garantir um contedo padro para um determinado

parmetro, deve ser utilizado o identificador DEFAULT, conforme
detalhamento no tpico Tratamento de valores padres para parmetros
de funes.
Exemplo 02 Passagem de variveis como contedos
Pgina 130
ADVPL 1
Local nFatorUser := 0
nFatorUser := GetFator() // Funo ilustrativa na qual o usurio informa o fator a ser utilizado.
nResultado := CalcFator(nFatorUser)
A passagem de contedos como variveis implica na utilizao de variveis de apoio para

executar a chamada de uma funo. Nesse caso foi informada a varivel nFatorUser, a qual
ser definida pelo usurio com a utilizao da funo ilustrativa GetFator(). O uso de variveis
de apoio flexibiliza a chamada de outras funes, pois elas sero parametrizadas de acordo
com as necessidades daquele processamento especfico, no qual se encontra a funo
chamadora.
Como a linguagem ADVPL trata os parmetros de forma posicional, o contedo da varivel

nFatorUser ser atribudo diretamente varivel definida como primeiro parmetro da funo
chamada, no caso nFator.
Por ser uma atribuio de parmetros por contedo, o interpretador da linguagem

basicamente executa uma operao de atribuio normal, ou seja, nFator := nFatorUser.
Ttulo ADVPL 1
Pgina 131
A passagem de parmetros no necessita que as variveis informadas na

funo chamadora tenham os mesmos nomes das variveis utilizadas na
definio de parmetros da funo chamada.
Dessa forma podemos ter:
Local nFatorUser := GetFator()
nResultado := CalcFator(nFatorUser)
Function CalcFator(nFator)
As variveis nFatorUser e nFator podem ter nomes diferentes pois o
interpretador far a atribuio de contedo com base na ordem dos
parmetros e no pelo nome das variveis.
Pgina 132
ADVPL 1
Passagem de parmetros por referncia

A passagem de parmetros por referncia uma tcnica muito comum nas linguagens de
programao, pois permite que variveis de escopo LOCAL tenham o seu contedo
manipulado por funes especficas, mantendo o controle dessas variveis restritas
funo que as definiu e s 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.
Passagem de parmetros tradicional Duas variveis x Duas reas de memria
Ttulo ADVPL 1
Pgina 133
Passagem de parmetros por referncia Duas variveis x uma nica rea de memria
Pgina 134
ADVPL 1
Dessa forma, a funo chamada tem acesso no apenas ao contedo, mas varivel em
si, pois a rea de memria a varivel e qualquer alterao ser visvel funo
chamadora quando tiver o retorno desta funo.
Tratamento de contedos padres para os parmetros de funes

O tratamento de contedos padro para parmetros de funes muito utilizado nas
funes padres da aplicao ERP, de forma a garantir a correta execuo dessas funes
por qualquer funo chamadora, evitando situaes de ocorrncias de erros pela falta da
definio de parmetros necessrios correta utilizao da funo.
A linguagem ADVPL no obriga a passagem de todos os parmetros

descritos na definio da funo, sendo que os parmetros no
informados sero considerados com contedo nulo.
Dessa forma, o uso do identificador DEFAULT permite ao desenvolvedor a garantia de

que, na utilizao da funo, determinados parmetros tero o valor com um tipo
adequado funo.
Exemplo:
Local nCnt
Default nFator := 1

nResultado *= nCnt
Next nCnt
Ttulo ADVPL 1
Pgina 135
Return nResultado
No exemplo descrito, se o parmetro nFator no for informado na funo chamadora, o

mesmo ter seu contedo definido como 1.
Se esse tratamento no fosse realizado e com isso o parmetro nFator no fosse
informado, ocorreria o seguinte evento de erro:
Exemplo:
Local nCnt
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
Como o interpretador realizar a ao nCnt += 1, e o contedo da varivel nCnt nulo,

ocorrer o erro de type mismath on +=, expected N U, pois os tipos das variveis
envolvidos na operao so diferentes: nCnt nulo (U) e 1 numrico (N).
Se o parmetro que possui a opo DEFAULT, descrita no fonte, for

informado, a linha de DEFAULT no ser executada, mantendo-se dessa
forma o contedo passado pela funo chamadora.
Pgina 136
ADVPL 1
Ttulo ADVPL 1
Pgina 137
8. DIRETIVAS DE COMPILAO
O compilador ADVPL possui uma funcionalidade denominada pr-processador. O prprocessador um programa que examina o programa fonte escrito em ADVPL e executa
certas modificaes nele, baseadas nas Diretivas de Compilao.
As diretivas de compilao so comandos que no so compilados, sendo dirigidos ao prprocessador, o qual executado pelo compilador antes da execuo do processo de
compilao propriamente dito. Portanto, o pr-processador modifica o programa fonte,
entregando para o compilador um programa modificado de acordo com as diretivas de
compilao. Estas so iniciadas pelo caractere #.
As diretivas podem ser colocadas em qualquer parte do programa, sendo que as

implementadas pela linguagem ADVPL so:

#INCLUDE
#DEFINE
#IFDEF
#IFNDEF
#ELSE
#ENDIF
#COMMAND
As diretivas de compilao tambm so conhecidas como UDC User

Defined Commands.
Lem
brese
Diretiva: #INCLUDE
A diretiva #INCLUDE indica em que arquivo de extenso CH (padro ADVPL) esto os UDCs
a serem utilizados pelo pr-processador.
Pgina 138
ADVPL 1
A aplicao ERP possui diversos includes que devem ser utilizados segundo a aplicao que
ser desenvolvida. Dessa forma, ser permitida a utilizao de recursos adicionais definidos
para a linguagem, implementados pela rea de Tecnologia da Totvs.
Os includes mais utilizados nas aplicaes ADVPL, desenvolvidas para o ERP so:
PROTHEUS.CH: Diretivas de compilao como padres para a linguagem. Contm a

especificao da maioria das sintaxes utilizadas nos fontes, inclusive permitindo a
compatibilidade da sintaxe tradicional do Clipper para os novos recursos
implementados no ADVPL.
Ttulo ADVPL 1
Pgina 139
O include PROTHEUS.CH ainda contm a referncia a outros includes utilizados pela

linguagem ADVPL que complementam essa funcionalidade de compatibilidade com a
sintaxe Clipper, tais como:
o
o
o
o
o
DIALOG.CH
FONT.CH
INI.CH
PTMENU.CH
PRINT.CH
A utilizao do include protheus.ch, nos fontes

desenvolvidos para a aplicao ERP Protheus, obrigatria e
necessria ao correto funcionamento das aplicaes
Fiqu
atento
AP5MAIL.CH: Permite a utilizao da sintaxe tradicional na definio das seguintes

funes de envio e recebimento de e-mail:
o
o
o
o
o
o
o
o
CONNECT SMTP SERVER

CONNECT POP SERVER
DISCONNECT SMTP SERVER
DISCONNECT POP SERVER
POP MESSAGE COUNT
SEND MAIL FROM
GET MAIL ERROR
RECEIVE MAIL MESSAGE
TOPCONN.CH: Permite a utilizao da sintaxe tradicional na definio das seguintes

funes de integrao com a ferramenta TOPCONNECT (MP10 DbAcess):
TCQUERY
TBICONN.CH: Permite a utilizao da sintaxe tradicional na definio de conexes,

com a aplicao Server do ambiente ERP, atravs das seguintes sintaxes:
Pgina 140
ADVPL 1
o
o
o
o
o
o
o
o
CREATE RPCCONN
CLOSE RPCCONN
PREPARE ENVIRONMENT
RESET ENVIRONMENT
OPEN REMOTE TRANSACTION
CLOSE REMOTE TRANSACTION
CALLPROC IN
OPEN REMOTE TABLES
XMLXFUN.CH: Permite a utilizao da sintaxe tradicional, na manipulao de arquivos

e strings no padro XML, atravs das seguintes sintaxes:
o
o
o
o
o
o
o
CREATE XMLSTRING
CREATE XMLFILE
SAVE XMLSTRING
SAVE XMLFILE
ADDITEM TAG
ADDNODE NODE
DELETENODE
Os recursos de tratamentos de e-mails, integrao com a

ferramenta TOPCONNECT (DbAcess), preparao de ambientes e
manipulao de arquivos e strings do padro XML, sero
abordados no curso de ADVPL Avanado.
Ttulo ADVPL 1
Pgina 141
O diretrio de includes deve ser especificado no Ambiente de

desenvolvimento do ERP Protheus (MP-IDE), para cada configurao de
compilao disponvel.
Se o diretrio de includes no estiver informado, ou esteja informado

incorretamente, ser exibida uma mensagem de erro informando:
No foi possvel criar o arquivo <caminho\nome> .ERX
As funes desenvolvidas para a aplicao ERP costumam utilizar

includes, para definir o contedo de strings e as variveis diversas,
utilizadas pela aplicao em diferentes idiomas. Dessa forma normal
verificar que um fonte possui um arquivo.CH com o mesmo nome, o
que caracteriza esse tipo de include.
Diretiva: #DEFINE
A diretiva #DEFINE permite que o desenvolvedor crie novos termos para serem utilizados 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.
Dessa forma, um termo definido atravs da diretiva #DEFINE pode ser considerado como uma
constante.
Os arquivos de include definidos para os fontes da aplicao ERP contm

diretivas #DEFINE para as strings de textos de mensagens exibidas para
os usurios nos trs idiomas com os quais a aplicao distribuda:
Pgina 142
ADVPL 1
Portugus, Ingls e Espanhol.
Por essa 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.
Ttulo ADVPL 1
Pgina 143
Diretivas: #IFDEF, IFNDEF, #ELSE e #ENDIF
As diretivas #IFDEF, #IFNDEF, #ELSE e #ENDIF permitem ao desenvolvedor criar fontes

flexveis e sensveis a determinadas configuraes da aplicao ERP.
Com essas 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. Assim, 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, que ir gerar um cdigo
compilado de acordo com a anlise dos parmetros de ambiente.
Essas diretivas de compilao esto normalmente associadas s seguintes verificaes de

ambiente:
Idioma: verifica as variveis SPANISH e ENGLISH, disponibilizadas pela aplicao. O

idioma portugus determinado pela exceo:
#IFDEF SPANISH
#DEFINE STR0001 Hola !!!
#ELSE
#IFDEF ENGLISH
#DEFINE STR0001 Hello !!!
#ELSE
#DEFINE STR0001 Ol !!!
#ENDIF
#ENDIF
Pgina 144
ADVPL 1
Apesar da estrutura semelhante ao IF-ELSE-ELSEIF-ENDIF, no

existe a diretiva de compilao #ELSEIF, o que torna necessrio o
uso de diversos #IFDEFs para a montagem de uma estrutura que
seria facilmente solucionada com IF-ELSE-ELSEIF-ENDIF.
A aplicao ERP disponibiliza para a varivel de escopo

PUBLIC - __LANGUAGE, que contm uma string que
identifica o idioma em uso pelo Sistema, cujos contedos
possveis so:
PORTUGUESE
SPANISH
ENGLISH
Banco de Dados: Verifica as variveis AXS e TOP para determinar se o banco de dados
em uso pela aplicao est no formado ISAM (DBF, ADS, CTREE, etc.) ou, se est
utilizando a ferramenta TOPCONNECT (DbAcess).
#IFDEF TOP
cQuery := SELECT * FROM +RETSQLNAME(SA1)

dbUseArea(.T., "TOPCONN", TcGenQry(,,cQuery), SA1QRY,.T.,.T.)
#ELSE
DbSelectArea(SA1)
#ENDIF
Ttulo ADVPL 1
Pgina 145
Os bancos de dados padro AS400 no permitem a execuo de

queries no formato SQLANSI, atravs da ferramenta
TOPCONNECT (DbAcess).
Dessa forma necessrio realizar uma verificao adicional ao

#IFDEF TOP antes de executar uma query, que no caso
realizada atravs do uso da funo TcSrvType(), a qual retorna
a string AS/400, quando este for o banco em uso.
Para esses bancos deve ser utilizada a sintaxe ADVPL

tradicional.
Diretiva: #COMMAND
A diretiva #COMMAND utilizada principalmente nos includes da linguagem ADVPL para

efetuar a traduo de comandos em sintaxe CLIPPER, para as funes implementadas pela
Tecnologia Microsiga.
Essa diretiva permite que o desenvolvedor defina para o compilador como uma expresso
deve ser interpretada.
Trecho do arquivo PROTHEUS.CH
#xcommand @ <nRow>, <nCol> SAY [ <oSay> <label: PROMPT,VAR > ] <cText> ;

[ PICTURE <cPict> ] ; [ <dlg: OF,WINDOW,DIALOG > <oWnd> ] ;
[ FONT <oFont> ] ; [ <lCenter: CENTERED, CENTER > ] ;
[ <lRight: RIGHT > ] ; [ <lBorder: BORDER > ] ;
[ <lPixel: PIXEL, PIXELS > ] ; [ <color: COLOR,COLORS > <nClrText> [,<nClrBack> ] ] ;
[ SIZE <nWidth>, <nHeight> ] ; [ <design: DESIGN > ] ;
[ <update: UPDATE > ] ; [ <lShaded: SHADED, SHADOW > ] ;
[ <lBox: BOX > ] ; [ <lRaised: RAISED > ] ;
=> ;
Pgina 146
ADVPL 1
[ <oSay> := ] TSay():New( <nRow>, <nCol>, <{cText}>,;

[<oWnd>], [<cPict>], <oFont>, <.lCenter.>, <.lRight.>, <.lBorder.>,;
<.lPixel.>, <nClrText>, <nClrBack>, <nWidth>, <nHeight>,;
<.design.>, <.update.>, <.lShaded.>, <.lBox.>, <.lRaised.> )
Atravs da diretiva #COMMAND, o desenvolvedor determinou as regras para que a sintaxe

tradicional da linguagem CLIPPER, para o comando SAY, fosse convertida na especificao de
um objeto TSAY() do ADVPL.
Ttulo ADVPL 1
Pgina 147
Exerccio 08
Vamos Desenvolver um programa que permita ao usurio pesquisar um cliente,
informando seu CNPJ e se o mesmo existir na base, exibir suas principais
informaes.
Exerccio 09
Utilizando a interface visual desenvolvida para o exerccio anterior, desenvolver a
funo genrica GetTexto(), para ser utilizada nas aplicaes do Jogo da Velha e
Jogo da Forca.
Exerccio 10
Utilizando a interface visual desenvolvida para o exerccio anterior, desenvolver a
funo genrica GetTexto(), para ser utilizada nas aplicaes do Jogo da Velha e
Jogo da Forca.
Exerccio 11
Utilizando a funo AVISO(), desenvolver um programa que permita ao usurio
selecionar a opo de busca de CNPJ por cliente ou fornecedor, e se encontrar,
exiba os seus dados principais.
Pgina 148
ADVPL 1
Exerccio 12
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 dados.
Ao final informar quais CNPJs foram informados, e de acordo com a seleo do
usurio, exibir os dados principais de um destes clientes.
Ttulo ADVPL 1
Pgina 149
Exerccio 13
Utilizando a funo FORMBATCH(), desenvolver uma rotina que verifique se para
cada item de uma nota fiscal de entrada existe o respectivo cabealho, e se for
encontrado algum item inconsistente, comunique a ocorrncia ao usurio que est
realizando o processamento.
Exerccio 14
Vamos Desenvolver uma rotina que, atravs do uso de um bloco de cdigo, converta
a estrutura da tabela SA1, obtida com a funo DBSTRUCT(), em uma string
denominada cCampo.
Pgina 150
ADVPL 1
MDULO
03:
CUSTOMIZAES
DESENVOLVENDO
PEQUENAS
9. ADVPL E O ERP MICROSIGA PROTHEUS

O ADVPL (Advanced Protheus Language) uma linguagem de programao desenvolvida
pela Totvs e que contm todas as instrues e funes necessrias ao desenvolvimento de
um sistema, independentemente de sua complexidade.
O Sistema Protheus, por outro lado, uma plataforma tecnolgica que engloba um Servidor
de Aplicao, um Dicionrio de Dados e as Interfaces para a conexo com o usurio. o
Protheus que executa o cdigo ADVPL, assim como 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 s reas especficas de negcios) e
pelo Configurador (programa que permite customizar o Sistema s necessidades do
usurio de forma fcil).
Ttulo ADVPL 1
Pgina 151
9.1. O Ambiente Protheus
O Sistema Protheus constitudo de um conjunto de Softwares que compem as

camadas de funcionalidades bsicas aos servios de aplicao, interface, banco de dados
e repositrio, conforme o diagrama da figura abaixo:
Figura: Camadas bsicas do Ambiente Protheus
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).
O objetivo do TOTVS DevStudio facilitar a tarefa de escrever programas: atravs de cores,

indica se a palavra escrita uma instruo, uma varivel, ou um comentrio; organiza a
biblioteca de programas em projetos e administra o repositrio de objetos; aponta erros de
sintaxe; permite o debug (execuo passo a passo do programa, verificando o contedo das
variveis) e fornece assistentes (modelos) de programas.
Pgina 152
ADVPL 1
Figura: Manuteno no repositrio de objetos
Aps compilar o programa, o resultado um objeto que carregado na memria ficando

disponvel para sua execuo atravs da aplicao PROTHEUS.
O objeto no um executvel, ou seja, no est convertido para a linguagem nativa do

equipamento. Quem faz esse trabalho o Protheus Server em tempo de execuo. Por isso,
o Protheus Server est sempre presente na memria em tempo de execuo, permitindo:
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;
Flexibilizao plataforma de trabalho. Assim, um mesmo programa pode rodar em

Ambientes Windows, Linux,
Ttulo ADVPL 1
Pgina 153
ou mesmo em um Hand Held, ficando a tarefa de adequao para o Servidor

Protheus;
Que o Sistema cresa de forma ilimitada, pois os objetos ficam fora do executvel;
O uso de macro substituies, ou seja, o uso de rotinas exteriores ao Sistema,

armazenadas em arquivos e que podem facilmente ser alteradas pelo usurio, pois o
Server tambm interpreta o cdigo fonte em tempo de execuo.
Figura: Diagrama esquemtico de objetos Protheus
O Repositrio de Objetos a biblioteca de objetos de todo o Ambiente Protheus, incluindo

tanto os objetos implementados para as funcionalidades bsicas do ERP como aqueles
gerados pelos usurios. A figura abaixo demonstra a estrutura e a interconexo entre as vrias
camadas.
Pgina 154
ADVPL 1
Figura: Estrutura de interconexo do Protheus
Ela demonstra tambm que os dados a serem processados podem estar armazenados em
bases ISAM ou em Bancos de Dados padro SQL. No primeiro caso, o server comunica- se
diretamente com os dados. Em Bancos SQL a interface TOPCONNECT / DBACCESS que
converte os comandos de entrada e sada, adequando-os ao SQL utilizado (SQl Server
Microsoft, Oracle, DB2, etc.).
Uma vez terminado o processamento do objeto chamado, ele descartado da memria, ou

seja, o Protheus um Sistema que pode crescer de forma ilimitada pois os objetos,
armazenados em um repositrio, praticamente no ocupam espao no HD (Hard Disk).
O Protheus uma plataforma multicamada. Entre as diversas camadas, temos a interface de

apresentao ao usurio (Remote), o tratamento dado para as regras de negcio
implementadas (Server), o acesso aos objetos do repositrio (Server), o acesso aos
dados disponveis no Banco de Dados (Server ou TOPCONNECT / DBACCESS ) e ao
gerenciamento de servios WEB (Server). Nesse processo, o Protheus possui, basicamente,
quatro aplicativos utilizados com diferentes finalidades:
Protheus Server / TOTVS AppServer: Responsvel pela comunicao entre o cliente,

o banco de dados e o RPO. O nome do executvel depende da verso do Sistema
(TOTVSAPPSERVER.EXE) sendo que as plataformas ISAM suportadas pelo Protheus
Server so DBF e CTREE.
Ttulo ADVPL 1
Pgina 155
Protheus Remote / TOTVS SmartClient: Instalado no Server ou na estao. O nome

tambm depende da verso do Sistema (TOTVSSMARTCLIENT.EXE).
TopConnect / DbAccess: Responsvel pela converso dos comandos de banco de

dados, adequando-os ao SQL utilizado.
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).
Alguns nomes referem-se a um conjunto de programas para facilitar a sua identificao:
RPO: o arquivo binrio do APO (Advanced Protheus Objects), ou seja, os objetos.
Build: Executveis, DLLs e o RPO completo.
Patch: Atualizaes pontuais do RPO, aplicadas por meio do IDE.
Update: Pacote de atualizao para o repositrio (RPO), liberado periodicamente

contendo todas as adequaes e melhorias disponibilizadas para o Sistema em um
determinado perodo, sendo no cumulativo, aplicadas por meio do DEV-Studio.
A interface de apresentao realizada pelo SmartClient que processa a parte da estao,

basicamente, tela e teclado. Pode estar gravado no Server e ser carregado via rede para a
memria da estao. Ou, de preferncia, deve ficar armazenado no HD da estao. Pode
tambm ser carregado pelo Internet Explorer, rodando dentro do prprio browser com o
SmartClient ActiveX e permitindo o acesso ao Protheus Server pela Internet, com as mesmas
funcionalidades do SmartClient, sendo que o browser precisa suportar o uso da tecnologia
ActiveX.
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.
Pgina 156
ADVPL 1
9.2. Organizao e configurao inicial do ambiente Protheus
O Protheus ocupa uma pasta que tem a seguinte estrutura:
Ttulo ADVPL 1
Pgina 157
Figura: Estrutura bsica das pastas do Protheus
APO: Contm o arquivo RPO, repositrio de objetos do Protheus.

SMARTCLIENT: Rene um conjunto de arquivos executveis, dlls e arquivos de
configurao do Sistema, para possibilitar o acesso ao servidor.
APPSERVER: Rene um conjunto de executveis, dlls e arquivos de configurao do
Sistema que compem o servidor.
INCLUDE: Contm as bibliotecas necessrias para a compilao de programas
Protheus.
DATA: Contm a base de dados no caso de verso ISAM.
SAMPLES: Oferece um conjunto de programas exemplo e arquivos ADVPL padres da
Microsiga.
SPOOL: Nesta pasta so gravados os relatrios gerados em disco pelo Sistema
Protheus.
SYSTEM: Contm os arquivos de menus, os arquivos de configuraes e os arquivos
de customizaes (SXs) do sistema Protheus.
SYSTEMLOAD: Contm o dicionrio de dados em formato TXT. neste arquivo que
esto todos os padres e formatos para a gerao dos arquivos de configuraes e de
customizaes (SXs), conforme a localizao de pas definida pelo usurio, na entrada
do Sistema.
MY PROJECTS: Sugere-se a criao desta pasta para armazenar projetos e fontes das
customizaes realizadas pelo usurio.
UPDATES: Sugere-se esta pasta para o armazenamento das atualizaes a serem
aplicadas no Sistema Protheus.
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.
Pgina 158
ADVPL 1
Figura: Formas de instalao e uso do Protheus
Para isso, necessrio configurar, ou seja, informar ao Protheus onde est cada uma delas.
Esse tipo de informao consta nos arquivos de parmetros de configurao do Sistema
(TOTVSAPPSERVER.INI e TOTVSSMARTCLIENT.INI) existentes nas respectivas pastas
APPSERVER e SMARTCLIENT.
Os parmetros do TOTVSAPPSERVER.INI so lidos pelo programa TOTVSAPPSERVER.EXE, logo

no incio de sua execuo. O mesmo procedimento ocorre em relao aos parmetros do
TOTVSSMARTCLIENT.INI pelo programa TOTVSSMARTCLIENT.EXE. A execuo desses dois
programas feita por meio de ao do usurio, facilitada pelos atalhos TOTVS APPSERVER e
TOTVS SMARTCLIENT.
Ttulo ADVPL 1
Pgina 159
Figura: Links dos parmetros de configurao
Para que o TOTVS AppServer e o TOTVS SmartClient sejam executados, os arquivos

TOTVSAPPSERVER.INI e TOTVSSMARTCLIENT.INI devem estar disponveis nas respectivas
pastas APPSERVER e SMARTCLIENT, pois so eles que indicam o endereo das demais pastas,
conforme a ilustrao da figura anterior.
O detalhe de preenchimento das propriedades dos respectivos atalhos TOTVS AppServer e o

TOTVS SmartClient demonstrado a seguir. No atalho do TOTV SAppServer, necessrio
que seja informado o parmetro -debug ou -console.
Pgina 160
ADVPL 1
Propriedades dos atalhos
Destino:
c:\protheus\bin\appserver\totvsappserve
- console
Iniciar
em:
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
Se o TOTVS Application Server, no for instalado como um Servio do NT, durante a

Instalao, isto pode ser realizado, executando-o com a opo de Linha de Comando.
-Remove
Para remov-lo da Lista de Servios do NT, possvel execut-lo com a opo de Linha
de Comando.
Destino:
c:\protheus\bin\smartclient\totvssmartc
M
Iniciar
em:
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).
Ttulo ADVPL 1
Pgina 161
-P (Main Program)
Identifica o Programa (APO) Inicial.
-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 as mltiplas instncias (Cpias) do TOTVS Smart Client, na mesma mquina, o que
por Default no permitido.
Pgina 162
ADVPL 1
Os parmetros que configuram o local do RPO, o Banco de Dados (ISAM ou SQL), os arquivos
de menus, configuraes e customizaes do sistema no arquivo INI so:
SourcePath: Indica o local de origem dos objetos. o endereo do Repositrio de

Objetos (Exemplo: SourcePath=C:\PROTHEUS\APO).
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).
StartPath: Indica qual a pasta dentro da pasta raiz (informada no parmetro

RootPath) que contm os arquivos de menus, os arquivos de configuraes e os
arquivos de customizaes
(SXs)
do
Sistema
Protheus
(Exemplo:
StartPath=\SYSTEM\).
No h necessidade de que os parmetros estejam em ordem nos arquivos de configurao

(.ini). Alm dos parmetros j detalhados, existem outros que podem indicar a verso do
Sistema, o tipo de banco de dados, a linguagem do pas em que est sendo utilizado e as
mscaras de edio e formatao.
Ttulo ADVPL 1
Pgina 163
[ENVIRONMENT]
SOURCEPATHC:\PROTHEU
S\APO
ROOTPATH=
C:\MP811\PROTHEUS_DAT
A
STARTPATH=\
PROTHEUS\
RPODB=TOP
RPOLANGUAGE=PORTUG
UESE
RPOVERSION=101
LOCALFILES=ADS
TRACE=0
LOCALDBEXTENSION=.DB
F
PICTFORMAT=DEFAULT
DATEFORMAT=DEFAULT
[DRIVERS]
ACTIVE=TCP
[TCP]
TYPE=TCPIP
PORT=1234
Figura: Exemplo de um ambiente em um arquivo de parmetros
No exemplo da figura anterior, o rtulo [environment] descreve um conjunto de parmetros

que sero inicializados no Sistema. Os rtulos [Drivers] e [TCP] identificam a comunicao que
pode ser estabelecida entre o Protheus Server e o Protheus Remote. Outros ambientes
podem ser configurados no mesmo arquivo (TOTVSAPPSERVER.INI).
J o arquivo de parmetros do Protheus Remote (TOTVSSMARTCLIENT.INI) contm apenas as
Pgina 164
ADVPL 1
configuraes locais, basicamente as informaes necessrias para a inicializao e a

comunicao com o Protheus Server, conforme o exemplo da figura a seguir.
[CONFIG]
LASTMAINPROG=SIGA
CFG
LANGUAGE=1
[DRIVERS]
ACTIVE=TCP
[TCP]
SERVER=172.16.72.41
PORT=1234
Figura: Exemplo de um arquivo de configurao do remote
Active: Indica qual a forma de comunicao.
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:
O parmetro Server=172.16.72.41 no arquivo TOTVSSMARTCLIENT.INI indica ao Protheus

Remote o endereo da mquina na qual est funcionando o Protheus Server.
Ttulo ADVPL 1
Pgina 165
9.3. O Configurador do Protheus
99..33..11..
FFuunncciioonnaalliiddaaddeess A
Abboorrddaaddaass
O objetivo deste tpico no abranger toda a estrutura e recursos do mdulo Configurador

da aplicao ERP, mas permitir a realizao de tarefas de configurao simples que sero
necessrias no desenvolvimento de pequenas customizaes.
Com foco neste objetivo, sero detalhadas as seguintes operaes:
Configurao e criao de novas tabelas no Dicionrio de Dados.

Atualizao das estruturas do Dicionrio de Dados.
o tabelas do sistema;
o validaes de campos;
o indices de tabelas;
o gatilhos de campos.
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
Sistema Protheus.
99..33..22..
EEssttrruuttuurraass bbssiiccaass ddaa aapplliiccaaoo EER

RPP PPrrootthheeuuss
Arquivos de configurao do sistema
Arquivo
Descrio
SIGAMAT Cadastro de empresas e filiais do sistema
Pgina 166
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
ADVPL 1
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
Sequncia de documentos (+1)
SXF
Sequncia 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
SXQ
Cadastro de filtros inteligentes da mbrowse (contm as

informaes necessrias para a criao do filtro).
SXR
SXS
SXT
Cadastro de relacionamento entre programa x filtro

(utilizada internamente pelo Protheus para verificar em
quais programas os filtros podero ser utilizados).
Cadastro de programas (utilizado na validao para
mostrar/inibir os filtros na execuo da mbrowse).
Tabela de usurios (contm as informaes dos usurios
que podero utilizar os filtros da mbrowse).
SXOffice Cadastro de relacionamento entre as entidades (tabelas) e

as consultas TOII.
Ttulo ADVPL 1
Pgina 167
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.).
No caso do SQL o acesso feito atravs do TOPCONNECT / DBACESS, que converte os

comandos do ADVPL para este ambiente.
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.
Pgina 168
ADVPL 1
A tabela a seguir demonstra alguns dos mdulos que compe a aplicao ERP PROTHEUS
atualmente:
Ambiente
SIGAATF
Identificao
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
SIGALOJA 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
Ttulo ADVPL 1
Pgina 169
O nome de cada tabela no Protheus constitudo de seis dgitos que so utilizados para
formar a seguinte representao:
SF
Primeiro dgito representa

a famlia, o segundo
dgito pode ser utilizado
para detalhar ainda mais a
famlia especificada no
primeiro
nvel
(subfamlia), e o terceiro
dgito a numerao
sequencial das tabelas da
famlia, iniciando em 0 e
finalizando em Z.
Os dois primeiros dgitos

identificam a que empresa
as
tabelas
esto
vinculadas,
lembrando
que a informao de filial
est contida nos dados da
tabela.
Onde:
O ltimo dgito fixo em

0.
A tabela a seguir demonstra algumas das principais famlias de tabelas utilizadas pela
aplicao ERP Protheus:
Famlia
Descrio
Tabelas pertencentes ao sistema bsico,

tambm chamado Classic
Cadastros de entidades compartilhadas

entre
os
Ambientes
(Clientes,
Fornecedores, Bancos entre outros)
Pgina 170
ADVPL 1
Famlia
Descrio
Cadastros dos Ambientes de Materiais

(Produtos, Saldos entre outros)
Arquivos de movimentaes diversas,

utilizados pelos ambientes de Materiais
(Solicitao
ao
Almoxarifado,
Solicitao de Compras, Pedido de
Compras, Pedido de Vendas, Ordens de
Produo entre outros)
Arquivos de movimentaes de estoque

(Itens de notas fiscais de entrada e
sada, movimentos internos de estoque
entre outros)
Cadastros
e
movimentaes
ambiente Financeiro
Cadastros e movimentaes Fiscais

(Cabealhos das notas fiscais de entrada
e sada, cadastro de tipos de entrada e
sada, livros fiscais, entre outros)
Cadastros
do
Ambiente
de
Planejamento e Controle de Produo
Movimentos
do
Ambiente
de
Planejamento e Controle de Produo
Cadastros e movimentos do Ambiente

Contbil (descontinuado)

Ativo Fixo

Gesto de Pessoal
Tabelas de configurao do Sistema
Tabelas livres para utilizao e projetos

especficos em clientes
Gesto de Projetos
Contabilidade Gerencial
do
Ttulo ADVPL 1
Pgina 171
Famlia
Descrio
Transportadoras e derivados
Comrcio exterior e derivados
Gesto Hospitalar
Gesto Educacional
Servios Pblicos
Reservado para projetos da fbrica de

software
Qualidade e derivados
Recursos Humanos e derivados
Plano de Sade
Workflow
Tabelas livres para utilizao e projetos

especficos em clientes em adio
famlia SZ
Pgina 172
ADVPL 1
ndices
Cada tabela do Sistema possui seus ndices definidos no arquivo de configurao SIX, o qual
pode ser atualizado com a utilizao 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 os bancos de dados ISAM sero 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 sequencial 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.
Ttulo ADVPL 1
Pgina 173
99..33..33..
A
Acceessssaannddoo oo m
mdduulloo CCoonnffiigguurraaddoorr
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.
Figura: Parmetros de inicializao do Sistema
Aps a confirmao, a validao do acesso feita conforme tela ilustrada a seguir:
Pgina 174
ADVPL 1
Figura: Validao de acesso
Ttulo ADVPL 1
Pgina 175
Figura: Confirmao do acesso ao mdulo Configurador
Logo aps a sua confirmao do usurio e senha com direito de administrador, ser
apresentada a tela inicial do configurador, conforme mostra a figura a seguir:
Figura: Interface principal do mdulo Configurador
9.4. uncionalidades do Configurador
A customizao de um Sistema como o Protheus consiste em adaptar o Sistema de forma a

melhor atender as necessidades do cliente.
A flexibilidade de um Sistema, ou seja, sua capacidade de adaptar-se (polimorfismo, aquele

que assume vrias formas) uma das mais importantes caractersticas de uma soluo ERP.
Pgina 176
ADVPL 1
As funcionalidades tratadas pelo Configurador definem a flexibilidade do ERP Protheus.

Flexibilizar sem despadronizar, ou seja, tudo que foi customizado permanece vlido, mesmo
com o desenvolvimento de novas verses.
Figura: Principais funcionalidades do mdulo Configurador
O Configurador o programa bsico para o processo de customizao do Protheus, atravs

da alterao das tabelas da famlia SX. Neles, o usurio ou o analista de suporte responsvel
pela implantao configura as informaes que sero utilizadas pelos demais ambientes do
Sistema.
Essas informaes vo de simples parmetros at complexas expresses e comandos que so

interpretados em tempo de execuo.
Nos prximos tpicos sero abordadas as funcionalidades de customizao disponveis no

Ambiente Configurador, relevantes ao objetivo de desenvolvimento de pequenas
customizaes para a aplicao ERP.
Ttulo ADVPL 1
Pgina 177
99..44..11..
D
Diicciioonnrriioo ddee D
Daaddooss ddaa aapplliiccaaoo EER
RPP
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.
Figura: Conjunto de pacotes que compe o Dicionrio de Dados
Pgina 178
ADVPL 1
99..44..22..
A
Addiioo ddee ttaabbeellaass aaoo D
Daaddooss
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).
2. Aps a seleo da opo Dicionrio de Dados sero exibidas as tabelas j cadastradas

no arquivo de sistema SX2.
Ttulo ADVPL 1
Pgina 179
Figura: Conjunto de tabelas j cadastradas no SX2
3. Aps a visualizao das tabelas j cadastradas no SX2 da empresa selecionada, utilize
o boto Incluir (
). Ao utilizar esta opo ser exibida a tela para definio dos
dados referentes nova tabela que ser criada:
Pgina 180
ADVPL 1
Figura: Cadastro de uma nova tabela
4. Realize o preenchimento das informaes solicitadas de acordo com as orientaes a

seguir, e ao trmino confirme o cadastramento da nova tabela com o boto Confirmar
).
Orientaes para o cadastramento de uma nova tabela
O domnio SZ1 at SZZ (considerando todos os nmero e todas as letras no ltimo

byte) reservado para dados exclusivos do usurio, pois esse intervalo no ser
utilizado pelo Sistema. Caso seja necessrio o domnio Z00 a ZZZ tambm pode ser
empregado para desenvolvimentos especficos do cliente.
Ttulo ADVPL 1
Pgina 181
No devem ser criadas tabelas especficas de clientes com

quaisquer outras nomenclaturas, o que pode afetar diretamente
um processo de atualizao futuro.
O nome da tabela preenchido automaticamente, adicionando 990. Esse dado referese empresa 99 (Teste Matriz) a qual est sendo adicionado tabela.
O Path refere-se pasta que conter efetivamente os dados das tabelas, quando
ISAM, As verses com banco de dados relacional no so utilizadas. Essa pasta ser
criada dentro da pasta indicada na configurao do Sistema como ROOTTPATH.
O modo de acesso compartilhado indica que o Sistema possibilitar o uso simultneo

da tabela por duas ou mais filiais. Se for compartilhado o campo Filial fica em branco.
Se for exclusivo, grava-se o cdigo da filial ativa e somente ela tem acesso ao registro.
Aps a confirmao, a tabela criada passa a fazer parte do cadastro do Dicionrio de

Dados, contendo somente o campo FILIAL, o qual criado como padro pela
funcionalidade do mdulo.
Pgina 182
ADVPL 1
99..44..33..
A
Addiioo ddee ccaam
mppooss ss ttaabbeellaass ddoo D
Daaddooss
Procedimento
1. Para adicionar um campo a uma tabela do 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).

3. Aps a visualizao das tabelas j cadastradas no SX2 da empresa selecionada,

Ttulo ADVPL 1
Pgina 183
localize 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:
Figura: Estrutura de uma tabela j cadastrada no Sistema
4. Selecione a opo Campos (

), para que sejam exibidos os campos
disponveis para a tabela no arquivo de sistema SX3.
Pgina 184
ADVPL 1
Figura: Estrutura de campos de uma tabela j cadastrada no Sistema

5. Aps a visualizao dos campos j cadastrados no SX3 da tabela selecionada, utilize a
opo Incluir (
). Ao utilizar esta opo ser exibida a tela para definio dos
dados referentes ao novo campo que ser criado:
Ttulo ADVPL 1
Pgina 185
Figura: Dados para parametrizao de um novo campo no Sistema

seguir, e ao trmino confirme o cadastramento do novo campo para a tabela com o
boto Confirmar (
).
6. Confirme as atualizaes para a tabela selecionada com o boto Confirmar (
7. Atualize as configuraes do Sistema com o boto Atualizar (
).
).
Figura: Atualizao dos dados do Sistema
Orientaes para o cadastramento de um novo campo
1. As propriedades definidas no Dicionrio de Dados (SX3) so as seguintes:
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.
Pgina 186
ADVPL 1
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.

Tamanho do campo: Tambm aqui necessrio certo cuidado ao alter-lo, pois
poderemos ter truncamentos em relatrios e consultas em que h espao para
contedos maiores que o original.
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.
Propriedade: Indica se um campo pode ou no ser alterado pelo usurio. Exemplo:

saldos normalmente no podem, pois quem cuida dessa tarefa so os programas.
2. Demais caractersticas que devem ser observadas na configurao do campo:
Guia: Campo
O campo Decimal ser solicitado somente para os campos de tipo numrico.
O formato ! indica que o caractere ser sempre maisculo, independente da ao

do usurio. O formato @! indica que essa caracterstica estende-se por todo o
campo.
O contexto real indica que o campo existir efetivamente no banco de dados e o

contexto virtual significa que o campo existir apenas no dicionrio de dados e
no fisicamente.
Ttulo ADVPL 1
Pgina 187
20
A propriedade alterar indica que o campo pode ser alterado.
Nesta janela, os dados esto classificados em seis pastas com objetivos de

preenchimento bem especficos:
Guia: Informaes
Contm as informaes a respeito dos ttulos.
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.
Descrio e Help: So propriedades que objetivam documentar o campo.
Guia: Opes
Contm os dados que facilitam a digitao.
Guia: Validaes
Representam as regras de validao do campo.
Validaes: Nesta propriedade, escreve-se uma funo de validao do campo que

est sendo digitado. Existe um conjunto de funes disponveis no ADVPL apropriadas
para esse caso.
Todas as validaes informadas sero executadas no momento do preenchimento do

prprio campo. Uma validao pode ser uma expresso lgica ou uma funo de
usurio que retorna um valor lgico Verdadeiro ou Falso. O sistema s permitir o
avano para o prximo campo quando o respectivo preenchimento resultar
Verdadeiro, seja na expresso ou no retorno da funo.
Guia: Uso
Descreve a forma de utilizao do campo.
Pgina 188
ADVPL 1
Guia: Mdulos
Relaciona todos os mdulos em que o campo ser utilizado.
Ttulo ADVPL 1
Pgina 189
99..44..44..
A
Addiioo ddee nnddiicceess ppaarraa aass ttaabbeellaass ddoo D
Daaddooss
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.
Os ndices do Sistema auxiliam na seleo e obteno de informaes da base de dados, alm

de determinar a ordem de apresentao dos registros de uma tabela em consultas e
relatrios.
Procedimento
1. Para adicionar um ndice a uma tabela do 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).

Pgina 190
ADVPL 1
3. Aps a visualizao das tabelas j cadastradas no SX2 da empresa selecionada,
localize 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:
Ttulo ADVPL 1
Pgina 191
Figura: Estrutura de uma tabela j cadastrada no Sistema
4. Selecione a opo ndices (

), para que sejam exibidos os ndices
disponveis para a tabela no arquivo de sistema SIX.
Figura: ndices disponveis para a tabela no arquivo de sistema SIX
5. Aps a visualizao dos ndices j cadastrados no SIX para a tabela selecionada, utilize
Pgina 192
ADVPL 1
a opo Incluir (
). Ao utilizar esta opo, ser exibida a tela para definio dos
dados referentes ao novo ndice que ser criado:
Figura: Adio de um ndice para uma tabela

seguir, e ao trmino confirme o cadastramento do novo ndice para a tabela com o boto
Confirmar (
).
7. Confirme as atualizaes para a tabela selecionada com o boto Confirmar (
8. Atualize as configuraes do Sistema com o boto Atualizar (
).
Ttulo ADVPL 1
Pgina 193
).
Figura: Atualizao dos dados do Sistema
Pgina 194
ADVPL 1
Orientaes para o cadastramento de um novo ndice
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 (
). Esta facilidade preenche, automaticamente, os campos de descrio.
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.
Uma tabela poder ter vrios ndices cadastrados no Dicionrio de Dados. Em

determinado momento, porm, apenas um deles oferecer acesso ao registro. Essa
ordem pode ser alterada em tempo de execuo pelos programas da aplicao,
atravs do comando DBSetOrder(), ou atravs da definio de uma ordem especfica
na utilizao de queries para acesso aos dados diretamente em bancos de dados de
Ambientes TOPCONNECT (DbAcess).
99..44..55..
A
Addiioo ddee ggaattiillhhooss ppaarraa ooss ccaam
mppooss ddaass ttaabbeellaass ddoo SSiisstteem
maa
Procedimento
1. Para adicionar um gatilho a um campo de uma tabela do dicionrio de dados de uma

empresa, selecione a opo Gatilho abaixo da empresa que ser atualizada. (rvore de
opes da parte esquerda da interface visual do Gerenciador de Bases de Dados).
2. Aps a seleo da opo Gatilhos sero exibidos os itens j cadastradas no arquivo de

sistema SX7.
Ttulo ADVPL 1
Pgina 195
Figura: Conjunto de gatilhos j cadastros no SX7
Pgina 196
ADVPL 1
3. Aps a visualizao dos gatilhos j cadastrados no SX7 da empresa selecionada, utilize
o boto Incluir (
) para realizar o cadastro de um novo gatilho no Sistema:
Figura: Dados para o cadastro de um novo gatilho no Sistema

seguir, e ao trmino confirme o cadastramento do novo gatilho de sitema com o
boto Confirmar (
).
Orientaes para o cadastramento de um novo gatilho
Pode haver vrios gatilhos para o mesmo campo. A ordem de execuo

determinada pelo campo Sequncia.
Os tipos do Gatilho Primrio, Estrangeiro e de Posicionamento definem se o Contra

Domnio um campo da mesma tabela, de outra tabela ou se o gatilho deve realizar
um posicionamento, respectivamente.
A regra pode ser uma expresso que resulta em um valor a ser preenchido no Contra
Domnio.
Ttulo ADVPL 1
Pgina 197
O posicionamento igual a Sim indica que ser executado um comando de busca do

registro de acordo com a chave indicada.
O Alias, a Ordem e a Chave descrevem a tabela envolvida no gatilho, seu ndice e a

chave para que a funcionalidade se posicione no registro adequado.
Pgina 198
ADVPL 1
99..44..66..
CCrriiaaoo ddee TTaabbeellaass G

Geennrriiccaass
Procedimento
1. Para adicionar uma tabela genrica, selecione os menus Ambiente, Cadastros, Tabelas.
2. Aps a seleo da opo Tabelas sero exibidos os itens j cadastradas no arquivo de

sistema SX5.
Figura: Conjunto de Tabelas j cadastras no SX5
3. Aps a visualizao das tabelas j cadastrados no SX5 da empresa selecionada, utilize
o boto Incluir (
) para realizar o cadastro de uma nova tabela no Sistema:
Ttulo ADVPL 1
Pgina 199
Figura: Dados para o cadastro de uma nova tabela no Sistema

seguir, e ao trmino confirme o cadastramento da nova tabela do sistema com o
boto Confirmar (
Pgina 200
).
ADVPL 1
99..44..77..
CCrriiaaoo ddee PPaarrm

meettrrooss
Procedimento
1. Para adicionar um Parmetro, selecione os menus Ambiente, Cadastros, Parmetros.
2. Aps a seleo da opo Tabelas sero exibidos os itens j cadastradas no arquivo de

sistema SX6.
Figura: Conjunto de Parmetros j cadastras no SX6
3. Aps a visualizao dos Parmetros j cadastrados no SX6 da empresa selecionada,
utilize o boto Incluir (
) para realizar o cadastro de uma nova tabela no sistema:
Ttulo ADVPL 1
Pgina 201
Figura: Dados para o cadastro de um novo parmetro no Sistema

seguir, e ao trmino confirme o cadastramento do novo Parmetro do Sistema com o
boto Confirmar (
Pgina 202
).
ADVPL 1
10.
TOTVS DEVELOPMENT STUDIO
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:
Figura: Representao da estrutura de um projeto no DEV-Studio

Ttulo ADVPL 1
Pgina 203
Compilao
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 um 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:
Se o programa no manipula arquivos, pode-se cham-lo diretamente do DEV-Studio

(nome no lado direito da barra de ferramentas);
Se o programa manipula tabelas existem duas opes:
Adicionar o programa no menu de um dos Ambientes e execut-lo atravs do

Remote.
Realizar a preparao do Ambiente na prpria rotina, permitindo sua execuo

diretamente pelo DEV-Studio.
No se pode compilar um programa com o Remote e o Monitor abertos, tenha este

finalizado ou no por erro.
Anlise e depurao de erros
Para identificar as causas de erros, a ferramenta DEV-Studio possui diversos recursos que
auxiliam o DEBUG.
A ao de DEBUG necessita que o programa seja executado a partir do DEV-Studio, sendo

necessrio observar as seguintes regras:
Pgina 204
ADVPL 1
Definir e marcar os pontos de parada mais adequados a anlise do fonte;
Executar a rotina atravs do DEV-Studio, selecionando seu nome diretamente, ou o

mdulo que contm a opo ou a ao que a executar;
A partir do momento em que o DEV-Studio pausar o processamento em um dos

pontos de parada especificados previamente, podem ser utilizadas as janelas de
visualizao, disponveis no DEV-Studio, que so:
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;
Na pilha de chamadas, verifica-se a sequncia de chamadas das funes;
Na pasta de Comandos, pode-se, enquanto o programa estiver pausado, escrever
qualquer comando e ao dar Enter, ele executado, permitindo pesquisar palavras e
expresses no prprio fonte ou em qualquer fonte armazenado no HD;
Ao parar pode-se ou continuar o programa at o prximo ponto de parada, caso haja

um outro definido, ou executar linha a linha da rotina.
Interface da aplicao
Por ser um ambiente integrado de desenvolvimento, o DEV-Studio proporciona todas essas

facilidades, por meio de interface nica como ilustra a figura a seguir:
Ttulo ADVPL 1
Pgina 205
Figura: Interface principal do TOTVS Development Studio
O DEV-Studio apresenta, no topo da tela, um conjunto de opes de menu e uma

srie de botes que facilitam a sua manipulao.
Na tela central, apresentado o cdigo das funes em ADVPL. Na parte inferior so

exibidas algumas pastas que facilitam a execuo de comandos, exibio de
contedos de variveis e mensagens, bem como dados sobre o projeto.
Pgina 206
ADVPL 1
DESENVOLVIMENTO DE PEQUENAS CUSTOMIZAES
11.
ACESSO E MANIPULAO DE BASES DE DADOS EM ADVPL
Como a linguagem ADVPL utilizada no desenvolvimento de aplicao para o sistema ERP

Protheus, ela deve possuir recursos que permitam o acesso e a manipulao de informaes,
independentemente da base de dados para o qual o Sistema foi configurado.
Desta forma a linguagem possui dois grupos de funes distintos para atuar com os bancos
de dados:
Funes de manipulao de dados genricos;

Funes de manipulao de dados especficas para ambientes TOPCONNECT /
DBACCESS.
Funes de manipulao de dados genricos
As funes de manipulao de dados, ditos como genricos, 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 utilizados na ferramenta ERP.
Dentre as melhorias implementadas pela rea de Tecnologia da Microsiga, podemos

mencionar o desenvolvimento de novas funes como, por exemplo, a funo MsSeek() verso da Microsiga para a funo DbSeek(), e a integrao entre a sintaxe ADVPL
convencional e a ferramenta de acesso a bancos de dados no padro SQL TOPCONNECT
(DbAcess).
A integrao, entre a aplicao ERP e a ferramenta TOPCONNECT, permite que as funes de

acesso e manipulao de dados escritos em ADVPL sejam interpretados e convertidos para
uma sintaxe compatvel com o padro SQL ANSI e desta forma aplicados aos SGDBs
(Sistemas Gerenciadores de Bancos de Dados) com sua sintaxe nativa.
Ttulo ADVPL 1
Pgina 207
Funes de manipulao de dados para Ambientes TOPCONNECT / DBACCESS

Para implementar um acesso mais otimizado e disponibilizar no Ambiente ERP
funcionalidades que utilizem de forma mais adequada os recursos dos SGDBs
homologados para o Sistema, foram implementadas funes de acesso e manipulao de
dados especficas para Ambientes TOPCONNECT/DBACCESS.
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.
As funes especficas para Ambientes TOPCONNECT sero abordadas

no material de ADVPL Avanado.
Pgina 208
ADVPL 1
11.1. Diferenas e compatibilizaes entre bases de dados

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 optar por escrever sua aplicao.
Acesso a dados e ndices
No acesso a informaes, em bases de dados do padro ISAM, so sempre lidos os registros

inteiros, enquanto no SQL pode-se ler apenas os campos necessrios naquele processamento.
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
sequencial, tendo como base o nome da tabela a qual ele est relacionado.
A cada incluso ou alterao de um registro todos os ndices so atualizados, tornando

necessrio planejar adequadamente quais e quantos ndices sero definidos para uma tabela,
pois uma quantidade excessiva pode comprometer o desempenho dessas operaes.
Deve ser considerada a possibilidade da utilizao de ndices temporrios para os processos

especficos, os quais sero criados em tempo de execuo da rotina. Esse fator deve levar em
considerao o esforo do Ambiente a cada execuo da rotina e a periodicidade com a
qual executada.
Estrutura dos registros (informaes)
Nas bases de dados padro ISAM cada registro possui um identificador nativo ou ID
sequencial e ascendente que funciona como o endereo base daquela informao.
Este ID, mais conhecido como RECNO ou RECNUMBER gerado no momento de incluso do
registro na tabela e somente ser alterado se a estrutura dos dados dessa tabela sofra alguma
manuteno. Dentre as manutenes que uma tabela de dados ISAM pode sofrer, possvel
citar a utilizao do comando PACK, o qual apagar fisicamente os registros deletados da
tabela, forando uma renumerao dos identificadores de todos os registros. Essa
Ttulo ADVPL 1
Pgina 209
situao tambm torna necessria a recriao de todos os ndices vinculados quela tabela.
Isso 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 as 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, por meio da criao de campos de controle especficos: R_E_C_N_O_, D_E_L_E_T_ e
R_E_C_D_E_L.
Esses campos permitem que a aplicao ERP gerencie as informaes do banco de dados, da
mesma forma que as informaes em bases de dados ISAM.
Com isso o campo R_E_C_N_O_ ser um identificador nico do registro dentro da tabela,
funcionando como o ID ou RECNUMBER de uma tabela ISAM, mas utilizando um recurso
adicional disponvel nos bancos de dados relacionais conhecido com Chave Primria.
Para a aplicao ERP Protheus o campo de controle R_E_C_N_O_ definido em todas as

tabelas como sendo sua chave primria, o que transfere o controle de sua numerao
sequencial ao banco de dados.
O campo D_E_L_E_T_ tratado internamente pela aplicao ERP como um flag ou marca de
excluso. Dessa 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 na tabela de bases de dados ISAM.
Pgina 210
ADVPL 1
11.2. Funes de acesso e manipulao de dados

As funes de acesso e manipulao de dados, descritas neste tpico, so as classificadas
anteriormente como funes genricas da linguagem ADVPL, permitindo que as mesmas
sejam utilizadas independentemente da base de dados para a qual a aplicao ERP est
configurada.
As funes de acesso e manipulao de dados definem basicamente:
Tabela que est sendo tratada;

Campos que devero ser lidos ou atualizados;
Mtodo de acesso direto s informaes (registros e campos).
Dentre as funes ADVPL disponveis para acesso e manipulao de informaes, este

material detalhar as seguintes opes:
SELECT()
DBSELECTAREA()
DBSETORDER()
DBSEEK() E MSSEEK()
DBSKIP()
DBGOTO()
DBGOTOP()
DBGOBOTTON()
DBSETFILTER()
RECLOCK()
SOFTLOCK()
MSUNLOCK()
DBDELETE()
DBUSEAREA()
DBCLOSEAREA()
DBRLOCK()
Ttulo ADVPL 1
Pgina 211
Sintaxe
DBRLOCK(xIdentificador)
Funo de base de dados, que efetua o lock (travamento) do registro
identificado pelo parmetro xIdentificador. Esse 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()
Descrio
Permite que um alias presente na conexo seja fechado, o que viabiliza

novamente seu uso em outro operao. Este comando tem efeito apenas no
alias ativo na conexo, sendo necessria sua utilizao em conjunto com o
comando DbSelectArea().
DBCOMMIT()
Sintaxe
DBCOMMIT()
Descrio
Efetua todas as atualizaes pendentes na rea de trabalho ativa.
DBCOMMITALL()
Sintaxe
DBCOMMITALL()
Descrio
Efetua todas as atualizaes pendentes em todas as rea de trabalho, em uso

pela thread (conexo) ativa.
DBDELETE()
Sintaxe
Pgina 212
DbDelete()
ADVPL 1
Descrio
Efetua a excluso lgica do registro posicionado na rea de trabalho ativa,

sendo necessria sua utilizao em conjunto com as funes RecLock() e
MsUnLock().
DBGOTO()
Sintaxe
DbGoto(nRecno)
Descrio
Move o cursor da rea de trabalho ativa para o record number (recno)

especificado, realizando um posicionamento direto, sem a necessidade de uma
busca (seek) prvia.
Ttulo ADVPL 1
Pgina 213
DBGOTOP()
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()
Descrio
Retorna um array contendo o record number (recno) de todos os registros,

travados da rea de trabalho ativa.
DBSEEK() E MSSEEK()
Sintaxe
DbSeek(cChave, lSoftSeek, lLast)

DbSeek: Permite posicionar o cursor da rea de trabalho ativo no registro com
as informaes especificadas na chave de busca, fornecendo um retorno lgico
indicando se o posicionamento foi efetuado com sucesso, ou seja, se a
informao especificada na chave de busca foi localizada na rea de trabalho.
Descrio
MsSeek(): Funo desenvolvida pela rea de Tecnologia da Microsiga, a qual
possui as mesmas funcionalidades bsicas da funo DbSeek(), com a vantagem
de no necessitar acessar novamente a base de dados para localizar uma
informao j utilizada pela thread (conexo) ativa.
DBSKIP()
Pgina 214
ADVPL 1
Sintaxe
DbSkip(nRegistros)
Descrio
Move o cursor do registro posicionado para o prximo (ou anterior,

dependendo do parmetro), em funo da ordem ativa para a rea de trabalho.
DBSELECTAREA()
Sintaxe
DbSelectArea(nArea | cArea)
Descrio
Define a rea de trabalho especificada como sendo a rea ativa. Todas as

operaes subsequentes que fizerem referncia a uma rea de trabalho para
utilizao, a menos que a rea desejada seja informada explicitamente.
Ttulo ADVPL 1
Pgina 215
DBSETFILTER()
Sintaxe
DbSetFilter(bCondicao, cCondicao)
Descrio
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.
DBSETORDER()
Sintaxe
DbSetOrder(nOrdem)
Descrio
Define qual ndice ser utilizado 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.
DBORDERNICKNAME()
Sintaxe
DbOrderNickName(NickName)
Descrio
Define qual ndice criado pelo usurio ser utilizado. O usurio pode incluir os
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()
Pgina 216
ADVPL 1
Sintaxe
DBUNLOCKALL()
Descrio
Libera o travamento de todos os registros de todas as reas de trabalho

disponveis na thread (conexo) ativa.
DBUSEAREA()
Sintaxe
DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,; lSoLeitura)
Descrio
Define um arquivo de base de dados como uma rea de trabalho disponvel na

aplicao.
MSUNLOCK()
Sintaxe
MsUnLock()
Descrio
Libera o travamento (lock) do registro posicionado, confirmando as atualizaes

efetuadas neste registro.
RECLOCK()
Sintaxe
RecLock(cAlias,lInclui)
Descrio
Efetua o travamento do registro posicionado na rea de trabalho ativa,

permitindo a incluso ou alterao das informaes do mesmo.
RLOCK()
Sintaxe
RLOCK() lSucesso
Descrio
Efetua o travamento do registro posicionado na rea de trabalho ativa.
SELECT()
Ttulo ADVPL 1
Pgina 217
Sintaxe
Select(cArea)
Descrio
Determina o nmero de referncia de um determinado alias em um ambiente

de trabalho. Caso o alias especificado no esteja em uso no 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
Descrio
Pgina 218
UNLOCK()
Libera o travamento do registro posicionado na rea de trabalho ativa e
confirma as atualizaes efetuadas naquele registro.
ADVPL 1
11.3. Diferenciao entre variveis e os nomes de campos
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
Essa linha de comando identifica que o valor atribudo varivel cRes deve ser o valor da
varivel de memria chamada NOME.
cRes := FIELD->NOME
Nesse 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 abertos,
para evitar a necessidade de selecionar a rea antes de acessar o contedo de determinado
campo.
cRes := CLIENTES->NOME
As tabelas de dados, utilizadas pela aplicao ERP, recebem automaticamente do Sistema
o apelido ou ALIAS, especificado para as mesmas no arquivo de sistema SX2. Assim, se o
campo NOME pertence a uma tabela da aplicao PROTHEUS, o mesmo poder ser
referenciado com a indicao do ALIAS pr-definido dessa tabela.
cRes := SA1->NOME // SA1 Cadastro de Clientes
Ttulo ADVPL 1
Pgina 219
Para maiores detalhes sobre abertura de arquivos com a atribuio

de apelidos, consulte a documentao sobre o acesso ao banco de
dados, ou documentao da funo dbUseArea().
Os alias das tabelas da aplicao ERP so padronizados em trs

letras, que correspondem s iniciais da tabela. As configuraes de
cada ALIAS, utilizadas pelo Sistema podem ser visualizadas atravs
do mdulo Configurador -> Bases de Dados -> Dicionrios -> Bases
de Dados.
Pgina 220
ADVPL 1
11.4. Controle de numerao sequencial

Alguns campos de numerao do Protheus so fornecidos pelo Sistema em ordem
ascendente. o caso, por exemplo, do nmero do pedido de venda e outros que servem
como identificador das informaes das tabelas. preciso ter um controle do fornecimento
desses nmeros, em especial quando vrios usurios esto trabalhando simultaneamente.
Os campos que recebem o tratamento de numerao sequencial

pela aplicao ERP no devem ser considerados como chave
primria das tabelas qual esto vinculados.
No caso especfico da aplicao ERP Protheus, a chave primria

em Ambientes TOPCONNECT ser o campo R_E_C_N_O_, e para
bases de dados padro ISAM, o conceito de chave primria
implementado pela regra de negcio do sistema, pois este padro
de dados no possui o conceito de unicidade de dados.
Semforos
Para definir o conceito do que um semforo de numerao deve-se avaliar a seguinte

sequncia de eventos no sistema:
Ao ser fornecido um nmero, ele permanece reservado at a concluso da operao
que o solicitou;
Se esta operao for confirmada o nmero indisponibilizado, mas se a operao for
cancelada, o nmero voltar a estar disponvel mesmo que naquele momento

nmeros maiores j tenham sido oferecidos e utilizados.
Com isso, mesmo que tenhamos vrios processos solicitando as numeraes sequenciais para
uma mesma tabela, como por exemplo incluses simultneas de pedidos de vendas, teremos
para cada pedido um nmero exclusivo e sem o intervalos e numeraes no utilizadas.
Ttulo ADVPL 1
Pgina 221
Funes de controle de semforos e numerao sequencial
A linguagem ADVPL permite a utilizao das seguintes funes para o controle das
numeraes sequenciais utilizadas nas tabelas da aplicao ERP:
GETSXENUM()
CONFIRMSXE()
ROLLBACKSXE()
GETSXENUM()
Sintaxe
GETSXENUM(cAlias, cCampo, cAliasSXE, nOrdem)
Descrio
Obtm o nmero sequncia do alias especificado no parmetro atravs da

referncia aos arquivos de sistema SXE/SXF, ou ao servidor de numerao,
quando esta configurao est habilitada no Ambiente Protheus.
CONFIRMSXE()
Sintaxe
CONFIRMSXE(lVerifica)
Descrio
Confirma o nmero alocado atravs do ltimo comando GETSXENUM().
ROLLBACKSXE()
Sintaxe
ROLLBACKSXE()
Descrio
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a

numerao disponvel para as outras conexes.
Pgina 222
ADVPL 1
12.
CUSTOMIZAES PARA A APLICAO ERP
Nesse tpico sero abordadas as formas pelas quais a aplicao ERP Protheus pode ser
customizada, com a utilizao da linguagem ADVPL.
Pelos recursos de configurao da aplicao ERP, disponveis no mdulo Configurador,

possvel implementar as seguintes customizaes:

validaes de campos e perguntas do Sistema e de usurios;

incluso de gatilhos em campos de Sistemas e de usurios;
incluso de regras em parmetros de Sistemas e de usurios;
Desenvolvimento de pontos de entrada para interagir com funes padres do
Sistema.
12.1. Customizao de campos Dicionrio de Dados
Ttulo ADVPL 1
Pgina 223
1122..11..11..
V
Vaalliiddaaeess ddee ccaam
mppooss ee ppeerrgguunnttaass
As funes de validao tm como caracterstica fundamental um retorno do tipo lgico, ou

seja, um contedo .T. Verdadeiro, ou .F. Falso.
Com base nessa premissa, a utilizao de validaes, no Dicionrio de Dados (SX3), ou nas
Perguntas de Processos e Relatrios (SX1), dever estar focada sempre na utilizao de
funes, ou expresses que resultem em um retorno lgico.
Com a utilizao do mdulo Configurador possvel alterar as propriedades de um campo,

ou de uma pergunta de forma a incluir as regras de validao para as seguintes situaes:
SX3 validao de usurio (X3_VLDUSER);

SX1 validao da pergunta (X1_VALID).
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()
Sintaxe
ExistChav(cAlias, cConteudo, nIndice)

Retorna .T. ,ou .F. se o contedo especificado existe no alias especificado. Se
existir, ser exibido um help de Sistema com um aviso informando a ocorrncia.
Descrio
Esta funo utilizada normalmente para verificar se um determinado cdigo de
cadastro j existe na tabela na qual a informao ser inserida, como por
exemplo, o CNPJ no cadastro de clientes, ou fornecedores.
Pgina 224
ADVPL 1
EXISTCPO()
Sintaxe
ExistCpo(cAlias, cConteudo, nIndice)

Retorna .T., ou .F. se o contedo especificado no existir no alias especificado. Se
no existir, ser exibido um help de Sistema com um aviso informando a
ocorrncia.
Descrio
Essa Funo utilizada normalmente para verificar se a informao digitada em
um campo, que dependente de outra tabela, realmente existe na mesma.
Como por exemplo, o cdigo de um cliente em um pedido de venda.
NAOVAZIO()
Sintaxe
NaoVazio()
Descrio
Retorna .T. ou .F. se o contedo do campo posicionado no momento no est

vazio.
NEGATIVO()
Sintaxe
Negativo()
Descrio
Retorna .T. ou .F. se o contedo digitado para o campo negativo.
PERTENCE()
Sintaxe
Pertence(cString)
Descrio
Retorna .T. ou .F. se o contedo digitado para o campo est contido na string,
definida como o parmetro da funo. Normalmente utilizada em campos com
a opo de combo, pois caso contrrio seria utilizada a funo ExistCpo().
Ttulo ADVPL 1
Pgina 225
POSITIVO()
Sintaxe
Positivo()
Descrio
Retorna .T. ou .F. se o contedo digitado para o campo positivo.
TEXTO()
Sintaxe
Texto()
Descrio
Retorna .T. ou .F. se o contedo digitado para o campo contm apenas

nmeros, ou alfanumricos.
VAZIO()
Sintaxe
Vazio()
Descrio
Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.
Pgina 226
ADVPL 1
1122..11..22..
PPiiccttuurreess ddee ffoorrm

maaoo ddiissppoonnvveeiiss
Com base na documentao disponvel no TDN, a linguagem ADVPL e a aplicao ERP

Protheus admitem as seguintes pictures:
Dicionrio de Dados (SX3) e GET
Funes
Contedo Funcionalidade
A
Permite apenas caracteres alfabticos
Exibe CR depois de nmeros positivos
Exibe numrico com o ponto e vrgula invertidos (formato Europeu)
Insere caracteres diferentes dos caracteres de template na exibio, mas no os

insere na varivel do GET
S<n>
Permite o rolamento horizontal do texto dentro do GET, <n>. um nmero

inteiro que identifica o tamanho da regio
Exibe DB depois de nmeros negativos
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 maisculos
Templates
X
Permite qualquer caractere
Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos
Ttulo ADVPL 1
Pgina 227
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
Exemplo 01 Picture campo numrico
CT2_VALOR Numrico 17,2

Picture: @E 99,999,999,999,999.99
Exemplo 02 Picture campo texto, com digitao apenas em caixa alta
A1_NOME Caracter - 40
Picture: @!
Pgina 228
ADVPL 1
SAY e PSAY
Funes
C
Exibe CR depois de nmeros positivos
Exibe numrico com o ponto e a vrgula invertidos (formato Europeu)
Insere caracteres diferentes dos caracteres de template
Exibe DB depois de nmeros negativos
Exibe zeros como brancos
Envolve nmeros negativos entre parnteses
Converte todos os caracteres alfabticos para maisculo
Templates
X
Exibe dgitos para qualquer tipo de dado
Converte caracteres alfabticos para maisculo
Exibe asterisco no lugar de espaos em branco e inicias em nmeros
Exibe a posio do ponto decimal
Exibe a posio do milhar
Ttulo ADVPL 1
Pgina 229
Exemplo 01 Picture campo numrico

CT2_VALOR Numrico 17,2
Picture: @E 99,999,999,999,999.99
Pgina 230
ADVPL 1
12.2. Customizao de gatilhos Configurador

A aplicao ERP utiliza o recurso de gatilhos em campo com a finalidade de auxiliar o usurio
no preenchimento de informaes, durante a sua digitao.. As funes que podem ser
utilizadas no gatilho esto diretamente relacionadas definio da expresso de retorno, que
ser executada na avaliao do gatilho do campo.
As regras que devem ser observadas na montagem de um gatilho e configurao de seu

retorno so:
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:
o
As Consultas de informaes, entre tabelas com estrutura de cabealho e

itens, devem utilizar a filial da tabela de origem, pois ambas as tabelas
devem possuir o mesmo tratamento de filial (compartilhado ou exclusivo).
Exemplos:
Pedido de vendas -> SC5 x SC6
Nota fiscal de entrada -> SF1 x SD1
Ficha de imobilizado -> SN1 x SN3
Oramento contbil -> CV1 x CV2
Consulta de informaes de tabelas de cadastros devem utilizar a filial da

tabela a ser consultada, pois o compartilhamento dos cadastros
normalmente independente em relao s movimentaes e outros
cadastros do Sistema.
Exemplos:
Cadastro
Cadastro
Cadastro
Cadastro
de
de
de
de
clientes -> SA1 (compartilhado)

fornecedores -> SA2 (compartilhado)
vendedores -> SA3 (exclusivo)
transportadoras -> SA4 (exclusivo)
Consulta as informaes de tabelas de movimentos que devem utilizar a

filial da tabela a ser consultada, pois apesar das movimentaes de um
mdulo seguirem um determinado padro. A consulta pode ser realizada
entre tabelas de mdulos distintos, o que poderia gerar um retorno
incorreto baseado nas diferentes parametrizaes desses Ambientes.
Exemplos:
Contas a pagar -> SE2 (compartilhado)
Movimentos contbeis -> CT2 (exclusivo)
Pedidos de compras -> SC7 (compartilhado)
Itens da nota fiscal de entrada -> SD1 (exclusivo)
Ttulo ADVPL 1
Pgina 231
Na definio da regra de retorno deve ser considerado o tipo do campo que ser
atualizado, pois esse campo que determina qual o tipo do retorno ser
considerado vlido para o gatilho.
12.3. Customizao de parmetros Configurador

Os parmetros de sistema utilizados pela aplicao ERP e definidos atravs do mdulo
configurador possuem as seguintes caractersticas fundamentais:
Tipo de parmetro: de forma similar a uma varivel, um parmetro ter um tipo de
contedo pr-definido em seu cadastro.

Essa informao utilizada pelas funes da aplicao ERP, na interpretao do
contedo do parmetro e no retorno dessa informao rotina que o consultou.
Interpretao do contedo do parmetro: Diversos parmetros do Sistema tm seu
contedo macro executado durante a execuo de uma rotina do ERP. Esses

parmetros macro executveis tem como nica caracterstica em comum o seu tipo:
caractere, mas no existe nenhum identificador explcito que permite a fcil
visualizao de quais parmetros possuem um retorno simples e de quais parmetros
tero o seu contedo macro executado para determinar o retorno real.
A nica forma eficaz de avaliar como um parmetro tratado (simples retorno, ou

macro execuo) atravs do cdigo fonte da rotina, que dever ser avaliado como
tratado o retorno de uma destas funes:
o
o
o
GETMV()
SUPERGETMV()
GETNEWPAR()
Um retorno macro executado determinado atravs do uso do operador & ou de

uma das funes de execuo de blocos de cdigo, em conjunto com uma das
funes citadas anteriormente.
Pgina 232
ADVPL 1
1122..33..11..
FFuunneess ppaarraa aa m
maanniippuullaaoo ddee ppaarrm
meettrrooss
A aplicao ERP disponibiliza as seguintes funes para consulta e atualizao de parmetros:
GETMV()
SUPERGETMV()
GETNEWPAR()
PUTMV()
GETMV()
Sintaxe
GETMV(cParametro)
Descrio
Retorna o contedo do parmetro especificado no arquivo SX6, considerando a

filial parametrizada na conexo. Se o parmetro no existir, ser exibido um
help do sistema informando a ocorrncia.
Ttulo ADVPL 1
Pgina 233
GETNEWPAR()
Sintaxe
GETNEWPAR(cParametro, cPadrao, cFilial)

filial parametrizada na conexo. Se o parmetro no existir, ser exibido um help
do Sistema informando a ocorrncia.
Descrio
Difere do SuperGetMV() pois considera que o parmetro pode no existir na
verso atual do Sistema, e por consequncia no ser exibida a mensagem de
help.
PUTMV()
Sintaxe
PUTMV(cParametro, cConteudo)
Descrio
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com

as parametrizaes informadas.
SUPERGETMV()
Sintaxe
SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)

filial parametrizada na conexo. Se o parmetro no existir, ser exibido um help
do Sistema informando a ocorrncia.
Descrio
Difere do GetMv() pois os parmetros consultados so adicionados em uma rea
de memria que permite que em uma nova consulta no seja necessrio acessar
e pesquisar o parmetro na base de dados.
Pgina 234
ADVPL 1
1122..33..22..
CCuuiiddaaddooss nnaa uuttiilliizzaaoo ddee uum

m ppaarrm
meettrroo
Um parmetro de sistema tem a finalidade de propiciar um retorno vlido a um contedo

previamente definido na configurao do mdulo para uma rotina, processo, ou quaisquer
outros tipos de funcionalidades disponveis na aplicao.
Apesar de haver parmetros que permitam a configurao de expresses, e por consequncia

a utilizao de funes para definir o retorno que ser obtido com a consulta desse
parmetro, expressamente proibido o uso de funes em parmetros para manipular
as informaes da base de dados do Sistema.
Se houver necessidade de ser implementado um tratamento adicional a um processo padro

do Sistema, o mesmo dever utilizar o recurso de ponto de entrada.
A razo dessa restrio simples:
As rotinas da aplicao ERP no protegem a consulta de contedos de parmetros,
quanto s gravaes realizadas dentro, ou fora de uma transao.
Dessa forma, qualquer alterao na base realizada por uma rotina, configurada em um
parmetro, pode ocasionar a perda da integridade das informaes do Sistema.
Ttulo ADVPL 1
Pgina 235
12.4. Pontos de Entrada Conceitos, Premissas e Regras

Conceitos
Um ponto de entrada uma User Function desenvolvida com a finalidade de interagir com
uma rotina padro da aplicao ERP.
A User Function dever ter um nome pr-estabelecido no desenvolvimento da rotina padro

do ERP, e de acordo com esta pr-disposio e o momento no qual o ponto de entrada
executado durante um processamento, ele poder:
Complementar uma validao realizada pela aplicao;
Complementar as atualizaes realizadas pelo processamento em tabelas padres do
ERP;
Implementar a atualizao de tabelas especficas durante o processamento de uma
rotina padro do ERP;
Executar uma ao sem processos de atualizaes, mas que necessite utilizar as
informaes atuais do Ambiente, durante o processamento da rotina padro para

determinar as caractersticas do processo;
Substituir um processamento padro do Sistema por uma regra especfica do cliente,
no qual o mesmo ser implementado.
Premissas e Regras
Um ponto de entrada no deve ser utilizado para outras finalidades seno para as
quais 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 a sua situao imediatamente anterior execuo do ponto
Pgina 236
ADVPL 1
restaurado ao trmino do mesmo, e para isto recomenda-se o uso das funes

GETAREA() e RESTAREA().
Como um ponto de entrada no executado da forma tradicional, ou seja, ele no
chamado como uma funo, ele no recebe parmetros. A aplicao ERP disponibiliza
uma varivel de Sistema denominada PARAMIXB, a qual recebe os parmetros da
funo chamadora e os disponibiliza para serem utilizados pela rotina customizada.
A varivel PARAMIXB no possui um padro de definio nos cdigos fontes da
aplicao ERP, desta forma seu tipo pode variar de um contedo simples (caractere,
numrico, lgico e etc.) a um tipo complexo como um array ou um objeto. Assim,
necessrio sempre avaliar a documentao sobre o ponto, bem como proteger a
funo customizada de tipos de PARAMIXB no tratados por ela.
Ttulo ADVPL 1
Pgina 237
13.
INTERFACES VISUAIS
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
para 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.
13.1. Sintaxe e componentes das interfaces visuais

A sintaxe convencional para definio de componentes visuais da linguagem ADVPL
depende diretamente, em include especificado no cabealho, do fonte. Os dois includes,
disponveis para o Ambiente ADVPL Protheus, so:
RWMAKE.CH: Permite
componentes visuais.
utilizao
da
sintaxe
CLIPPER
na
definio
dos
PROTHEUS.CH: Permite a utilizao da sintaxe ADVPL convencional, a qual um

aprimoramento da sintaxe CLIPPER, com a incluso de novos atributos para os
componentes visuais disponibilizados no ERP Protheus.
Para ilustrar a diferena na utilizao destes dois includes, seguem as diferentes
definies para o componentes Dialog e MsDialog:
Exemplo 01 Include Rwmake.ch
#include rwmake.ch
@ 0,0 TO 400,600 DIALOG oDlg TITLE "Janela em sintaxe Clipper"
ACTIVATE DIALOG oDlg CENTERED
Exemplo 02 Include Protheus.ch

DEFINE MSDIALOG oDlg TITLE "Janela em sintaxe ADVPL "FROM 000,000 TO 400,600
PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
Pgina 238
ADVPL 1
Ambas sintaxes produziro o mesmo efeito quando compiladas e

executadas no ambiente Protheus, mas deve ser utilizada sempre
a sintaxe ADVPL, por meio do uso do include PROTHEUS.CH.
Os componentes da interface visual que sero tratados neste tpico, utilizando a sintaxe
ADVPL so:
MSDIALOG()
MSGET()
SAY()
BUTTON()
SBUTTON()
BUTTON()
Sintaxe
@ nLinha,nColuna BUTTON cTexto SIZE

oObjetoRef ACTION AO
nLargura,nAltura UNIDADE OF
Descrio
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.
MSDIALOG()
Sintaxe
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO

nLiFim,nColFim OF oObjetoRef UNIDADE
Descrio
Define o componente MSDIALOG(), que utilizado como base para os demais

componentes da interface visual, pois um componente MSDIALOG() uma
janela da aplicao.
Ttulo ADVPL 1
Pgina 239
MSGET()
Sintaxe
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF

oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture
Descrio
Define o componente visual MSGET, que

informaes digitveis na tela da interface.
utilizado para captura de
SAY()
Sintaxe
@ nLinha, nColuna SAY cTexto

oObjetoRef
SIZE nLargura,nAltura UNIDADE OF
Descrio
Define o componente visual SAY, que utilizado para a exibio de textos em

uma tela de interface.
SBUTTON()
Sintaxe
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS

OF oObjetoRet
Descrio
Define o componente visual SButton, que permite a incluso de botes de

operao na tela da interface, que sero visualizados dependendo da interface
do sistema ERP, utilizada somente com um texto simples para sua identificao,
ou com uma imagem (BitMap) pr-definido.
Interface visual completa

Abaixo, segue um cdigo completo de interface, utilizando todos os elementos da
interface visual descritos anteriormente:
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL

@ 001,001 TO 040, 150 OF oDlg PIXEL
@ 010,010 SAY
Pgina 240
cTexto SIZE 55, 07 OF oDlg PIXEL
ADVPL 1
@ 010,050 MSGET
99.999.999/9999-99";
VALID !Vazio()
cCGC
SIZE
55,
11
OF
oDlg
PIXEL
PICTURE
"@R
DEFINE SBUTTON FROM 010, 120 TYPE 1 ACTION (nOpca := 1,oDlg:End());

ENABLE OF oDlg
ENABLE OF oDlg
O cdigo demonstrado anteriormente utilizado nos exerccios de fixao

deste material e dever produzir a seguinte interface:
Ttulo ADVPL 1
Pgina 241
13.2. Interfaces padres para atualizaes de dados

Os programas de atualizao de cadastros e digitao de movimentos seguem um padro
que se apia no Dicionrio de Dados.
Basicamente so duas as interfaces quer permitem a visualizao das informaes e a

manipulao dos dados do Sistema.
AxCadastro
Mbrowse
Ambos modelos utilizam como premissa que a estrutura da tabela a ser utilizada esteja
definida no dicionrio de dados do sistema (SX3).
1133..22..11..
A
AxxCCaaddaassttrroo(())
O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes de

customizao, composta por:
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Funes de pesquisa, visualizao, incluso, alterao e excluso de padres para

visualizao de registros simples, sem a opo de cabealho e itens.
Sintaxe: AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)
Parmetros
cAlias
Alias padro do sistema para utilizao, o qual deve estar definido no

dicionrio de dados SX3
cTitulo
Ttulo da Janela
cVldExc
Validao para Excluso
cVldAlt
Validao para Alterao
Pgina 242
ADVPL 1
Exemplo:
#include "protheus.ch"
User Function XCadSA2()
Local cAlias := "SA2"

Local cTitulo := "Cadastro de Fornecedores"
Local cVldExc := ".T."
Local cVldAlt := ".T."
dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)
Return
Ttulo ADVPL 1
Pgina 243
1133..22..22..
M
MB
Brroow
wssee(())
A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de recursos mais

aprimorados na visualizao e manipulao das informaes do Sistema, possuindo os
seguintes componentes:
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Parametrizao para as funes especficas para as aes de visualizao, incluso,

alterao e excluso de informaes, o que viabiliza a manuteno de informaes
com estrutura de cabealhos e itens.
Recursos adicionais como identificadores de status de registros, legendas e filtros para

as informaes.
Sintaxe simplificada: MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias)
Parmetros
nLin1,
nCol1, Coordenadas dos cantos aonde o browse ser exibido. Para seguir o
nLin2, nCol2
padro da AXCADASTRO() use 6,1,22,75 .
cAlias
Pgina 244
Alias padro do sistema para utilizao. Deve estar definido no dicionrio

de dados SX3.
ADVPL 1
Variveis private adicionais
Array contendo as funes que sero executadas pela Mbrowse.

Este array pode ser parametrizado com as funes bsicas da AxCadastro
conforme abaixo:
aRotina
cCadastro
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})
Ttulo do browse que ser exibido.
Exemplo:
User Function MBrwSA2()

Private cCadastro := "Cadastro de Fornecedores"
Private aRotina
:= {}
,"AxPesqui",0,1})
,"AxVisual",0,2})
,"AxInclui",0,3})
,"AxAltera",0,4})
,"AxDeleta",0,5})
Ttulo ADVPL 1
Pgina 245
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
Utilizando a parametrizao exemplificada, o efeito obtido com

o uso da Mbrowse() ser o mesmo obtido com o uso da
AxCadastro().
A posio das funes no array aRotina define o contedo de

uma varivel de controle que ser repassada para as funes
chamadas a partir da Mbrowse, convencionada como nOpc.
Dessa forma, para manter o padro da aplicao ERP a ordem a
ser seguida na definio do aRotina ;
1 Pesquisar;
2 Visualizar;
3 Incluir;
Pgina 246
ADVPL 1
4 Alterar;
5 Excluir;
6 Livre.
Ao definir as funes no array aRotina, se o nome da funo no

for especificado com (), a Mbrowse passar como parmetros
as seguintes variveis de controle:
cAlias: Alias ativo definido para a Mbrowse;

nRecno: Record number (recno) do registro posicionado no alias
ativo;
nOpc: Posio da opo utilizada na Mbrowse de acordo com a
ordem da funo no array a Rotina.
Ttulo ADVPL 1
Pgina 247
Exemplo: Funo BInclui() substituindo a funo AxInclui()
User Function MBrwSA2()
Private cCadastro := "Cadastro de Fornecedores"

Private aRotina
:= {}
,"AxPesqui"
,0,1})
,"AxVisual"
,0,2})
,"U_BInclui" ,0,3})
,"AxAltera"
,0,4})
,"AxDeleta"
,0,5})
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
USER FUNCTION BInclui(cAlias, nReg, nOpc)
Local cTudoOk := "(Alert('OK'),.T.)"

AxInclui(cAlias,nReg,nOpc,,,,cTudoOk)
RETURN
Pgina 248
ADVPL 1
Ttulo ADVPL 1
Pgina 249
1133..22..33..
A
AxxFFuunnccttiioonnss(())
Conforme foi mencionado nos tpicos sobre as interfaces padres AxCadastro() e Mbrowse(),
existem funes padres da aplicao ERP que permitem a visualizao, incluso, alterao e
excluso de dados em formato simples.
Essas funes so padres na definio da interface AxCadastro() e podem ser utilizadas

tambm da construo no array aRotina, utilizado pela Mbrowse(), as quais esto listadas a
seguir:
AXPESQUI()
AXVISUAL()
AXINCLUI()
AXALTERA()
AXDELETA()
AXALTERA()
Sintaxe
AxAltera(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact,

aButtons, aParam, aAuto, lVirtual, lMaximized)
Descrio
Funo de alterao padro das informaes de um registro, no formato

Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro().
AXDELETA()
Sintaxe
AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,; aAuto,

lMaximized)
Descrio
Funo de excluso padro das informaes de um registro, no formato

AXINCLUI()
Pgina 250
ADVPL 1
Sintaxe
AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,; cTransact,

aButtons, aParam, aAuto, lVirtual, lMaximized)
Descrio
Funo de incluso padro das informaes de um registro, no formato

AXPESQUI()
Sintaxe
AXPESQUI()
Descrio
Funo de pesquisa padro em registros exibidos pelos browses do Sistema,

que 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.
Ttulo ADVPL 1
Pgina 251
AXVISUAL()
Sintaxe
AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;

aButtons, lMaximized )
Descrio
Funo de visualizao padro das informaes de um registro, no formato

Exerccio 15
Desenvolver uma validao para um campo especfico do tipo caractere, cujo
contedo esteja relacionado a outra tabela e que exiba uma mensagem de aviso
caso o cdigo informado no exista nessa tabela relacionada.
Exerccio 16
Desenvolver uma validao para um campo caractere existente na base, para que
seja avaliado se aquele cdigo j existe cadastrado, e se positivo, exiba uma
mensagem de aviso alertando sobre a ocorrncia.
Exerccio 17
Desenvolver um gatilho que retorne uma descrio complementar para um campo
vinculado ao campo cdigo utilizado nos exerccios anteriores.
Pgina 252
ADVPL 1
Exerccio 18
Customizar o parmetro que define o prefixo do ttulo de contas a pagar, gerado
pela integrao COMPRAS -> FINANCEIRO atravs da incluso de uma nota fiscal de
entrada, de forma que o prefixo do ttulo seja gerado com o cdigo da filial corrente.
Exerccio 19
Proteger a rotina desenvolvida no exerccio anterior, de forma a garantir que na
utilizao da filial como prefixo do ttulo, no ocorrer duplicidade de dados em
contas a pagar do financeiro.
Exerccio 20
Vamos Implementar uma validao adicional no cadastro de clientes, com a
utilizao do ponto de entrada adequado, de forma que o campo CNPJ (A1_CGC)
seja obrigatrio para todos os tipos de clientes, exceto os definidos como Exterior.
Ttulo ADVPL 1
Pgina 253
APNDICES
BOAS PRTICAS DE PROGRAMAO
14.
UTILIZAO DE IDENTAO
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 a ferramenta DEV-Studio, a qual pode ser
configurada atravs da opo Preferncias:
Pgina 254
ADVPL 1
Ttulo ADVPL 1
Pgina 255
15.
CAPITULAO DE PALAVRAS-CHAVE
Uma conveno amplamente utilizada a de capitular as palavras chaves, funes, variveis e

campos utilizando uma combinao de caracteres em maisculo e minsculo, visando facilitar
a leitura do cdigo fonte. O cdigo a seguir:
local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo
Ficaria melhor com as palavras chaves e variveis capituladas:
Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo
Para as funes de manipulao de dados que comecem por db,

a capitulao s ser efetuada aps o db:
dbSeek()
dbSelectArea()
Pgina 256
ADVPL 1
15.1. Palavras em maisculo

A regra utilizar caracteres em maisculo para:
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...
16.
UTILIZAO DA NOTAO HNGARA
A notao hngara consiste em adicionar os prefixos aos nomes de variveis, de modo a

facilmente identificar o seu tipo. Isso facilita a criao de cdigos-fonte extensos, pois
usando a Notao Hngara, voc no precisa ficar o tempo todo voltando definio de
uma varivel para se lembrar de qual o tipo de dados que deve ser colocado nela.
Variveis devem ter um prefixo de Notao Hngara em minsculas, seguido de um nome
que identifique a funo da varivel, sendo que a inicial de cada palavra deve ser
maiscula.
obrigatria a utilizao desssa notao para nomear variveis.
Notao
Tipo
dado
de
Exemplo
Array
aValores
Bloco de
cdigo
bSeek
Caracter
c
cNome
Data
d
dDataBase
Lgico
l
lContinua
Numrico
n
nValor
Ttulo ADVPL 1
Pgina 257
Objeto
o
oMainWindow
Indefinido
x
Pgina 258
xConteudo
ADVPL 1
17.
PALAVRAS RESERVADAS
AADD
DTOS
INKEY
REPLICATE VAL
ABS
ELSE
INT
RLOCK
VALTYPE
ASC
ELSEIF
LASTREC
ROUND
WHILE
AT
EMPTY
LEN
ROW
WORD
BOF
ENDCASE
LOCK
RTRIM
YEAR
BREAK
ENDDO
LOG
SECONDS
CDOW
ENDIF
LOWER
SELECT
CHR
EOF
LTRIM
SETPOS
CMONTH
EXP
MAX
SPACE
COL
FCOUNT
MIN
SQRT
CTOD
FIELDNAME MONTH
STR
DATE
FILE
PCOL
SUBSTR
DAY
FLOCK
PCOUNT
TIME
DELETED
FOUND
PROCEDURE
TRANSFORM DEVPOS
FUNCTION
PROW
TRIM
DOW
IF
RECCOUNT TYPE
DTOC
IIF
RECNO
UPPER
AS
CATCH
THROW
TRY
Ttulo ADVPL 1
Pgina 259
As palavras reservadas no podem ser utilizadas para variveis,

procedimentos ou funes;
As Funes reservadas so pertencentes ao compilador e no

podem ser redefinidas por uma aplicao;
Todos os identificadores, que comearem com dois ou mais
caracteres _, so utilizados como identificadores internos e so
reservados.
Os Identificadores de escopo PRIVATE ou PUBLIC utilizados em
aplicaes especficas, desenvolvidas por ou para clientes, devem
ter sua identificao iniciada por um caractere _.
Pgina 260
ADVPL 1
GUIA DE REFERNCIA RPIDA: Funes e Comandos

ADVPL
Neste guia de referncia rpida sero descritas as funes bsicas da linguagem ADVPL,
incluindo as funes herdadas da linguagem Clipper, necessrias ao desenvolvimento no
Ambiente ERP.
Converso entre tipos de dados
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

cData
Caractere no formato DD/MM/AAAA.
Exemplo:
cData := 31/12/2006
dData := CTOD(cData)
IF dDataBase >= dData

MSGALERT(Data do sistema fora da competncia)
ELSE
MSGINFO(Data do sistema dentro da competncia)
ENDIF
CVALTOCHAR()
Ttulo ADVPL 1
Pgina 261
Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de
espaos a informao.

Sintaxe: CVALTOCHAR(nValor)
Parmetros
nValor
Valor numrico que ser convertido para caractere.
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
Pgina 262
ADVPL 1
DTOC()
Realiza a converso de uma informao do tipo data para caractere, sendo o resultado no
formato DD/MM/AAAA.

Sintaxe: DTOC(dData)
Parmetros
dData
Varivel com contedo data.
Exemplo:
MSGINFO(Database do sistema: +DTOC(dData)
DTOS()
Realiza a converso de uma informao do tipo data em um caractere, sendo o resultado no

formato AAAAMMDD.

Sintaxe: DTOS(dData)
Parmetros
dData
Varivel com contedo data.
Exemplo:
cQuery := SELECT A1_COD, A1_LOJA, A1_NREDUZ FROM SA1010 WHERE

cQuery += A1_DULTCOM >=+DTOS(dDataIni)+
Ttulo ADVPL 1
Pgina 263
STOD()
Realiza a converso de uma informao do tipo caractere, com contedo no formato

AAAAMMDD em data.
Sintaxe: STOD(sData)
Parmetros

sData
String no formato AAAAMMDD.
Exemplo:
sData := LERSTR(01,08) // Funo que realiza a leitura de uma string de um txt previamente
// aberto
dData := STOD(sData)
STR()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando

espaos direita.

Sintaxe: STR(nValor)
Parmetros
nValor
Pgina 264
ADVPL 1
Exemplo:
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.

Sintaxe: STRZERO(nValor, nTamanho)

Parmetros
nValor
nTamanho
Tamanho total desejado para a string retornada.
Exemplo:
NEXT nPercorridos
Ttulo ADVPL 1
Pgina 265
VAL()
Realiza a converso de uma informao do tipo caracter em numrica.
Sintaxe: VAL(cValor)
Parmetros

cValor
String que ser convertida para numrico.
Exemplo:
Static Function Modulo11(cData)

LOCAL L, D, P := 0
L := Len(cdata)
D := 0
P := 1
While L > 0
P := P + 1
D := D + (Val(SubStr(cData, L, 1)) * P)
If P = 9
P := 1
End
L := L - 1
End
D := 11 - (mod(D,11))
If (D == 0 .Or. D == 1 .Or. D == 10 .Or. D == 11)
D := 1
End
Return(D)
Pgina 266
ADVPL 1
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

cVariavel
Nome da varivel que se deseja avaliar, entre aspas ().
Exemplo:
IF TYPE(dDataBase) == D
MSGINFO(Database do sistema: +DTOC(dDataBase))
ELSE
MSGINFO(Varivel indefinida no momento)
Ttulo ADVPL 1
Pgina 267
VALTYPE()
Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em

execuo.
Sintaxe: VALTYPE(cVariavel)
Parmetros

cVariavel
Nome da varivel que se deseja avaliar.
Exemplo:
STATIC FUNCTION GETTEXTO(nTamanho, cTitulo, cSay)
LOCAL cTexto :=
LOCAL nColF
:= 0
LOCAL nLargGet
:= 0
PRIVATE oDlg
Default cTitulo:= "Tela para informar texto"

Default cSay := "Informe o texto:"
Default nTamanho
:= 1
IF ValType(nTamanho) != N // Se o parmetro foi passado incorretamente

nTamanho
:= 1
ENDIF
cTexto
:= Space(nTamanho)
nLargGet
:= Round(nTamanho * 2.5,0)
nColf
:= Round(195 + (nLargGet * 1.75) ,0)
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 120,nColF PIXEL

@ 005,005 TO 060, Round(nColF/2,0) OF oDlg PIXEL
Pgina 268
ADVPL 1
@ 010,010 SAY cSay SIZE 55, 7 OF oDlg PIXEL

@ 010,065 MSGET cTexto SIZE nLargGet, 11 OF oDlg PIXEL ;
Picture "@!" VALID !Empty(cTexto)
DEFINE SBUTTON FROM 030, 010 TYPE 1 ;
ACTION (nOpca := 1,oDlg:End()) ENABLE OF oDlg
DEFINE SBUTTON FROM 030, 040 TYPE 2 ;
ACTION (nOpca := 0,oDlg:End()) ENABLE OF oDlg
cTexto := IIF(nOpca==1,cTexto,"")
RETURN cTexto
Ttulo ADVPL 1
Pgina 269
Manipulao de arrays
Array()
A funo Array() utilizada na definio de variveis de tipo array, como uma opo a sintaxe
utilizando chaves ({}).

Sintaxe: Array(nLinhas, nColunas)

Parmetros
nLinhas
Determina o nmero de linhas com as quais o array ser criado.
nColunas
Determina o nmero de colunas com as quais o array ser criado.
Exemplo:
aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.
O array definido pelo comando Array() apesar de j possuir a

estrutura solicitada, no possui contedo em nenhum de seus
elementos, ou seja:
aDados[1] -> array de trs posies

aDados[1][1] -> posio vlida, mas de contedo nulo.
AADD()
Pgina 270
ADVPL 1
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.

Sintaxe: AADD(aArray, xItem)

Parmetros
aArray
Array pr-existente no qual ser adicionado o item definido em xItem.
xItem
Item que ser adicionado ao array.
Ttulo ADVPL 1
Pgina 271
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.
AADD(aItem, cVariavel1) // Adiciona um elemento no array aItem de acordo com o cVariavel1

// Neste ponto o array a Item possui 03 elementos os quais podem ser acessados com:
// aItem[1] -> corresponde ao contedo de cVariavel1
AADD(aDados,aItem) // Adiciona no array aDados o contedo do array aItem

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
AADD(aDados, aItem)
AADD(aDados, aItem)
// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros
// 03 elementos, sendo:

Pgina 272
ADVPL 1


// 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:
// Utilizando o array aDados, utilizado no exemplo da funo AADD()

aItens := ACLONE(aDados).
// Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array
// aDados.
Ttulo ADVPL 1
Pgina 273
Por ser uma estrutura de memria, um array no pode ser

simplesmente copiado para outro array, com a utilizao de uma
atribuio simples (:=).
Para mais informaes sobre a necessidade de utilizar o comando

ACLONE(), verifique o tpico 6.1.3 Cpia de Arrays.
ADEL()
A funo ADEL() permite a excluso de um elemento do array. Ao efetuar a excluso de um

elemento, todos os demais so reorganizados de forma que a ltima posio do array passar
a ser nula.

Sintaxe: ADEL(aArray, nPosio)

Parmetros
aArray
Array do qual deseja-se remover uma determinada posio.
nPosio
Posio do array que ser removida.
Exemplo:
// Utilizando o array aItens do exemplo da funo ACLONE() temos:
ADEL(aItens,1) // Ser removido o primeiro elemento do array aItens.
// Neste ponto, o array aItens continua com 03 elementos, onde:

// aItens[1] -> antigo aItens[2], o qual foi reordenado como efeito da excluso do item 1.
// 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.
Pgina 274
ADVPL 1
ASIZE()
A funo ASIZE permite a redefinio da estrutura de um array pr-existente, adicionando ou

removendo itens do mesmo.

Sintaxe: ASIZE(aArray, nTamanho)

Parmetros
aArray
Array pr-existente que ter sua estrutura redimensionada.
nTamanho
Tamanho com o qual se deseja 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.
Ttulo ADVPL 1
Pgina 275
Exemplo:
// Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo ADEL()
ASIZE(aItens,Len(aItens-1)).
// Nesse ponto o array aItens possui 02 elementos, ambos com contedos vlidos.
Utilizar a funo ASIZE(), aps o uso da funo ADEL(), uma

prtica recomendada e evita que seja acessada uma posio do
array com um contedo invlido para a aplicao em uso.
ASORT()
A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio
pr-estabelecido.

Sintaxe: ASORT(aArray, nInicio, nItens, bOrdem)

Parmetros
aArray
Array pr-existente que ter seu contedo ordenado utilizando um critrio

estabelecido.
nInicio
Posio inicial do array para incio da ordenao. Se no for informado, o array

ser ordenado a partir de seu primeiro elemento.
nItens
Quantos itens, a partir da posio inicial devero ser ordenados. Se no for

informado, sero ordenados todos os elementos do array.
bOrdem
O bloco de cdigo que permite a definio do critrio de ordenao do array. Se

o bOrdem no for informado, ser utilizado o critrio ascendente.
Pgina 276
ADVPL 1
Um bloco de cdigo basicamente uma funo escrita em linha. Dessa

forma, sua estrutura deve suportar todos os requisitos de uma funo,
os quais so por meio da anlise e interpretao de parmetros recebidos,
executar um processamento e fornecer um retorno.
Com base nesse requisito, possvel definir um bloco de cdigo com a
estrutura abaixo:
bBloco := { |xPar1, xPar2, ... xParZ| Ao1, Ao2, AoZ } , aonde:
|| -> define o intervalo onde esto compreendidos os parmetros
Ao Z-> expresso que ser executadas pelo bloco de cdigo
Ao1... AoZ -> intervalo de expresses que sero executadas pelo bloco
de cdigo, no formato de lista de expresses.
Retorno -> resultado da ltima ao executada pelo bloco de cdigo, no
caso
AoZ.
Para maiores detalhes sobre a estrutura e utilizao de blocos de cdigo,
consulte o tpico 6.2 Listas de Expresses e Blocos de cdigo.
Exemplo 01 Ordenao ascendente
aAlunos := { Mauren, Soraia, Andria}
aSort(aAlunos)
// Nesse ponto, os elementos do array aAlunos sero {Andria, Mauren, Soraia}
Ttulo ADVPL 1
Pgina 277
Exemplo 02 Ordenao descendente
aAlunos := { Mauren, Soraia, Andria}

bOrdem := {|x,y| x > y }
// 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, possvel substituir x por cNomeAtu.
// A varivel y receber o contedo do prximo item a ser avaliado, e usando a mesma
// analogia de x, possvel substituir y por cNomeProx. Dessa forma o bloco de cdigo
// bOrdem pode ser re-escrito como:
bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}
aSort(aAlunos,,bOrdem)
// Nesse ponto, os elementos do array aAlunos sero {Soraia , Mauren, Andria}
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.

Sintaxe: ASCAN(aArray, bSeek)

Parmetros
aArray
Array pr-existente no qual deseja identificar a posio que contm a

informao pesquisada.
bSeek
Bloco de cdigo que configura os parmetros da busca ser realizada.
Pgina 278
ADVPL 1
Exemplo:
aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}
bSeek := {|x| x == Denis}
nPosAluno := aScan(aAlunos,bSeek) // retorno esperado 2
Durante a execuo da funo aScan, a varivel x receber o contedo

do item que est posicionado no momento, no caso aAlunos[x]. Como
aAlunos[x] uma posio do array que contm o nome do aluno, x
poderia ser renomeada para cNome, e a definio do bloco bSeek poderia
ser re-escrita como:
bSeek := {|cNome| cNome == Denis}
Ttulo ADVPL 1
Pgina 279
Na definio dos programas sempre recomendvel utilizar

variveis com nomes significativos, desta forma os blocos de
cdigo no so exceo.
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.
AINS()
A funo AINS() permite a insero de um elemento no array especificado, em qualquer

ponto da estrutura do mesmo, diferindo dessa forma da funo AADD(), a qual sempre insere
um novo elemento ao final da estrutura j existente.

Sintaxe: AINS(aArray, nPosicao)

Parmetros
aArray
Array pr-existente no qual desejasse inserir um novo elemento.
nPosicao
Posio na qual o novo elemento ser inserido.
Exemplo:
aAlunos := {Edson, Robson, Renato, Tatiana}
AINS(aAlunos,3)
// Nesse ponto o array aAlunos ter o seguinte contedo:

// {Edson, Robson, nulo, Renato, Tatiana}
Pgina 280
ADVPL 1
Similar ao efeito da funo ADEL(), o elemento inserido no array

pela funo AINS() ter um contedo nulo, sendo necessrio
trat-lo aps a realizao deste comando.
Ttulo ADVPL 1
Pgina 281
Manipulao de blocos de cdigo
EVAL()
A funo EVAL() utilizada para avaliao direta de um bloco de cdigo, utilizando as

informaes disponveis no mesmo de sua execuo. Esta funo permite a definio e
passagem de diversos parmetros que sero considerados na interpretao do bloco de
cdigo.

Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)

Parmetros
bBloco
Bloco de cdigo que ser interpretado.
xParamZ
Parmetros que sero passados ao bloco de cdigo. A partir da passagem do

bloco, todos os demais parmetros da funo sero convertidos em parmetros
para a interpretao do cdigo.
Exemplo:
nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
nValor := EVAL(bBloco, nInt)
// O retorno ser dado pela avaliao da ultima ao da lista de expresses, no caso z.

// Cada uma das variveis definidas, em uma das aes da lista de expresses, fica disponvel
// para a prxima ao.
// Desta forma temos:
// N recebe nInt como parmetro (10)
// X tem atribudo o valor 10 (10)
// Y resultado da multiplicao de X por N (100)
// Z resultado da diviso de Y pela multiplicao de X por N ( 100 / 100) 1
Pgina 282
ADVPL 1
DBEVAL()
A funo DBEval() permite que todos os registros de uma determinada tabela sejam
analisados, e para cada registro ser executado o bloco de cdigo definido.

Sintaxe: Array(bBloco, bFor, bWhile)

Parmetros
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.
Ttulo ADVPL 1
Pgina 283
Exemplo 01
Considerando o trecho de cdigo abaixo:
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA <= mv_par02
nCnt++
dbSkip()
End
O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5") .And. X5_TABELA<=mv_par02})
Exemplo 02
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
While !Eof() .And. X5_TABELA == cTabela

AADD(aTabela,{X5_CHAVE,
Capital(X5_DESCRI)})
dbSkip()
End
Pgina 284
ADVPL 1
Exemplo 02 (continuao):
O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval({|| aAdd(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{|| X5_TABELA==cTabela})
Na utilizao da funo DBEVAL(), deve ser informado apenas um

dos dois parmetros: bFor ou bWhile.
Ttulo ADVPL 1
Pgina 285
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.

Sintaxe: AEVAL(aArray, bBloco, nInicio, nFim)

Parmetros
aArray
Array que ser avaliado na execuo da funo
bBloco
Bloco de cdigo principal, contendo as expresses que sero avaliadas para

cada elemento do array informado
nInicio
Elemento inicial do array, a partir do qual sero avaliados os blocos de cdigo
nFim
Elemento final do array, at o qual sero avaliados os blocos de cdigo
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
O mesmo pode ser re-escrito com o uso da funo AEVAL():
aEval(aCampos,{|x| SX3->(dbSeek(x)),IIF(Found(), AAdd(aTitulos,;

AllTrim(SX3->X3_TITULO)))})
Pgina 286
ADVPL 1
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 direita e esquerda.
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF

Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))
ASC()
Converte uma informao caractere em seu valor, de acordo com a tabela ASCII.

Sintaxe: ASC(cCaractere)
Parmetros
cCaractere
Caractere que ser consultado na tabela ASCII.
Ttulo ADVPL 1
Pgina 287
Exemplo:
USER FUNCTION NoAcento(Arg1)

Local nConta := 0
Local cLetra := ""
Local cRet := ""
Arg1 := Upper(Arg1)
For nConta:= 1 To Len(Arg1)
cLetra := SubStr(Arg1, nConta, 1)
Do Case
Case (Asc(cLetra) > 191 .and. Asc(cLetra) < 198) .or.;
(Asc(cLetra) > 223 .and. Asc(cLetra) < 230)
cLetra := "A"
cLetra := "E"

cLetra := "I"

(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) < 247)
cLetra := "O"

cLetra := "U"
Case Asc(cLetra) == 199 .or. Asc(cLetra) == 231

cLetra := "C"
Pgina 288
ADVPL 1
EndCase
cRet := cRet+cLetra
Next
Return UPPER(cRet)
AT()
Retorna primeira posio de um caractere ou string dentro de outra string especificada.

Sintaxe: AT(cCaractere, cString )
Parmetros

cCaractere
Caractere ou string que se deseja verificar.
cString
String na qual ser verificada a existncia do contedo de cCaractere.
Exemplo:
STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)
LOCAL cNoMascara
:= ""
LOCAL nX
:= 0
IF !Empty(cMascara) .AND. AT(cMascara,cString) > 0

FOR nX := 1 TO Len(cString)
IF !(SUBSTR(cString,nX,1) $ cMascara)
cNoMascara += SUBSTR(cString,nX,1)
ENDIF
NEXT nX
cNoMascara := PADR(ALLTRIM(cNoMascara),nTamanho)
ELSE
cNoMascara := PADR(ALLTRIM(cString),nTamanho)
ENDIF
RETURN cNoMascara
Ttulo ADVPL 1
Pgina 289
CHR()
Converte um valor nmero, referente a uma informao da tabela ASCII, no caractere que
esta informao representa.
Sintaxe: CHR(nASCII)
Parmetros

nASCII
Cdigo ASCII do caractere.
Exemplo:
#DEFINE CRLF CHR(13)+CHR(10) // FINAL DE LINHA
LEN()
Retorna o tamanho da string especificada no parmetro.

Sintaxe: LEN(cString)
Parmetros
cString
String que ser avaliada.
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF

Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))
Pgina 290
ADVPL 1
LOWER()
Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.

Sintaxe: LOWER(cString)
Parmetros
cString
String que ser convertida para caracteres minsculos.
Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
Ttulo ADVPL 1
Pgina 291
RAT()
Retorna a ltima posio de um caracter ou string dentro de outra string especificada.
Sintaxe: RAT(cCaractere, cString)

Parmetros

cCaractere
Caractere ou string que se deseja verificar
cString
String na qual ser verificada a existncia do contedo de cCaractere
STUFF()
Permite substituir um contedo caractere em uma string j existente, especificando a posio

inicial para esta adio e o nmero de caracteres que sero substitudos.

Sintaxe: STUFF(cString, nPosInicial, nExcluir, cAdicao)

Parmetros
Exemplo:
cLin
:= Space(100)+cEOL // Cria a string base
cCpo := PADR(SA1->A1_FILIAL,02) // Informao que ser armazenada na string
cLin := Stuff(cLin,01,02,cCpo) // Substitui o contedo de cCpo na string base
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).
Pgina 292
ADVPL 1

Sintaxe: SUBSTR(cString, nPosInicial, nCaracteres)

Parmetros
cString
String que se deseja verificar
nPosInicial
Posio inicial da informao que ser extrada da string
nCaracteres
Quantidade de caracteres que devero ser retornados a partir daquele ponto

(inclusive)
Exemplo:
cCampo
:= A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_
Ttulo ADVPL 1
Pgina 293
UPPER()
Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.
Sintaxe: UPPER(cString)
Parmetros

cString
String que ser convertida para caracteres maisculos.
Exemplo:
cTexto := advpl
MSGINFO(Texto:+LOWER(cTexto))
Manipulao de variveis numricas
ABS()
Retorna um valor absoluto (independente do sinal), com base no valor especificado no

parmetro.

Sintaxe: ABS(nValor)
Parmetros
nValor
Valor que ser avaliado
Exemplo:
nPessoas := 20
nLugares := 18
Pgina 294
ADVPL 1
IF nPessoas < nLugares

MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando)
ENDIF
Ttulo ADVPL 1
Pgina 295
INT()
Retorna a parte inteira de um valor especificado no parmetro.

Sintaxe: INT(nValor)
Parmetros

nValor
Exemplo:
STATIC FUNCTION COMPRAR(nQuantidade)
LOCAL nDinheiro := 0.30

LOCAL nPrcUnit := 0.25
IF nDinheiro >= (nQuantidade*nPrcUnit)

RETURN nQuantidade
ELSEIF nDinheiro > nPrcUnit
nQuantidade := INT(nDinheiro / nPrcUnit)
ELSE
nQuantidade := 0
ENDIF
RETURN nQuantidade
Pgina 296
ADVPL 1
NOROUND()
Retorna um valor, truncando a parte decimal do valor especificado no parmetro, de acordo

com a quantidade de casas decimais solicitadas.

Sintaxe: NOROUND(nValor, nCasas)

Parmetros
nValor
nCasas
Nmero de casas decimais vlidas. A partir da casa decimal especificada os

valores sero desconsiderados
Exemplo:
nBase := 2.985
nValor := NOROUND(nBase,2) 2.98
Ttulo ADVPL 1
Pgina 297
ROUND()
Retorna um valor, arredondando a parte decimal do valor especificado no parmetro, de

acordo com a quantidades de casas decimais solicitadas, utilizando o critrio matemtico.

Sintaxe: ROUND(nValor, nCasas)

Parmetros
nValor
nCasas
Nmero de casas decimais vlidas. As demais casas decimais sofrero o

arredondamento matemtico, aonde:
Se nX <= 4 0, seno +1 para a casa decimal superior
Exemplo:
nBase := 2.985
nValor := ROUND(nBase,2) 2.99
Pgina 298
ADVPL 1
Manipulao de arquivos
SELECT()
Determina o nmero de referncia de um determinado alias em um ambiente de trabalho.

Caso o alias especificado no esteja em uso no ambiente, ser retornado o valor 0 (zero).

Sintaxe: Select(cArea)
Parmetros
cArea
Nome de referncia da rea de trabalho a ser verificada
Exemplo:
nArea := Select(SA1)
ALERT(Referncia do alias SA1: +STRZERO(nArea,3)) // 10 (proposto)
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
nRecno
Record number do registro a ser posicionado
Ttulo ADVPL 1
Pgina 299
Exemplo:
DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro 100
IF !EOF() // Se a rea de trabalho no estiver em final de arquivo

MsgInfo(Voc est no cliente:+A1_NOME)
ENDIF
Pgina 300
ADVPL 1
DBGOTOP()
Move o cursor da rea de trabalho ativa para o primeiro registro lgico.
Sintaxe: DbGoTop()
Parmetros

Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo

DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbGoTop()
While !BOF() // Enquanto no for o incio do arquivo

nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(-1)
End
MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).
// Retorno esperado :000001, pois o DbGoTop posiciona no primeiro registro.
Ttulo ADVPL 1
Pgina 301
DBGOBOTTON()
Move o cursor da rea de trabalho ativa para o ltimo registro lgico.
Sintaxe: DbGoBotton()
Parmetros

Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo

DbSelectArea(SA1)
DbGoBotton()
While !EOF() // Enquanto no for o incio do arquivo

nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(1)
End
MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).
// Retorno esperado :000001, pois o DbGoBotton posiciona no ltimo registro.
DBSELECTAREA()
Define a rea de trabalho especificada como sendo a rea ativa. Todas as operaes
subsequentes que fizerem referncia a uma rea de trabalho para utilizao, a menos que a
rea desejada seja informada explicitamente.
Pgina 302
ADVPL 1

Sintaxe: DbSelectArea(nArea | cArea)

Parmetros
nArea
Valor numrico que representa a rea desejada, em funo de todas as reas j

abertas pela aplicao, que pode ser utilizado ao invs do nome da rea
cArea
Nome de referncia da rea de trabalho a ser selecionada
Exemplo 01: DbselectArea(nArea)
nArea := Select(SA1) // 10 (proposto)
DbSelectArea(nArea) // De acordo com o retorno do comando Select().
ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias selecionado, os comandos

// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME.
Exemplo 01: DbselectArea(cArea)
DbSelectArea(SA1) // Especificao direta do alias que deseja-se selecionar.
ALERT(Nome do cliente: +A1_NOME) // Como o SA1 o alias selecionado, os comandos

// a partir da seleo do alias compreendem que ele
// est implcito na expresso, o que causa o mesmo
// efeito de SA1->A1_NOME.
Ttulo ADVPL 1
Pgina 303
DBSETORDER()
Define qual ndice ser utilizado 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
nOrdem
Nmero de referncia da ordem que deseja ser definida como ordem ativa para
a rea de trabalho
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // De acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DBORDERNICKNAME()
Define qual ndice criado pelo usurio ser 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
NickName
NickName atribudo ao ndice criado pelo usurio.
Exemplo:
DbSelectArea(SA1)
DbOrderNickName(Tipo) // De acordo com o arquivo SIX -> A1_FILIAL+A1_TIPO
NickName: Tipo
Pgina 304
ADVPL 1
DBSEEK() E MSSEEK()
DbSeek(): Permite posicionar o cursor da rea de trabalho ativo no registro com as

informaes especificadas na chave de busca, fornecendo um retorno lgico e indicando se o
posicionamento foi efetuado com sucesso, ou seja, se a informao especificada, na chave de
busca, foi localizada na rea de trabalho.
Sintaxe: DbSeek(cChave, lSoftSeek, lLast)

Parmetros

cChave
Dados do registro que se deseja localizar, de acordo com a ordem de busca

previamente especificada pelo comando DbSetOrder(), ou seja, de acordo com o
ndice ativo no momento para a rea de trabalho.
lSoftSeek
Define se o cursor ficar posicionado no prximo registro vlido, em relao

chave de busca especificada, ou em final de arquivo, caso no seja encontrada
exatamente a informao da chave. Padro .F.
lLast
Define se o cursor ser posicionado no primeiro ou no ltimo registro de um

intervalo, com as mesmas informaes especificadas na chave. Padro .F.
Exemplo 01 Busca exata
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001, Loja: 02
MsgInfo(Cliente localizado, Consulta por cliente)
Else
MsgAlert(Cliente no encontrado, Consulta por cliente)
Endif
Ttulo ADVPL 1
Pgina 305
Exemplo 02 Busca aproximada
DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DbSeek(01 + 000001 + 02, .T. ) // Filial: 01, Cdigo: 000001, Loja: 02
// Exibe os dados do cliente localizado, o qual pode no ser o especificado na chave:
MsgInfo(Dados do cliente localizado: +CRLF +;
Pgina 306
Filial:
+ A1_FILIAL
+ CRLF +;
Cdigo:
+ A1_COD
+ CRLF +;
Loja:
+ A1_LOJA
+ CRLF +;
Nome:
+ A1_NOME + CRLF, Consulta por cliente)
ADVPL 1
MsSeek(): Funo desenvolvida pela rea de Tecnologia da Microsiga, a qual possui as

mesmas funcionalidades bsicas da funo DbSeek(), com a vantagem de no necessitar
novamente do acesso da base de dados para localizar uma informao j utilizada pela
thread (conexo) ativa.
Desta forma, a thread mantm em memria os dados necessrios para reposicionar os

registros j localizados atravs do comando DbSeek (no caso o Recno()), de forma que a
aplicao pode simplesmente efetuar o posicionamento sem executar novamente a busca.
A diferena entre o DbSeek() e o MsSeek() notada em aplicaes com grande volume de

posicionamentos, como relatrios, que necessitam referenciar diversas vezes o mesmo
registro, durante uma execuo.
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

nRegistros
Define em quantos registros o cursor ser deslocado. Padro 1
Exemplo 01 Avanando registros
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
Ttulo ADVPL 1
Pgina 307
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
Pgina 308
ADVPL 1
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.
Sintaxe: DbSetFilter(bCondicao, cCondicao)

Parmetros

bCondicao
Bloco que expressa a condio de filtro em forma executvel
cCondicao
Expresso de filtro simples na forma de string
Exemplo 01 Filtro com bloco de cdigo
bCondicao := {|| A1_COD >= 000001 .AND. A1_COD <= 001000}

DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(bCondicao)
DbGoBotton()
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
Ttulo ADVPL 1
Pgina 309
Exemplo 02 Filtro com expresso simples
cCondicao := A1_COD >= 000001 .AND. A1_COD <= 001000

DbSelectArea(SA1)
DbSetOrder(1)
DbSetFilter(,cCondicao)
DbGoBotton()
While !EOF()
MsgInfo(Voc est no cliente:+A1_COD)
DbSkip()
End
// O ltimo cliente visualizado deve ter o cdigo menor do que 001000.
Pgina 310
ADVPL 1
DBSTRUCT()
Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura ser um
array bidimensional conforme abaixo:
I
D
*
No
me
ca
mp
o
Tip
o
ca
mp
o
Tama
nho
Deci
mais
*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)
Ttulo ADVPL 1
Pgina 311
RECLOCK()
Efetua o travamento do registro posicionado na rea de trabalho ativa, permitindo a incluso

ou alterao das informaes do mesmo.

Sintaxe: RecLock(cAlias,lInclui)
Parmetros
cAlias
Alias que identifica a rea de trabalho que ser manipulada.
lInclui
Define se a operao ser uma incluso (.T.) ou uma alterao (.F.).
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.
Exemplo 02 - Alterao
DbSelectArea(SA1)
DbSeek(01 + 900001 + 01) // Busca exata
IF Found() // Avalia o retorno do ltimo DbSeek realizado

RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
Pgina 312
ADVPL 1
ENDIF
A linguagem ADVPL
RecLock(), as quais so:
possui
variaes
da
funo
RLOCK()
DBRLOCK()
A sintaxe e a descrio destas funes esto disponveis

no Guia de Referncia Rpido ao final deste material.
MSUNLOCK()
Libera o travamento (lock) do registro posicionado, confirmando as atualizaes efetuadas

neste registro.

Sintaxe: MsUnLock()
Parmetros
Nenhum
Exemplo:
DbSelectArea(SA1)
IF Found() // Avalia o retorno do ltimo DbSeek realizado

RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
Ttulo ADVPL 1
Pgina 313
SA1->A1_NREDUZ := ADVPL BSICO

MsUnLock() // Confirma e finaliza a operao
ENDIF
Pgina 314
ADVPL 1
A linguagem ADVPL possui variaes da funo MsUnlock(), as

quais so:
UNLOCK()
DBUNLOCK()
DBUNLOCKALL()
A sintaxe e a descrio destas funes esto disponveis no Guia

de Referncia Rpido ao final deste material.
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.
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 a integridade da informao.

Sintaxe: SoftLock(cAlias)
Parmetros
cAlias
Alias de referncia da rea de trabalho ativa, para o qual o registro posicionado

ser travado.
Ttulo ADVPL 1
Pgina 315
Exemplo:
cChave := GetCliente() // Funo ilustrativa que retorna os dados de busca de um cliente.
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
Pgina 316
ADVPL 1
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)
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.
Sintaxe: DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)
Ttulo ADVPL 1
Pgina 317
Parmetros
Parmetro opcional que permite, caso o cAlias especificado j esteja em uso,

ser fechado antes da abertura do arquivo da base de dados.
lNovo
Driver que permita a aplicao manipular o arquivo de base de dados

especificado. A aplicao ERP possui a varivel __LOCALDRIVER, definida a
partir das configuraes do .ini do server da aplicao.
cDriver
Algumas chaves vlidas: DBFCDX, CTREECDX, DBFCDXAX, TOPCONN.

cArquivo
Nome do arquivo de base de dados que ser aberto com o alias

especificado.
cAlias
Alias para referncia do arquivos de base de dados pela aplicao.
lComparilhado Se o arquivo poder ser utilizado por outras conexes.

lSoLeitura
Se o arquivo poder ser alterado pela conexo ativa.
Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
DBCLOSEAREA()
Permite que um alias presente na conexo seja fechado, o que viabiliza novamente seu uso
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:
Pgina 318
ADVPL 1
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)

DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
Controle de numerao sequencial
GETSXENUM()
Obtm o nmero sequncia do alias especificado no parmetro, atravs da referncia aos

arquivos de sistema SXE/SXF ou ao servidor de numerao, quando esta configurao est
habilitada no ambiente Protheus.

Sintaxe: GETSXENUM(cAlias, cCampo, cAliasSXE, nOrdem)

Parmetros
cAlias
Alias de referncia da tabela para a qual ser efetuado o controle da numerao

sequencial.
cCampo
Nome do campo no qual est implementado o controle da numerao.
cAliasSXE
Parmetro opcional, quando o nome do alias nos arquivos de controle de

numerao no o nome convencional do alias para o sistema ERP.
nOrdem
Nmero do ndice para verificar qual a prxima ocorrncia do nmero.
CONFIRMSXE()
Confirma o nmero alocado atravs do ltimo comando GETSXENUM().

Sintaxe: CONFIRMSXE(lVerifica)
Parmetros
Ttulo ADVPL 1
Pgina 319
lVerifica
Verifica se o nmero confirmado no foi alterado, e se por consequncia j

existe na base de dados.
ROLLBACKSXE()
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao

disponvel para outras conexes.

Sintaxe: ROLLBACKSXE()
Parmetros
Nenhum
Validao
EXISTCHAV()
Retorna .T. ou .F. se o contedo especificado existe no alias especificado. Se existir ser
exibido um help de sistema com um aviso informando da ocorrncia.
A Funo utilizada normalmente para verificar se um determinado cdigo de cadastro j

existe na tabela na qual a informao ser inserida, como por exemplo o CNPJ no cadastro de
clientes ou, fornecedores.

Sintaxe: ExistChav(cAlias, cConteudo, nIndice)

Parmetros
cAlias
Alias de referncia para a validao da informao
cConteudo
Chave a ser pesquisada, sem a filial
Pgina 320
ADVPL 1
nIndice
ndice de busca para consulta da chave
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.
Funo utilizada normalmente para verificar se a informao digitada em um campo, a qual

depende de outra tabela, realmente existe nesta outra tabela, como por exemplo o cdigo de
um cliente em um pedido de venda.

Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)

Parmetros
cAlias
Alias de referncia para a validao da informao
cConteudo
Chave a ser pesquisada, sem a filial
nIndice
ndice de busca para consulta da chave
Ttulo ADVPL 1
Pgina 321
NAOVAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio.

Sintaxe: NaoVazio()
Parmetros
Nenhum
NEGATIVO()
Retorna .T. ou .F. se o contedo digitado para o campo 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
cString
String contendo as informaes vlidas que podem ser digitadas para um

campo.
POSITIVO()
Retorna .T. ou .F. se o contedo digitado para o campo positivo.
Pgina 322
ADVPL 1

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
VAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.

Sintaxe: Vazio()
Parmetros
Nenhum
Parmetros
GETMV()
Retorna o contedo do parmetro especificado no arquivo SX6, considerando a filial

parametrizada na conexo. Se o parmetro no existir, ser exibido um help do sistema
informando a ocorrncia.

Sintaxe: GETMV(cParametro)
Parmetros
Ttulo ADVPL 1
Pgina 323
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema.
GETNEWPAR()

parametrizada na conexo. Se o parmetro no existir, ser exibido um help do sistema
Difere do SuperGetMV() pois considera que o parmetro pode no existir na verso atual do
sistema, e por consequncia no ser exibida a mensagem de help.

Sintaxe: GETNEWPAR(cParametro, cPadrao, cFilial)

Parmetros
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da filial de

sistema.
cPadrao
Contedo padro que ser utilizado, caso o parmetro no exista no SX6.
cFilial
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
Pgina 324
ADVPL 1
PUTMV()
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as

parametrizaes informadas.

Sintaxe: PUTMV(cParametro, cConteudo)

Parmetros
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da filial de sistema
cConteudo
Contedo que ser atribudo ao parmetro no SX6
SUPERGETMV()

parametrizada na conexo. Caso o parmetro no exista, ser exibido um help do sistema
Difere do GetMv(), pois os parmetros consultados so adicionados em uma rea de

memria, que permite que em uma nova consulta no seja necessrio acessar e pesquisar o
parmetro na base de dados.

Sintaxe: SUPERGETMV(cParametro , lHelp , cPadrao , cFilial)

Parmetros
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da filial de

sistema.
lHelp
Se ser exibida a mensagem de Help, caso o parmetro no seja encontrado no

SX6.
cPadrao
Contedo padro que ser utilizado caso o parmetro no exista no SX6.
Ttulo ADVPL 1
Pgina 325
cFilial
Pgina 326
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
ADVPL 1
Componentes da interface visual
MSDIALOG()
Define o componente MSDIALOG() que utilizado como base para os demais
componentes da interface visual, pois um componente MSDIALOG() uma janela da
aplicao.
Sintaxe:
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO nLiFim,nColFim OF

oObjetoRef UNIDADE
Parmetros
oObjetoDLG
Posio do objeto Say em funo da janela em que ele ser definido
cTitulo
Ttulo da janela de dilogo
nLinIni, nColIni
Posio inicial em linha / coluna da janela
nLiFim, nColFim
Posio final em linha / coluna da janela
oObjetoRef
Objeto dialog no qual a janela ser definida
UNIDADE
Unidade de medida das dimenses: PIXEL
Exemplo:
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL

Ttulo ADVPL 1
Pgina 327
Pgina 328
ADVPL 1
MSGET()
Define o componente visual MSGET, o qual utilizado para captura de informaes
digitveis na tela da interface.
Sintaxe:
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3

VALID VALID WHEN WHEN PICTURE cPicture
Parmetros
nLinha, nColuna
Posio do objeto MsGet em funo da janela em que ele ser definido
VARIAVEL
Varivel da aplicao que ser vinculada ao objeto MsGet, que definir

suas caractersticas e na qual ser armezanado o que for informado no
campo
nLargura,nAltura
Dimenses do objeto MsGet para exibio do texto
UNIDADE
oObjetoRef
Objeto dialog no qual o componente ser definido
cF3
String que define a consulta padro, a qual ser vinculada ao campo
VALID
Funo de validao para o campo.
WHEN
Condio para manipulao do campo, a qual pode ser diretamente .T. ou

.F., ou uma varivel ou uma chamada de funo.
cPicture
String contendo a definio da Picture de digitao do campo.
Ttulo ADVPL 1
Pgina 329
Exemplo:
@ 010,050 MSGET cCGC SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()
Pgina 330
ADVPL 1
SAY()
Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela
de interface.
Sintaxe:
@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef
Parmetros
nLinha, nColuna
Posio do objeto Say em funo da janela em que ele ser definido
cTexto
Texto que ser exibido pelo objeto Say
nLargura,nAltura
Dimenses do objeto Say para exibio do texto
UNIDADE
oObjetoRef
Exemplo:
@ 010,010 SAY cTexto SIZE 55, 07 OF oDlg PIXEL
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()
@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef

ACTION AO
Ttulo ADVPL 1
Pgina 331
Parmetros
nLinha,nColuna
Posio do objeto Button em funo da janela em que ele ser definido
cTexto
String contendo o texto que ser exibido no boto
nLargura,nAltura
Dimenses do objeto Button para exibio do texto
UNIDADE
oObjetoRef
AO
Funo ou lista de expresses que define o comportamento do boto

quando ele for utilizado
Exemplo:
010, 120 BUTTON Confirmar SIZE 080, 047 PIXEL OF oDlg;

ACTION (nOpca := 1,oDlg:End())
SBUTTON()
Define o componente visual SButton, que 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-definida.
Sintaxe: SBUTTON()
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF oObjetoRet
Parmetros
nLinha, nColuna
Posio do objeto sButton em funo da janela em que ele ser definido
TYPE N
Nmero que indica o tipo do boto (imagem) pr-definida que ser

utilizada
Pgina 332
ADVPL 1
AO
Funo ou lista de expresses que define o comportamento do boto

quando ele for utilizado
STATUS
Propriedade de uso do boto: ENABLE ou DISABLE
oObjetoRet
Exemplo:
ENABLE OF oDlg
Visual dos diferentes tipos de botes disponveis:
Interfaces de cadastro
AXCADASTRO()
Sintaxe
AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)
Descrio
O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes

de customizao.
Ttulo ADVPL 1
Pgina 333
MBROWSE()
Sintaxe
MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias)
Descrio
A Mbrowse() uma funcionalidade de cadastro que permite a utilizao de

recursos mais aprimorados na visualizao e manipulao das informaes do
sistema.
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
Pgina 334
ADVPL 1
AXVISUAL()
Funo de visualizao padro das informaes de um registro, no formato Enchoice,
conforme demonstrado no tpico sobre a interface AxCadastro().

Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;
aButtons, lMaximized )
Parmetros
cAlias
Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada
nReg
Record number (recno) do registro posicionado no alias ativo
nOpc
Nmero da linha do aRotina que definir o tipo de edio (Incluso,

Alterao, Excluso, Visualizao).
aAcho
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER"
nColMens
Parmetro no utilizado
cMensagem
Parmetro no utilizado.
cFunc
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
Botes adicionais para a EnchoiceBar, no formato:
aButtons
aArray[n][1]
->
Imagem
aArray[n][2] -> bloco de cdigo contendo
aArray[n][3] -> ttulo do boto.
lMaximized
Indica se a janela dever ser ou no maximizada.
do
ao
do
boto;
boto;
AXINCLUI()
Funo de incluso padro das informaes de um registro, no formato Enchoice,

Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;
cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)
Ttulo ADVPL 1
Pgina 335
Parmetros
cAlias
nReg
nOpc

Alterao, Excluso, Visualizao)
aAcho
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER"
cFunc
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso, o parmetro lVirtual definido
internamente pela AxFunction(), executada como .T.
aCpos
Vetor com nome dos campos que podero ser editados

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. )
lF3
Indica se a enchoice est sendo criada em uma consulta F3 para utilizar

variveis de memria
cTransact
Funo que ser executada dentro da transao da AxFunction()

aButtons
aArray[n][1]
->
Imagem
aArray[n][3] -> ttulo do boto
do
ao
do
boto
boto
Funes para execuo em pontos pr-definidos da AxFunction(),

conforme abaixo:
aParam
aParam[1] := Bloco de cdigo que ser processado antes da exibio da

interface.
aParam[2] := Bloco de cdigo para processamento na validao da
confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da transao da
Pgina 336
ADVPL 1
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[n][1] := Nome do campo
aAuto
aAuto[n][2] := Contedo do campo

aAuto[n][3] := Validao que ser utilizada em substituio as validaes
do SX3.
lVirtual
Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de

memria ou os campos da tabela na edio
lMaximized
Indica se a janela dever ser ou no maximizada
AXALTERA()
Funo de alterao padro das informaes de um registro, no formato Enchoice,

Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens, cMensagem,;
cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
Vide documentao de parmetros da funo AxInclui().
Ttulo ADVPL 1
Pgina 337
AXDELETA()
Funo de excluso padro das informaes de um registro, no formato Enchoice,

Sintaxe: AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,;
aAuto, lMaximized)
Parmetros
cAlias
nReg
nOpc

Alterao, Excluso, Visualizao)
cTransact
Funo que ser executada dentro da transao da AxFunction()
aCpos
Vetor com nome dos campos que podero ser editados

aButtons
aArray[n][1]
->
Imagem
aArray[n][3] -> ttulo do boto
do
a ao
do
boto
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
aParam[2] := Bloco de cdigo para processamento na validao da

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().
aAuto
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[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
Pgina 338
ADVPL 1
aAuto[n][3] := Validao que ser utilizada em substituio as validaes

do SX3.
lMaximized
Indica se a janela dever ser ou no maximizada
Ttulo ADVPL 1
Pgina 339
Funes visuais para aplicaes
ALERT()

Sintaxe: AVISO(cTexto)
Parmetros
cTexto
Texto a ser exibido
AVISO()

Sintaxe: AVISO(cTitulo, cTexto, aBotoes, nTamanho)

Retorno: numrico indicando o boto selecionado.
Parmetros
cTitulo
Ttulo da janela
cTexto
Texto do aviso
aBotoes
Array simples (vetor) com os botes de opo
nTamanho
Tamanho (1,2 ou 3)
Pgina 340
ADVPL 1
Ttulo ADVPL 1
Pgina 341
FORMBACTH()

Sintaxe: FORMBATCH(cTitulo, aTexto, aBotoes, bValid, nAltura, nLargura )

Parmetros
cTitulo
Ttulo da janela
aTexto
Array simples (vetor) contendo cada uma das linhas de texto que sero exibidas
no corpo da tela
Array com os botes do tipo SBUTTON(), com a seguinte estrutura:
aBotoes
{nTipo,lEnable,{|| Ao() }}
bValid
(opcional) Bloco de validao do janela
nAltura
(opcional) Altura em pixels da janela
nLargura
(opcional) Largura em pixels da janela
Pgina 342
ADVPL 1
MSGFUNCTIONS()

Sintaxe: MSGALERT(cTexto, cTitulo)

Sintaxe: MSGINFO(cTexto, cTitulo)
Sintaxe: MSGSTOP(cTexto, cTitulo)
Sintaxe: MSGYESNO(cTexto, cTitulo)
Parmetros
cTexto
Texto a ser exibido como mensagem
cTitulo
Ttulo da janela de mensagem
MSGALERT
MSGINFO
MSGSTOP
Ttulo ADVPL 1
Pgina 343
MSGYESNO
Pgina 344
ADVPL 1
Funes ADVPL para aplicaes
GETAREA()
Funo utilizada para proteger o ambiente ativo no momento de algum processamento
especfico. Para salvar uma outra rea de trabalho (alias) que no o ativo, a funo
GetArea() deve ser executada dentro do alias: ALIAS->(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
aArea
Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo uso

da funo GetArea().
Exemplo:
// ALIAS ATIVO ANTES DA EXECUO DA ROTINA SN3

User Function XATF001()
LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.
Ttulo ADVPL 1
Pgina 345
cVar := &(ReadVar())
dbSelectArea("SX5")
IF !dbSeek(xFilial()+"Z1"+cVar)
cSTR0001 := "REAV - Tipo de Reavaliacao"

cSTR0002 := "Informe um tipo de reavalicao valido"
cSTR0003 := "Continuar"
Aviso(cSTR0001,cSTR0002,{cSTR0003},2)
lRet := .F.
ENDIF
RestArea(aArea)
Return( lRet )
Pgina 346
ADVPL 1
REFERNCIAS BIBLIOGRFICAS
Referncias bibliogrficas
Gesto empresarial com ERP
Ernesto Haberkorn, 2006
Lgica de Programao A Construo de Algoritmos e Estruturas de Dados
Forbellone, Andr Luiz Villar - MAKRON, 1993
Introduo Programao - 500 Algoritmos Resolvidos
Anita Lopes, Guto Garcia CAMPUS / ELSEVIER, 2002
Apostila de Treinamento - ADVPL
Educao corporativa
Apostila de Treinamento Introduo programao
Educao corporativa
Apostila de Treinamento Boas Prticas de Programao
Inteligncia Protheus e Fbrica de Software
Curso Bsico de Lgica de Programao
Paulo Srgio de Moraes PUC Campinas
Ttulo ADVPL 1
Pgina 347
TDN TOTVS Developer Network
Microsiga Software S.A.
Materiais diversos de colaboradores Totvs
Colaboradores Totvs
Pgina 348
ADVPL 1

Apostila Advpl1 p10

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Apostila Advpl1 p10

Caricato da

Copyright:

Formati disponibili

ADVPL 1

Todos os direitos reservados.

0800 709 8100

OBJETIVOS DO CURSO .......................................................................................6

LGICA DE PROGRAMAO E ALGORITMOS ...........................................7

Lgica de Programao ........................................................................7

Desenvolvendo algoritmos ...................................................................9

1.2.1. Estudando algoritmos ................................................................................................................................10

Diagrama de bloco .............................................................................15

Estruturas de deciso e repetio........................................................20

2.2.1. Estruturas de deciso .................................................................................................................................20

MDULO 02: A LINGUAGEM ADVPL ...............................................................29

ESTRUTURA DE UM PROGRAMA ADVPL.................................................32

Tipo de Dados ....................................................................................42

Entendendo a influncia do escopo das variveis................................55

Operaes com Variveis ....................................................................57

4.5.1. Atribuio de variveis ...............................................................................................................................57

ESTRUTURAS BSICAS DE PROGRAMAO ...........................................80

5.1.1. Influenciando o fluxo de repetio...........................................................................................................85

Estruturas de deciso ..........................................................................87

ARRAYS E BLOCOS DE CDIGO ...............................................................96

Inicializando arrays ..................................................................................................................... 100

Listas de Expresses e Blocos de Cdigo .......................................... 110

Premissas para utilizao de Blocos de Cdigo ..................................................................... 110

Tipos e escopos de funes .............................................................. 123

Passagem de parmetros entre funes............................................ 128

DIRETIVAS DE COMPILAO ................................................................. 138

MDULO 03: DESENVOLVENDO PEQUENAS CUSTOMIZAES.................. 151

ADVPL E O ERP MICROSIGA PROTHEUS ............................................... 151

O Ambiente Protheus ....................................................................... 152

Organizao e configurao inicial do ambiente Protheus ................ 157

O Configurador do Protheus............................................................. 166

Funcionalidades Abordadas ...................................................................................................... 166

Funcionalidades do Configurador ..................................................... 176

Dicionrio de Dados da aplicao ERP .................................................................................... 178

10. TOTVS DEVELOPMENT STUDIO ............................................................. 203

Diferenas e compatibilizaes entre bases de dados ....................... 209

Funes de acesso e manipulao de dados .................................... 211

Diferenciao entre variveis e os nomes de campos........................ 219

Controle de numerao sequencial................................................... 221

12. CUSTOMIZAES PARA A APLICAO ERP ......................................... 223

Customizao de campos Dicionrio de Dados .............................. 223

Validaes de campos e perguntas..................................................................................... 224

Customizao de gatilhos Configurador......................................... 231

Customizao de parmetros Configurador ................................... 232

Funes para a manipulao de parmetros ..................................................................... 233

Pontos de Entrada Conceitos, Premissas e Regras .......................... 236

13. INTERFACES VISUAIS ............................................................................. 238

Sintaxe e componentes das interfaces visuais ................................... 238

Interfaces padres para atualizaes de dados ................................. 242

AxCadastro() ........................................................................................................................... 242

APNDICES ..................................................................................................... 254

Palavras em maisculo...................................................................... 257

16. UTILIZAO DA NOTAO HNGARA................................................. 257

Manipulao de variveis numricas............................................................. 294

a) Conceitos a serem aprendidos

Fundamentos e tcnicas de programao;

b) Habilidades e tcnicas a serem aprendidas

Resoluo de algoritmos atravs de sintaxes orientadas a linguagem ADVPL;

c) Atitudes a serem desenvolvidas

Adquirir conhecimentos atravs da anlise das funcionalidades disponveis no

MDULO 01: INTRODUO PROGRAMAO

1.1. Lgica de Programao