Programação Advpl I_P10

Prévia do material em texto

Educação Corporativa
Programação em
ADVPL l
1Todos os direitos reservados.
Matriz - Av. Braz Leme, 1.717 - 02511-000 - São Paulo - SP - Brasil.
Tel.: 55 (11) 3981 - 7001 www.microsiga.com.br
2 Todos os direitos reservados.Programação em ADVPL l
OBJETIVOS DO CURSO 5
INTRODUÇÃO À PROGRAMAÇÃO 6
Lógica de programação e algoritmos 6
ESTRUTURAS DE PROGRAMAÇÃO 12
Diagrama de bloco 12
Do case...Case 16
A LINGUAGEM ADVPL 20
Programação Com Interface Própria com o Usuário 20
Programação Sem Interface Própria com o Usuário 21
ESTRUTURA DE UM PROGRAMA ADVPL 22
Linhas de Programa 22
Áreas de um Programa ADVPL 24
Área de Identificação 25
Área de Ajustes Iniciais 26
Corpo do Programa 26
Área de Encerramento 27
DECLARAÇÃO E ATRIBUIÇÃO DE VARIÁVEIS 28
Tipo de Dados 28
Declaração de variáveis 29
Escopo de variáveis 30
Variáveis de escopo private 32
Variáveis de escopo public 33
Entendendo a influência do escopo das variáveis 34
Operações com Variáveis 35
Operadores da linguagem ADVPL 36
Operação de Macro Substituição 41
Funções de manipulação de variáveis 41
Manipulação de strings 43
Manipulação de variáveis numéricas 45
Verificação de tipos de variáveis 46
ESTRUTURAS BÁSICAS DE PROGRAMAÇÃO 47
Estruturas de repetição 47
Influenciando o fluxo de repetição 50
Estruturas de decisão 51
ARRAYS E BLOCOS DE CÓDIGO 56
Arrays 56
Inicializando arrays 58
Funções de manipulação de arrays 59
Cópia de arrays 61
Listas de Expressões e Blocos de Código 62
Premissas para utilização de Blocos de Código 62
Lista de expressões 63
Blocos de Código 65
Funções para manipulação de blocos de código 67
FUNÇÕES 68
Tipos e escopos de funções 69
DIRETIVAS DE COMPILAÇÃO 78
DESENVOLVENDO PEQUENAS CUSTOMIZAÇÕES 84
Advpl e o erp microsiga protheus 84
Su
m
ár
io
3Todos os direitos reservados. Programação em ADVPL I
O Ambiente Protheus 84
Organização e configuração inicial do ambiente Protheus 88
O Configurador do Protheus 94
Ambientes e tabelas 96
Acessando o módulo Configurador 98
Funcionalidades do Configurador 100
Dicionário de Dados da aplicação ERP 101
Adição de tabelas ao Dicionário de Dados 102
Adição de campos as tabelas do Dicionário de Dados 104
Orientações para o cadastramento de um novo campo 106
Adição de índices para as tabelas do Dicionário de Dados 107
Adição de gatilhos para os campos das tabelas do sistema 111
Criação de Tabelas Genéricas 113
Criação de Parâmetros 114
TOTVS DEVELOPMENT STUDIO 117
DESENVOLVIMENTO DE PEQUENAS CUSTOMIZAÇÕES 121
Acesso e manipulação de bases de dados em advpl 121
Diferenças e compatibilizações entre bases de dados 122
Funções de acesso e manipulação de dados 123
Diferenciação entre variáveis e nomes de campos 127
Controle de numeração seqüencial 128
Customizações para a aplicação ERP 130
Customização de campos – Dicionário de Dados 131
Pictures de formação disponíveis 133
Customização de gatilhos – Configurador 134
Customização de parâmetros – Configurador 135
Funções para manipulação de parâmetros 136
Cuidados na utilização de um parâmetro 137
Pontos de Entrada – Conceitos, Premissas e Regras 137
INTERFACES VISUAIS 139
Sintaxe e componentes das interfaces visuais 139
Interfaces padrões para atualizações de dados 142
AxCadastro() 142
MBrowse() 143
AxFunctions() 146
APÊNDICES - BOAS PRÁTICAS DE PROGRAMAÇÃO 148
Utilização de identação 148
Capitulação de palavras-chave 149
Palavras em maiúsculo 149
Palavras reservadas 150
Utilização da notação húngara 150
Guia de referência rápida: funções e comandos advpl 151
Verificação de tipos de variáveis 154
Manipulação de arrays 156
Manipulação de blocos de código 161
Manipulação de strings 164
Manipulação de variáveis numéricas 169
Manipulação de arquivos 171
Controle de numeração seqüencial 181
4 Todos os direitos reservados.Programação em ADVPL l
Validação 182
Parâmetros 184
Componentes da interface visual 185
Interfaces de cadastro 188
Funções visuais para aplicações 191
Funções ADVPL para aplicações 194
REFERÊNCIAS BIBLIOGRÁFICAS 195
5Todos os direitos reservados. Programação em ADVPL I
OBJETIVOS DO CURSO
Objetivos específicos do curso:
Ao final do curso o treinando deverá ter desenvolvido os seguintes conceitos, habilidades e atitudes:
a) Conceitos a serem aprendidos
- fundamentos e técnicas de programação;
- princípios básicos da linguagem ADVPL;
- comandos e funções específicas da Microsiga.
b) Habilidades e técnicas a serem aprendidas
- resolução de algoritmos através de sintaxes orientadas a linguagem ADVPL;
- análise de fontes de baixa complexidade da aplicação ERP Protheus;
- desenvolvimento de pequenas customizações para o ERP Protheus.
c) Atitudes a serem desenvolvidas
- adquirir conhecimentos através da análise dos funcionalidades disponíveis no ERP Protheus;
- embasar a realização de outros cursos relativos a linguagem ADVPL.
 
6 Todos os direitos reservados.Programação em ADVPL l
INTRODUÇÃO À PROGRAMAÇÃO
Lógica de programação e algoritmos
No aprendizado de qualquer linguagem de programação é essencial desenvolver os conceitos relacionados 
a lógica e a técnica da escrita de um programa.
Com foco nesta necessidade, este tópico irá descrever resumidamente os conceitos envolvidos no 
processo de desenvolvimento de um programa através dos conceitos relacionados à:
- Lógica de programação
- Algoritmos
- Diagramas de blocos
Lógica de Programação
Lógica
A lógica de programação é necessária para pessoas que desejam trabalhar com desenvolvimento de 
sistemas e programas, ela permite definir a seqüência lógica para o desenvolvimento. Então o que é 
lógica?
Lógica de programação é a técnica de encadear pensamentos para atingir determinado objetivo.
Seqüência Lógica
Estes pensamentos, podem ser descritos como uma seqüência de instruções, que devem ser
seguidas para se cumprir uma determinada tarefa.
Seqüência Lógica são passos executados até atingir um objetivo ou solução de um problema.
Instruções
Na linguagem comum, entende-se por instruções “um conjunto de regras ou normas definidas para a 
realização ou emprego de algo”.
Em informática, porém, instrução é a informação que indica a um computador uma ação elementar a 
executar. Convém ressaltar que uma ordem isolada não permite realizar o processo completo, para isso é 
necessário um conjunto de instruções colocadas em ordem seqüencial lógica.
Por exemplo, se quisermos fazer uma omelete de batatas, precisaremos colocar em prática uma série de 
instruções: descascar as batatas, bater os ovos, fritar as batatas, etc. É evidente que essas instruções têm 
que ser executadas em uma ordem adequada – não se pode descascar as batatas depois de fritá-las.
Dessa maneira, uma instrução tomada em separado não tem muito sentido; para obtermos o resultado, 
precisamos colocar em prática o conjunto de todas as instruções, na ordem correta.
7Todos os direitos reservados. Programação em ADVPL I
Instruções são um conjunto de regras ou normas definidas para a realização ou emprego de algo. Em 
informática, é o que indica a um computador uma ação elementar a executar.
Algoritmo
Um algoritmo é formalmente uma seqüência finita de passos que levam a execução de uma tarefa. 
Podemos pensar em algoritmo como uma receita, uma seqüência de instruções que dão cabo de uma 
meta específica. Estas tarefas não podem ser redundantes nem subjetivas na sua definição, devem ser 
claras e precisas.
Como exemplos de algoritmos podemos citar os algoritmos das operações básicas(adição, multiplicação, 
divisão e subtração) de números reais decimais. Outros exemplos seriam os manuais de aparelhos 
eletrônicos, como um videocassete, que explicam passo-a-passo como, por exemplo, gravar um evento.
Até mesmo as coisas mais simples, podem ser descritas por seqüências lógicas, 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 números quaisquer”
1. Escreva o primeiro número no retângulo A;
2. Escreva o segundo número no retângulo B;
3. Some o número do retângulo A com número do retângulo B e coloque o resultado no retângulo C.
Desenvolvendo algoritmos
Pseudocódigo
Os algoritmos são descritos em uma linguagem chamada pseudocódigo. Este nome é uma alusão à 
posterior implementação em uma linguagem de programação, ou seja, quando for utilizada a linguagem 
a de programação propriamente dita como, por exemplo, ADVPL.
Por isso os algoritmos são independentes das linguagens de programação, sendo que ao contrário de 
uma linguagem de programação não existe um formalismo rígido de como deve ser escrito o algoritmo.
O algoritmo deve ser fácil de interpretar e fácil de codificar. Ou seja, ele deve ser o intermediário entre a 
linguagem falada e a linguagem de programação.
8 Todos os direitos reservados.Programação em ADVPL l
Regras para construção do Algoritmo
Para escrever um algoritmo precisamos descrever a seqüência de instruções, de maneira simples e 
objetiva. Para isso utilizaremos algumas técnicas:
1. Usar somente um verbo por frase;
2. Imaginar que você está desenvolvendo um algoritmo para pessoas que não trabalham com 
informática;
3. Usar frases curtas e simples;
4. Ser objetivo;
5. Procurar usar palavras que não tenham sentido dúbio.
Fases
Para implementar de um algoritmo de simples interpretação e codificação é necessário inicialmente 
dividir o problema apresentado em três fases fundamentais, as quais são:
- ENTRADA: São os dados de entrada do algoritmo;
- PROCESSAMENTO: São os procedimentos utilizados para chegar ao resultado final;
- SAÍDA: São os dados já processados.
Estudando algoritmos 
Neste tópico serão demonstrados alguns algoritmos do cotidiano, os quais foram implementados 
utilizando os princípios descritos nos tópicos anteriores. 
- Mascar um chiclete
- Utilizar um telefone público – cartão
- Fritar um ovo
- Trocar lâmpadas
- Descascar batatas
- Jogar o jogo da forca
- Calcular a média de notas
- Jogar o jogo da velha – contra o algoritmo 
Mascar um chiclete
1. Pegar o chiclete
2. Retirar o papel
3. Mastigar
4. Jogar o papel no lixo
Anotações
9Todos os direitos reservados. Programação em ADVPL I
Utilizar um telefone público - cartão
1. Retirar o telefone do gancho
2. Esperar o sinal
3. Colocar o cartão
4. Discar o número
5. Falar no telefone
6. Colocar o telefone no ganho
Fritar um ovo
1. Pegar frigideira, ovo, óleo e sal
2. Colocar óleo na frigideira
3. Ascender 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
Trocar lâmpadas
1. Se a lâmpada estiver fora do alcance, pegar uma escada
2. Pegar a lâmpada nova
3. Se a lâmpada queimada estiver quente, pegar um pano
4. Tirar lâmpada queimada
5. Colocar lâmpada nova
Descascar batatas
1. Pegar faca, bacia e batatas
2. Colocar água na bacia
3. Enquanto houver batatas, descascar 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 média 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 média das notas.
10 Todos os direitos reservados.Programação em ADVPL l
Jogar o jogo da velha – contra o algoritmo
1. Enquanto existir um quadrado livre e ninguém ganhou ou perdeu o jogo:
1.1. Espere a jogada do adversário, continue depois
1.2. Se centro estiver livre: jogue no centro
1.3. Senão, se o adversário possuir 2 quadrados em linha com um quadrado livre, jogue neste quadrado
1.4. Senão, se há algum canto livre, jogue neste canto
 
Teste de mesa 
Após desenvolver um algoritmo ele deverá sempre ser testado. Este teste é chamado de TESTE DE MESA, 
que significa seguir as instruções do algoritmo de maneira precisa para verificar se o procedimento 
utilizado está correto ou não.
Para avaliar a aplicação do teste de mesa, utilizaremos o algoritmo de calcular a média de notas:
Algoritmo: Calcular a média de notas
1. Enquanto houver notas a serem recebidas:
a. Receber a nota;
2. Some todas as notas recebidas;
3. Divida o total obtido pela quantidade de notas recebidas;
4. Exiba a média das notas.
Teste de mesa:
1. Para cada nota informada, receber e registrar na tabela abaixo:
ID Nota 
 
2. Ao término das notas, a tabela deverá conter todas as notas informadas, como abaixo:
ID Nota 
1 8.0 
2 7.0 
3 8.0 
4 8.0 
5 7.0 
6 7.0 
3. Somar todas as notas: 45
4. Dividir a soma das notas, pelo total de notas informado: 45/6  7.5
5. Exibir a média obtida: Mensagem(Média: 7.5)
11Todos os direitos reservados. Programação em ADVPL I
Exercícios
Aprimorar os seguintes algoritmos descritos na apostila:
- Usar telefone público – cartão
- Fritar um ovo
- Mascar um chiclete
- Trocar lâmpadas
- Descascar batatas
- Jogar o “Jogo da Forca”
Anotações
12 Todos os direitos reservados.Programação em ADVPL l
ESTRUTURAS DE PROGRAMAÇÃO
Diagrama de bloco
O diagrama de blocos é uma forma padronizada e eficaz para representar os passos lógicos de um 
determinado processamento.
Com o diagrama podemos definir uma seqüência de símbolos, com significado bem definido, portanto, 
sua principal função é a de facilitar a visualização dos passos de um processamento.
Simbologia
Existem diversos símbolos em um diagrama de bloco. No quadro abaixo estão representados alguns dos 
símbolos mais utilizados:
Símbolo Função 
 
Terminador 
Indica o início e o fim de um processamento. 
 
Processamento 
Processamento em geral .
 
Entrada 
Manual 
Indica a entrada de dados através do teclado. 
 
Decisão 
Indica um ponto no qual deverá ser efetuada 
uma escolha entre duas situações possíveis . 
 
Exibição 
Mostra os resultados obtidos com um 
processamento. 
 
Documento 
Indica um documento utilizado pelo 
processamento, seja para entrada de 
informações ou para exibição dos dados 
disponíveis após um processamento. 
Cada símbolo irá conter uma descrição pertinente a forma com o qual o mesmo foi utilizado no fluxo, indicando o 
processamento ou a informação que o mesmo representa.
Fique
atento
13Todos os direitos reservados. Programação em ADVPL I
Representação de algoritmos através de diagramas de bloco
Algoritmo 01: Fritar um ovo
1. Pegar frigideira, ovo, óleo e sal
2. Colocar óleo na frigideira
3. Ascender 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
Início
Pegar óleo,
frigideira, ovo 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
do ovo no lixo
Retirar a
frigideira do fogo
quando o ovo
estiver no ponto
Desligar o fogo
Colocar sal a
gosto
FIM
Anotações
14 Todos os direitos reservados.Programação em ADVPL l
Algoritmo 02: Calcular a média de notas
1. Enquanto houver notas a serem recebidas:
a. Receber a nota;
2. Some todas as notas recebidas;
3. Divida o total obtido pela quantidade de notas recebidas;
4. Exiba a média das notas.
Início
Não
SimAinda há
notas?
Receber notas
Somar notas
recebidas
Dividir o total da
soma pela
quantidade de
notas informadas
Exibir média
das notas
FIM
Anotações
15Todos os direitos reservados. Programação em ADVPL I
Estruturas de decisão e repetição
A utilização de estruturas de decisão e repetição em um algoritmo permite a realização de ações 
relacionadas a situações que influenciam na execução e solução do problema.
Como foco na utilização da linguagem ADVPL serão ilustradas as seguintes estruturas:
Estruturas de decisão
- IF...ELSE
- DO CASE ... CASE
Estruturas de repetição
- WHILE...END
- FOR...NEXT
Estruturas de decisão
Os comandos de decisão são utilizados em algoritmos cuja solução não é obtida através da utilização de 
ações meramente seqüenciais, permitindo que este avalie as condições necessárias para optar por uma 
ou outra maneira de continuar seu fluxo.
As estruturas de decisão que serão analisadas são:
IF...ELSE
DO CASE ... CASE
IF...ELSE
A estrutura IF...ELSE (Se/Senão) permite a análise de uma condição e a partir da qual ser executada uma 
de duas ações possíveis: se a análise da condição resultar em um valor verdadeiro ou se a análise da 
condição resultar em um valor falso.
Representação 01: IF...ELSE com ações para ambas as situações
Ação vinculada ao 
resultado 
verdadeiro
Análise da 
condição
Verdadeiro Falso
Ações anteriores
...
Continuação do 
fluxo após a 
tomada da 
decisão
Ação vinculada ao 
resultado falso
16 Todos os direitos reservados.Programação em ADVPL l
Esta estrutura permite ainda que seja executada apenas uma ação, na situação em que a a análise da 
condição resultar em um valor verdadeiro.
Representação 02: IF...ELSE somente com ação para situação verdadeira
 
Ação vinculada ao 
resultado 
verdadeiro
Análise da 
condição
Verdadeiro
Falso
Ações anteriores
...
Continuação do 
fluxo após a 
tomada da 
decisão
Apesar das linguagens de programação possuírem variações para a estrutura IF...ELSE, conceitualmente todas as 
representações podem ser descritas com base no modelo apresentado.
A linguagem ADVPL possui uma variação para a estrutura IF...ELSE, descrita como IF...ELSEIF...ELSE.
Com esta estrutura é possível realizar a análise de diversas condições em seqüência, para as quais será avaliada somente 
a ação da primeira expressão cujo análise resultar em um valor verdadeiro.
Do case...Case
A estrutura DO CASE...ENDCASE (Caso) permite a análise de diversas condições consecutivas, para as quais 
somente a condição a primeira condição verdadeira será sua ação vinculada executada.
O recurso de análise de múltiplas condições é necessário para solução de problemas mais complexos, nos 
quais as possibilidades de solução superam a mera análise de um único resultado verdadeiro ou falso.
Fique
atento
Dica
17Todos os direitos reservados. Programação em ADVPL I
 
Análise da 
condição 1
Verdadeiro
Falso
Ações anteriores
...
Continuação do 
fluxo após a 
tomada da 
decisão
Ação vinculada a 
condição 1
Análise da 
condição 2
Verdadeiro Ação vinculada a 
condição 2
Análise da 
condição N
Verdadeiro Ação vinculada a 
condição N
Falso
Falso
Falso
Apesar das linguagens de programação possuírem variações para a estrutura DO CASE...CASE, 
conceitualmente todas as representações podem ser descritas com base no modelo apresentado.
 
Estruturas de repetição
Os comandos de repetição são utilizados em algoritmos nas situações em que é necessário realizar uma 
determinada ação ou um conjunto de ações para um número definido ou indefinido de vezes, ou ainda 
enquanto uma determinada condição for verdadeira.
As estruturas de decisão que serão analisadas são:
- WHILE...END
- FOR...TO...NEXT
WHILE...END
Nesta estrutura, o conjunto de ações será executado enquanto a análise de uma condição de referência 
resultar em um valor verdadeiro. É importante verificar que o bloco somente será executado, inclusive se 
na primeira análise a condição resultar em um valor verdadeiro.
Representação: WHILE...END
18 Todos os direitos reservados.Programação em ADVPL l
Ação vinculada ao 
resultado 
verdadeiro
Análise da 
condição
Verdadeiro
Falso
Ações anteriores
...
Continuação do 
fluxo
...
Loop
Existem diversas variações para a estrutura WHILE...END, na qual há a possibilidade da primeira execução 
ser realizada sem a análise da condição, a qual valerá apenas a partir da segunda execução.
A linguagem ADVPL aceita a sintaxe DO WHILE...ENDDO, que em outras linguagens representa a situação 
descrita anteriormente (análise da condição somente a partir da segunda execução), mas em ADVPL esta 
sintaxe tem o mesmo efeito do WHILE...END.
 
For...To...Next
Nesta estrutura, o conjunto de ações será executado uma quantidade de vezes definida, normalmente 
referenciada como “passo”.
Para cada “passo” realizado pela estrutura FOR...TO...NEXT, será avaliada uma condição que verificará se foi 
atingido o número de execuções previamente definido. Desta forma a estrutura compreende um controle 
de número de “passos” executados, o qual é incrementado na análise da expressão NEXT.
Semelhante a estrutura WHILE...END, a primeira ação somente será realizada mediante um resultado 
verdadeiro na análise da condição.
Anotações
19Todos os direitos reservados. Programação em ADVPL I
Exercícios
Representação: FOR...TO...NEXT
Ação vinculada ao 
resultado 
verdadeiro
Análise da 
condição
Verdadeiro
Falso
Ações anteriores
...
Continuação do 
fluxo
...
Incrementa o 
contador de 
“passos”
A estrutura FOR...TO...NEXT, dependendo da linguagem de programação, permite a realização de um incremento simples 
a cada execução da instrução NEXT, ou a adição de outro valor ao contador, o qual deverá especificado de acordo com a 
sintaxe da linguagem.
Em ADVPL pode ser utilizada a instrução “STEPS” para alterar o valor a ser adicionado no contador de passos a cada 
execução da instrução NEXT, sendo que este valor poderá ser até negativo, viabilizando uma contagem decrescente.
Fique
atento
Montar os diagramas de blocos para os algoritmos desenvolvidos no exercício anterior: 
- Usar telefone público – cartão
- Fritar um ovo
- Mascar um chiclete
- Trocar lâmpadas
- Descascar batatas
- Jogar o “Jogo da Forca”
20 Todos os direitos reservados.Programação em ADVPL l
A LINGUAGEM ADVPL 
A Linguagem ADVPL teve seu início em 1994, sendo na verdade uma evolução na utilização de linguagens 
no padrão xBase pela Microsiga Software S.A. (Clipper, Visual Objects e depois FiveWin). Com a criação 
da tecnologia Protheus, era necessário criar uma linguagem que suportasse o padrão xBase para a 
manutenção de todo o código existente do sistema de ERP Siga Advanced. Foi então criada a linguagem 
chamada Advanced Protheus Language.
O ADVPL é uma extensão do padrão xBase de comandos e funções, operadores, estruturas de controle de 
fluxo e palavras reservadas, contando também com funções e comandos disponibilizados pela Microsiga 
que a torna uma linguagem completa para a criação de aplicações ERP prontas para a Internet. Também 
é uma linguagem orientada a objetos e eventos, permitindo ao programador desenvolver aplicações 
visuais e criar suas próprias classes de objetos.
Quando compilados, todos os arquivos de código tornam-se unidades de inteligência básicas, chamados 
APO´s (de Advanced Protheus Objects). Tais APO´s são mantidos em um repositório e carregados 
dinamicamente pelo PROTHEUS Server para a execução. Como não existe a linkedição, ou união física 
do código compilado a um determinado módulo ou aplicação, funções criadas em ADVPL podem ser 
executadas em qualquer ponto do ambiente Advanced Protheus.
O compilador e o interpretador da linguagem ADVPL é o próprio servidor PROTHEUS (PROTHEUS Server), 
e existe um ambiente visual para desenvolvimento integrado (PROTHEUSIDE) onde o código pode ser 
criado, compilado e depurado.
Os programas em ADVPL podem conter comandos ou funções de interface com o usuário. De acordo 
com tal característica, tais programas sãosubdivididos nas seguintes categorias:
Programação Com Interface Própria com o Usuário
Nesta categoria entram os programas desenvolvidos para serem executados através do terminal remoto 
do Protheus, o Protheus Remote. O Protheus Remote é a aplicação encarregada da interface e da interação 
com o usuário, sendo que todo o processamento do código em ADVPL, o acesso ao banco de dados e 
o gerenciamento de conexões é efetuado no Protheus Server. O Protheus Remote é o principal meio de 
acesso a execução de rotinas escritas em ADVPL no Protheus Server, e por isso permite executar qualquer 
tipo de código, tenha ele interface com o usuário ou não. Porém nesta categoria são considerados apenas 
os programas que realizem algum tipo de interface remota utilizando o protocolo de comunicação do 
Protheus.
Podem-se criar rotinas para a customização do sistema ERP Microsiga Protheus, desde processos adicionais 
até mesmo relatórios. A grande vantagem é aproveitar todo o ambiente montado pelos módulos do ERP 
Microsiga Protheus. Porém, com o ADVPL é possível até mesmo criar toda uma aplicação, ou módulo, do 
começo.
Todo o código do sistema ERP Microsiga Protheus é escrito em ADVPL.
21Todos os direitos reservados. Programação em ADVPL I
Programação Sem Interface Própria com o Usuário
As rotinas criadas sem interface são consideradas nesta categoria porque geralmente têm uma utilização 
mais específica do que um processo adicional ou um relatório novo. Tais rotinas não têm interface com o 
usuário através do Protheus Remote, e qualquer tentativa nesse sentido (como a criação de uma janela 
padrão) ocasionará uma exceção em tempo de execução. Estas rotinas são apenas processos, ou Jobs, 
executados no Protheus Server. Algumas vezes, a interface destas rotinas fica a cargo de aplicações 
externas, desenvolvidas em outras linguagens, que são responsáveis por iniciar os processos no servidor 
Protheus através dos meios disponíveis de integração e conectividade no Protheus.
De acordo com a utilização e com o meio de conectividade utilizado, estas rotinas são subcategorizadas 
assim:
Programação por Processos
Rotinas escritas em ADVPL podem ser iniciadas como processos individuais (sem interface) no Protheus 
Server através de duas maneiras: Iniciadas por outra rotina ADVPL através da chamada de funções como 
StartJob() ou CallProc() ou iniciadas automaticamente na inicialização do Protheus Server (quando 
propriamente configurado).
Programação de RPC
Através de uma biblioteca de funções disponível no Protheus (uma API de comunicação), podem-se 
executar rotinas escritas em ADVPL diretamente no Protheus Server, através de aplicações externas 
escritas em outras linguagens. Isto é o que se chama de RPC (de Remote Procedure Call, ou Chamada de 
Procedimentos Remota).
O servidor Protheus também pode executar rotinas em ADVPL em outros servidores Protheus através 
de conexão TCP/IP direta utilizando o conceito de RPC. Do mesmo modo, aplicações externas podem 
requisitar a execução de rotinas escritas em ADVPL através de conexão TCP/IP direta.
Programação Web
O Protheus Server pode também ser executado como um servidor Web, respondendo a requisições HTTP. 
No momento destas requisições, pode executar rotinas escritas em ADVPL como processos individuais, 
enviando o resultado das funções como retorno das requisições para o cliente HTTP (como por exemplo, 
um Browser de Internet). Qualquer rotina escrita em ADVPL que não contenha comandos de interface 
pode ser executada através de requisições HTTP. O Protheus permite a compilação de arquivos HTML 
contendo código ADVPL embutido. São os chamados arquivos ADVPL ASP, para a criação de páginas 
dinâmicas.
Programação TelNet
TelNet é parte da gama de protocolos TCP/IP que permite a conexão a um computador remoto através de 
uma aplicação cliente deste protocolo. O PROTHEUS Server pode emular um terminal TelNet, através da 
execução de rotinas escritas em ADVPL. Ou seja, pode-se escrever rotinas ADVPL cuja interface final será 
um terminal TelNet ou um coletor de dados móvel.
22 Todos os direitos reservados.Programação em ADVPL l
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 são gravados em um arquivo texto que é 
transformado em uma linguagem executável por um computador através de um processo chamado 
compilação. A compilação substitui os comandos de alto nível (que os humanos compreendem) por 
instruções de baixo nível (compreendida pelo sistema operacional em execução no computador). No 
caso do ADVPL, não é o sistema operacional de um computador que irá executar o código compilado, 
mas sim o Protheus Server.
Dentro de um programa, os comandos e funções utilizados devem seguir regras de sintaxe da linguagem 
utilizada, pois caso contrário o programa será interrompido por erros. Os erros podem ser de compilação 
ou de execução.
Erros de compilação são aqueles encontrados na sintaxe que não permitem que o arquivo de código do 
programa seja compilado. Podem ser comandos especificados de forma errônea, utilização inválida de 
operadores, etc.
Erros de execução são aqueles que acontecem depois da compilação, quando o programa está sendo 
executado. Podem ocorrer por inúmeras razões, mas geralmente se referem as funções não existentes, ou 
variáveis não criadas ou inicializadas, etc.
Linhas de Programa
As linhas existentes dentro de um arquivo texto de código de programa podem ser linhas de comando, 
linhas de comentário ou linhas mistas.
Linhas de Comando
Linhas de comando possuem os comandos ou instruções que serão executadas. Por exemplo:
Local nCnt
Local nSoma := 0
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Linhas de Comentário
Linhas de comentário possuem um texto qualquer, mas não são executadas. Servem apenas para 
documentação e para tornar mais fácil o entendimento do programa. Existem três formas de se comentar 
linhas de texto. A primeira delas é utilizar o sinal de * (asterisco) no começo da linha:
* Programa para cálculo do total
* Autor: Microsiga Software S.A.
* Data: 2 de outubro de 2001
23Todos os direitos reservados. Programação em ADVPL I
Todas as linhas iniciadas com um sinal de asterisco são consideradas como comentário. Pode-se utilizar 
a palavra NOTE ou dois símbolos da letra "e" comercial (&&) para realizar a função do sinal de asterisco. 
Porém todas estas formas de comentário de linhas são obsoletas e existem apenas para compatibilização 
com o padrão xBase. A melhor maneira de comentar linhas em ADVPL é utilizar duas barras transversais:
// Programa para cálculo do total
// Autor: Microsiga Software S.A.
// Data: 2 de outubro de 2001
Outra forma de documentar textos é utilizar as barras transversais juntamente com o asterisco, podendo-
se comentar todo um bloco de texto sem precisar comentar linha a linha:
/*
Programa para cálculo 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 comentário.
Linhas Mistas
O ADVPL também permite que existam linhas de comando com comentário. Isto é possível adicionando-
se as duas barras transversais (//) ao final da linha de comando e adicionando-se o texto do comentário:
Local nCnt
Local nSoma := 0 // Inicializa a variável com zero para a soma
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Tamanho da Linha
Assim como a linha física, delimitada pela quantidade de caracteres que pode ser digitado no editor de 
textos utilizado, existe uma linha considerada linha lógica. A linha lógica, é aquela considerada para a 
compilação como uma única linha de comando.
A princípio, cada linha digitada no arquivo texto é diferenciada após o pressionamento da tecla <Enter>. 
Ou seja, a linha lógica, é a linha física no arquivo. Porém algumas vezes, por limitação física do editor de 
texto ou porestética, pode-se "quebrar" a linha lógica em mais de uma linha física no arquivo texto. Isto é 
efetuado utilizando-se o sinal de ponto-e-vírgula (;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter>
!Empty(cTel) .And. !Empty(cFax) .And. ; <enter>
!Empty(cEmail)
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
24 Todos os direitos reservados.Programação em ADVPL l
Neste exemplo existe uma linha de comando para a checagem das variáveis utilizadas. Como a linha 
torna-se muito grande, pode-se dividi-la em mais de uma linha física utilizando o sinal de ponto-e-vírgula. 
Se um sinal de ponto-e-vírgula for esquecido nas duas primeiras linhas, durante a execução do programa 
ocorrerá um erro, pois a segunda linha física será considerada como uma segunda linha de comando na 
compilação. E durante a execução esta linha não terá sentido.
Áreas de um Programa ADVPL
Apesar de não ser uma linguagem de padrões rígidos com relação à estrutura do programa, é importante 
identificar algumas de suas partes. Considere o programa de exemplo abaixo:
 
#include protheus.ch
/*
+===========================================+
| Programa: Cálculo 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 // Número para o cálculo
 
// Cálculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
 
// Exibe o resultado na tela, através da função alert
Alert("O fatorial de " + cValToChar(nFator) + ;
 " é " + cValToChar(nResultado))
 
// Termina o programa
Return
 
Anotações
25Todos os direitos reservados. Programação em ADVPL I
Anotações
A estrutura de um programa ADVPL é composta pelas seguintes áreas:
Área de Identificação
- Declaração dos includes
- Declaração da função
- Identificação do programa
Área de Ajustes Iniciais
- Declaração das variáveis
Corpo do Programa
- Preparação para o processamento
- Processamento
Área de Encerramento
Área de Identificação
Esta é uma área que não é obrigatória e é dedicada a documentação do programa. Quando existente, 
contém apenas comentários explicando a sua finalidade, data de criação, autor, etc., e aparece no começo 
do programa, antes de qualquer linha de comando.
O formato para esta área não é definido. Pode-se colocar qualquer tipo de informação desejada e escolher 
a formatação apropriada.
#include “protheus.ch”
 
/*
+==========================================+
| Programa: Cálculo do Fatorial |
| Autor : Microsiga Software S.A. |
| Data : 02 de outubro de 2001 |
+==========================================+
*/
User Function CalcFator()
Opcionalmente podem-se incluir definições de constantes utilizadas no programa ou inclusão de arquivos 
de cabeçalho nesta área.
26 Todos os direitos reservados.Programação em ADVPL l
Área de Ajustes Iniciais
Nesta área geralmente se fazem os ajustes iniciais, importantes para o correto funcionamento do 
programa. Entre os ajustes se encontram declarações de variáveis, inicializações, abertura de arquivos, 
etc. Apesar do ADVPL não ser uma linguagem rígida e as variáveis poderem ser declaradas em qualquer 
lugar do programa, é aconselhável fazê-lo nesta área visando tornar o código mais legível e facilitar a 
identificação de variáveis não utilizadas.
Local nCnt
Local nResultado := 0 // Resultado do fatorial
Local nFator := 10 // Número para o cálculo
Corpo do Programa
É nesta área que se encontram as linhas de código do programa. É onde se realiza a tarefa necessária 
através da organização lógica destas linhas de comando. Espera-se que as linhas de comando estejam 
organizadas de tal modo que no final desta área o resultado esperado seja obtido, seja ele armazenado 
em um arquivo ou em variáveis de memória, pronto para ser exibido ao usuário através de um relatório 
ou na tela.
// Cálculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
 
A preparação para o processamento é formada pelo conjunto de validações e processamentos necessários 
antes da realização do processamento em si. 
Avaliando o processamento do cálculo do fatorial descrito anteriormente, pode-se definir que a validação 
inicial a ser realizada é o conteúdo da variável nFator, pois a mesma determinará a correta execução do 
código.
// Cálculo do fatorial
nFator := GetFator() 
// GetFator – função ilustrativa na qual a variável recebe a informação do usuário.
If nFator <= 0
 Alert(“Informação inválida”)
Return
Endif
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt
Anotações
27Todos os direitos reservados. Programação em ADVPL I
Área de Encerramento
É nesta área onde as finalizações são efetuadas. É onde os arquivos abertos são fechados, e o resultado 
da execução do programa é utilizado. Pode-se exibir o resultado armazenado em uma variável ou em um 
arquivo ou simplesmente finalizar, caso a tarefa já tenha sido toda completada no corpo do programa. 
É nesta á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, através da função alert
Alert("O fatorial de " + cValToChar(nFator) + ;
 " é " + cValToChar(nResultado))
 
// Termina o programa
Return
Anotações
28 Todos os direitos reservados.Programação em ADVPL l
 
DECLARAÇÃO E ATRIBUIÇÃO DE VARIÁVEIS
Tipo de Dados
O ADVPL não é uma linguagem de tipos rígidos (strongly typed), o que significa que variáveis de memória 
podem receber diferentes tipos de dados durante a execução do programa. 
As variáveis podem também conter objetos, mas os tipos primários da linguagem são:
Numérico
O ADVPL não diferencia valores inteiros de valores com ponto flutuante, portanto podem-se criar variáveis 
numéricas com qualquer valor dentro do intervalo permitido. Os seguintes elementos são do tipo de 
dado numérico:
2
43.53
0.5
0.00001
1000000
 
Uma variável do tipo de dado numérico pode conter um número de dezoito dígitos incluindo o ponto 
flutuante, no intervalo de 2.2250738585072014 E–308 até 1.7976931348623158 E+308.
Lógico
Valores lógicos em ADVPL são identificados através de .T. ou .Y. para verdadeiro e .F. ou .N. para falso 
(independentemente se os caracteres estiverem em maiúsculo ou minúsculo).
Caractere
Strings ou cadeias de caracteres são identificadas em ADVPL por blocos de texto entre aspas duplas (") 
ou aspas simples ('):
"Olá mundo!"
'Esta é uma string'
"Esta é 'outra' string"
 
Uma variável do tipo caractere pode conter strings com no máximo 1 MB, ou seja, 1048576 caracteres.
Data
O ADVPL tem um tipo de dados específico para datas. Internamente as variáveis deste tipo de dado são 
armazenadas como um número correspondente a data Juliana.
29Todos os direitos reservados. Programação em ADVPL I
Variáveis do tipo de dados Data não podem ser declaradas diretamente, e sim através da utilização de 
funções específicas como por exemplo CTOD() que converte uma string para data.
 
Array
O Array é um tipo de dado especial. É a disposição de outros elementos em colunas e linhas. O ADVPL 
suporta arrays unidimensionais (vetores) ou multidimensionais (matrizes). Os elementos de um array 
são acessados através de índices numéricos iniciados em 1, identificando a linha e coluna para quantas 
dimensões existirem.
Arrays devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a memória do 
servidor.
Bloco de Código
O bloco de código é um tipo de dado especial. É utilizado para armazenar instruções escritas em ADVPL 
que poderão ser executadas posteriormente.
Declaração de variáveis
Variáveis de memória são um dos recursos mais importantes de uma linguagem. São áreas de memória 
criadas para armazenar informações utilizadas por um programa para a execução de tarefas. Por exemplo, 
quando o usuário digita uma informação qualquer, como o nome deum produto, em uma tela de um 
programa esta informação é armazenada em uma variável de memória para posteriormente ser gravada 
ou impressa.
A partir do momento que uma variável é criada, não é necessário mais se referenciar ao seu conteúdo, e 
sim ao seu nome. 
O nome de uma variável é um identificador único o qual deve respeitar um máximo de 10 caracteres. O 
ADVPL não impede a criação de uma variável de memória cujo nome contenha mais de 10 caracteres, 
porém apenas os 10 primeiros serão considerados para a localização do conteúdo armazenado. 
Portanto se forem criadas duas variáveis cujos 10 primeiros caracteres forem iguais, como nTotalGeralAnual 
e nTotalGeralMensal, as referências a qualquer uma delas no programa resultarão o mesmo, ou seja, serão 
a mesma variável:
 
nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))
 
Anotações
30 Todos os direitos reservados.Programação em ADVPL l
Quando o conteúdo da variável nTotalGeralMensal é exibido, o seu valor será de 300. Isso acontece porque 
no momento que esse valor foi atribuído à variável nTotalGeralAnual, o ADVPL considerou apenas os 10 
primeiros caracteres (assim como o faz quando deve exibir o valor da variável nTotalGeralMensal), ou seja, 
considerou-as como a mesma variável. Assim o valor original de 100 foi substituído pelo de 300.
Escopo de variáveis
O ADVPL não é uma linguagem de tipos rígidos para variáveis, ou seja, não é necessário informar o tipo 
de dados que determinada variável irá conter no momento de sua declaração, e o seu valor pode mudar 
durante a execução do programa. 
Também não há necessidade de declarar variáveis em uma seção específica do seu código fonte, embora 
seja aconselhável declarar todas as variáveis necessárias no começo, tornando a manutenção mais fácil e 
evitando a declaração de variáveis desnecessárias.
Para declarar uma variável deve-se utilizar um identificador de escopo. Um identificador de escopo é 
uma palavra chave que indica a que contexto do programa a variável declarada pertence. O contexto 
de variáveis pode ser local (visualizadas apenas dentro do programa atual), público (visualizadas por 
qualquer outro programa), entre outros. 
O Contexto de Variáveis dentro de um Programa
As variáveis declaradas em um programa ou função, são visíveis de acordo com o escopo onde são 
definidas. Como também do escopo depende o tempo de existência das variáveis. A definição do escopo 
de uma variável é efetuada no momento de sua declaração.
Local nNumero := 10
Esta linha de código declara uma variável chamada nNumero indicando que pertence seu escopo é 
local.
Os identificadores de escopo são:
- Local
- Static
- Private
- Public
O ADVPL não é rígido em relação à declaração de variáveis no começo do programa. A inclusão de um 
identificador de escopo não é necessário para a declaração de uma variável, contanto que um valor lhe 
seja atribuído.
nNumero2 := 15
Quando um valor é atribuído à uma variável em um programa ou função, o ADVPL criará a variável caso 
ela não tenha sido declarada anteriormente. A variável então é criada como se tivesse sido declarada 
como Private.
31Todos os direitos reservados. Programação em ADVPL I
Devido a essa característica, quando se pretende fazer uma atribuição a uma variável declarada 
previamente mas escreve-se o nome da variável de forma incorreta, o ADVPL não gerará nenhum erro de 
compilação ou de execução. Pois compreenderá o nome da variável escrito de forma incorreta como se 
fosse a criação de uma nova variável. Isto alterará a lógica do programa, e é um erro muitas vezes difícil 
de identificar.
Variáveis de escopo local
Variáveis de escopo local são pertencentes apenas ao escopo da função 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 variável nVar foi declarada como local e atribuída com o valor 10. Quando a função Filha 
é executada, nVar ainda existe mas não pode ser acessada. Quando a execução da função Pai terminar, a 
variável nVar é destruída. Qualquer variável com o mesmo nome no programa que chamou a função Pai 
não é afetada.
Variáveis de escopo local são criadas automaticamente cada vez que a função onde forem declaradas for 
ativada. Elas continuam a existir e mantêm seu valor até o fim da ativação da função (ou seja, até que a 
função retorne o controle para o código que a executou). Se uma função é chamada recursivamente (por 
exemplo, chama a si mesma), cada chamada em recursão cria um novo conjunto de variáveis locais.
A visibilidade de variáveis de escopo locais é idêntica ao escopo de sua declaração, ou seja, a variável é 
visível em qualquer lugar do código fonte em que foi declarada. Se uma função é chamada recursivamente, 
apenas as variáveis de escopo local criadas na mais recente ativação são visíveis.
Variáveis de escopo static
Variáveis de escopo static funcionam basicamente como as variáveis de escopo local, mas mantêm seu 
valor através da execução e devem ser declaradas explicitamente no código com o identificador STATIC.
O escopo das variáveis static depende de onde são declaradas. Se forem declaradas dentro do corpo de 
uma função ou procedimento, seu escopo será limitado àquela rotina. Se forem declaradas fora do corpo 
de qualquer rotina, seu escopo afeta a todas as funções declaradas no fonte.
 
32 Todos os direitos reservados.Programação em ADVPL l
Neste exemplo, a variável nVar é declarada como static e inicializada com o valor 10:
Function Pai()
Static nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Quando a função Filha é executada, nVar ainda existe mas não pode ser acessada. Diferente de variáveis 
declaradas como LOCAL ou PRIVATE, nVar continua a existir e mantêm seu valor atual quando a execução 
da função Pai termina. Entretanto, somente pode ser acessada por execuções subseqüentes da função 
Pai.
Variáveis de escopo private
A declaração é opcional para variáveis privadas. Mas podem ser declaradas explicitamente com o 
identificador PRIVATE.
Adicionalmente, a atribuição de valor a uma variável não criada anteriormente automaticamente cria a 
variável como privada. Uma vez criada, uma variável privada continua a existir e mantém seu valor até que 
o programa ou função onde foi criada termine (ou seja, até que a função onde foi criada retorne para o 
código que a executou). Neste momento, é automaticamente destruída.
É possível criar uma nova variável privada com o mesmo nome de uma variável já existente. Entretanto, a 
nova (duplicada) variável pode apenas ser criada em um nível de ativação inferior ao nível onde a variável 
foi declarada pela primeira vez (ou seja, apenas em uma função chamada pela função onde a variável já 
havia sido criada). A nova variável privada irá esconder qualquer outra variável privada ou pública (veja a 
documentação sobre variáveis públicas) com o mesmo nome enquanto existir.
Uma vez criada, uma variável privada é visível em todo o programa enquanto não for destruída 
automaticamente quando a rotina que a criou terminar ou uma outra variável privada com o mesmo 
nome for criada em uma subfunção chamada (neste caso, a variável existente torna-se inacessível até que 
a nova variável privada seja destruída).
Em termos mais simples, uma variável privada é visível dentro da função de criação e todas as funções 
chamadas por esta, a menos que uma função chamada crie sua própria variável privada com o mesmo 
nome.
Anotações
33Todos os direitos reservados. Programação em ADVPL I
Por exemplo:
Function Pai()
Private nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)
Neste exemplo, a variável nVar é criada com escopo private e inicializada com o valor 10. Quando a função 
Filha é executada, nVar ainda existe e, diferente de uma variável de escopo local, pode ser acessada pela 
função Filha.Quando a função Pai terminar, nVar será destruída e qualquer declaração de nVar anterior 
se tornará acessível novamente.
No ambiente ERP Protheus, existe uma convenção adicional a qual deve ser respeitada que variáveis em 
uso pela aplicação não sejam incorretamente manipuladas. Por esta convenção deve ser adicionado o 
caracter “_” antes do nome de variáveis PRIVATE e PUBLIC. Maiores informações avaliar o tópico: Boas 
Práticas de Programação.
Exemplo: Private _dData
Variáveis de escopo public
Podem-se criar variáveis de escopo public dinamicamente no código com o identificador PUBLIC. 
As variáveis deste escopo continuam a existir e mantêm seu valor até o fim da execução da thread 
(conexão).
É possível criar uma variável de escopo private com o mesmo nome de uma variável de escopo public 
existente, entretanto, não é permitido criar uma variável de escopo public com o mesmo nome de uma 
variável de escopo private existente.
Uma vez criada, uma variável de escopo public é visível em todo o programa onde foi declarada até que 
seja escondida por uma variável de escopo private criada com o mesmo nome. A nova variável de escopo 
private criada esconde a variável de escopo public existente, e esta se tornará inacessível até que a nova 
variável private seja destruída. Por exemplo:
Function Pai()
Public nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)
Neste exemplo, nVar é criada como public e inicializada com o valor 10. Quando a função Filha é executada, 
nVar ainda existe e pode ser acessada. Diferente de variáveis locais ou privates, nVar ainda existe após o 
término da a execução da função Pai.
34 Todos os direitos reservados.Programação em ADVPL l
Diferentemente dos outros identificadores de escopo, quando uma variável é declarada como pública 
sem ser inicializada, o valor assumido é falso (.F.) e não nulo (nil).
No ambiente ERP Protheus, existe uma convenção adicional a qual deve ser respeitada que variáveis em uso pela 
aplicação não sejam incorretamente manipuladas. Por esta convenção deve ser adicionado o caracter “_” antes do nome 
de variáveis PRIVATE e PUBLIC. Maiores informações avaliar o tópico: Boas Práticas de Programação.
Exemplo: Public _cRotina
Entendendo a influência do escopo das variáveis
Considere as linhas de código de exemplo: 
nResultado := 250 * (1 + (nPercentual / 100))
Se esta linha for executada em um programa ADVPL, ocorrerá um erro de execução com a mensagem 
"variable does not exist: nPercentual", pois esta variável está sendo utilizada em uma expressão de cálculo 
sem ter sido declarada. Para solucionar este erro, deve-se declarar a variável previamente: 
Local nPercentual, nResultado
nResultado := 250 * (1 + (nPercentual / 100))
Neste exemplo, as variáveis são declaradas previamente utilizando o identificador de escopo local. Quando 
a linha de cálculo for executada, o erro de variável não existente, não mais ocorrerá. Porém variáveis não 
inicializadas têm sempre o valor default nulo (Nil) e este valor não pode ser utilizado em um cálculo pois 
também gerará erros de execução (nulo não pode ser dividido por 100). A resolução deste problema é 
efetuada inicializando-se a variável através de uma das formas:
Local nPercentual, nResultado
nPercentual := 10
nResultado := 250 * (1 + (nPercentual / 100)) 
ou
Local nPercentual := 10, nResultado
nResultado := 250 * (1 + (nPercentual / 100))
 
A diferença entre o último exemplo e os dois anteriores é que a variável é inicializada no momento da 
declaração. Em ambos os exemplos, a variável é primeiro declarada e então inicializada em uma outra 
linha de código. 
É aconselhável optar pelo operador de atribuição composto de dois pontos e sinal de igual, pois 
o operador de atribuição utilizando somente o sinal de igual pode ser facilmente confundido com o 
operador relacional (para comparação) durante a criação do programa.
Fique
atento
35Todos os direitos reservados. Programação em ADVPL I
Operações com Variáveis
Atribuição de variáveis
Uma vez que um valor lhe seja atribuído, o tipo de dado de uma variável é igual ao tipo de dado do valor 
atribuído. Ou seja, uma variável passa a ser numérica se um número lhe é atribuído, passa a ser caractere 
se uma string de texto lhe for atribuída, etc. Porém mesmo que uma variável seja de determinado tipo de 
dado, pode-se mudar o tipo da variável atribuindo outro tipo a ela:
01 Local xVariavel // Declara a variável inicialmente com valor nulo
02 
03 xVariavel := "Agora a variável é caractere..."
04 Alert("Valor do Texto: " + xVariavel)
05 
06 xVariavel := 22 // Agora a variável é numérica
07 Alert(cValToChar(xVariavel))
08
09 xVariavel := .T. // Agora a variável é lógica
10 If xVariavel
11 Alert("A variável tem valor verdadeiro...")
12 Else
13 Alert("A variável tem valor falso...")
14 Endif
15
16 xVariavel := Date() // Agora a variável é data
17 Alert("Hoje é: " + DtoC(xVariavel))
18 
19 xVariavel := nil // Nulo novamente
20 Alert("Valor nulo: " + xVariavel)
21
22 Return
No programa de exemplo anterior, a variável xVariavel é utilizada para armazenar diversos tipos de dados. 
A letra "x" em minúsculo no começo do nome é utilizada para indicar uma variável que pode conter 
diversos tipos de dados, segundo a Notação Húngara (consulte documentação específica para detalhes). 
Este programa troca os valores da variável e exibe seu conteúdo para o usuário através da função ALERT(). 
Essa função recebe um parâmetro que deve ser do tipo string de caractere, por isso dependendo do tipo 
de dado da variável xVariavel é necessário fazer uma conversão antes.
Apesar dessa flexibilidade de utilização de variáveis, devem-se tomar cuidados na passagem de parâmetros 
para funções ou comandos, e na concatenação (ou soma) de valores. Note a linha 20 do programa de 
exemplo. Quando esta linha é executada, a variável xVariavel contém o valor nulo. A tentativa de soma de 
tipos de dados diferentes gera erro de execução 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 funções de conversão quando é 
necessário concatenar tipos de dados diferentes (por exemplo, nas linhas 07 e 17.
36 Todos os direitos reservados.Programação em ADVPL l
Note também que quando uma variável é do tipo de dado lógico, ela pode ser utilizada diretamente para 
checagem (linha 10):
If xVariavel
é o mesmo que
If xVariavel = .T.
Operadores da linguagem ADVPL
Operadores comuns
Na documentação sobre variáveis há uma breve demonstração de como atribuir valores a uma variável 
da forma mais simples. O ADVPL amplia significativamente a utilização de variáveis através do uso de 
expressões e funções. 
Uma expressão é um conjunto de operadores e operandos cujo resultado pode ser atribuído a uma 
variável ou então analisado para a tomada de decisões. Por exemplo:
Local nSalario := 1000, nDesconto := 0.10
Local nAumento, nSalLiquido
nAumento := nSalario * 1.20
nSalLiquido := nAumento * (1-nDesconto)
Neste exemplo são utilizadas algumas expressões para calcular o salário líquido após um aumento. Os 
operandos de uma expressão podem ser uma variável, uma constante, um campo de arquivo ou uma 
função.
Operadores Matemáticos
Os operadores utilizados em ADVPL para cálculos matemáticos são:
+ Adição 
- Subtração 
* Multiplicação 
/ Divisão 
** ou ^ Exponenciação 
% Módulo (Resto da Divisão) 
 
Operadores de String
Os operadores utilizados em ADVPL para tratamento de caracteres são:
+ Concatenação de strings (união) 
- Concatenação d e strings com eliminação d os b rancos f inais das strings 
intermediárias 
$ Comparação de Substrings (contido em) 
37Todos os direitos reservados. Programação em ADVPL I
Operadores Relacionais
Os operadores utilizados em ADVPL para operações e avaliações relacionais são:
< Comparação Menor 
> Comparação Maior 
= Comparação Igual 
== Comparação Exatamente Igual (para caracteres) 
<= Comparação Menor ou Igual 
>= Comparação Maiorou Igual 
<> ou # 
ou != 
Comparação Diferente 
 
Operadores Lógicos
Os operadores utilizados em ADVPL para operações e avaliações lógicas são:
.And. E lógico 
.Or. OU lógico 
.Not. ou ! NÃO lógico 
 
Operadores de Atribuição
Os operadores utilizados em ADVPL para atribuição de valores a variáveis de memória são:
:= Atribuição Simples 
+= Adição e Atribuição em Linha 
-= Subtração e Atribuição em Linha 
*= Multiplicação e Atribuição em Linha 
/= Divisão e Atribuição em Linha 
**= ou 
^= 
Exponenciação e Atribuição em Linha 
%= Módulo (resto da divisão) e Atribuição em Linha 
 
Atribuição Simples
O sinal de igualdade é utilizado para atribuir valor a uma variável de memória.
nVariavel := 10
Atribuição em Linha
O operador de atribuição em linha é caracterizado por dois pontos e o sinal de igualdade. Tem a mesma 
função do sinal de igualdade sozinho, porém aplica a atribuição às variáveis. Com ele pode-se atribuir 
mais de uma variável ao mesmo tempo.
nVar1 := nVar2 := nVar3 := 0
Quando diversas variáveis são inicializadas em uma mesma linha, a atribuição começa da direita para 
a esquerda, ou seja, nVar3 recebe o valor zero inicialmente, nVar2 recebe o conteúdo de nVar3 e nVar1 
recebe o conteúdo de nVar2 por final.
38 Todos os direitos reservados.Programação em ADVPL l
Com o operador de atribuição em linha, pode-se substituir as inicializações individuais de cada variável 
por uma inicialização apenas:
Local nVar1 := 0, nVar2 := 0, nVar3 := 0
por
Local nVar1 := nVar2 := nVar3 := 0
O operador de atribuição em linha também pode ser utilizado para substituir valores de campos em um 
banco de dados.
Atribuição Composta
Os operadores de atribuição composta são uma facilidade da linguagem ADVPL para expressões de 
cálculo e atribuição. Com eles pode-se economizar digitação:
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 variáveis. Entende-se 
por incremento aumentar o valor de uma variável numérica em 1 e entende-se por decremento diminuir 
o valor da variável em 1. Os operadores são:
++ Incremento Pós ou Pré-fixado 
-- Decremento Pós ou Pré-fixado 
Os operadores de decremento/incremento podem ser colocados tanto antes (pré-fixado) como depois 
(pós-fixado) do nome da variável. Dentro de uma expressão, a ordem do operador é muito importante, 
podendo alterar o resultado da expressão. Os operadores incrementais são executados da esquerda para 
a direita dentro de uma expressão.
Local nA := 10
Local nB := nA++ + nA
O valor da variável nB resulta em 21, pois a primeira referência a nA (antes do ++) continha o valor 10 que 
foi considerado e imediatamente aumentado em 1. Na segunda referência a nA, este já possuía o valor 
11. O que foi efetuado foi a soma de 10 mais 11, igual a 21. O resultado final após a execução destas duas 
linhas é a variável nB contendo 21 e a variável 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.
39Todos os direitos reservados. Programação em ADVPL I
Anotações
Operadores Especiais
Além dos operadores comuns, o ADVPL possui alguns outros operadores ou identificadores. Estas são 
suas finalidades:
() Agrupamento ou Função 
[] Elemento de Matriz 
{} Definição de Matriz, Constante ou Bloco de Código 
-> Identificador de Apelido 
& Macro substituição 
@ Passagem de parâmetro por referência 
|| Passagem de parâmetro por valor 
Os parênteses são utilizados para agrupar elementos em uma expressão mudando a ordem de precedência 
da avaliação da expressão (segundo as regras matemáticas por exemplo). Também servem para envolver 
os argumentos de uma função. 
Os colchetes são utilizados para especificar um elemento específico de uma matriz. Por exemplo, A[3,2], 
refere-se ao elemento da matriz A na linha 3, coluna 2.
As chaves são utilizadas para a especificação de matrizes literais ou blocos de código. Por exemplo, 
A:={10,20,30} cria uma matriz chamada A com três elementos.
O símbolo -> identifica um campo de um arquivo diferenciando-o de uma variável. Por exemplo, FUNC-
>nome refere-se ao campo nome do arquivo FUNC. Mesmo que exista uma variável chamada nome, é o 
campo nome que será acessado.
O símbolo & identifica uma avaliação de expressão através de macro e é visto em detalhes na documentação 
sobre macro substituição.
O símbolo @ é utilizado para indicar que durante a passagem de uma variável para uma função ou 
procedimento ela seja tomada como uma referência e não como valor.
O símbolo || é utilizado para indicar que durante a passagem de uma variável para uma função ou 
procedimento ela seja tomada como um e valor não como referência.
 
Ordem de Precedência dos Operadores
Dependendo do tipo de operador, existe uma ordem de precedência para a avaliação dos operandos. Em 
princípio, todas as operações com os operadores, são realizadas da esquerda para a direita se eles tiverem 
o mesmo nível de prioridade.
40 Todos os direitos reservados.Programação em ADVPL l
Anotações
A ordem de precedência, ou nível de prioridade de execução, dos operadores em ADVPL é:
1. Operadores de Incremento/Decremento pré-fixado
2. Operadores de String
3. Operadores Matemáticos
4. Operadores Relacionais
5. Operadores Lógicos
6. Operadores de Atribuição
7. Operadores de Incremento/Decremento pós-fixado
Em expressões complexas com diferentes tipos de operadores, a avaliação seguirá essa seqüência. Caso 
exista mais de um operador do mesmo tipo (ou seja, de mesmo nível), a avaliação se dá da esquerda para 
direita. Para os operadores matemáticos entretanto, há uma precedência a seguir:
1. Exponenciação
2. Multiplicação e Divisão
3. Adição e Subtração
Considere o exemplo:
Local nResultado := 2+10/2+5*3+2^3
O resultado desta expressão é 30, pois primeiramente é calculada a exponenciação 2^3(=8), então são 
calculadas as multiplicações e divisões 10/2(=5) e 5*3(=15), e finalmente as adições resultando em 
2+5+15+8(=30).
Alteração da Precedência
A utilização de parênteses dentro de uma expressão altera a ordem de precedência dos operadores. 
Operandos entre parênteses são analisados antes dos que se encontram fora dos parênteses. Se existirem 
mais de um conjunto de parênteses não-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 exponenciação 2^3(=8). Em seguida 2+10(=12) será 
calculado, 2+5(=7) calculado, e finalmente a divisão e a multiplicação serão efetuadas, o que resulta em 
12/7*3+8(=13.14).
Se existirem vários parênteses aninhados, ou seja, colocados um dentro do outro, a avaliação ocorrerá do 
parênteses mais intero em direção ao mais externo.
41Todos os direitos reservados. Programação em ADVPL I
Operação de Macro Substituição
O operador de macro substituição, simbolizado pelo "e" comercial (&), é utilizado para a avaliação de 
expressões em tempo de execução. Funciona como se uma expressão armazenada fosse compilada em 
tempo de execução, antes de ser de fato executada. 
Considere o exemplo:
01 X := 10
02 Y := "X + 1"
03 B := &Y // O conteúdo de B será 11
A variável X é atribuída com o valor 10, enquanto a variável Y é atribuída com a string de caracteres 
contendo "X + 1".
A terceira linha utiliza o operador de macro. Esta linha faz com que o número 11 seja atribuído à variável B. 
Pode-se perceber que esse é o valor resultante da expressão em formato de caractere contida na variável 
Y.
Utilizando-se uma técnica matemática elementar, a substituição, temos que na segunda linha, Y é definido 
como "X + 1", então pode-se substituir Y na terceira linha:
03 B := &"X + 1"
O operador de macro cancela as aspas:
03 B := X + 1
Pode-se perceberque o operador de macro remove as aspas, o que deixa um pedaço de código para 
ser executado. Deve-se ter em mente que tudo isso acontece em tempo de execução, o que torna tudo 
muito dinâmico. Uma utilização interessante é criar um tipo de calculadora, ou avaliador de fórmulas, que 
determina o resultado de algo que o usuário digita.
O operador de macro tem uma limitação: variáveis referenciadas dentro da string de caracteres (X nos 
exemplos anteriores) não podem ser locais. 
Funções de manipulação de variáveis
Além de atribuir, controlar o escopo e macro executar o conteúdo das variáveis é necessário manipular 
seu conteúdo através de funções específicas da linguagem para cada situação.
As operações de manipulação de conteúdo mais comuns em programação são:
- Conversões entre tipos de variáveis
- Manipulação de strings
- Manipulação de variáveis numéricas
- Verificação de tipos de variáveis
- Manipulação de arrays
- Execução de blocos de código
Neste tópico serão abordadas as conversões entre tipos de variáveis e as funções de manipulação de 
strings e variáveis numéricas.
42 Todos os direitos reservados.Programação em ADVPL l
Anotações
Conversões entre tipos de variáveis
As funções mais utilizadas nas operações entre conversão entre tipos de variáveis são:
- CTOD()
- CVALTOCHAR()
- DTOC()
- DTOS()
- STOD()
- STR()
- STRZERO()
- VAL()
CTOD()
Sintaxe CTOD(cData) 
Descrição 
Realiza a conversão de uma informação do tipo caracter no formato 
“DD/MM/AAAA” para uma variável do tipo data. 
 
CVALTOCHAR()
Sintaxe CVALTOCHAR(nValor) 
Descrição 
Realiza a conversão de uma informação do tipo numérico em uma string, 
sem a adição de espaços a informação. 
 
DTOC()
Sintaxe DTOC(dData) 
Descrição 
Realiza a conversão de uma informação do tipo data para em caracter, sendo 
o resultado no formato “DD/MM/AAAA”. 
 
DTOS()
Sintaxe DTOS(dData) 
Descrição 
Realiza a conversão de uma informação do tipo data em um caracter, sendo 
o resultado no formato “AAAAMMDD”. 
43Todos os direitos reservados. Programação em ADVPL I
STOD()
Sintaxe STOD(sData) 
Descrição 
Realiza a conversão de uma informação do tipo caracter com conteúdo no 
formato “AAAAMMDD” em data. 
 
STR()
Sintaxe STR(nValor) 
Descrição 
Realiza a conversão de uma informação do tipo numérico em uma string, 
adicionando espaços à direita. 
 
STRZERO()
Sintaxe STRZERO(nValor, nTamanho) 
Descrição 
Realiza a conversão de uma informação do tipo numérico em uma string, 
adicionando zeros à esquerda do número convertido, de forma que a string 
gerada tenha o tamanho especificado no parâmetro. 
 
VAL()
Sintaxe VAL(cValor) 
Descrição Realiza a conversão de uma informação do tipo caracter em numérica. 
 
Manipulação de strings
As funções mais utilizadas nas operações de manipulação do conteúdo de strings são:
- ALLTRIM()
- ASC()
- AT()
- CHR()
- CSTUFF()
- LEN()
- RAT()
- SUBSTR()
ALLTRIM()
Sintaxe ALLTRIM(cString) 
Descrição 
Retorna uma string sem os espaços à direita e à esquerda, referente ao 
conteúdo informado como parâmetro. 
 
A função ALLTRIM() implementa as ações das funções RTRIM (“right trim”) e 
LTRIM (“left trim”). 
44 Todos os direitos reservados.Programação em ADVPL l
Anotações
ASC()
Sintaxe ASC(cCaractere) 
Descrição 
Converte uma informação caractere em seu valor de acordo com a tabela 
ASCII. 
 
 
AT()
Sintaxe AT(cCaractere, cString ) 
Descrição 
Retorna a primeira posição de um caracter ou string dentro de outra string 
especificada. 
 
 
CHR()
Sintaxe CHR(nASCII) 
Descrição 
Converte um valor número referente a uma informação da tabela ASCII no 
caractere que esta informação representa. 
 
 
LEN()
Sintaxe LEN(cString) 
Descrição Retorna o tamanho da string especificada no parâmetro. 
 
LOWER()
Sintaxe LOWER(cString) 
Descrição 
Retorna uma string com todos os caracteres minúsculos, tendo como base a 
string passada como parâmetro. 
 
RAT()
Sintaxe RAT(cCaractere, cString) 
Descrição 
Retorna a última posição de um caracter ou string dentro de outra string 
especificada. 
 
 
45Todos os direitos reservados. Programação em ADVPL I
STUFF()
Sintaxe STUFF(cString, nPosInicial, nExcluir, cAdicao) 
Descrição 
Permite substituir um conteúdo caractere em uma string já existente, 
especificando a posição inicial para esta adição e o número de caracteres que 
serão substituídos. 
 
 
SUBSTR()
Sintaxe SUBSTR(cString, nPosInicial, nCaracteres) 
Descrição 
Retorna parte do conteúdo de uma string especificada, de acordo com a 
posição inicial deste conteúdo na string e a quantidade de caracteres que 
deverá ser retornada a partir daquele ponto (inclusive). 
 
 
UPPER()
Sintaxe UPPER(cString) 
Descrição 
Retorna uma string com todos os caracteres maiúsculos, tendo como base a 
string passada como parâmetro. 
Manipulação de variáveis numéricas
As funções mais utilizadas nas operações de manipulação do conteúdo de strings são:
- ABS()
- INT()
- NOROUND()
- ROUND()
ABS()
Sintaxe ABS(nValor) 
Descrição 
Retorna um valor absoluto (independente do sinal) com base no valor 
especificado no parâmetro. 
 
INT()
Sintaxe INT(nValor) 
Descrição Retorna a parte inteira de um valor especificado no parâmetro. 
 
46 Todos os direitos reservados.Programação em ADVPL l
NOROUND()
Sintaxe NOROUND(nValor, nCasas) 
Descrição 
Retorna um valor, truncando a parte decimal do valor especificado no 
parâmetro de acordo com a quantidade de casas decimais solicitadas. 
 
 
ROUND()
Sintaxe ROUND(nValor, nCasas) 
Descrição 
Retorna um valor, arredondando a parte decimal do valor especificado no 
parâmetro de acordo com a quantidades de casas decimais solicitadas, 
utilizando o critério matemático. 
 
Verificação de tipos de variáveis
As funções de verificação permitem a consulta ao tipo do conteúdo da variável durante a execução do 
programa.
- TYPE()
- VALTYPE()
TYPE()
Sintaxe TYPE(“cVariavel”) 
Descrição 
Determina o tipo do conteúdo de uma variável, a qual não foi definida na 
função em execução. 
 
VALTYPE()
Sintaxe VALTYPE(cVariável) 
Descrição 
Determina o tipo do conteúdo de uma variável, a qual foi definida na função 
em execução. 
 
 
Anotações
47Todos os direitos reservados. Programação em ADVPL I
ESTRUTURAS BÁSICAS DE PROGRAMAÇÃO
O ADVPL suporta várias estruturas de controle que permitem mudar a seqüência de fluxo de execução 
de um programa. Estas estruturas permitem a execução de código baseado em condições lógica e a 
repetição da execução de pedaços de código qualquer número 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 têm um identificador de início e 
um de fim, e qualquer estrutura aninhada deve se encontrar entre estes identificadores.
Também existem estruturas de controle para determinar que elementos, comandos, etc. em um programa 
serão compilados. Estas são as diretivas do pré-processador #ifdef...#endif e #ifndef...#endif. Consulte a 
documentação sobre o pré-processador para maiores detalhes.
As estruturas de controle em ADVPL estão divididas em:
- Estruturas de repetição
- Estruturas de decisão
Estruturas de repetição
Estruturas de repetição são designadas para executar uma seção de código mais de uma vez. Por exemplo, 
imaginando-se a existência de uma função para imprimir um relatório, pode-se desejar imprimi-lo quatro 
vezes. Claro, pode-se simplesmente chamar a função de impressão quatro vezes em seqüência, mas isto 
se tornaria pouco profissional e não resolveria o problema se o número de relatórios fosse variável.
Em ADVPL existem dois comandos para a repetição de seções de código, que são 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 seção de código em um 
número determinado de vezes.
Sintaxe
FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento] 
 Comandos...
 [EXIT]
 [LOOP]
NEXT
48Todos os direitos reservados.Programação em ADVPL l
 Parâmetros
Variável
 Especifica uma variável ou um elemento de uma m atriz para 
atuar como um contador. A variável ou o elemento da matriz 
não precisa ter sido declarado antes da execução do comando 
FOR...NEXT . Se a variável não existir, será criada como uma 
variável privada . 
 
 
nValorInicial é o valor inicial para o contador; nValorFinal é o 
valor final para o contador. Pode - se utilizar valores numéricos 
literais, variáveis ou expressões, contanto que o resultado seja 
do tipo de dado numérico. 
STEP
 
nIncremento
 
nIncremento é a quantidade que será incrementada ou 
decrementada no contador após cada execução da seção de 
comandos. Se o valor de nIncremento for negativo, o contador 
será decrementado. Se a cláusula STEP for omitida, o contador 
será incrementado em 1. Pode - se utilizar valores numéricos 
li terais, variáveis ou expressões, contanto que o resultado seja 
do tipo de dado numérico. 
Comandos Especifica um ou mais instruções de comando ADVPL que serão 
executadas. 
EXIT
 Transfere o controle de dentro do comando FOR...NEXT para o 
comando imediatame nte seguinte ao NEXT , ou seja, finaliza a 
repetição da seção de comandos imediatamente. Pode - se 
colocar o comando EXIT em qualquer lugar entre o FOR e o 
NEXT . 
LOOP 
 Retorna o controle diretamente para a cláusula 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 alcançado. Pode - se colocar o comando 
LOOP em qualquer lugar entre o FOR e o NEXT . 
nValorInicial
TOnValorFinal
Uma variável ou um elemento de uma matriz é utilizado como um contador para especificar quantas vezes os comandos 
ADVPL dentro da estrutura FOR...NEXT são executados. 
Os comandos ADVPL depois do FOR são executados até que o NEXT seja alcançado. O contador (Variavel) é então 
incrementado ou decrementado com o valor em nIncremento (se a cláusula STEP for omitida, o contador é incrementado 
em 1). Então, o contador é comparado com o valor em nValorFinal. Se for menor ou igual ao valor em nValorFinal, os 
comandos seguintes ao FOR são executados novamente. 
Se o valor for maior que o contido em nValorFinal, a estrutura FOR...NEXT é terminada e o programa continua a execução 
no primeiro comando após o NEXT.
Os valores de nValorInicial, nValorFinal e nIncremento são apenas considerados inicialmente. Entretanto, mudar o valor 
da variável utilizada como contador dentro da estrutura afetará o número de vezes que a repetição será executada. Se o 
valor de nIncremento é negativo e o valor de nValorInicial é maior que o de nValorFinal, o contador será decrementado 
a cada repetição.
Fique
atento
49Todos os direitos reservados. Programação em ADVPL I
Exemplo:
Local nCnt
Local nSomaPar := 0
For nCnt := 0 To 100 Step 2
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros números pares é: " + ;
 cValToChar(nSomaPar) )
Return
Este exemplo imprime a soma dos 100 primeiros números pares. A soma é obtida através da repetição 
do cálculo utilizando a própria variável de contador. Como a cláusula STEP está sendo utilizada, a variável 
nCnt será sempre incrementada em 2. E como o contador começa com 0, seu valor sempre será um 
número par.
O Comando WHILE...ENDDO
A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma seção de código 
enquanto uma determinada expressão resultar em verdadeiro (.T.).
Sintaxe
WHILE lExpressao 
 Comandos...
 [EXIT]
 [LOOP]
ENDDO
Parâmetros
lExpressao
 Especifica uma expressão lógica cujo valor determina quando os 
comandos entre o WHILE e o ENDDO são executados. Enquanto o 
resultado de lExpressao for avaliado como verdadeiro ( .T. ), o 
conjunto de comandos são executados. 
Comandos Especifica um ou mais instruções de comando ADVPL que serão 
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 
repetição da seç ão de comandos imediatamente. Pode - se colocar o 
comando EXIT em qualquer lugar entre o WHILE e o ENDO . 
LOOP
 Retorna o controle diretamente para a cláusula WHILE sem executar 
o restante dos comandos entre o LOOP e o ENDDO. A expressão em 
lExpressao é reava liada para a decisão se os comandos continuarão 
sendo executados. 
 
50 Todos os direitos reservados.Programação em ADVPL l
Exemplo:
Local nNumber := nAux := 350
nAux := Int(nAux / 2) 
While nAux > 0
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros números pares é: " + ;
 cValToChar(nSomaPar) ) 
Return
Os comandos entre o WHILE e o ENDDO são executados enquanto o resultado da avaliação da expressão 
em lExpressao permanecer verdadeiro (.T.). Cada palavra chave WHILE deve ter uma palavra chave ENDDO 
correspondente.
Influenciando o fluxo de repetição
A linguagem ADVPL permite a utilização de comandos que influem diretamente em um processo de 
repetição, sendo eles:
- LOOP
- EXIT
LOOP
A instrução LOOP é utilizada para forçar um desvio no fluxo do programa de volta a análise da condição 
de repetição. Desta forma, todas as operações que seriam realizadas dentro da estrutura de repetição 
após o LOOP serão desconsideradas.
Exemplo: 
aItens:= ListaProdutos() // função ilustrativa que retorna um array com dados dos produtos
nQuantidade := Len(aItens)
nItens := 0
While nItens < nQuantidade
 
nItens++ 
IF BLOQUEADO(aItens [nItens]) // função ilustrativa que verifica se o produto está 
 LOOP // bloqueado.
ENDIF
IMPRIME() // função ilustrativa que realiza a impressão de um item liberado para uso
End
// Caso o produto esteja bloqueado, o mesmo não será impresso, pois a execução da // instrução LOOP 
fará o fluxo do programa retornar a partir da análise da condição.
51Todos os direitos reservados. Programação em ADVPL I
EXIT
A instrução EXIT é utilizada para forçar o término de uma estrutura de repetição. Desta forma, todas as 
operações que seriam realizadas dentro da estrutura de repetição após o EXIT serão desconsideradas, e o 
programa irá continuar a execução a partir da próxima instrução posterior ao término da estrutura (END 
ou NEXT).
Exemplo: 
While .T.
 
IF MSGYESNO(“Deseja jogar o jogo da forca?”)
 JFORCA() // Função ilustrativa que implementa o algoritmo do jogo da forca. 
 ELSE
 EXIT
 ENDIF
End
MSGINFO(“Final de Jogo”)
// Enquanto não for respondido “Não” para a pergunta: “Deseja jogar o jogo da 
// forca”, será executada a função do jogo da forca.
// Caso seja selecionada a opção “Não”, será executada a instrução EXIT que provocará o término do LOOP, 
permitindo a execução da mensagem de “Final de Jogo”.
Estruturas de decisão
Estruturas de desvio são designadas para executar uma seção de código se determinada condição lógica 
resultar em verdadeiro (.T.). 
Em ADVPL existem dois comandos para execução de seções de código de acordo com avaliações lógicas, 
que são 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 expressão lógica.
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
52 Todos os direitos reservados.Programação em ADVPL l
Parâmetros
LExpressao Especifica u ma e xpressão l ógica que é avaliada. Se l Expressao 
resultar e m verdadeiro ( .T.), qualquer c omando s eguinte ao I F e 
antecedente ao E LSE ou E NDIF ( o que ocorrer primeiro) será 
executado. 
Se lExpressao resultar em falso (.F.) e a cláusula ELSE for definida, 
qualquer c omando a pós essa c láusula e anterior a o ENDIF s erá 
executada. Se a cláusula ELSE não for definida, todos os comandos 
entre o IF e o E NDIF s ão i gnorados. Neste caso, a execução d o 
programa continua com o primeiro comando seguinte ao ENDIF. 
Comandos Conjunto de comandos A DVPL que serão executados dependendo da 
avaliação da expressão lógica