MODULO 1

A LINGUAGEM ADVPL
Aula 1 A linguagem ADVPL
A linguagem ADVPL teve seu incio em 1994, sendo na verdade uma
evoluo das linguagens de padro xBase (Clipper, Visual Objects e FiveWin)
utilizadas pela Microsiga Software S.A. A linguagem ADVPL foi criada aps a
criao da tecnologia Protheus, pois era necessrio ter uma linguagem que
suportasse o padro xBase do ERP Siga Advanced.
O ADVPL (Advanced Protheus Language) uma extenso do padro xBase
de comandos e funes, operadores, estruturas de controle e fluxo e
palavras reservadas, conta tambm com funes e comandos
disponibilizados pela Microsiga. A linguagem tambm est adaptada para
aplicaes web e orientada a objetos e eventos, permitindo assim ao
programados desenvolver aplicaes visuais e crias suas prprias classes de
objetos.
Aps compilados, os arquivos de cdigo se tornam APOs (Advanced
Protheus Objects). Os APOs so unidades de inteligncia bsicas que so
mantidas em um repositrio e carregados dinamicamente pelo Protheus
Server para sua execuo. No existe uma unio fsica do cdigo compilado
a mdulos determinados ou aplicaes, sendo assim, qualquer cdigo fonte
pode ser executado por todos os pontos do ERP Protheus.
O compilador e interpretador da linguagem o prprio Protheus Server, seu
ambiente de desenvolvimento o TDS (TOTVS Developer Studio), nele
podemos criar, compilar e depurar nosso cdigo.
Programas compilados pela linguagem ADVPL podem conter comandos ou
funes de interface com o usurio, tais programas so divididos em duas
categorias: Programao com interface prpria com o Usurio e
Programao sem interface prpria com o usurio.
Conhecendo as categorias:
Programao de interface prpria com o usurio
Nesta categoria esto os programas desenvolvidos para serem executados
pelo terminal remoto do Protheus (Protheus Remote). O terminal remoto do
Protheus a aplicao que est encarregada da interface e interao com o
usurio, j o processamento do cdigo ADVPL, o acesso ao banco de dados
e o gerenciamento de conexes todo efetuado pelo Protheus Server. O
Terminal remoto do Protheus o principal meio de acesso a execuo de
rotinas escritas em ADVPL no Protheus server, e por isso permitido a
execuo de qualquer tipo de cdigo, tendo ele interface com usurio ou
no. Nesta categoria so considerados apenas os programas que realizem
algum tipo de interface remota.
Nesta categoria pode-se criar rotinas para customizao do sistema ERP
Protheus, desde processos adicionais e relatrios. possvel criarmos com a
linguagem ADVPL toda uma aplicao e at um modulo do zero.
Programao sem interface prpria com o usurio
Nesta categoria so consideradas as rotinas sem interface, essas rotinas
possuem uma utilizao mais especifica, tais rotinas no possuem interface
com usurio, se tentarmos acessar tais rotinas atravs de uma janela
padro ir ocorrer uma exceo em tempo de execuo, essas rotinas so
conhecidas como processos, ou Jobs, e so executadas diretamente no
Protheus Server. Algumas vezes essas rotinas possuem uma interface em
aplicaes externas, tais aplicaes externas podem ser feitas em outras
linguagens, essas linguagens podem acessar o Protheus Server atravs dos
meios disponveis de integrao e conectividade no Protheus. De acordo
com a utilizao e com o meio de conectividade utilizado, essas rotinas
podem ser categorizadas da seguinte forma:

Programao por processos

As rotinas escritas em ADVPL podem ser iniciadas como pequenos
processos individuais (sem interface) no Protheus Server atravs de
duas maneiras. A primeira maneira atravs de outra rotina ADVPL
utilizando as chamadas de funes StartJob() e CallProc(). A segunda
maneira configurar para que elas sejam iniciadas automaticamente
na inicializao do Protheus Server.

Programao de RPC
Atravs de uma biblioteca de funes disponveis no Protheus (API de
comunicao), podemos executar rotinas escritas em ADVPL
diretamente no Protheus Server e atravs de aplicaes externas
escritas em outras linguagens. Isto o que chamado de RPC
(Remote Procedure Call ou Procedimento de Chamada Remota).

O servidor Protheus tambm executa rotinas ADVPL em outros

servidores Protheus atravs de conexo TCP/IP direta, utilizando o
conceito de RPC. Dessa mesma forma as aplicaes externas podem
requisitar a execuo de rotinas escritas em ADVPL atravs de
conexo TCP/IP direta.

Programao Web
O Protheus Server tambm pode ser executado como um servidor
WEB, respondendo a requisies HTTP. No momento dessas
requisies, podem-se executar rotinas escritas em ADVPL como
processos individuais, enviando o resultado como das funes ADVPL
para o cliente HTTP (Ex: Browser para internet). O Protheus permite a
compilao de arquivos HTML desde que eles contenham o cdigo
ADVPL embutido, essa tcnica conhecida como ADVPL ASP ou
ADVPL WEB, utilizada para criar pginas web dinmicas.

Programao Telnet
O Protheus Server permite emular um terminal Telnet que permite a
conexo a computadores remotos, sendo assim podemos executar
rotinas escritas em ADVPL cuja interface ser em um terminal telnet
ou um coletor de dados mvel.

Palavras Chave: LINGUAGEM ADVPL, MCROSIGA, PROTHEUS, ADVPL

ASP
Aula 2 Estrutura de um Programa ADVPL
Programas de computador nada mais so do que grupos de comandos com
o objetivo de executar determinadas tarefas. Esses comandos podem ser
gravados em arquivos de texto e transformados em uma linguagem
executvel por um computador, esse o processo de compilao. O
processo de compilao substitui os comandos de alto nvel (DE
ENTEDIMENTO HUMANO) por linguagem de mquina (LINGUAGUEM
COMPREENDIDA APENAS PELO COMPUTADOR). No caso do ADVPL quem
executa o processo de compilao o Protheus Server e no o computador.
Dentro dos programas, os comandos e funes seguem as regras da sintaxe
utilizada pela linguagem, caso o programador no siga tais regras o
processo de compilao ir resultar em erros. Esses erros podem ser de
compilao ou execuo. Os erros de compilao so aqueles encontrados
na sintaxe e no permitem que o cdigo do programa seja compilado. Os
erros de execuo so aqueles que acontecem depois da compilao, ou
seja, quando o programa j est em execuo.

Linhas de Programa
As linhas existentes dentro do arquivo de cdigo do programa, podem ser
linhas de comando, linhas de comentrio ou linhas mistas.

Linhas de Comando

Linhas de comando possuem os comandos e instrues que sero

executados.
Por Exemplo:

Linhas de comentrio
 Linhas de comentrio possuem um texto qualquer, mas no so
executadas. Servem apenas para documentao e para torna mais
fcil o entendimento do cdigo fonte. Podemos comentar o cdigo de
duas formas diferentes. Atravs de duas barras invertidas // no incio
da linha e atravs do conjunto /* */ que comenta um bloco de cdigo
inteiro.

Exemplos:

Linhas Mistas

O ADVPL tambm permite que existam linhas de comando com

comentrio adicionando (//) no final do comando e seguida
escrevendo o comentrio.

Exemplo:

Tamanho da Linha

Assim como a linha fsica que delimitada pela quantidade de

caracteres que o editor de texto utilizado permite, existe uma linha
lgica que aquela considerada para compilao como uma nica
linha de comando.

A princpio, cada linha digitada no cdigo diferenciada aps sua

quebra, ou seja, a linha lgica, a linha fsica no arquivo. Porm
algumas vezes, por limitao do editor de cdigo ou questes de
esttica, podemos quebrar a linha lgica em mais de uma linha
fsica utilizando o sinal de ponto e vrgula.
 Exemplo:

Utilizando apenas uma linha fsica e uma linha lgica:

Utilizando duas linhas fsicas e apenas uma linha lgica:

Aula 3 Declarao e Atribuio de Variveis

TIPOS DE DADOS

A Linguagem ADVPL no fortemente tipada, isso significa que as variveis

de memria podem receber diferentes tipos de dados durante a execuo.

Tipo de Dado Numrico

A linguagem ADVPL no diferencia valores inteiros de valores com pontos

flutuantes, por isso pode-se criar variveis numricas com qualquer valor
dentro do intervalo permitido. Variveis do tipo numrico podem conter
nmeros com at 18 dgitos incluindo ponto flutuante, intervalo de
2.2250738585072014 E-308 at 1.7976931348623158 E+308

Exemplos de dados numricos:

2
34.43
0.6
0.00342
30240000

Tipo de Dado lgico

Os valores lgicos em ADVPL so identificados atravs dos caracteres .T.

ou .Y. para verdadeiro e .F. ou .N. para falso.

Exemplo de variveis lgicas

lTrue := .T.
lFalse := .F.

Tipo de Dado Caractere

Os dados de caracteres no ADVPL so identificados atravs de blocos de

texto entre aspas duplas () ou aspas simples (). Uma varivel do tipo
caracter pode conter strings de no mximo 1MB, ou seja, a varivel pode
conter at 1048576 caracteres.

Exemplos de dados caracter

Hello World!
Uma frase uma String

Tipo de Dado Data

O ADVPL tem um tipo de dado especifico para datas. Variveis do tipo Data
no podem ser declaradas diretamente, elas precisam do auxilio de funes
especificas como por exemplo a funo CTOD() que converte uma String
para o tipo Data

Exemplo de variveis Data:

cData := CTOD(01/01/2014)

Tipo de Dado Array

O Tipo de dado Array a disposio de outros elementos em linhas em

colunas. A linguagem ADVPL suporta arrays unidimensionais (Vetor) e
multidimensionais (Matrizes). Para se acessar os elementos de um Array
necessrio ndice numrico que no iniciados por 1 e indicam a posio da
linha e coluna.

Exemplo de varivel do tipo Array:

aVogais := {a,e,i,o,u}

DECLARAO DE VARIAVEIS

Variveis so um dos recursos mais importantes de uma linguagem. Elas

so reas de memorias criadas para armazenar informaes utilizadas em
um programa. Por exemplo, quando digitamos uma informao qualquer,
essa informao armazenada em uma varivel para posteriormente ser
utilizado pelo programa.

Quando criamos uma varivel, no nos referenciamos mais ao seu contedo

e sim ao nome dado a varivel. O nome dado a varivel um identificador
nico, em ADVPL somente sero considerados os primeiros 10 caracteres do
nome de uma varivel, ou seja, as variveis devem ter no mximo 10
caracteres.

Exemplos de declarao de variveis

String
cString := Hellho World!

Numerica
nValor := 5
nDecima := 5.76

Obs: Precisamos tomar cuidado com o tamanho das variveis e seus nomes,
pois o ADVPL ir considerar apenas os 10 primeiros caracteres de cada
varivel, veja abaixo um exemplo de inconsistncia de dados devido a mal
declarao de variveis.

Exemplo
Se criarmos duas variveis cujo os 10 primeiros caracteres sejam iguais,
como por exemplo nTotalGeralAnual e nTotalGeralMes, as referncias a estas
variveis vo resultar na mesma.

nTotalGeralAnual := 100
nTotalGeralMes := 300

Aps as atribuies acima, caso quisssemos exibir o valor das duas

variveis ambas iriam exibir 300, por que como o ADVPL trata apenas os 10
primeiros caracteres das variveis, ele vai entender que as duas variveis
so uma s.

Aula 4 Escopo das Variveis

A linguagem ADVPL no possui tipos rgidos de variveis, ou seja, no

necessrio informar qual o tipo da varivel no momento da sua declarao.
O valor das variveis pode mudar durante a execuo do cdigo fonte.

aconselhvel que as variveis sejam declaradas no inicio do seu cdigo

fonte para uma melhor manuteno, mais nada impede que a declarao
possa ser feita em outra parte do cdigo.

Quando declaramos uma varivel em ADVPL devemos utilizar o identificar

de escopo, o identificador de escopo uma palavra reservada que vai
indicar o contexto a qual a varivel pertence. O contexto de varivel pode
ser local (a varivel somente ser utilizada dentro do programa atual),
pblico (a varivel pode ser utilizada em outros programas). Existe tambm
outros contextos que podem ser utilizados.

O CONTEXTO DE VARIAVEIS DENTRO DE UM PROGRAMA

A visibilidade de uma varivel em um programa ADVPL vai de acordo com o

escopo em que ela foi definida. Definimos o escopo de uma varivel no
momento da sua declarao.

Exemplo:
Local nCod := 022
O exemplo acima indica que a varivel nCod de escopo local.
Os identificadores de escopo so:

Local
Static
Private
Public

Variveis de escopo local

As variveis de escopo local pertencem apenas a funo onde foram
declaradas e devem ser explicitamente declaradas com o identificador
LOCAL.
Exemplo

Nesse exemplo declaramos a varivel nCont com escopo LOCAL e a

inicializamos com o valor 10, no decorrer da funo nos deparamos com a
execuo de uma outra funo (FUNCFILHA), dentro desta funo a varivel
nCont no existe pois ela de escopo local, logo ela existe apenas na
funo AULA4.
As variveis de escopo local so criadas automaticamente toda vez que as
funes forem ativas, o tempo de durao da varivel local o mesmo
tempo de execuo da funo no sistema.
Variveis de escopo static
As variveis de escopo static funcionam como uma varivel de escopo local,
porm elas mantm o seu valor atravs da execuo. As variveis de
escopo static devem ser declaradas explicitamente no cdigo com o
identificador STATIC.
O escopo das variveis static depende de onde elas so declaradas, se
declaramos ela dentro de uma funo o seu escopo estar limitado somente
a esta funo, caso a declaremos no corpo do fonte seu escopo ir afetar
todas as funo que estiverem dentro do cdigo fonte.
Exemplo
Quando a FUNCFILHA executada, a varivel lRetorno ainda existe porm
no pode ser acessada. Diferente das variveis Locais e Privates, lRetorno
continua a existir e mantm seu valor atual quando a funo principal
termina. Entretanto ela s poder ser acessada por execues posteriores.
Variveis de escopo private
A declarao de variveis privadas no ADVPL opcional, mas as mesmas
podem ser declaradas explicitamente com o identificador PRIVATE. Uma vez
criada, uma varivel privada continua a existir e mantm seu valor at que
o programa ou funo onde foi criada termine.
Uma vez criada, a varivel privada visvel em todo programa enquanto
no for destruda automaticamente quando a funo que a criou terminar,
ou seja, uma varivel privada visvel dentro da funo de criao e todas
as funes chamadas por esta, a menos que uma funo chamada crie uma
varivel de mesmo nome.
Exemplo

No exemplo a varivel cNome criada com o escopo private e inicializada

com a string Jeronimo, quando a funo FUNCFILHA executada a varivel
cNome ainda existe e pode ser acessada e modificada, sendo assim, a
varivel cNome pode ou no retornar com um novo valor da funo
FUNCFILHA.
Obs: No ambiente Protheus, existe uma conveno adicional que deve ser
respeitada para que variveis em uso pela aplicao no sejam
manipuladas incorretamente. Por esta conveco devemos adicionar o
caracter _ antes do nome das variveis PRIVATE e PUBLIC. Ex: _cNome
Variveis de escopo public
Podemos criar variveis de escopo public dinamicamente no cdigo ADVPL
utilizando o identificador PUBLIC. As variveis desse escopo continuam a
existir e mantm seu valor at o final da conexo(thread). O ADVPL permite
criar variveis de escopo private com o mesmo nome de uma varivel de
escopo public, porm no permitido criar uma varivel de escopo public
com o mesmo nome de uma varivel de escopo private.
Uma vez que a varivel de escopo public criada, ela passa a ser visivel em
todos os programas em que for declarada, caso se declare uma varivel de
escopo private de mesmo nome, a varivel public ir ficar escondida at o
final da execuo da varivel private.
Exemplo

No exemplo a varivel cNome criada com o escopo public e inicializada

com a string Jeronimo, quando a funo FUNCFILHA executada a varivel
cNome ainda existe e pode ser acessada e modificada, sendo assim, a
varivel cNome pode ou no retornar com um novo valor da funo
FUNCFILHA.
Diferentemente dos outros identificadores de escopo, quando uma varivel
PUBLIC declarada sem ser inicializada, ela ir assumir o valor falso (.F.) e
nulo (NIL)
Obs: No ambiente Protheus, existe uma conveno adicional que deve ser
respeitada para que variveis em uso pela aplicao no sejam
manipuladas incorretamente. Por esta conveco devemos adicionar o
caracter _ antes do nome das variveis PRIVATE e PUBLIC. Ex: _cNome
Entendendo a influncia do escopo das variveis
Consideremos a linha de cdigo abaixo:

Se essa linha de cdigo for executada em um programa ADVPL, ocorrer um

erro na execuo com a seguinte nomenclatura variable does not exist:
nPorcento. Esse erro ocorre porque estamos utilizando a varivel nPorcento
numa expresso sem a ter declarado antes. Neste caso devemos declara as
variveis previamente.

No exemplo acima as variveis esto sendo declaradas previamente

utilizando o identificador de escopo LOCAL. Quando a linha de cdigo com a
expresso for executada, no ir mais ocorrer o erro de varivel inexistente.
Porm toda varivel declarada e no inicializada recebe como padro o
valor (NIL). Neste caso teremos um novo erro, pois no podemos fazer a
diviso de 100 por um valor nulo.
Para resolvermos esse problema fazemos da seguinte forma

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.

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