Programação ADVPL

Programao ADVPL I
Todos os direitos autorais reservados pela TOTVS S.A.

Proibida a reproduo total ou parcial, bem como a armazenagem em sistema de recuperao e a
transmisso, de qualquer modo ou por qualquer outro meio, seja este eletrnico, mecnico, de fotocpia, de
gravao, ou outros, sem prvia autorizao por escrito da proprietria.
O desrespeito a essa proibio configura em apropriao indevida dos direitos autorais e patrimoniais da
TOTVS.
Conforme artigos 122 e 130 da LEI no. 5.988 de 14 de Dezembro de 1973.
0072 - Programao
ADVPL I
Protheus
11
SUMRIO
OBJETIVOS DO CURSO .............................................................................................. 8
MDULO 01: INTRODUO PROGRAMAO......................................................... 9
LGICA DE PROGRAMAO E ALGORITMOS ............................................................. 9
Lgica de Programao ............................................................................................. 9
Desenvolvendo algoritmos ..................................................................................... 11
Estudando algoritmos..................................................................................................... 11
Teste de mesa ................................................................................................................. 13
ESTRUTURAS DE PROGRAMAO ........................................................................... 15
Diagrama de bloco ................................................................................................. 15
Estruturas de deciso e repetio ........................................................................... 19
Estruturas de deciso ..................................................................................................... 19
Estruturas de repetio .................................................................................................. 23
MDULO 02: A LINGUAGEM ADVPL........................................................................ 27
ESTRUTURA DE UM PROGRAMA ADVPL.................................................................. 30
reas de um Programa ADVPL ................................................................................ 32
DECLARAO E ATRIBUIO DE VARIVEIS ............................................................ 36
Tipo de Dados ........................................................................................................ 36
Declarao de variveis .......................................................................................... 37
Escopo de variveis ................................................................................................ 38
Entendendo a influncia do escopo das variveis .................................................... 43
Operaes com Variveis........................................................................................ 44
Atribuio de variveis ................................................................................................... 44
Operadores da linguagem ADVPL................................................................................... 45
Operao de Macro Substituio ................................................................................... 51
Funes de manipulao de variveis ............................................................................ 52
ESTRUTURAS BSICAS DE PROGRAMAO ............................................................. 58
Estruturas de repetio .......................................................................................... 58
Influenciando o fluxo de repetio................................................................................. 61
Estruturas de deciso ............................................................................................. 63
-2Introduo programao e ADVPL Bsico
ARRAYS E BLOCOS DE CDIGO................................................................................ 68

Arrays .................................................................................................................... 68
Inicializando arrays ......................................................................................................... 70
Funes de manipulao de arrays ................................................................................ 71
Cpia de arrays ............................................................................................................... 73
Listas de Expresses e Blocos de Cdigo .................................................................. 75
Premissas para utilizao de Blocos de Cdigo .............................................................. 75
Lista de expresses ......................................................................................................... 76
Blocos de Cdigo ............................................................................................................ 78
Funes para manipulao de blocos de cdigo ............................................................ 80
FUNES ................................................................................................................ 81
Tipos e escopos de funes ..................................................................................... 82
Passagem de parmetros entre funes.................................................................. 85
DIRETIVAS DE COMPILAO ................................................................................... 91
MDULO 03: DESENVOLVENDO PEQUENAS CUSTOMIZAES ................................ 97
ADVPL E O ERP MICROSIGA PROTHEUS ................................................................... 97
O Ambiente Protheus ............................................................................................. 97
Organizao e configurao inicial do ambiente Protheus ..................................... 102
O Configurador do Protheus ................................................................................. 109
Funcionalidades Abordadas ......................................................................................... 109
Estruturas bsicas da aplicao ERP Protheus ............................................................. 109
Acessando o mdulo Configurador .............................................................................. 112
Funcionalidades do Configurador ......................................................................... 115
Dicionrio de Dados da aplicao ERP ......................................................................... 116
Adio de tabelas ao Dicionrio de Dados ................................................................... 116
Adio de campos s tabelas do Dicionrio de Dados ................................................. 119
Adio de ndices para as tabelas do Dicionrio de Dados .......................................... 124
Adio de gatilhos para os campos das tabelas do Sistema ........................................ 129
Criao de Tabelas Genricas ....................................................................................... 131
Criao de Parmetros ................................................................................................. 132
TOTVS DEVELOPMENT STUDIO ............................................................................. 134
DESENVOLVIMENTO DE PEQUENAS CUSTOMIZAES .......................................... 137
ACESSO E MANIPULAO DE BASES DE DADOS EM ADVPL ................................... 137
Diferenas e compatibilizaes entre bases de dados............................................ 138
Funes de acesso e manipulao de dados .......................................................... 139

Diferenciao entre variveis e nomes de campos ................................................ 145
Controle de numerao seqencial ....................................................................... 146
CUSTOMIZAES PARA A APLICAO ERP ............................................................ 147
Customizao de campos Dicionrio de Dados ................................................... 148
Validaes de campos e perguntas .............................................................................. 148
Pictures de formao disponveis ................................................................................. 150
Customizao de gatilhos Configurador.............................................................. 153
Customizao de parmetros Configurador ........................................................ 154
Funes para manipulao de parmetros .................................................................. 154
Cuidados na utilizao de um parmetro..................................................................... 155
Pontos de Entrada Conceitos, Premissas e Regras .............................................. 156
INTERFACES VISUAIS ............................................................................................ 157
Sintaxe e componentes das interfaces visuais ....................................................... 157
Interfaces padres para atualizaes de dados ..................................................... 160
AxCadastro() ................................................................................................................. 160
MBrowse() .................................................................................................................... 161
AxFunctions() ................................................................................................................ 164
APNDICES ........................................................................................................... 166
BOAS PRTICAS DE PROGRAMAO..................................................................... 166
UTILIZAO DE IDENTAO.................................................................................. 167
CAPITULAO DE PALAVRAS-CHAVE..................................................................... 168
Palavras em maisculo ......................................................................................... 169
UTILIZAO DA NOTAO HNGARA ................................................................... 169
PALAVRAS RESERVADAS ....................................................................................... 170
GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL ................................. 171
Converso entre tipos de dados ............................................................................ 171
CTOD()........................................................................................................................... 171
CVALTOCHAR() .............................................................................................................. 171
DTOC()........................................................................................................................... 172
DTOS() ........................................................................................................................... 172
STOD() ........................................................................................................................... 172
STR() .............................................................................................................................. 173
STRZERO() ..................................................................................................................... 173

VAL() ............................................................................................................................. 174
Verificao de tipos de variveis ........................................................................... 174
TYPE() ............................................................................................................................ 174
VALTYPE()...................................................................................................................... 174
Manipulao de arrays ......................................................................................... 176
Array() ........................................................................................................................... 176
AADD() .......................................................................................................................... 176
ACLONE() ...................................................................................................................... 177
ADEL() ........................................................................................................................... 178
ASIZE() ........................................................................................................................... 178
ASORT() ......................................................................................................................... 179
ASCAN()......................................................................................................................... 181
AINS() ............................................................................................................................ 182
Manipulao de blocos de cdigo ......................................................................... 183
EVAL()............................................................................................................................ 183
DBEVAL() ....................................................................................................................... 183
AEVAL() ......................................................................................................................... 185
Manipulao de strings ........................................................................................ 186
ALLTRIM()...................................................................................................................... 186
ASC() ............................................................................................................................. 186
AT() ............................................................................................................................... 187
CHR() ............................................................................................................................. 188
LEN().............................................................................................................................. 188
LOWER() ........................................................................................................................ 188
RAT() ............................................................................................................................. 189
STUFF() .......................................................................................................................... 189
SUBSTR() ....................................................................................................................... 190
UPPER() ......................................................................................................................... 190
Manipulao de variveis numricas .................................................................... 190
ABS() ............................................................................................................................. 190
INT() .............................................................................................................................. 191
NOROUND() .................................................................................................................. 191
ROUND() ....................................................................................................................... 192
Manipulao de arquivos ..................................................................................... 192
SELECT() ........................................................................................................................ 192
DBGOTO() ..................................................................................................................... 193
DBGOTOP() ................................................................................................................... 193
DBGOBOTTON() ............................................................................................................ 194

DBSELECTAREA() ........................................................................................................... 194
DBSETORDER() .............................................................................................................. 195
DBSEEK() E MSSEEK() .................................................................................................... 196
DBSKIP() ........................................................................................................................ 197
DBSETFILTER() ............................................................................................................... 198
DBSTRUCT() .................................................................................................................. 199
RECLOCK() ..................................................................................................................... 199
MSUNLOCK() ................................................................................................................. 200
SOFTLOCK() ................................................................................................................... 201
DBDELETE() ................................................................................................................... 202
DBUSEAREA() ................................................................................................................ 202
DBCLOSEAREA() ............................................................................................................ 203
Controle de numerao seqencial ....................................................................... 203
GETSXENUM() ............................................................................................................... 203
CONFIRMSXE() .............................................................................................................. 204
ROLLBACKSXE() ............................................................................................................. 204
Validao ............................................................................................................. 204
EXISTCHAV() .................................................................................................................. 204
EXISTCPO() .................................................................................................................... 204
NAOVAZIO() .................................................................................................................. 205
NEGATIVO() .................................................................................................................. 205
PERTENCE() ................................................................................................................... 205
POSITIVO() .................................................................................................................... 205
TEXTO() ......................................................................................................................... 206
VAZIO().......................................................................................................................... 206
Parmetros .......................................................................................................... 206
GETMV()........................................................................................................................ 206
GETNEWPAR()............................................................................................................... 206
PUTMV() ....................................................................................................................... 207
SUPERGETMV() ............................................................................................................. 207
Componentes da interface visual .......................................................................... 208
MSDIALOG() .................................................................................................................. 208
MSGET() ........................................................................................................................ 208
SAY().............................................................................................................................. 209
BUTTON() ...................................................................................................................... 210
SBUTTON() .................................................................................................................... 210
Interfaces de cadastro .......................................................................................... 211
AXCADASTRO().............................................................................................................. 211
MBROWSE() .................................................................................................................. 212
AXPESQUI() ................................................................................................................... 212
AXVISUAL() .................................................................................................................... 212
AXINCLUI() .................................................................................................................... 213
AXALTERA() ................................................................................................................... 214
AXDELETA() ................................................................................................................... 214
Funes visuais para aplicaes ............................................................................ 215
ALERT() .......................................................................................................................... 215
AVISO() .......................................................................................................................... 215
FORMBACTH()............................................................................................................... 216
MSGFUNCTIONS() ......................................................................................................... 217
Funes ADVPL para aplicaes ............................................................................ 218
GETAREA()..................................................................................................................... 218
RESTAREA() ................................................................................................................... 218
REFERNCIAS BIBLIOGRFICAS ............................................................................. 219
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 TOTVS.
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
Adquirir conhecimentos atravs da anlise das funcionalidades

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

LGICA DE PROGRAMAO E ALGORITMOS
No aprendizado de qualquer linguagem de programao essencial desenvolver os
conceitos relacionados a 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
Lgica de Programao
Lgica
A lgica de programao necessria para pessoas que desejam trabalhar com
desenvolvimento de sistemas e programas, ela permite definir a seqncia lgica para
o desenvolvimento. Ento o que lgica?
Lgica de programao a tcnica de encadear pensamentos para atingir

determinado objetivo.
Seqncia Lgica
Estes pensamentos podem ser descritos como uma seqncia de instrues, que
devem ser
seguidas para se cumprir uma determinada tarefa.
Seqncia Lgica so passos executados at atingir um objetivo ou soluo de um

problema.
Instrues
Na linguagem comum, entende-se por instrues 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 tm que ser executadas em uma ordem adequada
no se pode descascar as batatas depois de frit-las.
Dessa maneira, uma instruo tomada em separado no tem muito sentido, para
obtermos o resultado, precisamos colocar em prtica o conjunto de todas as
instrues, na ordem correta.
Instrues so 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 seqncia finita de passos que levam execuo de
uma tarefa. Podemos pensar em algoritmo como uma receita, uma seqncia de
instrues que do cabo de uma meta especfica. Estas tarefas no podem ser
redundantes nem subjetivas na sua definio, devem ser claras e precisas.
Como exemplos de algoritmos podemos citar os algoritmos das operaes bsicas
(adio, multiplicao, diviso e subtrao) de nmeros reais decimais. Outros
exemplos seriam os manuais de aparelhos eletrnicos, como um videocassete, que
explicam passo-a-passo como, por exemplo, gravar um evento.
At mesmo as coisas mais simples podem ser descritas por seqncias lgicas, tais
como:
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.
- 10 Introduo programao e ADVPL Bsico
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.
Regras para construo do Algoritmo
Para escrever um algoritmo precisamos descrever a seqncia 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 sentido dbio.
Fases
Para implementar de um algoritmo de simples interpretao e codificao necessrio
inicialmente dividir o problema apresentado em trs fases fundamentais, as quais so:
ENTRADA: So os dados de entrada do algoritmo;
PROCESSAMENTO: So os procedimentos utilizados para chegar ao resultado
final;
SADA: So os dados j processados.
Estudando algoritmos
Neste tpico sero demonstrados alguns algoritmos do cotidiano, os quais 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
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. 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 lmpadas
1. Se a lmpada estiver fora do alcance, pegar uma escada.
2. Pegar a lmpada nova.
3. Se a lmpada queimada estiver quente, pegar um pano.
4. Tirar lmpada queimada.

5. Colocar lmpada 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 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 centro estiver livre: jogue no centro.
1.3. Seno, se o adversrio possuir 2 quadrados em linha com um quadrado
livre, jogue neste quadrado.
1.4. Seno, se h algum canto livre, jogue neste canto.
Teste de mesa
Aps desenvolver um algoritmo, ele dever sempre ser testado. Este teste chamado
de TESTE DE MESA, que significa seguir as instrues do algoritmo de maneira precisa
para verificar se o procedimento utilizado est correto ou no.
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
1
2
3
4
5
6
Nota
8.0
7.0
8.0
8.0
7.0
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 mdia obtida: Mensagem (Mdia: 7.5)
Exerccios
Aprimorar os seguintes algoritmos descritos na apostila:
Usar telefone pblico carto.

Fritar um ovo.
Mascar um chiclete.
Trocar lmpadas.
Descascar batatas.
Jogar o Jogo da Forca.
ESTRUTURAS DE PROGRAMAO
Diagrama de bloco
O diagrama de blocos uma forma padronizada e eficaz para representar os passos
lgicos de um determinado processamento.
Com o diagrama podemos definir uma seqncia de smbolos, com significado bem
definido, portanto, sua principal funo a de facilitar a visualizao dos passos de um
processamento.
Simbologia
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.
Processamento
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
processamento.
obtidos
com
um
Exibio
Documento
Indica um documento utilizado pelo

processamento, seja para entrada de
informaes ou para exibio dos dados
disponveis aps um processamento.
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.
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. 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.
Algoritmo 02: Calcular a mdia de notas

a. Receber a nota.
Estruturas de deciso e repetio

A utilizao de estruturas de deciso e repetio em um algoritmo permite a realizao
de aes relacionadas a situaes que influenciam na execuo e soluo do problema.
Como foco na utilizao da linguagem ADVPL, sero ilustradas as seguintes estruturas:
Estruturas de deciso
o IF...ELSE
o DO CASE ... CASE
Estruturas de repetio
o WHILE...END
o FOR...NEXT
Os comandos de deciso so utilizados em algoritmos cuja soluo no obtida
atravs da utilizao de aes meramente seqenciais, 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

Aes anteriores
...
Verdadeiro
Anlise da
condio
Ao vinculada ao
resultado
verdadeiro
Falso
Ao vinculada ao
resultado falso
Continuao do
fluxo aps a
tomada da
deciso
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.
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 seqncia, para as quais ser avaliada somente a ao da primeira
expresso cujo anlise resultar em um valor verdadeiro.
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
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.
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
Nesta estrutura, o conjunto de aes ser executado enquanto a anlise de uma
condio de referncia resultar em um valor verdadeiro. importante verificar que o
bloco somente ser executado, inclusive se na primeira anlise a condio resultar em
um valor verdadeiro.
Representao: WHILE...END
Aes anteriores
...
Anlise da
condio
Loop
Falso
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo
...
Existem diversas variaes para a estrutura WHILE...END, na qual h 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.
FOR...TO...NEXT
Nesta estrutura, o conjunto de aes ser executado uma quantidade de vezes
definida, normalmente referenciada como passo.
Para cada passo realizado pela estrutura FOR...TO...NEXT, ser avaliada uma
condio que verificar se foi atingido o nmero de execues previamente definido.
Desta forma a estrutura compreende um controle de nmero de passos executados,
o qual incrementado na anlise da expresso NEXT.
Semelhante a estrutura WHILE...END, a primeira ao somente ser realizada
mediante um resultado verdadeiro na anlise da condio.
Representao: FOR...TO...NEXT
Aes anteriores
...
Anlise da
condio
Falso
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Incrementa o
contador de
passos
Continuao do
fluxo
...
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, o
qual 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.
Exerccios
Montar os diagramas de blocos para os algoritmos desenvolvidos no exerccio anterior:
Usar telefone pblico carto.

Fritar um ovo.
Mascar um chiclete.
Trocar lmpadas.
Descascar batatas.
Jogar o Jogo da Forca.
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 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
Nesta categoria, entram os programas desenvolvidos para serem executados 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 a execuo de rotinas escritas em ADVPL no Protheus Server, e por isso permite
executar qualquer tipo de cdigo, tenha ele interface com o usurio ou no. Porm,
nesta categoria so considerados apenas os programas que realizem algum tipo de
interface remota, utilizando o protocolo de comunicao do Protheus.
Podem-se criar rotinas para a customizao do sistema ERP Microsiga Protheus, desde
processos adicionais at mesmo relatrios. A grande vantagem aproveitar todo o
Ambiente montado pelos mdulos do ERP Microsiga Protheus. Porm, com o ADVPL
possvel at mesmo criar toda uma aplicao, ou mdulo, do comeo.
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. Estas rotinas so apenas processos, ou Jobs,
executados no Protheus Server. Algumas vezes, a interface destas 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
Atravs de uma biblioteca de funes disponvel no Protheus (uma API de

comunicao), podem-se executar rotinas escritas em ADVPL diretamente no Protheus
Server, por aplicaes externas escritas em outras linguagens. Isto 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, 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 destas requisies, pode executar rotinas escritas em
ADVPL como processos individuais, enviando o resultado das funes como retorno
das requisies para o cliente HTTP (como por exemplo, um Browser de Internet).
Qualquer rotina escrita em ADVPL, que no contenha comandos de interface, pode ser
executada atravs de requisies HTTP. O Protheus permite a compilao de arquivos

HTML, contendo cdigo ADVPL embutido. So os chamados arquivos ADVPL ASP, para
a criao de pginas dinmicas.
Programao TelNet
TelNet parte da gama de protocolos TCP/IP que permite a conexo a um computador

remoto, atravs de uma aplicao cliente deste protocolo. O PROTHEUS Server pode
emular um terminal pela execuo de rotinas escritas em ADVPL. Ou seja, pode-se
escrever rotinas ADVPL cuja interface final ser um terminal TelNet ou um coletor de
dados mvel.
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, atravs de um processo chamado 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 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
Linhas de Comentrio
Linhas de comentrio possuem um texto qualquer, mas no so executadas. Servem

apenas para 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
Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio.
Pode-se utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para
realizar a funo do sinal de asterisco. Porm todas estas formas de comentrio de
linhas so obsoletas e existem apenas para 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 utilizar as barras transversais juntamente com o
asterisco, podendo-se 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
Tamanho da Linha
Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser
digitado no editor de textos utilizado, existe uma linha considerada linha lgica. A linha
lgica aquela considerada para a compilao como uma nica linha de comando.
A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento
da tecla <Enter>. Ou seja, a linha lgica a linha fsica no arquivo. Porm algumas
vezes, por limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha
lgica em mais de uma linha fsica no arquivo texto. Isto efetuado utilizando-se o
sinal de ponto-e-vrgula (;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter>
!Empty(cTel) .And. !Empty(cFax) .And. ; <enter>
!Empty(cEmail)
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas.
Como a linha torna-se muito grande, pode-se 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.
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:
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. Pode-se colocar qualquer tipo de informao
desejada e escolher a formatao apropriada.
/*
+==========================================+
| Programa: Clculo do Fatorial
|
| Autor : Microsiga Software S.A.
|
| Data : 02 de outubro de 2001
|
+==========================================+
*/
User Function CalcFator()
Opcionalmente podem-se incluir definies de constantes utilizadas no programa ou

incluso de arquivos de cabealho nesta rea.
rea de Ajustes Iniciais
Nesta rea geralmente se fazem os ajustes iniciais, importantes para o correto
funcionamento do programa. Entre os ajustes se encontram declaraes de variveis,
inicializaes, abertura de arquivos, etc. Apesar do ADVPL no ser uma linguagem
rgida e as variveis poderem ser declaradas em qualquer lugar do programa,
aconselhvel faz-lo nesta rea visando tornar o cdigo mais legvel e facilitar a
identificao de variveis no utilizadas.
Local nCnt
Local nResultado := 0 // Resultado do fatorial
Local nFator := 10 // Nmero para o clculo
Corpo do Programa
nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a
tarefa necessria por meio da organizao lgica destas linhas de comando. Espera-se
que as linhas de comando estejam organizadas de tal modo que no final desta rea o
resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variveis

de memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela.
nResultado *= nCnt
Next nCnt
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, pode-se
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
rea de Encerramento
nesta rea onde as finalizaes so efetuadas. onde os arquivos abertos so
fechados, e o resultado da execuo do programa utilizado. Pode-se exibir o
resultado armazenado em uma varivel 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, atravs da funo alert
// Termina o programa
Return
DECLARAO E ATRIBUIO DE VARIVEIS

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
podem-se criar variveis numricas com qualquer valor dentro do intervalo permitido.
Os seguintes elementos so do tipo de dado numrico:
2
43.53
0.5
0.00001
1000000
Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos,
incluindo o ponto flutuante, no intervalo de 2.2250738585072014 E
308 at 1.7976931348623158 E+308.
Lgico
Valores lgicos em ADVPL so identificados atravs de .T. ou .Y. para verdadeiro e .F.
ou .N. para falso (independentemente se os caracteres estiverem em maisculo ou
minsculo).
Caractere
Strings ou cadeias de caracteres so identificadas em ADVPL por blocos de texto entre
aspas duplas (") ou aspas simples ('):
"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"
Uma varivel do tipo caractere pode conter strings com no mximo 1 MB, ou seja,
1048576 caracteres.
Data
O ADVPL tem um tipo de dados especfico para datas. Internamente as variveis deste
tipo de dado so armazenadas como um nmero correspondente data Juliana.
Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs
da utilizao de funes especficas como, por exemplo, CTOD() que converte uma
string para data.
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.
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 necessrio mais se referenciar
ao seu contedo, e sim ao seu nome.
O nome de uma varivel um identificador nico o qual deve respeitar um mximo de
10 caracteres. O ADVPL no impede a criao de uma varivel de memria cujo nome
contenha mais de 10 caracteres, porm apenas os 10 primeiros sero considerados
para a localizao do contedo armazenado.
Portanto se forem criadas duas variveis cujos 10 primeiros caracteres forem iguais,
como nTotalGeralAnual e nTotalGeralMensal, as referncias a qualquer uma delas no
programa resultaro o mesmo, ou seja, sero a mesma varivel:
nTotalGeralMensal := 100
nTotalGeralAnual := 300
Alert("Valor mensal: " + cValToChar(nTotalGeralMensal))
Quando o contedo da varivel nTotalGeralMensal exibido, o seu valor ser de 300.
Isso acontece porque no momento que esse valor foi 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.
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 deve-se 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
Quando um valor atribudo a uma varivel em um programa ou funo, o ADVPL
criar a varivel caso ela no tenha 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. Pois compreender o
nome da varivel escrito de forma incorreta como se fosse a criao de uma nova
varivel. Isto alterar a lgica do programa, e um erro muitas vezes difcil de
identificar.
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.
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.
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.
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.
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 a qual
deve ser respeitada que 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.
Maiores informaes avaliar o tpico: Boas Prticas de Programao.
Exemplo: Private _dData
Variveis de escopo public

Podem-se criar variveis de escopo public dinamicamente, no cdigo com o
identificador PUBLIC. As variveis deste escopo continuam a existir e mantm seu valor
at o fim da execuo da thread (conexo).
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.)
Neste 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).
No ambiente ERP Protheus, existe uma conveno adicional a qual
deve ser respeitada que variveis em uso pela aplicao no sejam
incorretamente manipuladas. Por esta conveno deve ser adicionado
o caractere _ antes do nome de variveis PRIVATE e PUBLIC.
Maiores informaes avaliar o tpico: Boas Prticas de Programao.
Exemplo: Public _cRotina
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 este
erro, deve-se declarar a varivel previamente:
Local nPercentual, nResultado

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

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

nPercentual := 10
ou
Local nPercentual := 10, nResultado
A diferena, entre o ltimo exemplo e os dois anteriores, que a varivel inicializada
no momento da declarao. Em ambos os 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.
Operaes com Variveis

Atribuio de variveis
Uma vez que um valor lhe seja atribudo, o tipo de dado de uma varivel igual ao tipo
de dado do valor atribudo. Ou seja, uma varivel passa a ser numrica se um nmero
lhe atribudo, passa a ser caractere se uma string de texto lhe for atribuda etc.
Porm, mesmo que uma varivel seja de determinado tipo de dado, pode-se mudar o
tipo da varivel atribuindo outro tipo a ela:
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
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.
Operadores da linguagem ADVPL

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)
Neste exemplo so utilizadas algumas expresses para calcular o salrio lquido aps
um aumento. Os operandos de uma expresso podem ser uma varivel, uma
constante, um campo de arquivo ou uma funo.
Operadores Matemticos
Os operadores utilizados em ADVPL para clculos matemticos so:
+
*
/
** ou ^
%
Adio
Subtrao
Multiplicao
Diviso
Exponenciao
Mdulo (Resto da Diviso)
Operadores de String
Os operadores utilizados em ADVPL para tratamento de caracteres so:
+
$
Concatenao de strings (unio).

Concatenao de strings com eliminao dos brancos finais das strings
intermedirias.
Comparao de Substrings (contido em).
Operadores Relacionais
Os operadores utilizados em ADVPL para operaes e avaliaes relacionais so:
<
>
=
==
<=
>=
<> ou #
ou !=
Comparao Menor
Comparao Maior
Comparao Igual
Comparao Exatamente Igual (para caracteres)
Comparao Menor ou Igual
Comparao Maior ou Igual
Comparao Diferente
Operadores Lgicos
Os operadores utilizados em ADVPL para operaes e avaliaes lgicas so:
.And.
.Or.
.Not. ou !
E lgico
OU lgico
NO lgico
Operadores de Atribuio
Os operadores utilizados em ADVPL para atribuio de valores a variveis de memria
so:
:=
+=
-=
*=
/=
**= ou ^=
%=
Atribuio Simples
Adio e Atribuio em Linha
Subtrao e Atribuio em Linha
Multiplicao e Atribuio em Linha
Diviso e Atribuio em Linha
Exponenciao e Atribuio em Linha
Mdulo (resto da diviso) e Atribuio em Linha
Atribuio Simples
O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.

nVariavel := 10
Atribuio em Linha
O operador de atribuio em linha caracterizado por dois pontos e o sinal de

igualdade. Tem a mesma funo do sinal de igualdade sozinho, porm aplica a
atribuio s variveis. Com ele pode-se atribuir mais de uma varivel ao mesmo
tempo.
nVar1 := nVar2 := nVar3 := 0
Quando diversas variveis so inicializadas em uma mesma linha, a atribuio
comea da direita para a esquerda, ou seja, nVar3 recebe o 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, pode-se substituir as inicializaes
individuais de cada varivel por uma inicializao apenas:
Local nVar1 := 0, nVar2 := 0, nVar3 := 0
por
Local nVar1 := nVar2 := nVar3 := 0
O operador de atribuio em linha tambm pode ser utilizado para substituir
valores de campos em um banco de dados.
Atribuio Composta
Os operadores de atribuio composta so uma facilidade da linguagem ADVPL para

expresses de clculo e atribuio. Com eles pode-se economizar digitao:
Operador
Exemplo
Equivalente a
+=
-=
*=
/=
**= ou ^=
%=
X
X
X
X
X
X
+= Y
-= Y
*= Y
/= Y
**= Y
%= Y
X
X
X
X
X
X
=
=
=
=
=
=
X
X
X
X
X
X
+Y
-Y
*Y
/Y
** Y
%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 (prfixado) 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
O valor da varivel nB resulta em 21, pois a primeira referncia a nA (antes do ++)
continha o valor 10 que foi considerado e imediatamente aumentado em 1. Na
segunda referncia a nA, este j possua o valor 11. O que foi efetuado foi a soma
de 10 mais 11, igual a 21. O resultado final aps a execuo destas duas linhas a
varivel nB contendo 21 e a varivel nA contendo 11.
No entanto:
Local nA := 10
Local nB := ++nA + nA
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.
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.
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
Operadores
Operadores
Operadores
Operadores
Operadores
Operadores
de Incremento/Decremento pr-fixado
de String
Matemticos
Relacionais
Lgicos
de Atribuio
de Incremento/Decremento ps-fixado
Em expresses complexas com diferentes tipos de operadores, a avaliao seguir

essa seqncia. 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 fora dos parnteses. Se existirem mais de um conjunto de parnteses
no-aninhados, o grupo mais a esquerda ser avaliado primeiro e assim
sucessivamente.
Local nResultado := (2+10)/(2+5)*3+2^3
No exemplo acima primeiro ser calculada a exponenciao 2^3(=8). Em seguida
2+10(=12) ser calculado, 2+5(=7) calculado, e finalmente a diviso e a
multiplicao sero efetuadas, o que resulta em 12/7*3+8(=13.14).
Se existirem vrios parnteses aninhados, ou seja, colocados um dentro do outro, a
avaliao ocorrer do parnteses mais intero em direo ao mais externo.
Operao de Macro Substituio

O operador de macro substituio, simbolizado pelo "e" comercial (&), utilizado
para a avaliao de expresses em tempo de execuo. Funciona como se uma
expresso armazenada fosse compilada em tempo de execuo, antes de ser de
fato executada.
Considere o exemplo:
01 X := 10
02 Y := "X + 1"
03 B := &Y // O contedo de B ser 11
A varivel X atribuda com o valor 10, enquanto a varivel Y atribuda com a
string de caracteres contendo "X + 1".
A terceira linha utiliza o operador de macro. Esta linha faz com que o nmero 11
seja atribudo varivel B. Pode-se perceber que esse o valor resultante da
expresso em formato de caractere contida na varivel Y.
Utilizando-se uma tcnica matemtica elementar, a substituio, temos que na
segunda linha, Y definido como "X + 1", ento pode-se substituir Y na terceira
linha:
03 B := &"X + 1"
O operador de macro cancela as aspas:
03 B := X + 1
Pode-se perceber que o operador de macro remove as aspas, o
pedao de cdigo para ser executado. Deve-se ter em mente
acontece em tempo de execuo, o que torna tudo muito dinmico.
interessante criar um tipo de calculadora, ou avaliador de
determina o resultado de algo que o usurio digita.
que deixa um
que tudo isso
Uma utilizao
frmulas, que
O operador de macro tem uma limitao: variveis referenciadas dentro da string

de caracteres (X nos exemplos anteriores) no podem ser locais.
Funes de manipulao de variveis

Alm de atribuir, controlar o escopo e macro executar o contedo das variveis,
necessrio manipular seu contedo atravs de funes especficas da linguagem
para cada situao.
As 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()
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.
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

uma string, adicionando espaos direita.
STRZERO()
Sintaxe
STRZERO(nValor, nTamanho)
Descrio

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()
ALLTRIM()
Sintaxe
ALLTRIM(cString)
Retorna uma string sem os espaos direita e esquerda,
referente ao contedo informado como parmetro.
Descrio
A funo ALLTRIM() implementa as aes das funes RTRIM

(right trim) e LTRIM (left trim).
ASC()
Sintaxe
ASC(cCaractere)
Descrio
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.
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.
STUFF()
Sintaxe
Descrio
STUFF(cString, nPosInicial, nExcluir, cAdicao)

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()
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
Descrio
NOROUND(nValor, nCasas)
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.
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, a qual no foi

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

definida na funo em execuo.
ESTRUTURAS BSICAS DE PROGRAMAO

O ADVPL suporta vrias estruturas de controle que permitem mudar a seqncia de
fluxo de execuo de um programa. Estas estruturas permitem a execuo de
cdigo baseado em condies 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 prprocessador #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.
Estruturas de repetio so designadas para executar uma seo de cdigo mais de
uma vez. Por exemplo, imaginando-se a existncia de uma funo para imprimir
um relatrio, pode-se desejar imprimi-lo quatro vezes. Claro, pode-se
simplesmente chamar a funo de impresso quatro vezes em seqncia, mas isto
se tornaria pouco profissional e no resolveria o problema se o nmero de
relatrios fosse varivel.
Em ADVPL existem dois comandos para a repetio de sees de cdigo, que so os
comandos FOR...NEXT e o comando WHILE...ENDDO.
O Comando FOR...NEXT
A estrutura de controle FOR...NEXT, ou simplesmente o loop FOR, repete uma
seo de cdigo em um nmero determinado de vezes.
Sintaxe
FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento]

Comandos...
[EXIT]
[LOOP]
NEXT
Parmetros
Varivel
nValorInicial
TO nValorFinal
STEP
nIncremento
Comandos
EXIT
LOOP
Especifica uma varivel ou um elemento de uma matriz para

atuar como um contador. A varivel ou o elemento da matriz
no precisa ter sido declarado antes da execuo do
comando FOR...NEXT. Se a varivel no existir, ser criada
como uma varivel privada.
nValorInicial o valor inicial para o contador; nValorFinal o
valor final para o contador. Pode-se utilizar valores
numricos literais, variveis ou expresses, contanto que o
resultado seja do tipo de dado numrico.
nIncremento a 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. Pode-se utilizar valores
numricos literais, variveis ou expresses, contanto que o
resultado seja do tipo de dado numrico.
Especifica um ou mais instrues de comando ADVPL que
sero executadas.
Transfere o controle de dentro do comando FOR...NEXT
para o comando imediatamente seguinte ao NEXT, ou seja,
finaliza a repetio da seo de comandos imediatamente.
Pode-se colocar o comando EXIT em qualquer lugar entre o
FOR e o NEXT.
Retorna o controle diretamente para a clusula FOR sem
executar o restante dos comandos entre o LOOP e o NEXT. O
contador incrementado ou decrementado normalmente,
como se o NEXT tivesse sido alcanado. Pode-se colocar o
comando LOOP em qualquer lugar entre o FOR e o NEXT.
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
Este exemplo imprime a soma dos 100 primeiros nmeros pares. A soma obtida
atravs da repetio do clculo, utilizando a prpria varivel de contador. Como a
clusula STEP est sendo utilizada, a varivel nCnt ser sempre incrementada em
2. E como o contador comea com 0, seu valor sempre ser um nmero par.
O Comando WHILE...ENDDO
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
Comandos
EXIT
LOOP
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.
Especifica um ou mais instrues de comando ADVPL, que sero
executadas enquanto lExpressao for avaliado como verdadeiro
(.T.).
Transfere o controle de dentro do comando WHILE...ENDDO para
o comando imediatamente seguinte ao ENDDO, ou seja, finaliza a
repetio da seo de comandos imediatamente. Pode-se colocar
o comando EXIT em qualquer lugar entre o WHILE e o ENDO.
Retorna o controle diretamente para a clusula WHILE sem
executar o restante dos comandos entre o LOOP e o ENDDO. A
expresso em lExpressao reavaliada para a deciso se os
comandos continuaro sendo executados.
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.
Influenciando o fluxo de repetio

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. Desta forma, todas as operaes, que seriam
realizadas dentro da estrutura de repetio aps o LOOP, sero desconsideradas.
Exemplo:
aItens:= ListaProdutos() // funo ilustrativa que retorna um array com dados dos
produtos.
nQuantidade := Len(aItens)
nItens := 0
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
// Caso o produto esteja bloqueado, o mesmo no ser impresso, pois a

execuo da // instruo LOOP far o fluxo do programa retornar a partir
da anlise da condio.
EXIT
A instruo EXIT utilizada para forar o trmino de uma estrutura de repetio.
Desta forma, todas as operaes que seriam realizadas dentro da estrutura de
repetio aps o EXIT sero desconsideradas, e o programa 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.
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 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
Comandos
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 so ignorados. Neste
caso, a execuo do programa continua com o primeiro
comando seguinte ao ENDIF.
Conjunto de comandos ADVPL que sero executados
dependendo da avaliao da expresso lgica em lExpressao.
Pode-se 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
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
lExpressaoX
Comandos
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.
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.).
Caso a lExpressaoX avaliada resulte em falso (.F.) ser avaliada
a prxima expresso lExpressaoX, vinculada ao prximo
comando ELSEIF, ou caso o mesmo no exista ser executada
a ao definida para o comando ELSE.
Conjunto de comandos ADVPL que sero executados,
dependendo da avaliao da expresso lgica em lExpressao.
O campo IF...ELSE...ELSEIF...ENDIF possui a mesma estruturao

de deciso que pode ser obtida com a utilizao do comando DO
CASE...ENDCASE.
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
Parmetros
CASE
lExpressao1
Comandos...
OTHERWISE
Comandos
Quando a primeira expresso CASE, resultante em verdadeiro

(.T.), for encontrada, o conjunto de comandos seguinte
executado. A execuo do conjunto de comandos continua at
que a prxima clusula CASE, OTHERWISE ou ENDCASE seja
encontrada. Ao terminar de executar esse conjunto de
comandos, a execuo continua com o primeiro comando
seguinte ao ENDCASE.
Se uma expresso CASE resultar em falso (.F.), o conjunto de
comandos seguinte a esta at a prxima clusula ignorado.
Apenas um conjunto de comandos executado. Estes so os
primeiros comandos cuja expresso CASE avaliada como
verdadeiro (.T.). Aps a execuo, qualquer outra expresso
CASE posterior ignorada (mesmo que sua avaliao resultasse
em verdadeiro).
Se todas as expresses CASE forem avaliadas como falso (.F.), a
clusula OTHERWISE determina se um conjunto adicional de
comandos deve ser executado. Se essa clusula for 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.
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
Exerccio
Desenvolver um programa que implemente o algoritmo de descascar batatas,
utilizando a estrutura de repetio While, demonstrando quantas batatas foram
descascadas:
Exerccio
utilizando a estrutura de repetio FOR, demonstrando quantas batatas foram
descascadas:
Exerccio
utilizando a estrutura de repetio FOR, demonstrando quantas batatas faltam para
serem descascadas:
Exerccios
Desenvolver um programa que implemente o algoritmo do Jogo da Forca:
Exerccios
Desenvolver um programa que implemente o algoritmo do Jogo da Velha:
ARRAYS E BLOCOS DE CDIGO

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.}
Este array contem uma string, um nmero e um valor lgico. Em outras linguagens
como C ou Pascal, este "pacote" de informaes pode ser chamado como um
"struct" (estrutura em C, por exemplo) ou um "record" (registro em Pascal, por
exemplo). Como se fosse na verdade um registro de um banco de dados, um
pacote de informaes construdo com diversos campos. Cada campo tendo um
pedao diferente de dado.
Suponha que no exemplo anterior, o array aFunct1 contenha informaes sobre o
nome de uma pessoa, sua idade e sua situao matrimonial. Os seguintes #defines
podem ser criados para indicar cada posio dos valores dentro de um array:
#define FUNCT_NOME 1
#define FUNCT_IDADE 2
#define FUNCT_CASADO 3
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, pode-se 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
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.
Inicializando arrays
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
02
03
04
05
06
07
08
Local
Local
Local
Local
nCnt
aX[10]
aY := Array(10)
aZ := {0,0,0,0,0,0,0,0,0,0}
For nCnt := 1 To 10
aX[nCnt] := nCnt * nCnt
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.
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.
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
02
03
04
05
06
07
08
Local
Local
Local
Local
nCnt
aX[0]
aY := Array(0)
aZ := {}
For nCnt := 1 To nSize

AADD(aX, nCnt*nCnt)
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).
Funes de manipulao de arrays

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()
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, 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.
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
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.
Cpia de arrays
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.
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 represente 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.
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 deseja-se obter um
array com a mesma estrutura e informaes que compe outro array j existente.
Listas de Expresses e Blocos de Cdigo

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

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))
Pode-se escrever:
// 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 desta regra de
precedncia possvel atribuir um valor a mais de uma varivel ao mesmo tempo:
Z := Y := X := 0
Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:
Z := ( Y := (X := 0) )
Apesar de o ADVPL avaliar expresses da esquerda para a direita, no caso de

atribuies isso acontece ao contrrio, da direita para a esquerda. O valor
atribudo varivel X, que retorna o valor para ser atribudo varivel Y e assim
sucessivamente. Pode-se dizer que o zero foi "propagado atravs da expresso".
Segunda premissa
Em ADVPL pode-se juntar diversas linhas de cdigo em uma nica linha fsica de
comando. Por exemplo, o cdigo:
If lAchou
Alert("Cliente encontrado!")
Endif
pode ser escrito assim:
If lAchou ; Alert("Cliente encontrado!") ;
Endif
O ponto-e-vrgula indica ao ADVPL que a nova linha de cdigo est para comear.
Pode-se ento colocar diversas linhas lgicas de cdigo na mesma linha fsica,
atravs do editor de texto utilizado.
Apesar da possibilidade de se escrever todo o programa assim, em uma nica linha
fsica, isto no recomendado, pois dificulta a legibilidade do programa e,
conseqentemente, a manuteno.
Lista de expresses
A evoluo dos blocos de cdigo comea com as listas de expresses. Nos exemplos
a seguir, o smbolo ==> indicar o retorno da expresso aps sua avaliao (seja
para atribuir em uma varivel, exibir para o usurio ou imprimir em um relatrio),
que ser impressa em um relatrio, por exemplo.
Duas Linhas de Cdigo
@00,00 PSAY x := 10
@00,00 PSAY y := 20
==>
==>
10
20
Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento
impresso.
Duas linhas de cdigo em uma , utilizando ponto-e-vrgula
Este o mesmo cdigo que o anterior, apenas escrito em uma nica linha:
Alert( cValToChar( x := 10 ; y := 20 ) )
==>
10
Apesar desse cdigo se encontrar em uma nica linha fsica, existem duas linhas
lgicas separadas pelo ponto e vrgula. Ou seja, esse cdigo equivalente a:
Alert( cValToChar( x := 10 ) )
y := 20
Portanto, apenas o valor 10 da varivel x ser passado para as funes cvaltochar e
alert para ser exibido. E o valor 20 apenas ser atribudo varivel y.
Convertendo para uma lista de expresses

Quando parnteses so colocados ao redor do cdigo e o sinal de ponto-e-vrgula
substitudo por uma vrgula apenas, o cdigo torna-se uma lista de expresses:
Alert( cValToChar ( ( X := 10 , Y := 20 ) ) )
==>
20
O valor de retorno resultante de uma lista de expresses o valor resultante da

ltima expresso ou elemento da lista. Funciona como se fosse um pequeno
programa ou funo, que retorna o resultado de sua ltima avaliao (efetuadas da
esquerda para a direita).
Neste exemplo, a expresso x := 10 avaliada, e ento a expresso y := 20, cujo
valor resultante passado para a funo alert e cvaltochar, e ento exibido. Depois
que essa linha de cdigo executada, o valor de X igual a 10 e o de y igual a 20,
e 20 ser exibido.
Teoricamente, no h limitao para o nmero de expresses que podem ser
combinadas em uma lista de expresses. Na prtica, o nmero mximo por volta
de 500 smbolos.
Debugar listas de expresses difcil 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 pode-se 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, pode-se fazer com
que vrias coisas aconteam onde normalmente apenas uma aconteceria.
X := 10 ; Y := 20
If X > Y
Alert("X")
Z := 1
Else
Alert("Y")
Z := -1
Endif
Aqui temos o mesmo conceito, escrito utilizando listas de expresses na funo
IIF():
X := 10 ; Y := 20
iif( X > Y , ;
( Alert("X"), Z := 1 ) , ;
( Alert("Y"), Z := -1 ) )
De listas de expresses para blocos de cdigo
Considere a seguinte lista de expresses:
Alert( cValToChar( ( x := 10, y := 20 ) ) ) ==> 20
O ADVPL permite criar funes, que so pequenos pedaos de cdigo, como se

fosse um pequeno programa, utilizados para diminuir partes de tarefas mais
complexas e reaproveitar cdigo em mais de um lugar num programa. Para
maiores detalhes consulte a documentao sobre a criao de funes em ADVPL.
Porm, a idia neste momento que a lista de expresses, utilizada na linha
anterior, pode ser criada como uma funo:
Function Lista()
X := 10
Y := 20
Return Y
E a linha de exemplo, com a lista de expresses, pode ser substituda, tendo o
mesmo resultado, por:
Alert( cValToChar( Lista() ) ) ==> 20
Como mencionado anteriormente, uma lista de expresses como um pequeno
programa ou funo. Com poucas mudanas, uma lista de expresses pode se
tornar um bloco de cdigo:
( X := 10 , Y := 20 ) // Lista de Expresses
{|| X := 10 , Y := 20 } // Bloco de Cdigo
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}
Blocos de Cdigo
Diferentemente de uma matriz, no se pode acessar elementos de um bloco de
cdigo, atravs de um ndice numrico. Porm blocos de cdigo so semelhantes a
uma lista de expresses, e a uma pequena funo.
Ou seja, podem ser executados. Para a execuo, ou avaliao de um bloco de
cdigo, deve-se utilizar a funo Eval():
nRes := Eval(B) ==> 20
Essa funo recebe como 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 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 eventos de objetos so acionados ou para
modificar o comportamento padro de algumas funes.
Por exemplo, considere a matriz abaixo:
A := {"GARY HALL", "FRED SMITH", "TIM JONES"}
Esta matriz pode ser ordenada pelo primeiro nome, utilizando-se a chamada da
funo asort(A), resultado na matriz com os elementos ordenados dessa forma:
{"FRED SMITH", "GARY HALL", "TIM JONES"}
A ordem padro para a funo asort ascendente. Este comportamento pode ser
modificado atravs da informao de um bloco de cdigo que ordena a matriz de
forma descendente:
B := { |X, Y| X > Y }
aSort(A, B)
O bloco de cdigo (de acordo com a documentao da funo asort) deve ser
escrito para aceitar dois parmetros que so os dois elementos da matriz para
comparao. Note que o 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,
pode-se utilizar o seguinte bloco de cdigo:
B := { |X, Y| SUBSTR(X, At(" ",X)+1) > SUBSTR(Y, At(" ",Y)+1) }
Note que este bloco de cdigo procura e compara as partes dos caracteres,
imediatamente seguinte a um espao em branco. Depois de utilizar esse bloco de
cdigo para a funo asort, a matriz conter:
{"GARY HALL", "TIM JONES", "FRED SMITH"}
Finalmente, para ordenar um sub-elemento (coluna) de uma matriz por exemplo,

pode-se utilizar o seguinte bloco de cdigo:
B := { |X, Y| X[1] > Y[1] }
Funes para manipulao de blocos de cdigo

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 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.
FUNES
A maior parte das rotinas que queremos escrever em programas so compostas de
um conjunto de comandos, rotinas estas que 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 pode-se passar parmetros, os
quais contm os dados e 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, o que permite executar uma funo escrevendo:
Calcula(parA, parB, parC) // Chamada da funo em uma rotina
E a funo deve estar escrita:
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.
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 que:
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 DEM (Documentao
Eletrnica
Microsiga)
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 do 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.
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 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
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.
1. Funes do tipo Function() somente podem ser executadas
atravs dos mdulos do ERP.
2. Somente podero ser compiladas funes do tipo Function()
se o MP-IDE possuir uma autorizao especial fornecida pela
Microsiga.
3. 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.
1. 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 resultados indesejados durante a
execuo da aplicao.
2. 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 DEM o tpico sobre
preparao de ambiente e a documentao sobre a funo
RpcSetEnv().
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 duplicao de funes na aplicao.
Neste contexto as Static Functions() so utilizadas para:
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 as necessidades
especficas de uma funo principal / aplicao.
3. Proteger 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 cdigo 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 a Inteligncia Protheus da Microsiga.
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()
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
Avaliando a funo CalcFator() descrita anteriormente, podemos verificar que a

mesma recebe como parmetro para sua execuo a varivel nFator.
Com base nesta funo, podemos descrever duas forma de passagem de
parmetros por contedo:
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. Neste 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.
Duas caractersticas da linguagem ADVPL tornam necessria uma
ateno especial na chamada de funes:
1. 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.
2. Os parmetros, de uma funo, so atribudos de acordo
com a ordem em que tais parmetros so definidos na
chamada desta ordem. No realizada nenhum tipo de
consistncia, em relao aos tipos dos contedos, e
obrigatoriedade de parmetros nesta ao.
Os parmetros de uma funo so caracterizados como variveis

de escopo LOCAL para efeito de execuo.
Desta forma os mesmos no devem ser definidos novamente como
LOCAL, na rea de definio e inicializao de variveis, pois caso
isto ocorra haver a perda dos valores recebidos pela redefinio
das variveis na funo.
Caso seja necessrio garantir um contedo padro para um
determinado parmetro, dever ser utilizado o identificador
DEFAULT, conforme detalhado no tpico Tratamento de valores
padres para parmetros de funes.
Exemplo 02 Passagem de variveis como contedos

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. Neste caso foi informada a varivel
nFatorUser, a qual ser definida pelo usurio atravs 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 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 :=
nFatorUser.
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.
Desta 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.
Passagem de parmetros por referncia
A passagem de parmetros por referncia uma tcnica muito comum nas
linguagens de programao, a qual permite que variveis de escopo LOCAL tenham
seu contedo manipulado por funes especficas, mantendo o controle destas
variveis restrito funo que as definiu e as funes desejadas pela aplicao.
A passagem de parmetros por referncia utiliza o conceito de que uma varivel

uma rea de memria e, portanto, passar um parmetro por referncia nada mais
do que, ao invs de passar o contedo para a funo chamada, passar qual a rea
de memria utilizada pela varivel passada.
Passagem de parmetros tradicional Duas variveis x Duas reas de memria
Passagem de parmetros por referncia Duas variveis x uma nica rea de memria
Desta forma, a funo chamada tem acesso no apenas ao contedo, mas

varivel em si, pois a rea de memria a varivel, e qualquer alterao nesta ser
visvel funo chamadora quando tiver o retorno desta funo.
Tratamento de contedos padres para parmetros de funes

O tratamento de contedos padres para parmetros de funes muito utilizado
nas funes padres da aplicao ERP, de forma a garantir a correta execuo
destas funes por qualquer funo chamadora, evitando situaes de ocorrncias
de erros pela falta da definio de parmetros necessrios 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.
Desta forma o uso do identificador DEFAULT permite ao desenvolvedor garantir
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
Return nResultado
No exemplo descrito, caso o parmetro nFator no seja informado na funo

chamadora, o mesmo ter seu contedo definido como 1.
Se este 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).
Caso o parmetro que possui a opo DEFAULT, descrita no fonte,
seja informado, a linha de DEFAULT no ser executada, mantendo
desta forma o contedo passado pela funo chamadora.
DIRETIVAS DE COMPILAO
O compilador ADVPL possui uma funcionalidade denominada pr-processador, o
qual nada mais do que 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 pr-processador, 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.
Lembre-se
Diretiva: #INCLUDE
A diretiva #INCLUDE indica em que arquivo de extenso CH (padro ADVPL)
esto os UDCs a serem utilizados pelo pr-processador.
A aplicao ERP possui diversos includes, os quais devem ser utilizados segundo a
aplicao que ser desenvolvida, o que permitir a utilizao de recursos adicionais
definidos para a linguagem, implementados pela rea de Tecnologia da Microsiga.
Os includes mais utilizados nas aplicaes ADVPL, desenvolvidas para o ERP so:
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.
O include PROTHEUS.CH ainda contm a referncia a outros includes

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

desenvolvidos para a aplicao ERP Protheus, obrigatria
e necessria ao correto funcionamento das aplicaes.
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):
o
TCQUERY
TBICONN.CH: Permite a utilizao da sintaxe tradicional na definio de

conexes, com a aplicao Server do ambiente ERP, atravs das seguintes
sintaxes:
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
CREATE XMLSTRING
CREATE XMLFILE
SAVE XMLSTRING
o
o
o
o
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.
O diretrio de includes deve ser especificado no Ambiente de

desenvolvimento do ERP Protheus (MP-IDE), para cada
configurao de compilao disponvel.
Caso o diretrio de includes no esteja 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 variveis diversas,
utilizadas pela aplicao em diferentes idiomas. Desta forma
normal verificar que um fonte possui um arquivo.CH com o
mesmo nome, o que caracteriza este tipo de include.
Diretiva: #DEFINE
A diretiva #DEFINE permite que o desenvolvedor crie novos termos para serem
utilizadas no cdigo fonte. Este termo tem o efeito de uma varivel de escopo
PUBLIC, mas que afeta somente o fonte na qual o #DEFINE est definido, com a
caracterstica de no permitir a alterao de seu contedo.
Desta forma, um termo definido atravs da diretiva #DEFINE pode ser considerado
como uma constante.
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: Portugus, Ingls e Espanhol.
Por esta razo a aplicao ERP possui trs repositrios distintos
para cada uma das bases de dados homologadas pela Microsiga,
pois cada compilao utiliza uma diretiva referente ao seu idioma.
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.
Atravs destas diretivas, podem ser verificados parmetros do Sistema, tais como o
idioma com o qual est parametrizado e a base de dados utilizada para armazenar
e gerenciar as informaes do ERP.
Desta forma, ao invs de escrever dois ou mais cdigos fontes que realizam a
mesma funo, mas utilizando recursos distintos para cada base de dados ou
exibindo mensagem para cada um dos idiomas tratados pela aplicao, o
desenvolvedor pode preparar seu cdigo fonte para ser avaliado pelo prprocessador, o qual ir gerar um cdigo compilado de acordo com a anlise dos
parmetros de ambiente.
Estas diretivas de compilao
verificaes de ambiente:
esto
normalmente
associadas
as
seguintes
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
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 IFELSE-ELSEIF-ENDIF.
A aplicao ERP disponibiliza a varivel de escopo PUBLIC __LANGUAGE, a qual contm uma string que identifica o
idioma em uso pelo Sistema, cujo os 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
Os bancos de dados padro AS400 no permitem a execuo

de queries no formato SQLANSI, atravs da ferramenta
TOPCONNECT (DbAcess).
Desta 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 estes
tradicional.
bancos
deve
ser
utilizada
sintaxe
ADVPL
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.
Esta diretiva permite que o desenvolvedor defina para o compilador como uma
expresso dever 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 > ] ;
=> ;
[ <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.
Exerccio
Desenvolver um programa que permita ao usurio pesquisar um cliente,
informando seu CNPJ e caso o mesmo exista na base, exibir suas principais
informaes.
Exerccio
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
Utilizando a funo AVISO(), desenvolver um programa que permita ao usurio
selecionar a opo de busca de CNPJ por cliente ou fornecedor, e caso encontre
exiba seus dados principais.
Exerccio
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.
Exerccio
Utilizando a funo FORMBATCH(), desenvolver uma rotina que verifique se para
cada item de um nota fiscal de entrada existe o respectivo cabealho, e caso seja
encontrado algum item inconsistente, comunique esta ocorrncia ao usurio que
est realizando o processamento.
Exerccio
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.
MDULO 03: DESENVOLVENDO PEQUENAS CUSTOMIZAES
ADVPL E O ERP MICROSIGA PROTHEUS

O ADVPL (Advanced Protheus Language) uma linguagem de programao
desenvolvida pela Microsiga e que contm todas as instrues e funes
necessrias ao desenvolvimento de um sistema, independente de sua
complexidade.
O PROTHEUS, por outro lado, uma plataforma tecnolgica que engloba um
Servidor de Aplicao, um Dicionrio de Dados e as Interfaces para conexo com o
usurio. o Protheus que executa o cdigo ADVPL e o devido acesso base da
dados.
O Protheus composto pelo ERP (que engloba, alm das funcionalidades
descritas nos captulos anteriores, mais de trinta verticais aplicadas a reas
especficas de negcios) e pelo Configurador (programa que permite
customizar o Sistema s necessidades do usurio de forma fcil).
O Ambiente Protheus
O 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: travs

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.
Figura: Manuteno no repositrio de objetos

Aps compilar o programa, o resultado um objeto, o qual 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 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.
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).
Neste 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.
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.
Organizao e configurao inicial do ambiente Protheus

O Protheus ocupa uma pasta que tem a seguinte estrutura:
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.
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.
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.
Propriedades dos atalhos
Destino:
c:\protheus\bin\appserver\totvsappse
rver.exe
- 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, pode-se execut-lo com a opo de
Linha de Comando.
Destino:
c:\protheus\bin\smartclient\totvssmartclien
te.exe 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).
-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 mltiplas instncias (Cpias) do TOTVS Smart Client, na mesma mquina,
o que por Default no permitido.
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, linguagem do pas em que
est sendo utilizado e as mscaras de edio e formatao.
[ENVIRONMENT]
SOURCEPATHC:\TOTVS11\APO
ROOTPATH=
C:\TOTVS11\PROTHEUS_DATA
STARTPATH=\ PROTHEUS\
RPODB=TOP
RPOLANGUAGE=PORTUGUESE
RPOVERSION=110
LOCALFILES=ADS
TRACE=0
LOCALDBEXTENSION=.DBF
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 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=SIGACFG
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.
O Configurador do Protheus
Funcionalidades Abordadas
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 ndices 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 PROTHEUS.
Estruturas bsicas da aplicao ERP Protheus

Arquivos de configurao do sistema
Arquivo
SIGAMAT
SIGAPSS
SIX
SX1
SX2
SX3
SX4
SX5
SX6
SX7
SX8
SX9
SXA
SXB
SXD
SXE
SXF
SXG
SXK
SXO
SXP
SXQ
SXR
Descrio
Cadastro de empresas e filiais do sistema
Arquivo de usurios, grupos e senhas do sistema
ndices dos arquivos
Perguntas e respostas
Mapeamento de tabelas
Dicionrio de Dados
Agenda do Schedule de processos
Tabelas
Parmetros
Gatilhos de Interface
Fora de uso
Relacionamentos entre tabelas
Pastas cadastrais apontadas no SX3
Consulta por meio da tecla F3 (Consulta Padro)
Controle do Schedule de processos
Seqncia de documentos (+1)
Seqncia de documentos (Prximo)
Tamanho padro para campos apontado pelo SX3
Resposta de Perguntas (SX1) por usurios
Controle de LOGs por tabela
Histrico de Logs cadastrados no SXO
Cadastro de filtros inteligentes da mbrowse (contm as
informaes necessrias para a criao do filtro).
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).
SXS
SXT
Cadastro de relacionamento entre as entidades

SXOffice (tabelas) e as consultas TOII.
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.
A tabela a seguir demonstra alguns dos mdulos que compe a aplicao ERP
PROTHEUS atualmente:
Ambiente
SIGAATF
SIGACOM
SIGACON
SIGAEST
SIGAFAT
SIGAFIN
SIGAFIS
SIGAPCP
SIGAGPE
SIGAFAS
SIGAVEI
SIGALOJ
SIGATMK
A
SIGAOFI
SIGAPON
SIGAEIC
SIGATCF
SIGAMNT
SIGARSP
SIGAQIE
SIGAQMT
Identificao
ATIVO FIXO
COMPRAS
CONTABILIDADE
ESTOQUE E CUSTOS
FATURAMENTO
FINANCEIRO
LIVROS FISCAIS
PLANEJAMENTO E CONTROLE DA PRODUO
GESTO DE PESSOAL
FATURAMENTO DE SERVIOS
VECULOS
CONTROLE DE LOJAS/AUTOMAO COMERCIAL
CALL CENTER
OFICINAS
PONTO ELETRNICO
EASY IMPORT CONTROL
TERMINAL
MANUTENO DE ATIVOS
RECRUTAMENTO E SELEO DE PESSOAL
INSPEO DE ENTRADA QUALIDADE
METODOLOGIA QUALIDADE
O nome de cada tabela no Protheus constitudo de seis dgitos, os quais so

utilizados para formar a seguinte representao:
F
Onde:
F
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 seqencial 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.
O ltimo dgito fixo em 0.
A tabela a seguir demonstra algumas das principais famlias de tabelas utilizadas

pela aplicao ERP Protheus:
Famlia
S
S
S
S
S
S
A
C
C
C
C
D
E
G
J
N
P
Q
R
T
I
N
R
X
Z
T
V
W
-
Descrio
Tabelas pertencentes ao sistema bsico, tambm chamado
Classic.
Cadastros de entidades compartilhadas entre os Ambientes
(Clientes, Fornecedores, Bancos entre outros).
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 do 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)
Cadastros e movimentos do Ambiente Ativo Fixo
Cadastros e movimentos do Ambiente Gesto de Pessoal
Tabelas de configurao do Sistema
Tabelas livres para utilizao e projetos especficos em clientes.
Gesto de Projetos
Contabilidade Gerencial
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
Famlia
W
Z
-
Descrio
Workflow
Tabelas livres para utilizao e projetos especficos em clientes
em adio famlia SZ.
ndices
Cada tabela do Sistema possui seus ndices definidos no arquivo de configurao
SIX, o qual pode ser atualizado atravs do mdulo Configurador.
Os arquivos de ndices das tabelas de Sistema sero criados de acordo com o banco
de dados utilizado (ISAM ou conexo via TOPCONNECT).
Para bancos de dados ISAM, 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
seqencial em funo do nome da tabela original.
As especificaes das chaves de ndices de cada um das tabelas est disponvel no
arquivo de sistema SIX, e a chave nica da tabela utilizada para banco de dados
est descrita na tabela SX2.
Menus
Cada mdulo da aplicao ERP possui um menu padro com todas as
funcionalidades disponveis para o Ambiente, menu este definido atravs de sintaxe
XML (arquivos .XNU).
Os menus possuem uma estrutura padro que permite ao usurio localizar e
identificar facilmente cada uma das funcionalidades oferecidas pelo Ambiente.
Acessando o mdulo Configurador

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:
Figura: Validao de acesso
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
Funcionalidades 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.
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.
Dicionrio de Dados da aplicao ERP

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
Adio de tabelas ao Dicionrio de Dados

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.
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:
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.
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 refere-se 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.
Adio de campos s tabelas do Dicionrio de Dados

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

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:
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.
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:
Figura: Dados para parametrizao de um novo campo no Sistema

orientaes a 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.
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:
relatrios.
Define como o campo aparece nas telas e nos
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.
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.
Guia: Mdulos
Relaciona todos os mdulos em que o campo ser utilizado.
Adio de ndices para as tabelas do Dicionrio de Dados

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

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:
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 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

orientaes a 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 (
).
Figura: Atualizao dos dados do Sistema

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 (
campos de descrio.
). Esta facilidade preenche, automaticamente, os
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).
Adio de gatilhos para os campos das tabelas do Sistema

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
2. Aps a seleo da opo Gatilhos sero exibidos os itens j cadastradas no
arquivo de sistema SX7.
Figura: Conjunto de gatilhos j cadastros no SX7

3. Aps a visualizao dos gatilhos j cadastrados no SX7 da empresa

novo gatilho no Sistema:
) para realizar o cadastro de um
Figura: Dados para o cadastro de um novo gatilho no Sistema

orientaes a 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 Seqncia.
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.
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.
Criao de Tabelas Genricas

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

Figura: Conjunto de Tabelas j cadastras no SX5

3. Aps a visualizao das tabelas j cadastrados no SX5 da empresa

nova tabela no Sistema:
) para realizar o cadastro de uma
Figura: Dados para o cadastro de uma nova tabela no Sistema

orientaes a seguir, e ao trmino confirme o cadastramento da nova tabela
do sistema com o boto Confirmar (
).
Criao de Parmetros
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
Figura: Conjunto de Parmetros j cadastras no SX6

3. Aps a visualizao dos Parmetros j cadastrados no SX6 da empresa

nova tabela no sistema:
) para realizar o cadastro de uma
Figura: Dados para o cadastro de um novo parmetro no Sistema

orientaes a seguir, e ao trmino confirme o cadastramento do novo
Parmetro do Sistema com o boto Confirmar (
).
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
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:
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 seqncia 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:
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.
DESENVOLVIMENTO DE PEQUENAS CUSTOMIZAES

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.
Funes de manipulao de dados para
DBACCESS
Ambientes TOPCONNECT
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.
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 seqencial, tendo como base o nome da tabela ao 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 destas operaes.
Deve ser considerada a possibilidade de utilizao de ndices temporrios para
processos especficos, os quais sero criados em tempo de execuo da rotina. Este
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 seqencial e ascendente que funciona como o endereo base daquela
informao.
Este ID, mas conhecido como RECNO ou RECNUMBER gerado no momento de
incluso do registro na tabela e somente ser alterado caso a estrutura dos dados
desta tabela sofra alguma manuteno. Dentre as manutenes que uma tabela de
dados ISAM pode sofrer, 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. Esta situao tambm torna necessria a
recriao de todos os ndices vinculados quela tabela.
Isto ocorre nas bases de dados ISAM devido ao conceito de excluso lgica de
registros que as mesmas possuem. J os bancos de dados padro SQL nativamente
utilizam apenas o conceito de excluso fsica de registros, o que para outras
aplicaes seria transparente, mas no o caso do ERP Protheus.
Para manter a compatibilidade das aplicaes desenvolvidas para bases de dados
padro ISAM, a rea de Tecnologia e Banco de Dados da Microsiga implementou,
nos bancos de dados padro SQL, o conceito de excluso lgica de registros
existente nas bases de dados ISAM, 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.
Estes campos permitem que a aplicao ERP gerencie as informaes do banco de
dados, da mesma forma que as informaes em bases de dados ISAM.
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 seqencial ao banco de dados.
O campo D_E_L_E_T_ tratado internamente pela aplicao ERP como um flag
ou marca de excluso. Desta forma, os registros que estiverem com este campo
marcado sero considerados como excludos logicamente. A execuo do comando
PACK, em uma tabela de um banco de dados padro SQL, visa excluir fisicamente
os registros com o campo D_E_L_E_T_ marcado, mas no causar o efeito de
renumerao de RECNO (no caso R_E_C_N_O_) que ocorre na tabela de bases de
dados ISAM.
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()
Sintaxe
DBRLOCK(xIdentificador)
Funo de base de dados, que efetua o lock (travamento) do
registro identificado pelo parmetro xIdentificador. Este
parmetro pode ser o Recno() para tabelas em formado ISAM,
ou a chave primria para bancos de dados relacionais.
Descrio
Se o parmetro xIdentificador no for especificado, todos os
locks da rea de trabalho sero liberados, e o registro
posicionado ser travado e adicionado em uma lista de registros
bloqueados.
DBCLOSEAREA()
Sintaxe
DbCloseArea()
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
DbDelete()
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.
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()
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 subseqentes que fizerem referncia a uma
rea de trabalho para utilizao, a menos que a rea desejada
seja informada explicitamente.
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()
Sintaxe
DBUNLOCKALL()
Descrio
Libera o travamento de todos os registros de todas as reas de

trabalho disponveis na thread (conexo) ativa.
DBUSEAREA()
Sintaxe
Descrio
DbUseArea(lNovo,
cDriver,
cArquivo,
cAlias,
lComparilhado,; lSoLeitura)
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()
Sintaxe
Descrio
Select(cArea)
Determina o nmero de referncia de um determinado alias em
um ambiente de trabalho. Caso o alias especificado no esteja
em uso no Ambiente, ser retornado o valor 0 (zero).
SOFTLOCK()
Sintaxe
SoftLock(cAlias)
Permite a reserva do registro posicionado na rea de trabalho
ativa de forma que outras operaes, com exceo da atual, no
possam atualizar este registro. Difere da funo RecLock() pois
no gera uma obrigao de atualizao, e pode ser sucedido por
ele.
Descrio
Na aplicao ERP Protheus, o SoftLock() utilizado nos browses,

antes da confirmao da operao de alterao e excluso, pois
neste momento a mesma ainda no foi efetivada, mas outras
conexes no podem acessar aquele registro pois o mesmo est
em manuteno, o que implementa da integridade da
informao.
UNLOCK()
Sintaxe
UNLOCK()
Descrio
Libera o travamento do registro posicionado na rea de trabalho

ativa e
confirma as atualizaes efetuadas naquele registro.
Diferenciao entre variveis e 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
Esta linha de comando identifica que o valor atribudo varivel cRes deve ser o
valor da varivel de memria chamada NOME.
cRes := FIELD->NOME
Neste caso, o valor atribudo varivel cRes ser o valor do campo NOME,
existente no arquivo ou tabela aberto na rea atual.
O identificador FIELD pode ser substitudo pelo apelido de um arquivo ou tabela
abertos, para evitar a necessidade de selecionar a rea antes de acessar o
contedo de terminado 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 desta
tabela.
cRes := SA1->NOME // SA1 Cadastro de Clientes
Para maiores detalhes sobre abertura de arquivos com atribuio

de apelidos, consulte a documentao sobre acesso a banco de
dados ou a documentao da funo dbUseArea().
Os alias das tabelas da aplicao ERP so padronizados em trs
letras, que correspondem s iniciais da tabela. As configuraes de
cada ALIAS, utilizado pelo Sistema, podem ser visualizadas atravs
do mdulo Configurador -> Bases de Dados -> Dicionrios ->
Bases de Dados.
Controle de numerao seqencial

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 seqencial
pela aplicao ERP, no devem ser considerados como chave
primria das tabelas aos quais 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 seqncia 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 ser disponvel mesmo que
naquele momento nmeros maiores j tenham sido oferecidos e utilizados.
Com isso,
seqenciais
pedidos de
intervalos e
mesmo que tenhamos vrios processos solicitando numeraes

para uma mesma tabela, como por exemplo incluses simultneas de
vendas, teremos para cada pedido um nmero exclusivos e sem o
numeraes no utilizadas.
Funes de controle de semforos e numerao seqencial

A linguagem ADVPL permite a utilizao das seguintes funes para o controle das
numeraes seqenciais utilizadas nas tabelas da aplicao ERP:
GETSXENUM()
CONFIRMSXE()
ROLLBACKSXE()
GETSXENUM()
Sintaxe
GETSXENUM(cAlias, cCampo, cAliasSXE, nOrdem)
Descrio
Obtm o nmero seqncia 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
GETSXENUM().
alocado
atravs
do
ltimo
comando
ROLLBACKSXE()
Sintaxe
ROLLBACKSXE()
Descrio
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(),

retornando a numerao disponvel para outras conexes.
CUSTOMIZAES PARA A APLICAO ERP

Neste 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
Configurador, possvel implementar as seguintes customizaes:
no
mdulo
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
Customizao de campos Dicionrio de Dados

Validaes de campos e perguntas
As funes de validao tm como caracterstica fundamental um retorno do tipo
lgico, ou seja, um contedo .T. Verdadeiro ou .F. Falso.
Com base nesta premissa, a utilizao de validaes, no Dicionrio de Dados (SX3)
ou nas Perguntas de Processos e Relatrios (SX1), dever focar sempre na
utilizao de funes ou expresses que resultem em um retorno lgico.
Atravs do mdulo Configurador possvel alterar as propriedades de um campo ou
de uma pergunta, de forma a incluir 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. Caso exista ser exibido um help de Sistema com
um aviso informando da ocorrncia.
Descrio
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.
EXISTCPO()
Sintaxe
ExistCpo(cAlias, cConteudo, nIndice)

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.
Descrio
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.
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 parmetro da funo.
Normalmente utilizada em campos com a opo de combo, pois
caso contrrio seria utilizada a funo ExistCpo().
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.
Pictures de formao disponveis

Com base na documentao disponvel no DEM Documentao Eletrnica
Microsiga, a linguagem ADVPL e a aplicao ERP Protheus admitem as seguintes
pictures:
Dicionrio de Dados (SX3) e GET
Funes
Contedo
A
C
E
R
S<n>
X
Z
(
)
!
Funcionalidade
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.
Permite 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 maisculo.
Templates
Contedo Funcionalidade
X
Permite qualquer caractere.
9
Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal
para numricos.
#
Permite dgitos, sinais e espaos em branco para qualquer tipo de
!
*
.
,
dado.
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: @!
SAY e PSAY
Funes
Contedo
C
E
R
X
Z
(
!
Funcionalidade
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
Contedo
X
9
#
!
*
.
,
Funcionalidade
Exibe dgitos para qualquer tipo de dado.
Exibe asterisco no lugar de espaos em branco e inicias em nmeros.
Exibe a posio do 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
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 digitao de informaes.
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
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 destes Ambientes.
Exemplos:
Contas a pagar -> SE2 (compartilhado)
Movimentos contbeis -> CT2 (exclusivo)
Pedidos de compras -> SC7 (compartilhado)
Itens da nota fiscal de entrada -> SD1 (exclusivo)
Na definio da regra de retorno deve ser considerado o tipo do campo que

ser atualizado, pois este campo que determina qual tipo do retorno ser
considerado vlido para o gatilho.
Customizao de parmetros Configurador

Os parmetros de sistema utilizados pela aplicao ERP e definidos atravs do
mdulo configurador possuem as seguintes caractersticas fundamentais:
Tipo do parmetro: de forma similar a uma varivel, um parmetro ter um
tipo de contedo pr-definido em seu cadastro.
Esta informao utilizada pelas funes da aplicao ERP, na interpretao
do contedo do parmetro e retorno desta 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. Estes parmetros macro executveis tem como nica caracterstica em
comum 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 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, no qual
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.
Funes para manipulao de parmetros

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. Caso o
parmetro no exista, ser exibido um help do sistema
informando a ocorrncia.
GETNEWPAR()
Sintaxe
Descrio
GETNEWPAR(cParametro, cPadrao, cFilial)

parmetro no exista, ser exibido um help do Sistema
Difere do SuperGetMV() pois considera que o parmetro pode
no existir na verso atual do Sistema, e por conseqncia no
ser exibida a mensagem de help.
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)

parmetro no exista, ser exibido um help do Sistema
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.
Cuidados na utilizao de um parmetro

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
conseqncia a utilizao de funes para definir o retorno que ser obtido com a
consulta deste parmetro, expressamente proibido o uso de funes em
parmetros para manipular informaes da base de dados do Sistema.
Caso haja a 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 desta restrio simples:
As rotinas da aplicao ERP no protegem a consulta de contedos de
parmetros, quanto a gravaes realizadas dentro ou fora de uma
transao.
Desta forma, qualquer alterao na base realizada por uma rotina,
configurada em um parmetro, pode ocasionar a perda da integridade das
informaes do Sistema.
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 especificas 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 o mesmo foi pr-definido, sob pena de causar a perda da
integridade das informaes da base de dados ou provocar eventos de erro
durante a execuo da rotina padro.
Um ponto de entrada deve ser transparente para o processo padro, de
forma que todas as tabelas, acessadas pelo ponto de entrada e que sejam
utilizadas pela rotina padro, devero ter sua situao imediatamente
anterior execuo do ponto 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.
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 a atender as necessidades bsicas de acesso e
manuteno das informaes do Sistema.
Neste tpico sero abordadas as sintaxes convencionais para definio das
interfaces visuais da linguagem ADVPL e as interfaces de manuteno, disponveis
no Ambiente ERP Protheus.
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 a utilizao da sintaxe CLIPPER na definio dos
componentes visuais.
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, segue abaixo 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
Ambas as 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
Descrio
@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura

UNIDADE OF oObjetoRef ACTION AO
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
Descrio
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM

nLinIni,nColIni TO nLiFim,nColFim OF oObjetoRef UNIDADE
Define o componente MSDIALOG(), o qual utilizado como base
para os demais componentes da interface visual, pois um
componente MSDIALOG() uma janela da aplicao.
MSGET()
Sintaxe
Descrio
@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura

UNIDADE OF oObjetoRef F3 cF3 VALID VALID WHEN WHEN
PICTURE cPicture
Define o componente visual MSGET, o qual utilizado para
captura de informaes digitveis na tela da interface.
SAY()
Sintaxe
Descrio
@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura

UNIDADE OF oObjetoRef
Define o componente visual SAY, o qual utilizado para exibio
de textos em uma tela de interface.
SBUTTON()
Sintaxe
Descrio
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION

AO STATUS OF oObjetoRet
Define o componente visual SButton, o qual permite a incluso de
botes de operao na tela da interface, os quais sero
visualizados dependendo da interface do sistema ERP, utilizada
somente com um texto simples para sua identificao, ou com
uma imagem (BitMap) pr-definido.
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
cTexto SIZE 55, 07 OF oDlg PIXEL
@ 010,050 MSGET cCGC

99.999.999/9999-99";
VALID !Vazio()
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:
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 os modelos utilizam como premissa que a estrutura da tabela a ser utilizada
esteja definida no dicionrio de dados do sistema (SX3).
AxCadastro()
O AxCadastro() uma funcionalidade de cadastro simples, com poucas opes de
customizao, a qual composta de:
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.
Exemplo:
#include "protheus.ch"
User Function XCadSA2()
Local
Local
Local
Local
cAlias := "SA2"
cTitulo := "Cadastro de Fornecedores"
cVldExc := ".T."
cVldAlt := ".T."
dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)
Return
MBrowse()
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 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,
nLin2, nCol2
Coordenadas dos cantos aonde o browse ser exibido. Para

seguir o padro da AXCADASTRO() use 6,1,22,75 .
Alias padro do sistema para utilizao, o qual deve estar
definido no dicionrio de dados SX3.
cAlias
Variveis private adicionais

Array contendo as funes que sero executadas pela
Mbrowse.
Este array pode ser parametrizados com as funes bsicas
da AxCadastro conforme abaixo:
aRotina
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})
cCadastro
Ttulo do browse que ser exibido.
Exemplo:
User Function MBrwSA2()
Local cAlias := "SA2"
Private cCadastro := "Cadastro de Fornecedores"
Private aRotina
:= {}
AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
,"AxInclui",0,3})
,"AxAltera",0,4})
,"AxDeleta",0,5})
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
1. Utilizando a parametrizao exemplificada, o efeito obtido

com o uso da Mbrowse() ser o mesmo obtido com o uso da
AxCadastro().
2. 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.
Desta forma, para manter o padro da aplicao ERP a
ordem a ser seguida na definio do aRotina ;
1
2
3
4
5
6
Pesquisar
Visualizar
Incluir
Alterar
Excluir
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.
Exemplo: Funo BInclui() substituindo a funo AxInclui()

User Function MBrwSA2()
Local cAlias := "SA2"
Private cCadastro := "Cadastro de Fornecedores"
Private aRotina
:= {}
AADD(aRotina,{"Pesquisar" ,"AxPesqui"
,0,1})
AADD(aRotina,{"Visualizar" ,"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
AxFunctions()
Conforme 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.
Estas 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
Descrio
AxAltera(cAlias, nReg, nOpc, aAcho, cFunc, aCpos,

cTudoOk, lF3,; cTransact, aButtons, aParam, aAuto,
lVirtual, lMaximized)
Funo de alterao padro das informaes de um registro, no
formato Enchoice, conforme demonstrado no tpico sobre a
interface AxCadastro().
AXDELETA()
Sintaxe
Descrio
AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons,

aParam,; aAuto, lMaximized)
Funo de excluso padro das informaes de um registro, no
AXINCLUI()
Sintaxe
Descrio
AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk,

lF3,; cTransact, aButtons, aParam, aAuto, lVirtual,
lMaximized)
Funo de incluso padro das informaes de um registro, no
AXPESQUI()
Sintaxe
AXPESQUI()
Descrio
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.
AXVISUAL()
Sintaxe
Descrio
AXVISUAL(cAlias,
nReg,
nOpc,
aAcho,
nColMens,
cMensagem, cFunc,; aButtons, lMaximized )
Funo de visualizao padro das informaes de um registro, no
Exerccio
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 nesta tabela relacionada.
Exerccio
Desenvolver uma validao para um campo caractere existente na base, para que
seja avaliado se aquele cdigo j existe cadastrado, e caso positivo exiba uma
mensagem de aviso alertando desta ocorrncia.
Exerccio
Desenvolver um gatilho que retorne uma descrio complementar para um campo
vinculado ao campo cdigo utilizado nos exerccios anteriores.
Exerccio
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
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.
Exercico
Implementar uma validao adicional no cadastro de clientes, atravs do ponto de
entrada adequado, de forma que o campo CNPJ (A1_CGC) seja obrigatrio para
todos os tipos de cliente, exceto os definidos como Exterior.
APNDICES
BOAS PRTICAS DE PROGRAMAO
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:
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 funes de manipulao de dados que comecem por db, a

capitulao s ser efetuada aps o db:
dbSeek()
dbSelectArea()
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...
UTILIZAO DA NOTAO HNGARA

A notao hngara consiste em adicionar os prefixos aos nomes de variveis, de
modo a facilmente se identificar seu tipo. Isto facilita na 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 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 desta notao para nomear variveis.
Notao
a
b
c
d
l
n
o
x
Tipo de dado
Array
Bloco de cdigo
Caracter
Data
Lgico
Numrico
Objeto
Indefinido
Exemplo
aValores
bSeek
cNome
dDataBase
lContinua
nValor
oMainWindow
xConteudo
PALAVRAS RESERVADAS
AADD
ABS
ASC
AT
BOF
BREAK
ENDIF
LTRIM
SPACE
CTOD
FILE
PCOUNT
TRANSFORM
DOW
IIF
CATCH
DTOS
ELSE
ELSEIF
EMPTY
ENDCASE
ENDDO
LOWER
SETPOS
COL
FIELDNAME
PCOL
TIME
DEVPOS
IF
RECNO
THROW
INKEY
INT
LASTREC
LEN
LOCK
LOG
SELECT
CMONTH
FCOUNT
MONTH
SUBSTR
DELETED
FUNCTION
RECCOUNT
UPPER
REPLICATE
RLOCK
ROUND
ROW
RTRIM
SECONDS
CHR
EXP
MIN
STR
DAY
FOUND
PROW
TYPE
TRY
VAL
VALTYPE
WHILE
WORD
YEAR
CDOW
EOF
MAX
SQRT
DATE
FLOCK
PROCEDURE
TRIM
DTOC
AS
Palavras reservadas no podem ser utilizadas para variveis,

procedimentos ou funes;
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.
Identificadores de escopo PRIVATE ou PUBLIC utilizados em
aplicaes especficas, desenvolvidas por ou para clientes,
devem ter sua identificao iniciada por um caractere _.
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()
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
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)+
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
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
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)
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)
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
LOCAL nLargGet
PRIVATE oDlg
:=
:= 0
:= 0
Default cTitulo
Default cSay
Default nTamanho
:= "Tela para informar texto"

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

nTamanho
:= 1
ENDIF
cTexto
nLargGet
nColf
:= Space(nTamanho)
:= Round(nTamanho * 2.5,0)
:= 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
@ 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
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()
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
xItem
Array pr-existente no qual ser adicionado o item definido em

xItem.
Item que ser adicionado ao array.
Exemplo:
aDados := {} // Define que a varivel aDados um array, sem especificar suas
dimenses.
aItem := {} // Define que a varivel aItem um array, sem especificar suas
dimenses.
AADD(aItem, cVariavel1) // Adiciona um elemento no array aItem de acordo com o
cVariavel1
cVariavel2

cVariavel3
// Neste ponto o array a Item
com:
// aItem[1] -> corresponde ao
possui 03 elementos os quais podem ser acessados

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:
// 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.
Por ser uma estrutura de memria, um array no pode ser

simplesmente copiado para outro array, atravs 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, aonde:
// 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.
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.
Exemplo:
// Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo
ADEL()
ASIZE(aItens,Len(aItens-1)).
// Neste ponto o array aItens possui 02 elementos, ambos com contedos vlidos.
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
nInicio
nItens
bOrdem
Array pr-existente que ter seu contedo ordenado atravs de

um critrio estabelecido.
Posio inicial do array para incio da ordenao. Caso no seja
informado, o array ser ordenado a partir de seu primeiro
elemento.
Quantos itens, a partir da posio inicial devero ser ordenados.
Caso no seja informado, sero ordenados todos os elementos do
array.
Bloco de cdigo que permite a definio do critrio de ordenao
do array. Caso bOrdem no seja informado, ser utilizado o
critrio ascendente.
Um bloco de cdigo basicamente uma funo escrita em linha.

Desta forma, sua estrutura deve suportar todos os requisitos de
uma funo, os quais so por meio da anlise e interpretao de
parmetros recebidos, executar um processamento e fornecer um
retorno.
Com base nesse requisito, pode-se definir um bloco de cdigo com
a estrutura abaixo:
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)
// Neste ponto, os elementos do array aAlunos sero {Andria, Mauren,
Soraia}
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, pode-se substituir x por cNomeAtu.
// A varivel y receber o contedo do prximo item a ser avaliado, e usando a
mesma
// analogia de x, pode-se substituir y por cNomeProx. Desta forma o bloco de
cdigo
// bOrdem pode ser re-escrito como:
bOrdem := {|cNomeAtu, cNomeProx| cNomeAtu > cNomeProx}

aSort(aAlunos,,bOrdem)
// Neste 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
bSeek
Array pr-existente no qual desejasse identificar a posio que

contm a informao pesquisada.
Bloco de cdigo que configura os parmetros da busca a ser
realizada.
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}
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 desta 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)
// Neste ponto o array aAlunos ter o seguinte contedo:
// {Edson, Robson, nulo, Renato, Tatiana}
Similar ao efeito da funo ADEL(), o elemento inserido no array

pela funo AINS() ter um contedo nulo, sendo necessrio tratlo aps a realizao deste comando.
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
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.
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_TABELA<=mv_par02})
},,{||X5_FILIAL==xFilial("SX5")
.And.
Exemplo 02
dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()
While !Eof() .And. X5_TABELA == cTabela
AADD(aTabela,{X5_CHAVE, Capital(X5_DESCRI)})
dbSkip()
End
Exemplo 02 (continuao):
O mesmo pode ser re-escrito com o uso da funo DBEVAL():
dbEval({||
X5_TABELA==cTabela})
aAdd(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{||
Na utilizao da funo DBEVAL(), deve ser informado apenas um

dos dois parmetros: bFor ou bWhile.
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.
Elemento final do array, at o qual sero avaliados os blocos de
cdigo.
nFim
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)))})
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.
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"
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
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)))
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))
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).
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_
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
IF nPessoas < nLugares
MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando)
ENDIF
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
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
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
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.
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
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.
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 subseqentes que fizerem referncia a uma rea de trabalho para
utilizao, a menos que a rea desejada seja informada explicitamente.
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.
DBSETORDER()
Define qual ndice ser utilizada pela rea de trabalho ativa, ou seja, pela rea
previamente selecionada atravs do comando DbSelectArea(). As ordens
disponveis no Ambiente Protheus so aquelas definidas no SINDEX /SIX, ou as
ordens disponibilizadas por meio de ndices temporrios.
Sintaxe: DbSetOrder(nOrdem)
Parmetros
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
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
lSoftSeek
lLast
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.
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.
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
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 +;
Filial:
+ A1_FILIAL + CRLF +;
Cdigo: + A1_COD
+ CRLF +;
Loja:
+ A1_LOJA
+ CRLF +;
Nome:
+ A1_NOME + CRLF, Consulta por cliente)
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
Exemplo 02 Retrocedendo registros

DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGoBotton() // Posiciona o cursor no final da rea de trabalho ativa.
While !BOF() // Enquanto o cursor da rea de trabalho ativa no indicar incio de
arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip(-1)
End
DBSETFILTER()
Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de
um bloco de cdigo ou atravs de uma expresso simples.
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.
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.
DBSTRUCT()
Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A
estrutura ser um array bidimensional conforme abaixo:
ID*
Nome campo
Tipo campo
Tamanho
Decimais
*ndice do array
Sintaxe: DbStruct()
Parmetros
Nenhum
Exemplo:
cCampos :=
DbSelectArea(SA1)
aStructSA1 := DbStruct()
FOR nX := 1 to Len(aStructSA1)
cCampos += aStructSA1[nX][1] + /
NEXT nX
ALERT(cCampos)
RECLOCK()
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
ENDIF
A linguagem ADVPL possui variaes da funo RecLock(), as quais

so:
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
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
ENDIF
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.
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
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:
lComparilhado,;
lSoLeitura)
DbUseArea(lNovo,
cDriver,
cArquivo,
cAlias,
Parmetros
lNovo
cDriver
cArquivo
cAlias
Parmetro opcional que permite, caso o cAlias especificado j

esteja em uso, ser fechado antes da abertura do arquivo da
base de dados.
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.
Algumas chaves vlidas: DBFCDX, CTREECDX,
DBFCDXAX, TOPCONN.
Nome do arquivo de base de dados que ser aberto com o
alias especificado.
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:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
Controle de numerao seqencial

GETSXENUM()
Obtm o nmero seqncia 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
cCampo
cAliasSXE
nOrdem
Alias de referncia da tabela para a qual ser efetuado o controle

da numerao seqencial.
Nome do campo no qual est implementado o controle da
numerao.
Parmetro opcional, quando o nome do alias nos arquivos de
controle de numerao no o nome convencional do alias para o
sistema ERP.
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
lVerifica
Verifica se o nmero confirmado no foi alterado, e se por

conseqncia 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. Caso
exista ser exibido um help de sistema com um aviso informando da ocorrncia.
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.
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.
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.
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. Caso o parmetro no exista, ser exibido um help do
sistema informando a ocorrncia.
Sintaxe: GETMV(cParametro)
Parmetros
cParametro
Nome do parmetro do sistema no SX6, sem a especificao da

filial de sistema.
GETNEWPAR()
Difere do SuperGetMV() pois considera que o parmetro pode no existir na verso
atual do sistema, e por conseqncia no ser exibida a mensagem de help.
Sintaxe: GETNEWPAR(cParametro, cPadrao, cFilial)

Parmetros
cParametro

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.
PUTMV()
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.
Sintaxe: PUTMV(cParametro, cConteudo)

Parmetros
cParametro

filial de sistema.
cConteudo
Contedo que ser atribudo ao parmetro no SX6.
SUPERGETMV()
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

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.
cFilial
Define para qual filial ser efetuada a consulta do parmetro.

Padro filial corrente da conexo.
Componentes da interface visual

MSDIALOG()
Define o componente MSDIALOG(), o qual utilizado como base para os demais
componentes da interface visual, pois um componente MSDIALOG() uma janela
da aplicao.
Sintaxe:
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
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

oObjetoRef F3 cF3 VALID VALID WHEN WHEN PICTURE cPicture
UNIDADE
OF
Parmetros
nLinha, nColuna
VARIAVEL
Posio do objeto MsGet em funo da janela em que ele

ser definido.
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
cPicture
Condio para manipulao do campo, a qual pode ser

diretamente .T. ou .F., ou uma varivel ou uma chamada de
funo.
String contendo a definio da Picture de digitao do
campo.
Exemplo:
@ 010,050 MSGET cCGC
99.999.999/9999-99";
VALID !Vazio()
SIZE 55, 11 OF oDlg PIXEL PICTURE "@R
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
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, o qual permite a incluso de botes de
operao na tela da interface, os quais sero visualizados dependendo da interface
do sistema ERP utilizada somente com um texto simples para sua identificao, ou
com uma imagem (BitMap) pr-definido.
Sintaxe: SBUTTON()
DEFINE SBUTTON FROM

oObjetoRet
nLinha, nColuna TYPE
N ACTION AO STATUS OF
Parmetros
nLinha, nColuna
TYPE N
AO
Posio do objeto sButton em funo da janela em que ele

ser definido.
Nmero que indica o tipo do boto (imagem) pr-definida
que ser utilizada.
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.
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
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,
cMensagem, cFunc,; aButtons, lMaximized )
nOpc,
aAcho,
nColMens,
Parmetros
cAlias
nReg
nOpc
aAcho
Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser

editada.
Record number (recno) do registro posicionado no alias
ativo.
Nmero da linha do aRotina que definir o tipo de edio
(Incluso, Alterao, Excluso, Visualizao).
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
aButtons
lMaximized
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:
aArray[n][1] -> Imagem do boto
aArray[n][2] -> bloco de cdigo contendo a ao do boto
aArray[n][3] -> ttulo do boto
Indica se a janela dever ser ou no maximizada.
AXINCLUI()
Funo de incluso padro das informaes de um registro, no formato Enchoice,
conforme demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk,

lF3,; cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
cAlias
nReg
nOpc
aAcho
cFunc

editada.
ativo.
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".
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.
cTudoOk
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:
(Func1(), Func2(), ...,FuncX(), .T. )
lF3
cTransact
aButtons
aParam
aAuto
Indica se a enchoice est sendo criada em uma consulta F3

para utilizar variveis de memria.
Funo que ser executada dentro da transao da
AxFunction().
Funes para execuo em pontos pr-definidos da
AxFunction(), conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da
exibio da interface.
aParam[2] := Bloco de cdigo para processamento na
validao da confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da
transao da AxFunction().
aParam[4] := Bloco de cdigo que ser executado fora da
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

aAuto[n][3] := Validao que ser utilizada em substituio
as validaes do SX3.
Indica se a Enchoice() chamada pela AxFunction() utilizar
variveis de memria ou os campos da tabela na edio
lVirtual
lMaximized
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().
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
cTransact
aCpos
aButtons
aParam

editada.
ativo.
Funo que ser executada dentro da transao da
AxFunction().
Vetor com nome dos campos que podero ser editados.
Funes para execuo em pontos pr-definidos da
AxFunction(), conforme abaixo:
aParam[1] := Bloco de cdigo que ser processado antes da
exibio da interface.
aParam[2] := Bloco de cdigo para processamento na
validao da confirmao.
aParam[3] := Bloco de cdigo que ser executado dentro da
aParam[4] := Bloco de cdigo que ser executado fora da
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
aAuto[n][3] := Validao que ser utilizada em substituio
as validaes do SX3.
lMaximized
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).
FORMBACTH()
Sintaxe: FORMBATCH(cTitulo,
nLargura )
Parmetros
cTitulo
aTexto
aBotoes
aTexto,
aBotoes,
bValid,
nAltura,
Ttulo da janela.
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:
{nTipo,lEnable,{|| Ao() }}
bValid
(opcional) Bloco de validao do janela.
nAltura
(opcional) Altura em pixels da janela.
nLargura
(opcional) Largura em pixels da janela.
MSGFUNCTIONS()
Sintaxe:
Sintaxe:
Sintaxe:
Sintaxe:
MSGALERT(cTexto, cTitulo)
MSGINFO(cTexto, cTitulo)
MSGSTOP(cTexto, cTitulo)
MSGYESNO(cTexto, cTitulo)
Parmetros
cTexto
Texto a ser exibido como mensagem.
cTitulo
Ttulo da janela de mensagem.
MSGALERT
MSGINFO
MSGSTOP
MSGYESNO
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
Array contendo: {cAlias, nOrdem, nRecno}, normalmente

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

User Function XATF001()
LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.
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 )
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
DEM Documentao Eletrnica Microsiga
Microsiga Software S.A.
Materiais diversos de colaboradores Microsiga
Colaboradores Microsiga

Programação ADVPL

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Programação ADVPL

Încărcat de

Drepturi de autor:

Formate disponibile

Programao ADVPL I

Todos os direitos autorais reservados pela TOTVS S.A.

-2Introduo programao e ADVPL Bsico

ARRAYS E BLOCOS DE CDIGO................................................................................ 68

Funes de acesso e manipulao de dados .......................................................... 139

STRZERO() ..................................................................................................................... 173

DBGOBOTTON() ............................................................................................................ 194

-7Introduo programao e ADVPL Bsico

Fundamentos e tcnicas de programao;

b) Habilidades e tcnicas a serem aprendidas

Resoluo de algoritmos atravs de sintaxes orientadas a linguagem

c) Atitudes a serem desenvolvidas

Adquirir conhecimentos atravs da anlise das funcionalidades

-8Introduo programao e ADVPL Bsico

MDULO 01: INTRODUO PROGRAMAO

Lgica de programao a tcnica de encadear pensamentos para atingir

Seqncia Lgica so passos executados at atingir um objetivo ou soluo de um

-9Introduo programao e ADVPL Bsico

Em informtica, porm, instruo a informao que indica a um computador uma

Instrues so um conjunto de regras ou normas definidas para a realizao ou

Chupar uma bala

Somar dois nmeros quaisquer

Utilizar um telefone pblico - carto

Retirar o telefone do gancho.

4. Tirar lmpada queimada.

Jogar o jogo da velha contra o algoritmo

Algoritmo: Calcular a mdia de notas

3. Somar todas as notas: 45

- 14 Introduo programao e ADVPL Bsico

Usar telefone pblico carto.

- 15 Introduo programao e ADVPL Bsico

Indica um ponto no qual dever ser efetuada

Indica um documento utilizado pelo

Cada smbolo ir conter uma descrio pertinente forma com o

- 16 Introduo programao e ADVPL Bsico

Representao de algoritmos atravs de diagramas de bloco

Algoritmo 01: Fritar um ovo

- 17 Introduo programao e ADVPL Bsico

Algoritmo 02: Calcular a mdia de notas

- 18 Introduo programao e ADVPL Bsico

Estruturas de deciso e repetio

- 19 Introduo programao e ADVPL Bsico

Representao 01: IF...ELSE com aes para ambas as situaes

- 20 Introduo programao e ADVPL Bsico

Apesar das linguagens de programao possurem variaes para a

A linguagem ADVPL possui uma variao para a estrutura IF...ELSE,

- 21 Introduo programao e ADVPL Bsico

Apesar das linguagens de programao possurem variaes para a

- 22 Introduo programao e ADVPL Bsico

Existem diversas variaes para a estrutura WHILE...END, na qual h a

- 23 Introduo programao e ADVPL Bsico

A linguagem ADVPL aceita a sintaxe DO WHILE...ENDDO, que em

- 24 Introduo programao e ADVPL Bsico

- 25 Introduo programao e ADVPL Bsico

A estrutura FOR...TO...NEXT, dependendo da linguagem de

Usar telefone pblico carto.

- 26 Introduo programao e ADVPL Bsico

MDULO 02: A LINGUAGEM ADVPL

- 27 Introduo programao e ADVPL Bsico

Programao por Processos

Atravs de uma biblioteca de funes disponvel no Protheus (uma API de

executada atravs de requisies HTTP. O Protheus permite a compilao de arquivos