Programação+ADVPL+I - P10Capacitação Interna

Educao Corporativa
Programao ADVPL I
(Capacitao Interna)

Matriz Av. Braz Leme, 1.717 02511-000 So Paulo SP Brasil.
Tel.: 55 (11) 3981-7001 www.microsiga.com.br

- 2 -

Introduo programao e ADVPL Bsico

ESTRUTURA DO TREINAMENTO

OBJETIVOS DO CURSO ................................................................................................................................. 6
MDULO 01: Introduo programao...................................................................................................... 7
1. Lgica de Programao e Algoritmos .................................................................................................. 7
1.1. Lgica de Programao ............................................................................................................... 7
1.2. Desenvolvendo algoritmos .......................................................................................................... 8
1.2.1. Estudando algoritmos .................................................................................................................. 9
1.2.2. Teste de mesa .......................................................................................................................... 11
2. Estruturas de programao ............................................................................................................... 12
2.1. Diagrama de bloco .................................................................................................................... 12
2.2. Estruturas de deciso e repetio ............................................................................................. 15
2.2.1. Estruturas de deciso ................................................................................................................ 15
2.2.2. Estruturas de repetio ............................................................................................................. 18
MDULO 02: A linguagem ADVPL .............................................................................................................. 20
3. Estrutura de um Programa ADVPL ..................................................................................................... 22
3.1. reas de um Programa ADVPL .................................................................................................. 24
4. Declarao e Atribuio de Variveis ................................................................................................ 27
4.1. Tipo de Dados ........................................................................................................................... 27
4.2. Declarao de variveis ............................................................................................................ 28
4.3. Escopo de variveis................................................................................................................... 29
4.4. Entendendo a influncia do escopo das variveis...................................................................... 33
4.5. Operaes com Variveis .......................................................................................................... 34
4.5.1. Atribuio de variveis .............................................................................................................. 34
4.5.2. Operadores da linguagem ADVPL ................................................................................................ 35
4.5.3. Operao de Macro Substituio ................................................................................................. 40
4.5.4. Funes de manipulao de variveis .......................................................................................... 41
5. Estruturas bsicas de programao................................................................................................... 47
5.1. Estruturas de repetio ............................................................................................................. 47
5.1.1. Influenciando o fluxo de repetio .............................................................................................. 50
5.2. Estruturas de deciso ............................................................................................................... 52
6. Arrays e Blocos de Cdigo ................................................................................................................. 56
6.1. Arrays ....................................................................................................................................... 56
6.1.1. Inicializando arrays ................................................................................................................... 58
6.1.2. Funes de manipulao de arrays .............................................................................................. 59
6.1.3. Cpia de arrays ........................................................................................................................ 61
6.2. Listas de Expresses e Blocos de Cdigo................................................................................... 63
6.2.1. Premissas para utilizao de Blocos de Cdigo .............................................................................. 63
6.2.2. Lista de expresses ................................................................................................................... 64
6.2.3. Blocos de Cdigo ...................................................................................................................... 66
6.2.4. Funes para manipulao de blocos de cdigo ............................................................................ 68
7. Funes ............................................................................................................................................. 69
7.1. Tipos e escopos de funes ....................................................................................................... 70
7.2. Passagem de parmetros entre funes ................................................................................... 73
8. Diretivas de compilao .................................................................................................................... 79
MDULO 03: Desenvolvendo pequenas customizaes .............................................................................. 84
9. ADVPL e o ERP Microsiga Protheus .................................................................................................... 84
9.1. O Ambiente Protheus ................................................................................................................ 84
9.2. Organizao e configurao inicial do ambiente Protheus ........................................................ 88

- 3 -


9.3. O Configurador do Protheus ...................................................................................................... 94
9.3.1. Funcionalidades Abordadas ........................................................................................................ 94
9.3.2. Estruturas bsicas da aplicao ERP Protheus ............................................................................... 94
9.3.3. Acessando o mdulo Configurador .............................................................................................. 97
9.4. Funcionalidades do Configurador ............................................................................................ 100
9.4.1. Dicionrio de Dados da aplicao ERP ........................................................................................ 101
9.4.2. Adio de tabelas ao Dicionrio de Dados .................................................................................. 101
9.4.3. Adio de campos as tabelas do Dicionrio de Dados................................................................... 104
9.4.4. Adio de ndices para as tabelas do Dicionrio de Dados ............................................................ 109
9.4.5. Adio de gatilhos para os campos das tabelas do sistema ........................................................... 112
9.4.6. Criao de Tabelas Genricas ................................................................................................... 114
9.4.7. Criao de Parmetros ............................................................................................................ 115
10. TOTVS Development Studio ......................................................................................................... 117
Desenvolvimento de pequenas customizaes .................................................................................... 120
11. Acesso e manipulao de bases de dados em ADVPL .................................................................. 120
11.1. Diferenas e compatibilizaes entre bases de dados ............................................................. 121
11.2. Funes de acesso e manipulao de dados ............................................................................ 122
11.3. Diferenciao entre variveis e nomes de campos .................................................................. 127
11.4. Controle de numerao seqencial ......................................................................................... 128
12. Customizaes para a aplicao ERP ........................................................................................... 129
12.1. Customizao de campos Dicionrio de Dados ..................................................................... 130
12.1.1. Validaes de campos e perguntas........................................................................................ 130
12.1.2. Pictures de formao disponveis .......................................................................................... 132
12.2. Customizao de gatilhos Configurador ............................................................................... 134
12.3. Customizao de parmetros Configurador .......................................................................... 135
12.3.1. Funes para manipulao de parmetros ............................................................................. 135
12.3.2. Cuidados na utilizao de um parmetro ............................................................................... 136
12.4. Pontos de Entrada Conceitos, Premissas e Regras ............................................................... 137
13. Interfaces visuais ....................................................................................................................... 138
13.1. Sintaxe e componentes das interfaces visuais ........................................................................ 138
13.2. Interfaces padres para atualizaes de dados ...................................................................... 141
13.2.1. AxCadastro() ..................................................................................................................... 141
13.2.2. MBrowse() ......................................................................................................................... 142
13.2.3. AxFunctions()..................................................................................................................... 146
APNDICES .............................................................................................................................................. 148
BOAS PRTICAS DE PROGRAMAO ........................................................................................................ 148
14. Utilizao de Identao ............................................................................................................... 148
15. Capitulao de Palavras-Chave ................................................................................................... 149
15.1. Palavras em maisculo ........................................................................................................... 150
16. Utilizao da Notao Hngara ................................................................................................... 150
17. Palavras reservadas .................................................................................................................... 151
LISTAS DE EXERCCIOS ........................................................................................................................... 152
Mdulo 01: Introduo programao ................................................................................................ 152
Mdulo 02: A linguagem ADVPL ........................................................................................................... 153
Mdulo 03: Desenvolvendo pequenas customizaes .......................................................................... 156
REFERNCIAS BIBLIOGRFICAS .............................................................................................................. 158
GUIA DE REFERNCIA RPIDA: Funes e Comandos ADVPL .................................................................. 160
Converso entre tipos de dados........................................................................................................... 160
CTOD() ...................................................................................................................................... 160
CVALTOCHAR() ........................................................................................................................... 160
DTOC() ...................................................................................................................................... 161
DTOS() ...................................................................................................................................... 161

- 4 -


STOD() ...................................................................................................................................... 161
STR() ........................................................................................................................................ 162
STRZERO() ................................................................................................................................ 162
VAL() ........................................................................................................................................ 163
Matemticas ........................................................................................................................................ 164
ACOS() ...................................................................................................................................... 164
CEILING() .................................................................................................................................. 164
COS() ........................................................................................................................................ 164
LOG10() .................................................................................................................................... 165
SIN() ......................................................................................................................................... 165
SQRT() ...................................................................................................................................... 166
TAN() ........................................................................................................................................ 166
Verificao de tipos de variveis ......................................................................................................... 167
TYPE() ....................................................................................................................................... 167
VALTYPE().................................................................................................................................. 167
Manipulao de arrays ......................................................................................................................... 168
ARRAY() .................................................................................................................................... 168
AADD() ...................................................................................................................................... 169
ACLONE() .................................................................................................................................. 170
ADEL() ...................................................................................................................................... 170
ASIZE() ..................................................................................................................................... 171
ASORT() .................................................................................................................................... 171
ASCAN() .................................................................................................................................... 173
AINS() ....................................................................................................................................... 174
Manipulao de blocos de cdigo......................................................................................................... 175
EVAL() ....................................................................................................................................... 175
DBEVAL() ................................................................................................................................... 175
AEVAL() ..................................................................................................................................... 177
Manipulao de strings ........................................................................................................................ 178
ALLTRIM() .................................................................................................................................. 178
ASC() ........................................................................................................................................ 178
AT() .......................................................................................................................................... 179
BITON() ..................................................................................................................................... 180
CHR() ........................................................................................................................................ 180
DESCEND() ................................................................................................................................ 180
GETDTOVAL() ............................................................................................................................. 181
ISALPHA().................................................................................................................................. 182
ISDIGIT() .................................................................................................................................. 182
ISLOWER() ................................................................................................................................ 182
ISUPPER() .................................................................................................................................. 183
LEN() ........................................................................................................................................ 183
LOWER().................................................................................................................................... 184
LTRIM() ..................................................................................................................................... 184
MATHC() .................................................................................................................................... 185
OEMTOANSI() ............................................................................................................................ 185
PADL() / PADR() / PADC() ............................................................................................................ 186
RAT() ........................................................................................................................................ 186
RTRIM() ..................................................................................................................................... 187
SPACE()..................................................................................................................................... 187
STRTOKARR() ............................................................................................................................. 188
STRTRAN() ................................................................................................................................. 188
STUFF() ..................................................................................................................................... 189
SUBSTR() .................................................................................................................................. 189
TRANSFORM() ............................................................................................................................ 190
UPPER() ..................................................................................................................................... 190
Manipulao de data / hora ................................................................................................................. 191
CDOW() ..................................................................................................................................... 191
CMONTH() ................................................................................................................................. 191
DATE() ...................................................................................................................................... 192
DAY() ........................................................................................................................................ 192
DOW() ....................................................................................................................................... 193
DTOC() ...................................................................................................................................... 193
DTOS() ...................................................................................................................................... 194
ELAPTIME() ................................................................................................................................ 194
MONTH() ................................................................................................................................... 195
SECONDS() ................................................................................................................................ 195

- 5 -


TIME() ....................................................................................................................................... 196
YEAR() ...................................................................................................................................... 196
Manipulao de variveis numricas ................................................................................................... 197
ABS() ........................................................................................................................................ 197
INT() ......................................................................................................................................... 197
NOROUND() ............................................................................................................................... 198
ROUND() ................................................................................................................................... 198
Manipulao de arquivos ..................................................................................................................... 199
SELECT() ................................................................................................................................... 199
DBGOTO() ................................................................................................................................. 199
DBGOTOP() ................................................................................................................................ 200
DBGOBOTTON().......................................................................................................................... 200
DBSELECTAREA() ........................................................................................................................ 201
DBSETORDER() .......................................................................................................................... 201
DBSEEK() E MSSEEK()................................................................................................................. 202
DBSKIP() ................................................................................................................................... 203
DBSETFILTER() ........................................................................................................................... 204
DBSTRUCT() .............................................................................................................................. 205
RECLOCK() ................................................................................................................................ 205
MSUNLOCK() .............................................................................................................................. 206
SOFTLOCK() ............................................................................................................................... 207
DBDELETE() ............................................................................................................................... 208
DBUSEAREA() ............................................................................................................................ 208
DBCLOSEAREA() ......................................................................................................................... 209
Controle de numerao seqencial ...................................................................................................... 209
GETSXENUM() ............................................................................................................................ 209
CONFIRMSXE() ........................................................................................................................... 209
ROLLBACKSXE() ......................................................................................................................... 210
Validao ............................................................................................................................................. 210
EXISTCHAV() ............................................................................................................................. 210
EXISTCPO() ............................................................................................................................... 210
NAOVAZIO() .............................................................................................................................. 211
NEGATIVO() ............................................................................................................................... 211
PERTENCE() ............................................................................................................................... 211
POSITIVO() ................................................................................................................................ 211
TEXTO() .................................................................................................................................... 211
VAZIO() ..................................................................................................................................... 212
Parmetros .......................................................................................................................................... 212
GETMV() .................................................................................................................................... 212
GETNEWPAR() ............................................................................................................................ 212
PUTMV() .................................................................................................................................... 213
SUPERGETMV() ........................................................................................................................... 213
Componentes da interface visual ......................................................................................................... 214
MSDIALOG() .............................................................................................................................. 214
MSGET() .................................................................................................................................... 215
SAY() ........................................................................................................................................ 216
BUTTON() .................................................................................................................................. 216
SBUTTON() ................................................................................................................................ 217
Interfaces de cadastro ........................................................................................................................ 218
AXCADASTRO() .......................................................................................................................... 218
MBROWSE() ............................................................................................................................... 218
AXPESQUI() ............................................................................................................................... 218
AXVISUAL() ............................................................................................................................... 219
AXINCLUI() ................................................................................................................................ 219
AXALTERA() ............................................................................................................................... 220
AXDELETA() ............................................................................................................................... 221
Funes visuais para aplicaes .......................................................................................................... 222
ALERT() ..................................................................................................................................... 222
AVISO() ..................................................................................................................................... 222
FORMBACTH() ............................................................................................................................ 223
MSGFUNCTIONS() ....................................................................................................................... 224
Funes ADVPL para aplicaes .......................................................................................................... 225
GETAREA() ................................................................................................................................. 225
RESTAREA() ............................................................................................................................... 225

- 6 -


OBJETIVOS DO CURSO

Objetivos especficos do curso:

Ao final do curso o treinando dever ter desenvolvido os seguintes conceitos, habilidades e
atitudes:

a) Conceitos a serem aprendidos

fundamentos e tcnicas de programao;
princpios bsicos da linguagem ADVPL;
comandos e funes especficas da Microsiga.

b) Habilidades e tcnicas a serem aprendidas

resoluo de algoritmos atravs de sintaxes orientadas a linguagem ADVPL;
anlise de fontes de baixa complexidade da aplicao ERP Protheus;
desenvolvimento de pequenas customizaes para o ERP Protheus.

c) Atitudes a serem desenvolvidas

adquirir conhecimentos atravs da anlise dos funcionalidades disponveis no
ERP Protheus;
embasar a realizao de outros cursos relativos a linguagem ADVPL.

- 7 -


MDULO 01: Introduo programao

1. Lgica de Programao e Algoritmos

No aprendizado de qualquer linguagem de programao essencial desenvolver os conceitos
relacionados a lgica e a tcnica da escrita de um programa.

Com foco nesta necessidade, este tpico ir descrever resumidamente os conceitos envolvidos
no processo de desenvolvimento de um programa atravs dos conceitos relacionados :

E Lgica de programao
E Algoritmos
E Diagramas de blocos

1.1. Lgica de Programao

Lgica

A lgica de programao necessria para pessoas que desejam trabalhar com
desenvolvimento de sistemas e programas, ela permite definir a 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.

- 8 -


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 a execuo de uma
tarefa. Podemos pensar em algoritmo como uma receita, uma seqncia de instrues que do
cabo de uma meta especfica. Estas tarefas no podem ser redundantes nem subjetivas na sua
definio, devem ser claras e precisas.

Como exemplos de algoritmos podemos citar os algoritmos das operaes bsicas (adio,
multiplicao, diviso e subtrao) de nmeros reais decimais. Outros exemplos seriam os
manuais de aparelhos eletrnicos, como um videocassete, que explicam passo-a-passo como,
por exemplo, gravar um evento.

At mesmo as coisas mais simples, podem ser descritas por seqncias lgicas, tais como:

E Chupar uma bala
1. Pegar a bala;
2. Retirar o papel;
3. Chupar a bala;
4. Jogar o papel no lixo.

E Somar dois nmeros quaisquer
1. Escreva o primeiro nmero no retngulo A;
2. Escreva o segundo nmero no retngulo B;
3. Some o nmero do retngulo A com nmero do retngulo B e coloque o
resultado no retngulo C.

1.2. Desenvolvendo algoritmos

Pseudocdigo

Os algoritmos so descritos em uma linguagem chamada pseudocdigo. Este nome uma
aluso posterior implementao em uma linguagem de programao, ou seja, quando for
utilizada a linguagem a 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.

- 9 -


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:

E ENTRADA: So os dados de entrada do algoritmo;
E PROCESSAMENTO: So os procedimentos utilizados para chegar ao resultado final;
E SADA: So os dados j processados.

1.2.1. 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. Pegar o chiclete
2. Retirar o papel
3. Mastigar
4. Jogar o papel no lixo

Utilizar um telefone pblico - carto

1. Retirar o telefone do gancho
2. Esperar o sinal
3. Colocar o carto
4. Discar o nmero
5. Falar no telefone
6. Colocar o telefone no ganho

- 10 -


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

- 11 -


1.2.2. 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 Nota
1 8.0
2 7.0
3 8.0
4 8.0
5 7.0
6 7.0

3. Somar todas as notas: 45
4. Dividir a soma das notas, pelo total de notas informado: 45/6 7.5
5. Exibir a mdia obtida: Mensagem(Mdia: 7.5)

- 12 -


2. Estruturas de programao

2.1. 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

Terminador
Indica o incio e o fim de um processamento.

Processamento
Processamento em geral.

Entrada
Manual
Indica a entrada de dados atravs do teclado.

Deciso
Indica um ponto no qual dever ser efetuada
uma escolha entre duas situaes possveis.

Exibio
Mostra os resultados obtidos com um
processamento.

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 a forma com o qual o
mesmo foi utilizado no fluxo, indicando o processamento ou a informao
que o mesmo representa.

- 13 -


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

- 14 -


Algoritmo 02: Calcular a mdia de notas

a. Receber a nota;


- 15 -


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

E Estruturas de deciso
o IF...ELSE
o DO CASE ... CASE

E Estruturas de repetio
o WHILE...END
o FOR...NEXT

2.2.1. Estruturas de deciso

Os comandos de deciso so utilizados em algoritmos cuja soluo no obtida atravs da
utilizao de aes meramente seqenciais, permitindo que este avalie as condies
necessrias para optar por uma ou outra maneira de continuar seu fluxo.

As estruturas de deciso que sero analisadas so:

E IF...ELSE
E 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

- 16 -


Esta estrutura permite ainda que seja executada apenas uma ao, na situao em que a a
anlise da condio resultar em um valor verdadeiro.

Representao 02: IF...ELSE somente com ao para situao verdadeira

Ao vinculada ao
resultado
verdadeiro
Anlise da
condio
Verdadeiro
Falso
Aes anteriores
...
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.

- 17 -


DO CASE...CASE

A estrutura DO CASE...ENDCASE (Caso) permite a anlise de diversas condies consecutivas,
para as quais somente a condio a primeira condio verdadeira ser sua ao vinculada
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.

Anlise da
condio 1
Verdadeiro
Falso
Aes anteriores
...
Continuao do
fluxo aps a
tomada da
deciso
Ao vinculada a
condio 1
Anlise da
condio 2
Verdadeiro
Ao vinculada a
condio 2
Anlise da
condio N
Verdadeiro
Ao vinculada a
condio N
Falso
Falso
Falso

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.

- 18 -


2.2.2. Estruturas de repetio

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:

E WHILE...END
E 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

Ao vinculada ao
resultado
verdadeiro
Anlise da
condio
Verdadeiro
Falso
Aes anteriores
...
Continuao do
fluxo
...
Loop

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.

- 19 -


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

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.

- 20 -


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) onde 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

- 21 -


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

E 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 atravs da
chamada de funes como StartJob() ou CallProc() ou iniciadas automaticamente na
inicializao do Protheus Server (quando propriamente configurado).

E 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, atravs de
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 atravs de conexo
TCP/IP direta.
Programao Web

O Protheus Server pode tambm ser executado como um servidor Web, respondendo a
requisies HTTP. No momento destas requisies, pode executar rotinas escritas em ADVPL
como processos individuais, enviando o resultado das funes como retorno das requisies
para o cliente HTTP (como por exemplo, um Browser de Internet). Qualquer rotina escrita em
ADVPL que no contenha comandos de interface pode ser executada atravs de requisies
HTTP. O Protheus permite a compilao de arquivos HTML contendo cdigo ADVPL embutido.
So os chamados arquivos ADVPL ASP, para a criao de pginas dinmicas.

E Programao TelNet

TelNet parte da gama de protocolos TCP/IP que permite a conexo a um computador remoto
atravs de uma aplicao cliente deste protocolo. O PROTHEUS Server pode emular um
terminal TelNet, atravs da execuo de rotinas escritas em ADVPL. Ou seja, pode-se escrever
rotinas ADVPL cuja interface final ser um terminal TelNet ou um coletor de dados mvel.

- 22 -


3. Estrutura de um Programa ADVPL

Um programa de computador nada mais do que um grupo de comandos logicamente
dispostos com o objetivo de executar determinada tarefa. Esses comandos so gravados em
um arquivo texto que transformado em uma linguagem executvel por um computador
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 ir 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 as funes
no existentes, ou variveis no criadas ou inicializadas, etc.

Linhas de Programa

As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser linhas de
comando, linhas de comentrio ou linhas mistas.

E 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

E 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

- 23 -


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.

E 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

E 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

- 24 -


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.

3.1. reas de um Programa ADVPL

Apesar de no ser uma linguagem de padres rgidos com relao estrutura do programa,
importante identificar algumas de suas partes. Considere o programa de exemplo abaixo:

#include protheus.ch

/*
+===========================================+
| Programa: Clculo do Fatorial |
| Autor : Microsiga Software S.A. |
| Data : 02 de outubro de 2001 |
+===========================================+
*/

User Function CalcFator()

Local nCnt
Local nResultado := 1 // Resultado do fatorial
Local nFator := 5 // Nmero para o clculo

// Clculo do fatorial
For nCnt := nFator To 1 Step -1
nResultado *= nCnt
Next nCnt

// Exibe o resultado na tela, atravs da funo alert
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))

// Termina o programa
Return

A estrutura de um programa ADVPL composta pelas seguintes reas:

E rea de Identificao
- Declarao dos includes
- Declarao da funo
- Identificao do programa

E rea de Ajustes Iniciais
- Declarao das variveis

E Corpo do Programa
- Preparao para o processamento
- Processamento

E rea de Encerramento

- 25 -


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 atravs da organizao lgica destas linhas de comando. Espera-se que as linhas de
comando estejam organizadas de tal modo que no final desta rea o resultado esperado seja
obtido, seja ele armazenado em um arquivo ou em variveis de memria, pronto para ser
exibido ao usurio atravs de um relatrio ou na tela.

nResultado *= nCnt
Next nCnt

- 26 -


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

- 27 -


4. Declarao e Atribuio de Variveis

4.1. Tipo de Dados

O ADVPL no uma linguagem de tipos rgidos (strongly typed), o que significa que variveis
de memria podem receber diferentes tipos de dados durante a execuo do programa.

As variveis podem tambm conter objetos, mas os tipos primrios da linguagem so:

Numrico

O ADVPL no diferencia valores inteiros de valores com ponto flutuante, portanto podem-se
criar variveis numricas com qualquer valor dentro do intervalo permitido. Os seguintes
elementos so do tipo de dado numrico:

2
43.53
0.5
0.00001
1000000

Uma varivel do tipo de dado numrico pode conter um nmero de dezoito dgitos incluindo o
ponto flutuante, no intervalo de 2.2250738585072014 E308 at 1.7976931348623158
E+308.

Lgico

Valores lgicos em ADVPL so identificados atravs de .T. ou .Y. para verdadeiro e .F. ou .N.
para falso (independentemente se os caracteres estiverem em maisculo ou minsculo).

Caractere

Strings ou cadeias de caracteres so identificadas em ADVPL por blocos de texto entre aspas
duplas (") ou aspas simples ('):

"Ol mundo!"
'Esta uma string'
"Esta 'outra' string"

Uma varivel do tipo caractere pode conter strings com no mximo 1 MB, ou seja, 1048576
caracteres.

Data

O ADVPL tem um tipo de dados especfico para datas. Internamente as variveis deste tipo de
dado so armazenadas como um nmero correspondente a data Juliana.

Variveis do tipo de dados Data no podem ser declaradas diretamente, e sim atravs da
utilizao de funes especficas como por exemplo CTOD() que converte uma string para
data.

- 28 -


Array

O Array um tipo de dado especial. a disposio de outros elementos em colunas e linhas. O
ADVPL suporta arrays unidimensionais (vetores) ou multidimensionais (matrizes). Os
elementos de um array so acessados atravs de ndices numricos iniciados em 1,
identificando a linha e coluna para quantas dimenses existirem.

Arrays devem ser utilizadas com cautela, pois se forem muito grandes podem exaurir a
memria do servidor.

Bloco de Cdigo

O bloco de cdigo um tipo de dado especial. utilizado para armazenar instrues escritas
em ADVPL que podero ser executadas posteriormente.

4.2. Declarao de variveis

Variveis de memria so um dos recursos mais importantes de uma linguagem. So reas de
memria criadas para armazenar informaes utilizadas por um programa para a execuo de
tarefas. Por exemplo, quando o usurio digita uma informao qualquer, como o nome de um
produto, em uma tela de um programa esta informao armazenada em uma varivel de
memria para posteriormente ser gravada ou impressa.

A partir do momento que uma varivel criada, no 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.

- 29 -


4.3. Escopo de variveis

O ADVPL no uma linguagem de tipos rgidos para variveis, ou seja, no necessrio
informar o tipo de dados que determinada varivel ir conter no momento de sua declarao,
e o seu valor pode mudar durante a execuo do programa.

Tambm no h necessidade de declarar variveis em uma seo especfica do seu cdigo
fonte, embora seja aconselhvel declarar todas as variveis necessrias no comeo, tornando
a manuteno mais fcil e evitando a declarao de variveis desnecessrias.

Para declarar uma varivel 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 nNumero := 10

Esta linha de cdigo declara uma varivel chamada nNumero indicando que pertence seu
escopo local.

Os identificadores de escopo so:

E Local
E Static
E Private
E 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 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.

- 30 -


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.

- 31 -


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
automaticamente cria 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 criada 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 ir
esconder qualquer outra varivel privada ou pblica (veja a documentao sobre variveis
pblicas) com o mesmo nome enquanto existir.

Uma vez criada, uma varivel privada visvel em todo o programa enquanto no for
destruda automaticamente quando a rotina que a criou terminar ou uma outra varivel
privada com o mesmo nome for criada em uma subfuno chamada (neste caso, a varivel
existente torna-se inacessvel at que a nova varivel privada seja destruda).
Em termos mais simples, uma varivel privada visvel dentro da funo de criao e todas as
funes chamadas por esta, a menos que uma funo chamada crie sua prpria varivel
privada com o mesmo nome.

- 32 -


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 caracter _ antes
do nome de 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 onde foi
declarada at que seja escondida por uma varivel de escopo private criada com o mesmo
nome. A nova varivel de escopo private criada esconde a varivel de escopo public existente,
e esta se tornar inacessvel at que a nova varivel private seja destruda. Por exemplo:

Function Pai()
Public nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)

- 33 -


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 caracter _ antes
do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o
tpico: Boas Prticas de Programao.

Exemplo: Public _cRotina

4.4. Entendendo a influncia do escopo das variveis

Considere as linhas de cdigo de exemplo:

nResultado := 250 * (1 + (nPercentual / 100))

Se esta linha for executada em um programa ADVPL, ocorrer um erro de execuo com a
mensagem "variable does not exist: nPercentual", pois esta varivel est sendo utilizada em
uma expresso de clculo sem ter sido declarada. Para solucionar 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.

- 34 -


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.

4.5. Operaes com Variveis

4.5.1. 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.

- 35 -


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.

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

+ Adio
- Subtrao
* Multiplicao
/ Diviso
** ou ^ Exponenciao
% Mdulo (Resto da Diviso)

Operadores de String

Os operadores utilizados em ADVPL para tratamento de caracteres so:

+ Concatenao de strings (unio)
- Concatenao de strings com eliminao dos brancos finais das strings
intermedirias
$ Comparao de Substrings (contido em)

- 36 -


Operadores Relacionais

Os operadores utilizados em ADVPL para operaes e avaliaes relacionais so:

< Comparao Menor
> Comparao Maior
= Comparao Igual
== Comparao Exatamente Igual (para caracteres)
<= Comparao Menor ou Igual
>= Comparao Maior ou Igual
<> ou #
ou !=
Comparao Diferente

Operadores Lgicos

Os operadores utilizados em ADVPL para operaes e avaliaes lgicas so:

.And. E lgico
.Or. OU lgico
.Not. ou ! NO lgico

Operadores de Atribuio

Os operadores utilizados em ADVPL para atribuio de valores a variveis de memria so:

:= Atribuio Simples
+= Adio e Atribuio em Linha
-= Subtrao e Atribuio em Linha
*= Multiplicao e Atribuio em Linha
/= Diviso e Atribuio em Linha
**= ou
^=
Exponenciao e Atribuio em Linha
%= Mdulo (resto da diviso) e Atribuio em Linha

E Atribuio Simples

O sinal de igualdade utilizado para atribuir valor a uma varivel de memria.
nVariavel := 10

E 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

- 37 -


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.

E 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
+= X += Y X = X + Y
-= X -= Y X = X - Y
*= X *= Y X = X * Y
/= X /= Y X = X / Y
**= ou ^= X **= Y X = X ** Y
%= X %= Y X = X % Y

Operadores de Incremento/Decremento

A linguagem ADVPL possui operadores para realizar incremento ou decremento de variveis.
Entende-se por incremento aumentar o valor de uma varivel numrica em 1 e entende-se por
decremento diminuir o valor da varivel em 1. Os operadores so:

++ Incremento Ps ou Pr-fixado
-- Decremento Ps ou Pr-fixado

Os operadores de decremento/incremento podem ser colocados tanto antes (pr-fixado) como
depois (ps-fixado) do nome da varivel. Dentro de uma expresso, a ordem do operador
muito importante, podendo alterar o resultado da expresso. Os operadores incrementais so
executados da esquerda para a direita dentro de uma expresso.

Local nA := 10
Local nB := nA++ + nA

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

- 38 -


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.

- 39 -


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. Operadores de Incremento/Decremento pr-fixado
2. Operadores de String
3. Operadores Matemticos
4. Operadores Relacionais
5. Operadores Lgicos
6. Operadores de Atribuio
7. Operadores 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. Exponenciao
2. Multiplicao e Diviso
3. 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).

E 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.

- 40 -


4.5.3. 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 que deixa um pedao de
cdigo para ser executado. Deve-se ter em mente que tudo isso acontece em tempo de
execuo, o que torna tudo muito dinmico. Uma utilizao interessante criar um tipo de
calculadora, ou avaliador de frmulas, que determina o resultado de algo que o usurio digita.

O operador de macro tem uma limitao: variveis referenciadas dentro da string de
caracteres (X nos exemplos anteriores) no podem ser locais.

- 41 -


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

E Converses entre tipos de variveis
E Manipulao de strings
E Manipulao de variveis numricas
E Verificao de tipos de variveis
E Manipulao de arrays
E 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 caracter 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.

- 42 -


DTOC()

Sintaxe DTOC(dData)
Descrio
Realiza a converso de uma informao do tipo data para em caracter, sendo
o resultado no formato DD/MM/AAAA.

DTOS()

Sintaxe DTOS(dData)
Descrio
Realiza a converso de uma informao do tipo data em um caracter, sendo
o resultado no formato AAAAMMDD.

STOD()

Sintaxe STOD(sData)
Descrio
Realiza a converso de uma informao do tipo caracter com contedo no
formato AAAAMMDD em data.

STR()

Sintaxe STR(nValor)
Descrio
adicionando espaos direita.

STRZERO()

Sintaxe STRZERO(nValor, nTamanho)
Descrio
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 caracter em numrica.

- 43 -


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)
Descrio
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).

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 caracter ou string dentro de outra string
especificada.

- 44 -


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 caracter ou string dentro de outra string
especificada.

STUFF()

Sintaxe STUFF(cString, nPosInicial, nExcluir, cAdicao)
Descrio
Permite substituir um contedo caractere em uma string j existente,
especificando a posio inicial para esta adio e o nmero de caracteres que
sero substitudos.

SUBSTR()

Sintaxe SUBSTR(cString, nPosInicial, nCaracteres)
Descrio
Retorna parte do contedo de uma string especificada, de acordo com a
posio inicial deste contedo na string e a quantidade de caracteres que
dever ser retornada a partir daquele ponto (inclusive).

- 45 -


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 NOROUND(nValor, nCasas)
Descrio
Retorna um valor, truncando a parte decimal do valor especificado no
parmetro de acordo com a quantidade de casas decimais solicitadas.

ROUND()

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

- 46 -


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.

- 47 -


5. 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 lgica e a repetio da execuo de pedaos de cdigo qualquer nmero de vezes.

Em ADVPL, todas as estruturas de controle podem ser "aninhadas" dentro de todas as demais
estruturas contanto que estejam aninhadas propriamente. Estruturas de controle tm um
identificador de incio e um de fim, e qualquer estrutura aninhada deve se encontrar entre
estes identificadores.

Tambm existem estruturas de controle para determinar que elementos, comandos, etc. em
um programa sero compilados. Estas so as diretivas do pr-processador #ifdef...#endif e
#ifndef...#endif. Consulte a documentao sobre o pr-processador para maiores detalhes.

As estruturas de controle em ADVPL esto divididas em:

E Estruturas de repetio
E Estruturas de deciso

5.1. Estruturas de repetio

Estruturas de repetio so designadas para executar uma seo de cdigo mais de uma vez.
Por exemplo, imaginando-se a existncia de uma funo para imprimir um relatrio, 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.

E Sintaxe

FOR Variavel := nValorInicial TO nValorFinal [STEP nIncremento]
Comandos...
[EXIT]
[LOOP]
NEXT

- 48 -


E Parmetros

Varivel Especifica uma varivel ou um elemento de uma matriz para
atuar como um contador. A varivel ou o elemento da matriz
no precisa ter sido declarado antes da execuo do comando
FOR...NEXT. Se a varivel no existir, ser criada como uma
varivel privada.
nValorInicial
TO nValorFinal
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.
STEP
nIncremento
nIncremento a quantidade que ser incrementada ou
decrementada no contador aps cada execuo da seo de
comandos. Se o valor de nIncremento for negativo, o contador
ser decrementado. Se a clusula STEP for omitida, o contador
ser incrementado em 1. Pode-se utilizar valores numricos
literais, variveis ou expresses, contanto que o resultado seja
do tipo de dado numrico.
Comandos Especifica um ou mais instrues de comando ADVPL que sero
executadas.
EXIT 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.
LOOP Retorna o controle diretamente para a clusula FOR sem
executar o restante dos comandos entre o LOOP e o NEXT. O
contador incrementado ou decrementado normalmente, como
se o NEXT tivesse sido alcanado. 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 (Variavel) 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.

- 49 -


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.).

E Sintaxe

WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO

E Parmetros

lExpressao Especifica uma expresso lgica cujo valor determina quando os
comandos entre o WHILE e o ENDDO so executados. Enquanto o
resultado de lExpressao for avaliado como verdadeiro (.T.), o
conjunto de comandos so executados.
Comandos Especifica um ou mais instrues de comando ADVPL que sero
executadas enquanto lExpressao for avaliado como verdadeiro (.T.).
EXIT Transfere o controle de dentro do comando WHILE...ENDDO para o
comando imediatamente seguinte ao ENDDO, ou seja, finaliza a
repetio da seo de comandos imediatamente. Pode-se colocar o
comando EXIT em qualquer lugar entre o WHILE e o ENDO.
LOOP Retorna o controle diretamente para a clusula WHILE sem executar
o restante dos comandos entre o LOOP e o ENDDO. A expresso em
lExpressao reavaliada para a deciso se os comandos continuaro
sendo executados.

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.

- 50 -


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

5.1.1. Influenciando o fluxo de repetio

A linguagem ADVPL permite a utilizao de comandos que influem diretamente em um
processo de repetio, sendo eles:

E LOOP
E 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.

- 51 -


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 ir 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.

- 52 -


5.2. Estruturas de deciso

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.

E Sintaxe

IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF

E Parmetros

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

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

- 53 -


O Comando IF...ELSEIF...ELSE...ENDIF

Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro
(.T.).

E Sintaxe

IF lExpressao1
Comandos
[ELSEIF lExpressaoX
Comandos]
[ELSE
Comandos...]
ENDIF

E Parmetros

lExpressao1 Especifica uma expresso lgica que avaliada. Se lExpressao
resultar em verdadeiro (.T.), executar os comandos
compreendidos entre o IF e a prxima expresso da estrutura
(ELSEIF ou IF)
Se lExpressao resultar em falso (.F.), ser avaliada a prxima
expresso lgica vinculada ao comando ELSEIF, ou se o mesmo
no existir ser executada a ao definida no comando ELSE.
lExpressaoX Especifica uma expresso lgica que ser avaliada para cada
comando ELSEIF. Esta expresso somente ser avaliada se a
expresso lgica especificada no comando IF resultar em falso
(.F.).
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 parao comando ELSE.
Comandos 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.

- 54 -


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.).

E Sintaxe

DO CASE
CASE lExpressao1
Comandos
[CASE lExpressao2
Comandos
...
CASE lExpressaoN
Comandos]
[OTHERWISE
Comandos]
ENDCASE

E Parmetros

CASE
lExpressao1
Comandos...
Quando a primeira expresso CASE resultante em verdadeiro (.T.)
for encontrada, o conjunto de comandos seguinte executado. A
execuo do conjunto de comandos continua at que a prxima
clusula CASE, OTHERWISE ou ENDCASE 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).
OTHERWISE
Comandos
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.

- 55 -


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

- 56 -


6. Arrays e Blocos de Cdigo

6.1. Arrays

Arrays ou matrizes, so colees de valores, semelhantes a uma lista. Uma matriz pode ser
criada atravs de diferentes maneiras.

Cada item em um array referenciado pela indicao de sua posio numrica na lista,
iniciando pelo nmero 1.

O exemplo a seguir declara uma varivel, atribui um array de trs elementos a ela, e ento
exibe um dos elementos e o tamanho do array:

Local aLetras // Declarao da varivel
aLetras := {"A", "B", "C"} // Atribuio do array a varivel
Alert(aLetras[2]) // Exibe o segundo elemento do array
Alert(cValToChar(Len(aLetras))) // Exibe o tamanho do array

O ADVPL permite a manipulao de arrays facilmente. Enquanto que em outras linguagens
como C ou Pascal necessrio alocar memria para cada elemento de um array (o que
tornaria a utilizao de "ponteiros" necessria), o ADVPL se encarrega de gerenciar a memria
e torna simples adicionar elementos a um array, utilizando a funo AADD():

AADD(aLetras,"D") // Adiciona o quarto elemento ao final do array
Alert(aLetras[4]) // Exibe o quarto elemento
Alert(aLetras[5]) // Erro! No h um quinto elemento no array

Arrays como Estruturas

Uma caracterstica interessante do ADVPL que um array pode conter qualquer tipo de dado:
nmeros, datas, lgicos, caracteres, objetos, etc., e ao mesmo tempo. Em outras palavras, os
elementos de um array no precisam ser necessariamente do mesmo tipo de dado, em
contraste com outras linguagens como C e Pascal.

aFunct1 := {"Pedro",32,.T.}

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

- 57 -


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.

- 58 -


6.1.1. 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 Local nCnt
02 Local aX[10]
03 Local aY := Array(10)
04 Local aZ := {0,0,0,0,0,0,0,0,0,0}
05
06 For nCnt := 1 To 10
07 aX[nCnt] := nCnt * nCnt
08 Next nCnt

Este cdigo preenche o array com uma tabela de quadrados. Os valores sero 1, 4, 9, 16 ...
81, 100. Note que a linha 07 se refere varivel aX, mas poderia tambm trabalhar com aY ou
aZ.

O objetivo deste exemplo demonstrar trs modos de criar um array de tamanho conhecido
no momento da criao do cdigo.

1. Na linha 02 o array criada usando aX[10]. Isto indica ao ADVPL para alocar espao
para 10 elementos no array. Os colchetes [ e ] so utilizados para indicar o tamanho
necessrio.

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.

- 59 -


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 de
criao de um array vazio (sem nenhum elemento) e adio de elementos dinamicamente.

01 Local nCnt
02 Local aX[0]
03 Local aY := Array(0)
04 Local aZ := {}
05
06 For nCnt := 1 To nSize
07 AADD(aX, nCnt*nCnt)
08 Next nCnt

1. A linha 02 utiliza os colchetes para criar um array vazio. Apesar de no ter nenhum
elemento, seu tipo de dado array.

2. Na linha 03 a chamada da funo array cria uma matriz sem nenhum elemento.

3. Na linha 04 est declarada a representao de um array vazio em ADVPL. Mais uma
vez, esto sendo utilizadas as chaves para indicar que o tipo de dados da varivel array.
Note que {} um array vazio (tem o tamanho 0), enquanto {Nil} um array com um nico
elemento nulo (tem tamanho 1).

Porque cada uma destes arrays no contm elementos, a linha 07 utiliza a funo AADD() para
adicionar elementos sucessivamente at o tamanho necessrio (especificado por exemplo na
varivel nSize).

6.1.2. 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()

- 60 -


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 podem 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.

- 61 -


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 AINS(aArray, nPosicao)
Descrio
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.

6.1.3. Cpia de arrays

Conforme comentado anteriormente, um array uma rea na memria, o qual possui uma
estrutura permite que as informaes sejam armazenadas e organizadas das mais diversas
formas.

Com base nesse conceito, o array pode ser considerado apenas como um mapa ou um guia
de como as informaes esto organizadas e de como elas podem ser armazenadas ou
consultadas. Para se copiar um array deve-se levar este conceito em considerao, pois caso
contrrio o resultado esperado no ser o obtido na execuo da cpia.

Para copiar o contedo de uma varivel, utiliza-se o operador de atribuio :=, conforme
abaixo:

nPessoas := 10
nAlunos := nPessoas

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

- 62 -


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 onde as informaes
esto realmente armazenadas.

Como foi copiado o mapa e no as informaes, qualquer ao utilizando o rtulo aAlunos ir
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.

- 63 -


6.2. 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.

6.2.1. 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

- 64 -


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.

6.2.2. 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 impresso em um
relatrio por exemplo.

Duas Linhas de Cdigo

@00,00 PSAY x := 10 ==> 10
@00,00 PSAY y := 20 ==> 20

Cada uma das linhas ter a expresso avaliada, e o valor da varivel ser ento impresso.

Duas linha 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.

- 65 -


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

- 66 -


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}

6.2.3. 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 avalias 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

- 67 -


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 est comparando - a funo asort seleciona os
elementos (talvez utilizando o algoritmo QuickSort) e passa-os para o bloco de cdigo. O bloco
de cdigo compara-os e retorna verdadeiro (.T.) se encontram na ordem correta, ou falso (.F.)
se no. Se o valor de retorno for falso, a funo asort ir ento trocar os valores de lugar e
seguir comparando o prximo par de valores.
Ento, no bloco de cdigo anterior, a comparao X > Y verdadeira se os elementos esto
em ordem descendente, o que significa que o primeiro valor maior que o segundo.

Para ordenar a mesma matriz pelo ltimo nome, tambm em ordem descendente, pode-se
utilizar o seguinte bloco de cdigo:

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] }

- 68 -


6.2.4. 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 mesmo 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 registro 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.

- 69 -


20 20 20 20

7. 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, o 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 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 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 podem haver funes com o mesmo nome, e para permitir que os usurios e analistas

- 70 -


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.

7.1. Tipos e escopos de funes

Em ADVPL podem ser utilizados os seguintes tipos de funes:

E Function()
E User Function()
E Static Function()
E 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.

- 71 -


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 para evitar 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 as 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()

- 72 -


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 de 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 (MP-IDE) 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()

- 73 -


7.2. Passagem de parmetros entre funes

Como mencionado anteriormente os parmetros das funes descritas utilizando a linguagem
ADVPL so posicionais, ou seja, na sua passagem no importa o nome da varivel e sim a
sua posio dentro da lista de parmetros.

Complementando esta definio, podem ser utilizadas duas formas distintas de passagens de
parmetros para funes descritas na linguagem ADVPL:

E Passagem de parmetros por contedo
E 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:

E Passagem de contedos diretos
E Passagem de variveis como contedos

Exemplo 01 Passagem de contedos diretos

User Function DirFator()


nResultado := CalcFator(5)

- 74 -


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 a varivel definida como primeiro parmetro da funo chamado, no nosso caso
nFator.

Por ser uma atribuio de parmetros por contedo, o interpretador da linguagem basicamente
executa uma operao de atribuio normal, ou seja, nFator := 5.

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 atravs de uma atribuio.

2. Os parmetros de uma funo so atribudos de acordo com a ordem
com os quais so definidos na chamada da mesma. 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.

- 75 -


Como a linguagem ADVPL trata os parmetros de forma posicional, o contedo da varivel
nFatorUser ser atribudo diretamente a varivel definida como primeiro parmetro da funo
chamado, no nosso caso nFator.

Por ser uma atribuio de parmetros por contedo, o interpretador da linguagem basicamente
executa uma operao de atribuio normal, ou seja, nFator := 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 a funo que as definiu e
as funes desejadas pela aplicao.

A passagem de parmetros por referncia utiliza o conceito de que uma varivel uma rea
de memria e portanto passar um parmetro por referncia nada mais do que ao invs de
passar o contedo para a funo chamada, passar qual a rea de memria utilizada pela
varivel passada.

- 76 -


Passagem de parmetros tradicional Duas variveis x Duas reas de memria

Passagem de parmetros por referncia Duas variveis x uma nica rea de memria

- 77 -


Desta forma a funo chamada tem acesso no apenas ao contedo, mas a varivel em si,
pois a rea de memria a varivel, e qualquer alterao nesta ser visvel a funo
chamadora quando tiver o retorno da funo chamadora.

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 a 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 a 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.

- 78 -


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.

- 79 -


8. 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, as so iniciadas pelo caractere
#.

As diretivas podem ser colocadas em qualquer parte do programa, sendo que as
implementadas pela linguagem ADVPL so:

E #INCLUDE
E #DEFINE
E #IFDEF
E #IFNDEF
E #ELSE
E #ENDIF
E #COMMAND

Lembre-se

As diretivas de compilao tambm so conhecidas como UDC User Defined
Commands.

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:

E PROTHEUS.CH: diretivas de compilao 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.

- 80 -


O include PROTHEUS.CH ainda contm a referncia a outros includes utilizadas pela
linguagem ADVPL que complementam esta funcionalidade de compatibilidade com a
sintaxe Clipper, tais como:

o DIALOG.CH
o FONT.CH
o INI.CH
o PTMENU.CH
o 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.

E AP5MAIL.CH: Permite a utilizao da sintaxe tradicional na definio das seguintes
funes de envio e recebimento de e-mail:

o CONNECT SMTP SERVER
o CONNECT POP SERVER
o DISCONNECT SMTP SERVER
o DISCONNECT POP SERVER
o POP MESSAGE COUNT
o SEND MAIL FROM
o GET MAIL ERROR
o RECEIVE MAIL MESSAGE

E TOPCONN.CH: Permite a utilizao da sintaxe tradicional na definio das seguintes
funes de integrao com a ferramenta TOPCONNECT (MP10 DbAcess):

o TCQUERY

E TBICONN.CH: Permite a utilizao da sintaxe tradicional na definio de conexes com
a aplicao Server do ambiente ERP, atravs da seguintes sintaxes:

o CREATE RPCCONN
o CLOSE RPCCONN
o PREPARE ENVIRONMENT
o RESET ENVIRONMENT
o OPEN REMOTE TRANSACTION
o CLOSE REMOTE TRANSACTION
o CALLPROC IN
o OPEN REMOTE TABLES

E XMLXFUN.CH: Permite a utilizao da sintaxe tradicional na manipulao de arquivos e
strings no padro XML, atravs das seguintes sintaxes:

o CREATE XMLSTRING
o CREATE XMLFILE
o SAVE XMLSTRING
o SAVE XMLFILE

- 81 -


o ADDITEM TAG
o ADDNODE NODE
o 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.

- 82 -


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 pr-processador, o qual ir gerar um cdigo compilado de acordo com a
anlise dos parmetros de ambiente.

Estas diretivas de compilao esto normalmente associadas as seguintes verificaes de
ambiente:

E 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 IF-ELSE-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:

E PORTUGUESE
E SPANISH
E ENGLISH

- 83 -


E 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 bancos deve ser utilizada a sintaxe ADVPL tradicional.

Diretiva: #COMMAND

A diretiva #COMMAND utilizada principalmente nos includes da linguagem ADVPL para
efetuar a traduo de comandos em sintaxe CLIPPER para as funes implementadas pela
Tecnologia Microsiga.

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.

- 84 -


MDULO 03: Desenvolvendo pequenas customizaes

9. 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).

9.1. 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: atravs de cores,
indica se a palavra escrita uma instruo, uma varivel ou um comentrio; organiza a
biblioteca de programas em projetos e administra o repositrio de objetos; aponta erros de

- 85 -


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:

E 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;

E 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;

E Que o sistema cresa de forma ilimitada, pois os objetos ficam fora do executvel;

E O uso de macro substituies, ou seja, o uso de rotinas exteriores ao sistema
armazenadas em arquivos e que podem facilmente alteradas pelo usurio, pois o Server
tambm interpreta o cdigo fonte em tempo de execuo.

- 86 -


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

- 87 -


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

E 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.

E Protheus Remote / TOTVS SmartClient: Instalado no Server ou na estao. O
nome tambm depende da verso do sistema (TOTVSSMARTCLIENT.EXE).

E TopConnect / DbAccess: Responsvel pela converso dos comandos de banco de
dados, adequando-os ao SQL utilizado.

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

E RPO: o arquivo binrio do APO (Advanced Protheus Objects), ou seja, os objetos.

E Build: Executveis, DLLs e o RPO completo.

E Patch: Atualizaes pontuais do RPO, aplicadas por meio do IDE.

E 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.

- 88 -


9.2. 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.

- 89 -


. 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

- 90 -


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.

- 91 -


Propriedades dos atalhos

=
Destino:
c:\protheus\bin\appserver\totvsappserver.exe
- console
Iniciar em: c:\protheus\bin\appserver

E -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.

E -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.

E -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\totvssmartcliente.exe
M
Iniciar em: c:\protheus\bin\smartclient

E -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).

E -P (Main Program)

Identifica o Programa (APO) Inicial.

E -E (Environment)

Nome da Seo de Environment, no (Ini do Server), que ser utilizada, para definies gerais.

E -C (Connection)

Nome da Seo de Conexo, que ser utilizada, para a conexo ao TOTVS Application Server.

E -M (AllowMultiSession)

Permite mltiplas instncias (Cpias) do TOTVS Smart Client, na mesma mquina, o que por
Default no permitido.

- 92 -


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:

E SourcePath: Indica o local de origem dos objetos. o endereo do Repositrio de
Objetos (Exemplo: SourcePath=C:\PROTHEUS\APO)

E 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)

E 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:\PROTHEUS\APO
ROOTPATH= C:\MP811\PROTHEUS_DATA
STARTPATH=\ PROTHEUS\
RPODB=TOP
RPOLANGUAGE=PORTUGUESE
RPOVERSION=101
LOCALFILES=ADS
TRACE=0
LOCALDBEXTENSION=.DBF
PICTFORMAT=DEFAULT
DATEFORMAT=DEFAULT

[DRIVERS]
ACTIVE=TCP

[TCP]
TYPE=TCPIP
PORT=1234

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.

- 93 -


[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

E Active: Indica qual a forma de comunicao.

E 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.

E 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.

- 94 -


9.3. O Configurador do Protheus

9.3.1. Funcionalidades Abordadas

O objetivo deste tpico no abranger todo 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

E Configurao e criao de novas tabelas no Dicionrio de Dados
E 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.

9.3.2. Estruturas bsicas da aplicao ERP Protheus

Arquivos de configurao do sistema

Arquivo Descrio
SIGAMAT Cadastro de empresas e filiais do sistema
SIGAPSS Arquivo de usurios, grupos e senhas do sistema
SIX ndices dos arquivos
SX1 Perguntas e respostas
SX2 Mapeamento de tabelas
SX3 Dicionrio de Dados
SX4 Agenda do Schedule de processos
SX5 Tabelas
SX6 Parmetros
SX7 Gatilhos de Interface
SX8 Fora de uso
SX9 Relacionamentos entre tabelas
SXA Pastas cadastrais apontadas no SX3
SXB Consulta por meio da tecla F3 (Consulta Padro)
SXD Controle do Schedule de processos
SXE Seqncia de documentos (+1)
SXF Seqncia de documentos (Prximo)
SXG Tamanho padro para campos apontado pelo SX3
SXK Resposta de Perguntas (SX1) por usurios
SXO Controle de LOGs por tabela
SXP Histrico de Logs cadastrados no SXO
SXQ
Cadastro de filtros inteligentes da mbrowse (contm as
informaes necessrias para a criao do filtro).
SXR
Cadastro de relacionamento entre programa x filtro
(utilizada internamente pelo Protheus para verificar em
quais programas os filtros podero ser utilizados).

- 95 -


SXS
Cadastro de programas (utilizado na validao para
mostrar/inibir os filtros na execuo da mbrowse).
SXT
Tabela de usurios (contm as informaes dos
usurios que podero utilizar os filtros da mbrowse).
SXOffice
Cadastro de relacionamento entre as entidades
(tabelas) e as consultas TOII.

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 Identificao
SIGAATF ATIVO FIXO
SIGACOM COMPRAS
SIGACON CONTABILIDADE
SIGAEST ESTOQUE E CUSTOS
SIGAFAT FATURAMENTO
SIGAFIN FINANCEIRO
SIGAFIS LIVROS FISCAIS
SIGAPCP PLANEJAMENTO E CONTROLE DA PRODUO
SIGAGPE GESTO DE PESSOAL
SIGAFAS FATURAMENTO DE SERVIOS
SIGAVEI VECULOS
SIGALOJ CONTROLE DE LOJAS/AUTOMAO COMERCIAL
SIGATMK CALL CENTER
SIGAOFI OFICINAS
SIGAPON PONTO ELETRNICO
SIGAEIC EASY IMPORT CONTROL
SIGATCF TERMINAL
SIGAMNT MANUTENO DE ATIVOS
SIGARSP RECRUTAMENTO E SELEO DE PESSOAL
SIGAQIE INSPEO DE ENTRADA QUALIDADE
SIGAQMT METODOLOGIA QUALIDADE

O nome de cada tabela no Protheus constitudo de seis dgitos, os quais so utilizados para
formar a seguinte representao:

F X X E E 0

- 96 -


Onde:

F SF X 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.
E E 0 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 Descrio
S - Tabelas pertencentes ao sistema bsico, tambm chamado Classic
S A
Cadastros de entidades compartilhadas entre os ambientes
(Clientes, Fornecedores, Bancos entre outros).
S B
Cadastros dos ambientes de Materiais (Produtos, Saldos entre
outros).
S C
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).
S D
Arquivos de movimentaes de estoque (Itens de notas fiscais de
entrada e sada, movimentos internos de estoque entre outros).
S E Cadastros e movimentaes do ambiente Financeiro.
S F
Cadastros e movimentaes Fiscais (Cabealhos das notas fiscais
de entrada e sada, cadastro de tipos de entrada e sada, livros
fiscais, entre outros).
S G Cadastros do ambiente de Planejamento e Controle de Produo
S H Movimentos do ambiente de Planejamento e Controle de Produo
S I Cadastros e movimentos do ambiente Contbil (descontinuado)
S N Cadastros e movimentos do ambiente Ativo Fixo
S R Cadastros e movimentos do ambiente Gesto de Pessoal
S X Tabelas de configurao do sistema
S Z Tabelas livres para utilizao e projetos especficos em clientes.
A - Gesto de Projetos
C - Contabilidade Gerencial
C T Contabilidade Gerencial
C V Contabilidade Gerencial
C W Contabilidade Gerencial
D - Transportadoras e derivados
E - Comrcio exterior e derivados
G - Gesto Hospitalar
J - Gesto Educacional
N - Servios Pblicos
P - Reservado para projetos da fbrica de software
Q - Qualidade e derivados
R - Recursos Humanos e derivados
T - Plano de Sade
W - Workflow
Z - Tabelas livres para utilizao e projetos especficos em clientes em
adio a famlia SZ.

- 97 -


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, ser gerados arquivos com a mesma nomenclatura da tabela de
dados, mas com uma extenso diferenciada (atualmente .CDX). No caso da utilizao de um
banco de dados, cada ndice ser uma numerao seqencial em funo do nome da tabela
original.

As especificaes das chaves de ndices de cada um das tabelas est disponvel no arquivo de
sistema SIX, e a chave nica da tabela utilizada para banco de dados est descrita na tabela
SX2.

Menus

Cada mdulo da aplicao ERP possui um menu padro com todas as funcionalidades
disponveis para o ambiente, menu este definido atravs de sintaxe XML (arquivos .XNU).

Os menus possuem uma estrutura padro que permite ao usurio localizar e identificar
facilmente cada uma das funcionalidades oferecidas pelo ambiente.

9.3.3. 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

- 98 -


Aps a confirmao, a validao do acesso feita conforme tela ilustrada a seguir:

Figura: Validao de acesso

Figura: Confirmao do acesso ao mdulo Configurador

- 99 -


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

- 100 -


9.4. 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
interpretadas 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.

- 101 -


9.4.1. 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

9.4.2. 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.

- 102 -


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:

- 103 -


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

E 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.

E O nome da tabela preenchido automaticamente, adicionando 990. Esse dado refere-
se empresa 99 (Teste Matriz) a qual est sendo adicionado tabela.

E O Path refere-se pasta que conter efetivamente os dados das tabelas, quando ISAM,
nas verses com banco de dados relacional no so utilizadas. Essa pasta ser criada
dentro da pasta indicada na configurao do sistema como ROOTTPATH.

E 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.

E 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

- 104 -


funcionalidade do mdulo.

9.4.3. Adio de campos as 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 atualizada. (rvore
de opes da parte esquerda da interface visual do Gerenciador de Bases de Dados).



3. Aps a visualizao das tabelas j cadastradas no SX2 da empresa selecionada, 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:

- 105 -


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

- 106 -


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

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

- 107 -


20 20 20 20

Orientaes para o cadastramento de um novo campo

1. As propriedades definidas no Dicionrio de Dados (SX3) so as seguintes:

E 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.

E 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.

E 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.

E Formato de edio: Define como o campo aparece nas telas e nos relatrios.

E 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.

E 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

E O campo Decimal ser solicitado somente para os campos de tipo numrico.

E 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.

E 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.

E A propriedade alterar indica que o campo pode ser alterado.

E Nesta janela, os dados esto classificados em seis pastas com objetivos de
preenchimento bem especficos:

- 108 -


Guia: Informaes

E Contm as informaes a respeito dos ttulos.

E 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.

E Descrio e Help: So propriedades que objetivam documentar o campo.

Guia: Opes

E Contm os dados que facilitam a digitao.

Guia: Validaes

E Representam as regras de validao do campo.

E 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.

E 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

E Descreve a forma de utilizao do campo.

Guia: Mdulos

E Relaciona todos os mdulos em que o campo ser utilizado.

- 109 -


9.4.4. 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 atualizada. (rvore
de opes da parte esquerda da interface visual do Gerenciador de Bases de Dados).



3. Aps a visualizao das tabelas j cadastradas no SX2 da empresa selecionada, 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:

- 110 -


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:

- 111 -


Figura: Adio de um ndice para uma tabela

seguir, e ao trmino confirme o cadastramento do novo ndice para a tabela com o boto
Confirmar ( ).
7. Confirme as atualizaes para a tabela selecionada com o boto Confirmar ( ).
8. Atualize as configuraes do sistema com o boto Atualizar ( ).

Figura: Atualizao dos dados do sistema

- 112 -


Orientaes para o cadastramento de um novo ndice

E 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.

E Para selecionar os campos j cadastrados na tabela, pode ser utilizado o boto Campos
( ). Esta facilidade preenche, automaticamente, os campos de descrio.

E 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.

E 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 as dados diretamente em bancos de dados de
ambientes TOPCONNECT (DbAcess).

9.4.5. 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 atualizada. (rvore de
opes da parte esquerda da interface visual do Gerenciador de Bases de Dados).

2. Aps a seleo da opo Gatilhos sero exibidos os itens j cadastradas no arquivo de
sistema SX7.

Figura: Conjunto de gatilhos j cadastros no SX7

- 113 -


3. Aps a visualizao dos gatilhos j cadastrados no SX7 da empresa selecionada, utilize
o boto Incluir ( ) para realizar o cadastro de um novo gatilho no sistema:

Figura: Dados para o cadastro de um novo gatilho no sistema

seguir, e ao trmino confirme o cadastramento do novo gatilho de sitema com o boto
Confirmar ( ).

Orientaes para o cadastramento de um novo gatilho

E Pode haver vrios gatilhos para o mesmo campo. A ordem de execuo determinada
pelo campo Seqncia.

E 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.

E A regra pode ser uma expresso que resulta em um valor a ser preenchido no Contra
Domnio.

E O posicionamento igual a Sim indica que ser executado um comando de busca do
registro de acordo com a chave indicada.

E 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.

- 114 -


9.4.6. Criao de Tabelas Genricas

Procedimento

1. Para adicionar uma tabela genrica, selecione os menus Ambiente, Cadastros, Tabelas.

2. Aps a seleo da opo Tabelas sero exibidos os itens j cadastradas no arquivo de
sistema SX5.

Figura: Conjunto de Tabelas j cadastras no SX5

3. Aps a visualizao das tabelas j cadastrados no SX5 da empresa selecionada, utilize o
boto Incluir ( ) para realizar o cadastro de uma nova tabela no sistema:

Figura: Dados para o cadastro de uma nova tabela no sistema

- 115 -


seguir, e ao trmino confirme o cadastramento da nova tabela do sistema com o boto
Confirmar ( ).

9.4.7. 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 arquivo de
sistema SX6.

Figura: Conjunto de Parmetros j cadastras no SX6

3. Aps a visualizao dos Parmetros j cadastrados no SX6 da empresa selecionada,
utilize o boto Incluir ( ) para realizar o cadastro de uma nova tabela no sistema:

- 116 -


Figura: Dados para o cadastro de um novo parmetro no sistema

seguir, e ao trmino confirme o cadastramento do novo Parmetro do sistema com o
boto Confirmar ( ).

- 117 -


10. TOTVS Development Studio

A ferramenta TOTVS Development Studio um programa que faz parte do Protheus e permite
o trabalho de edio, compilao e depurao de programas escritos em ADVPL.

Projeto

Um programa para ser compilado deve ser vinculado a um projeto. Normalmente, programas
que fazem parte de um determinado mdulo ou ambiente esto em um mesmo projeto.

A vinculao dos programas a um projeto feita por meio dos arquivos do tipo PRW. Na
verdade, um projeto pode ser constitudo de um ou mais arquivos deste tipo, que por sua vez,
podem ter uma ou mais funes, conforme ilustra o diagrama a seguir:

Figura: Representao da estrutura de um projeto no DEV-Studio

- 118 -


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 uma dos fontes ser processado e
compilado separadamente, permitindo a visualizao do progresso da operao e das
mensagens de aviso (warnings) ou erros (critical errors) na guia Mensagens.

Execuo

Para que os objetos compilados e disponveis n RPO sejam utilizados, devem ser observadas as
seguintes regras:

E Se o programa no manipula arquivos, pode-se cham-lo diretamente do DEV-Studio
(nome no lado direito da barra de ferramentas);

E Se o programa manipula tabelas existem duas opes:

. Adicionar o programa no menu de um dos ambientes e executa-lo atravs do
Remote.

. Realizar a preparao do ambiente na prpria rotina, permitindo sua execuo
diretamente pelo DEV-Studio.

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

E Definir e marcar os pontos de parada mais adequados a anlise do fonte;

E Executar a rotina atravs do DEV-Studio, selecionando seu nome diretamente, ou o
mdulo que contm a opo ou a ao que ir execut-la;

E 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

E Atravs da Janela de Watchs possvel determinar quais variveis devem ser exibidas;

- 119 -


E Na pilha de chamadas, verifica-se a seqncia de chamadas das funes;
E 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;

E 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

E O DEV-Studio apresenta, no topo da tela, um conjunto de opes de menu e uma srie
de botes que facilitam a sua manipulao.

E 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.

- 120 -


Desenvolvimento de pequenas customizaes

11. Acesso e manipulao de bases de dados em ADVPL

Como a linguagem ADVPL utilizada no desenvolvimento de aplicao para o sistema ERP
Protheus, ela deve possuir recursos que permitam o acesso e a manipulao de informaes
independentemente da base de dados para o qual o sistema foi configurado.

Desta forma a linguagem possui dois grupos de funes distintos para atuar com os bancos de
dados:

E Funes de manipulao de dados genricas
E Funes de manipulao de dados especficas para ambientes TOPCONNECT /
DBACCESS

Funes de manipulao de dados genricas

As funes de manipulao de dados ditas como genricas permitem que uma aplicao ADVPL
seja escrita da mesma forma, independente se a base de dados configurada para o sistema
ERP for do tipo ISAM ou padro SQL.

Muitas destas funes foram inicialmente herdadas da linguagem CLIPPER, e mediante novas
implementaes da rea de Tecnologia da Microsiga foram melhoradas e adequadas s
necessidades do ERP. Por esta razo possvel encontrar em documentaes da linguagem
CLIPPER informaes sobre funes de manipulao de dados utilizadas na ferramenta ERP.

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 escritas em ADVPL sejam interpretadas e convertidas para
uma sintaxe compatvel com o padro SQL ANSI e desta forma aplicadas aos SGDBs (Sistemas
Gerenciadores de Bancos de Dados) com sua sintaxe nativa.

Funes de manipulao de dados para ambientes TOPCONNECT / DBACCESS

Para implementar um acesso mais otimizado e disponibilizar no ambiente ERP funcionalidades
que utilizem de forma mais adequada os recursos dos SGDBs homologados para o sistema,
foram implementadas funes de acesso e manipulao de dados especficas para ambientes
TOPCONNECT/DBACCESS.

Estas funes permitem que o desenvolvedor ADVPL execute comandos em sintaxe SQL
diretamente de um cdigo fonte da aplicao, disponibilizando recursos como execuo de
queries de consulta, chamadas de procedures e comunicao com outros bancos de dados
atravs de ODBCs.

As funes especficas para ambientes TOPCONNECT sero abordas no
material de ADVPL Avanado.

- 121 -


11.1. Diferenas e compatibilizaes entre bases de dados

Como a aplicao ERP pode ser configurada para utilizar diferentes tipos de bases de dados
importante mencionar as principais diferenas entre estes recursos, o que pode determinar a
forma como o desenvolvedor ir 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
pode-se citar a utilizao do comando PACK, o qual ir apagar fisicamente os registros
deletados da tabela forando uma renumerao dos identificadores de todos os registros. Esta
situao tambm torna necessria a recriao de todos os ndices vinculados quela tabela.

Isto ocorre nas bases de dados ISAM devido ao conceito de excluso lgica de registros que as
mesmas possuem. J os bancos de dados padro SQL nativamente utilizam apenas o conceito
de excluso fsica de registros, o que para outras aplicaes seria transparente, mas no o
caso do ERP Protheus.

Para manter a compatibilidade das aplicaes desenvolvidas para bases de dados padro
ISAM, a rea de Tecnologia e Banco de Dados da Microsiga implementou nos bancos de dados
padro SQL o conceito de excluso lgica de registros existente nas bases de dados ISAM
atravs da criao de campos de controle especficos: R_E_C_N_O_, D_E_L_E_T_ e
R_E_C_D_E_L.

Estes campos permitem que a aplicao ERP gerencie as informaes do banco de dados da
mesma forma que as informaes em bases de dados ISAM.

- 122 -


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 nas tabela de bases de dados ISAM.

11.2. Funes de acesso e manipulao de dados

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

As funes de acesso e manipulao de dados definem basicamente:

E Tabela que est sendo tratada;
E Campos que devero ser lidos ou atualizados;
E Mtodo de acesso direto as informaes (registros e campos).

Dentre as funes ADVPL disponveis para acesso e manipulao de informaes, este material
ir detalhar as seguintes opes:

SELECT()
DBSELECTAREA()
DBSETORDER()
DBSEEK() E MSSEEK()
DBSKIP()
DBGOTO()
DBGOTOP()
DBGOBOTTON()
DBSETFILTER()
RECLOCK()
SOFTLOCK()
MSUNLOCK()
DBDELETE()
DBUSEAREA()
DBCLOSEAREA()

- 123 -


DBRLOCK()

Sintaxe DBRLOCK(xIdentificador)
Descrio
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.

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 seu
reuso em outro operao. Este comando tem efeito apenas no alias ativo na
conexo, sendo necessria sua utilizao em conjunto com o comando
DbSelectArea().

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 uma
busca (seek) prvio.

- 124 -


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)
Descrio
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.

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 com sendo a rea ativa. Todas as
operaes subseqentes que fizerem referncia a uma rea de trabalho a
utilizao, a menos que a rea desejada seja informada explicitamente.

- 125 -


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

DBORDERNICKNAME()

Sintaxe DbOrderNickName(NickName)
Descrio
Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os
seus prprios ndices e no momento da incluso deve criar o NICKNAME para
o mesmo.

DBUNLOCK()

Sintaxe DBUNLOCK()
Descrio
Mesma funcionalidade da funo UNLOCK(), s que recomendada para
ambientes de rede nos quais os arquivos so compartilhados.

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
DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)
Descrio
Define um arquivo de base de dados como uma rea de trabalho disponvel
na aplicao.

MSUNLOCK()

Sintaxe MsUnLock()
Descrio
Libera o travamento (lock) do registro posicionado confirmando as
atualizaes efetuadas neste registro.

- 126 -


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 Select(cArea)
Descrio
Determina o nmero de referncia de um determinado alias em um
ambiente de trabalho. Caso o alias especificado no esteja em uso no
ambiente, ser retornado o valor 0 (zero).

SOFTLOCK()

Sintaxe SoftLock(cAlias)
Descrio
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 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.

- 127 -


11.3. 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 aberto, 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 as 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.

- 128 -


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

E Ao ser fornecido um nmero, ele permanece reservado at a concluso da operao
que o solicitou;

E 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, mesmo que tenhamos vrios processos solicitando numeraes seqenciais para
uma mesma tabela, como por exemplo incluses simultneas de pedidos de vendas, teremos
para cada pedido um nmero exclusivos e sem o intervalos e numeraes no utilizadas.

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.

- 129 -


CONFIRMSXE()

Sintaxe CONFIRMSXE(lVerifica)
Descrio Confirma o nmero alocado atravs do ltimo comando GETSXENUM().

ROLLBACKSXE()

Sintaxe ROLLBACKSXE()
Descrio
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(),
retornando a numerao disponvel para outras conexes.

12. Customizaes para a aplicao ERP

Neste tpico sero abordas as formas pelas quais a aplicao ERP Protheus pode ser
customizada com a utilizao da linguagem ADVPL.

Pelos recursos de configurao da aplicao ERP disponveis no mdulo Configurador possvel
implementar as seguintes customizaes:

E Validaes de campos e perguntas do sistema e de usurios
E Incluso de gatilhos em campos de sistemas e de usurios
E Incluso de regras em parmetros de sistemas e de usurios
E Desenvolvimento de pontos de entrada para interagir com funes padres do sistema

- 130 -


12.1. Customizao de campos Dicionrio de Dados

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

E SX3 Validao de usurio (X3_VLDUSER)
E 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)
Descrio
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.

- 131 -


EXISTCPO()

Sintaxe ExistCpo(cAlias, cConteudo, nIndice)
Descrio
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.

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.

- 132 -


12.1.2. 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 Funcionalidade
A Permite apenas caracteres alfabticos.
C Exibe CR depois de nmeros positivos.
E Exibe numrico com o ponto e vrgula invertidos (formato Europeu).
R Insere caracteres diferentes dos caracteres de template na exibio, mas no os
insere na varivel do GET.
S<n> Permite rolamento horizontal do texto dentro do GET, <n> um nmero inteiro
que identifica o tamanho da regio.
X Exibe DB depois de nmeros negativos.
Z Exibe zeros como brancos.
( Exibe nmeros negativos entre parnteses com os espaos em branco iniciais.
) Exibe nmeros negativos entre parnteses sem os espaos em branco iniciais.
! Converte caracteres alfabticos para maisculo.

Templates
X Permite qualquer caractere.
9 Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos.
# Permite dgitos, sinais e espaos em branco para qualquer tipo de dado.
! Converte caracteres alfabticos para maisculo.
* Exibe um asterisco no lugar dos espaos em branco iniciais em nmeros.
. Exibe o ponto decimal.
, Exibe a posio do milhar.

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

- 133 -


SAY e PSAY

Funes
C Exibe CR depois de nmeros positivos
E Exibe numrico com o ponto e a vrgula invertidos (formato Europeu)
R Insere caracteres diferentes dos caracteres de template
X Exibe DB depois de nmeros negativos
Z Exibe zeros como brancos
( Envolve nmeros negativos entre parnteses
! Converte todos os caracteres alfabticos para maisculo

Templates
X Exibe dgitos para qualquer tipo de dado
9 Exibe dgitos para qualquer tipo de dado
# Exibe dgitos para qualquer tipo de dado
! Converte caracteres alfabticos para maisculo
* Exibe asterisco no lugar de espaos em branco inicias em nmeros
. Exibe a posio do ponto decimal
, Exibe a posio do milhar

Exemplo 01 Picture campo numrico

CT2_VALOR Numrico 17,2
Picture: @E 99,999,999,999,999.99

- 134 -


12.2. Customizao de gatilhos Configurador

A aplicao ERP utiliza o recurso de gatilhos em campo com a finalidade de auxiliar o usurio
no preenchimento de informaes durante a digitao de informaes. As funes que podem
ser utilizadas no gatilho esto diretamente relacionadas a definio da expresso de retorno
que ser executada na avaliao do gatilho do campo.

As regras que devem ser observadas na montagem de um gatilho e configurao de seu
retorno so:

E 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

o 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 de clientes -> SA1 (compartilhado)
Cadastro de fornecedores -> SA2 (compartilhado)
Cadastro de vendedores -> SA3 (exclusivo)
Cadastro de transportadoras -> SA4 (exclusivo)

o Consulta a informaes de tabelas de movimentos 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)

E 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.

- 135 -


12.3. Customizao de parmetros Configurador

Os parmetros de sistema utilizados pela aplicao ERP e definidos atravs do mdulo
configurador possuem as seguintes caractersticas fundamentais:

E 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 a rotina que o consultou.

E 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 explicito 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 GETMV()
o SUPERGETMV()
o 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.

12.3.1. 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.

- 136 -


GETNEWPAR()

Sintaxe GETNEWPAR(cParametro, cPadrao, cFilial)
Descrio

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)
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.

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

E As rotinas da aplicao ERP no protegem a consulta de contedos de parmetros
quanto a gravaes realizadas dentro ou fora de uma transao.

E Desta forma, quaisquer alterao na base realizada por uma rotina configurada em um
parmetro pode ocasionar a perda da integridade das informaes do sistema.

- 137 -


12.4. Pontos de Entrada Conceitos, Premissas e Regras

Conceitos

Um ponto de entrada uma User Function desenvolvida com a finalidade de interagir com uma
rotina padro da aplicao ERP.

A User Function dever ter um nome pr-estabelecido no desenvolvimento da rotina padro do
ERP, e de acordo esta pr-disposio e o momento no qual o ponto de entrada executado
durante um processamento, ele poder:

E Complementar uma validao realizada pela aplicao;

E Complementar as atualizaes realizadas pelo processamento em tabelas padres do
ERP;

E Implementar a atualizao de tabelas especificas durante o processamento de uma
rotina padro do ERP;

E 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;

E Substituir um processamento padro do sistema por uma regra especfica do cliente no
qual o mesmo ser implementado.

Premissas e Regras

E 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.

E Um ponto de entrada deve ser transparente para o processo padro, de forma que
todas as tabelas acessadas pelo ponto de entrada e que sejam utilizadas pela rotina
padro, devero ter sua situao imediatamente anterior execuo do ponto
restaurada ao trmino do mesmo, e para isto recomenda-se o uso das funes
GETAREA() e RESTAREA().

E 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.

E A varivel PARAMIXB no possui um padro de definio nos cdigos fontes da
aplicao ERP, desta forma seu tipo pode variar deste um contedo simples (caractere,
numrico, lgico e etc.) a um tipo complexo como um array ou um objeto. Desta forma
necessrio sempre avaliar a documentao sobre o ponto bem como proteger a
funo customizada de tipos de PARAMIXB no tratados por ela.

- 138 -


13. Interfaces visuais

A linguagem ADVPL possui duas formas distintas para definio de interfaces visuais no
ambiente ERP: sintaxe convencional, nos padres da linguagem CLIPPER e a sintaxe orientada
a objetos.

Alm das diferentes sintaxes disponveis para definio das interfaces visuais o ERP Protheus
possui funcionalidades pr-definidas, as quais j contm todos os tratamentos necessrios 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.

13.1. Sintaxe e componentes das interfaces visuais

A sintaxe convencional para definio de componentes visuais da linguagem ADVPL depende
diretamente no include especificado no cabealho do fonte. Os dois includes disponveis para o
ambiente ADVPL Protheus so:

E RWMAKE.CH: permite a utilizao da sintaxe CLIPPER na definio dos componentes
visuais.

E 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 atravs do uso do include PROTHEUS.CH

- 139 -


Os componentes da interface visual que sero tratados neste tpico, utilizando a sintaxe
ADVPL so:

MSDIALOG()
MSGET()
SAY()
BUTTON()
SBUTTON()

BUTTON()

Sintaxe
@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE
OF oObjetoRef ACTION AO
Descrio
Define o componente visual Button, o qual permite a incluso de botes de
operao na tela da interface, os quais sero visualizados somente com um
texto simples para sua identificao.

MSDIALOG()

Sintaxe
DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni
TO nLiFim,nColFim OF oObjetoRef UNIDADE
Descrio
Define o componente MSDIALOG(), o qual utilizado como base para os
demais componentes da interface visual, pois um componente MSDIALOG()
uma janela da aplicao.

MSGET()

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

SAY()

Sintaxe
@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF
oObjetoRef
Descrio
Define o componente visual SAY, o qual utilizado para exibio de textos
em uma tela de interface.

SBUTTON()

Sintaxe
DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO
STATUS OF oObjetoRet
Descrio
Define o componente visual SButton, 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.

- 140 -


Interface visual completa

Abaixo segue um cdigo completo de interface, utilizado 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 SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()

DEFINE SBUTTON FROM 010, 120 TYPE 1 ACTION (nOpca := 1,oDlg:End());
ENABLE OF oDlg

ENABLE OF oDlg


O cdigo demonstrado anteriormente utilizados nos exerccios de fixao
deste material e dever produzir a seguinte interface:

- 141 -


13.2. Interfaces padres para atualizaes de dados

Os programas de atualizao de cadastros e digitao de movimentos seguem um padro que
se apia no Dicionrio de Dados.

Basicamente so duas as interfaces quer permitem a visualizao das informaes e a
manipulao dos dados do sistema.

E AxCadastro
E Mbrowse

Ambos os modelos utilizam como premissa que a estrutura da tabela a ser utilizada esteja
definida no dicionrio de dados do sistema (SX3).

13.2.1. AxCadastro()

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 padres para
visualizao de registros simples, sem a opo de cabealho e itens.

E Sintaxe: AxCadastro(cAlias, cTitulo, cVldExc, cVldAlt)

E 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 cAlias := "SA2"
Local cTitulo := "Cadastro de Fornecedores"
Local cVldExc := ".T."
Local cVldAlt := ".T."

dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)
Return

- 142 -


13.2.2. 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.

E Sintaxe simplificada: MBrowse(nLin1, nCol1, nLin2, nCol2, cAlias)

E Parmetros

nLin1, nCol1,
nLin2, nCol2
Coordenadas dos cantos aonde o browse ser exibido. Para seguir o
padro da AXCADASTRO() use 6,1,22,75 .
cAlias
Alias padro do sistema para utilizao, o qual deve estar definido no
dicionrio de dados SX3.

- 143 -


E Variveis private adicionais

aRotina

Array contendo as funes que sero executadas pela Mbrowse.
Este array pode ser parametrizados com as funes bsicas da
AxCadastro conforme abaixo:

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()

Private cCadastro := "Cadastro de Fornecedores"
Private 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})

dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return

- 144 -


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 Pesquisar
2 Visualizar
3 Incluir
4 Alterar
5 Excluir
6 Livre

Ao definir as funes no array aRotina, se o nome da funo no for
especificado com (), a Mbrowse passar como parmetros as seguintes
variveis de controle:

cAlias: Alias ativo definido para a Mbrowse
nRecno: Record number (recno) do registro posicionado no alias
ativo.
nOpc: Posio da opo utilizada na Mbrowse de acordo com a ordem
da funo no array a Rotina.

- 145 -


Exemplo: Funo BInclui() substituindo a funo AxInclui()


User Function MBrwSA2()


Private cCadastro := "Cadastro de Fornecedores"
Private aRotina := {}

AADD(aRotina,{"Pesquisar" ,"AxPesqui" ,0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual" ,0,2})
AADD(aRotina,{"Incluir" ,"U_BInclui" ,0,3})
AADD(aRotina,{"Alterar" ,"AxAltera" ,0,4})
AADD(aRotina,{"Excluir" ,"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

- 146 -


13.2.3. 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
AxAltera(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;
cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)
Descrio
Funo de alterao padro das informaes de um registro, no formato
Enchoice, conforme demonstrado no tpico sobre a interface AxCadastro().

AXDELETA()

Sintaxe
AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,;
aAuto, lMaximized)
Descrio
Funo de excluso padro das informaes de um registro, no formato

AXINCLUI()

Sintaxe
AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;
Descrio
Funo de incluso padro das informaes de um registro, no formato

AXPESQUI()

Sintaxe AXPESQUI()
Descrio
Funo de pesquisa padro em registros exibidos pelos browses do sistema,
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.

- 147 -


AXVISUAL()

Sintaxe
AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;
aButtons, lMaximized )
Descrio
Funo de visualizao padro das informaes de um registro, no formato

- 148 -


APNDICES

BOAS PRTICAS DE PROGRAMAO

14. Utilizao de Identao

obrigatria a utilizao da identao, pois torna o cdigo muito mais legvel. Veja os
exemplos abaixo:

A utilizao da identao seguindo as estruturas de controle de fluxo (while, if, caso etc) torna
a compreenso do cdigo muito mais fcil:

Para identar o cdigo utilize a tecla <TAB> e na ferramenta DEV-Studio, a qual pode ser
configurada atravs da opo Preferncias:

- 149 -


15. Capitulao de Palavras-Chave

Uma conveno amplamente utilizada a de capitular as palavras chaves, funes, variveis e
campos utilizando uma combinao de caracteres em maisculo e minsculo, visando facilitar
a leitura do cdigo fonte. O cdigo a seguir:

local ncnt while ( ncnt++ < 10 ) ntotal += ncnt * 2 enddo

Ficaria melhor com as palavras chaves e variveis capituladas:

Local nCnt While ( nCnt++ < 10 ) nTotal += nCnt * 2 EndDo

Para funes de manipulao de dados que comecem por db, a capitulao
s ser efetuada aps o db:

E dbSeek()
E dbSelectArea()

- 150 -


15.1. Palavras em maisculo

A regra utilizar caracteres em maisculo para:

E Constantes:
#define NUMLINES 60 #define NUMPAGES 1000

E Variveis de memria:
M-> CT2_CRCONV M->CT2_MCONVER := CriaVar("CT2_CONVER")

E Campos:
SC6->C6_NUMPED

E Querys:
SELECT * FROM...

16. 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 Tipo de dado Exemplo
a Array aValores
b Bloco de cdigo bSeek
c Caracter cNome
d Data dDataBase
l Lgico lContinua
n Numrico nValor
o Objeto oMainWindow
x Indefinido xConteudo

- 151 -


17. Palavras reservadas

AADD DTOS INKEY REPLICATE VAL
ABS ELSE INT RLOCK VALTYPE
ASC ELSEIF LASTREC ROUND WHILE
AT EMPTY LEN ROW WORD
BOF ENDCASE LOCK RTRIM YEAR
BREAK ENDDO LOG SECONDS CDOW
ENDIF LOWER SELECT CHR EOF
LTRIM SETPOS CMONTH EXP MAX
SPACE COL FCOUNT MIN SQRT
CTOD FIELDNAME MONTH STR DATE
FILE PCOL SUBSTR DAY FLOCK
PCOUNT TIME DELETED FOUND PROCEDURE
TRANSFORM DEVPOS FUNCTION PROW TRIM
DOW IF RECCOUNT TYPE DTOC
IIF RECNO UPPER TRY AS
CATCH THROW

E Palavras reservadas no podem ser utilizadas para variveis,
procedimentos ou funes;

E Funes reservadas so pertencentes ao compilador e no podem ser
redefinidas por uma aplicao;

E Todos os identificadores que comearem com dois ou mais caracteres
_ so utilizados como identificadores internos e so reservados.

E Identificadores de escopo PRIVATE ou PUBLIC utilizados em aplicaes
especficas desenvolvida por ou para clientes devem ter sua
identificao iniciada por um caractere _.

- 152 -


LISTAS DE EXERCCIOS

Mdulo 01: Introduo programao

01
Aprimorar os seguintes algoritmos descritos na apostila:

E Usar telefone pblico carto
E Fritar um ovo
E Mascar um chiclete
E Trocar lmpadas
E Descascar batatas
E Jogar o Jogo da Forca

02
Montar os diagramas de blocos para os algoritmos desenvolvidos no exerccio
anterior:

E Usar telefone pblico carto
E Fritar um ovo
E Mascar um chiclete
E Trocar lmpadas
E Descascar batatas
E Jogar o Jogo da Forca

- 153 -


Mdulo 02: A linguagem ADVPL

01

Desenvolver um programa que implemente o algoritmo de descascar batatas,
utilizando a estrutura de repetio While, demonstrando quantas batatas
foram descascadas:

02

utilizando a estrutura de repetio FOR, demonstrando quantas batatas foram
descascadas:

03

utilizando a estrutura de repetio FOR, demonstrando quantas batatas faltam
para serem descascadas:

- 154 -


04 Desenvolver um programa que implemente o algoritmo do Jogo da Forca:

05 Desenvolver um programa que implemente o algoritmo do Jogo da Velha:

06
Desenvolver um programa que permita ao usurio pesquisar um cliente
informando seu CNPJ e caso o mesmo exista na base, exibir suas principais
informaes.

07
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.

- 155 -


08
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.

09
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.

10
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.

11
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.

- 156 -


Mdulo 03: Desenvolvendo pequenas customizaes

01
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.

02
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.

03
Desenvolver um gatilho que retorne uma descrio complementar para um
campo vinculado ao campo cdigo utilizado nos exerccios anteriores.

- 157 -


04
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.

05
Proteger a rotina desenvolvida no exerccio anterior, de forma a garantir que
na utilizao da filial como prefixo do ttulo no ir ocorrer duplicidade de
dados no contas a pagar do financeiro.

06
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.

- 158 -


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

Educao Corporativa

Guia de Referncia Rpida
ADVPL Bsico

Matriz Av. Braz Leme, 1.717 02511-000 So Paulo SP Brasil.
Tel.: 55 (11) 3981-7001 www.microsiga.com.br

- 160 -

ADVPL Bsico

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.

E Sintaxe: CTOD(cData)
E Parmetros

cData Caracter 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.

E Sintaxe: CVALTOCHAR(nValor)
E Parmetros

nValor Valor numrico que ser convertido para caractere.

Exemplo:

FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos

- 161 -

ADVPL Bsico

DTOC()

Realiza a converso de uma informao do tipo data para em caracter, sendo o resultado no
formato DD/MM/AAAA.

E Sintaxe: DTOC(dData)
E 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 caracter, sendo o resultado no
formato AAAAMMDD.

E Sintaxe: DTOS(dData)
E 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 caracter com contedo no formato
AAAAMMDD em data.

E Sintaxe: STOD(sData)
E 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)

- 162 -

ADVPL Bsico

STR()

Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos
direita.

E Sintaxe: STR(nValor)
E Parmetros


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.

E Sintaxe: STRZERO(nValor, nTamanho)
E Parmetros

nTamanho Tamanho total desejado para a string retornada.

Exemplo:

NEXT nPercorridos

- 163 -

ADVPL Bsico

VAL()

Realiza a converso de uma informao do tipo caracter em numrica.

E Sintaxe: VAL(cValor)
E 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)

- 164 -

ADVPL Bsico

Matemticas

ACOS()

Funo utilizada para calcular o valor do arco co-seno.

E Sintaxe: ACOS(nValor)
E Parmetros:

nValor Valor entre -1 e 1 de quem ser calculado o Arco Co-Seno.

E Retorno:

Numrico Range de 0 a radianos.

Se o valor informado no parmetro for menor que 1 ou maior que 1, acos
retorna um valor indefinido por default [+ , -]

CEILING()

Funo utilizada para calcular o valor mais prximo possvel de um valor nMax informado como
parmetro para a funo.

E Sintaxe: CELLING(nMax)
E Parmetros

nMax Valor limite para anlise da funo, no formato floating-point.

E Retorno:

Numrico
Valor do tipo double, representando o menor inteiro que maior ou igual ao
valor de nMax. No h retorno de erro na funo.

COS()

Funo utilizada para calcular o valor do co-seno ou co-seno hiperblico.

Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo COS().

E Sintaxe: COS(nAngulo)
E Parmetros:

nAngulo Valor que representa o ngulo em radianos.

E Retorno:

Numrico Valor que representa o co-seno ou co-seno hiperblico do ngulo informado.

- 165 -

ADVPL Bsico

E Situaes invlidas:

Entrada Exceo apresentada Significado da Exceo
QNAN,IND None Sem Domnio
(cosf, cos) INVALID Sem Domnio
x 7.104760e+002 (cosh, coshf) INEXACT+OVERFLOW OVERFLOW

LOG10()

Funo utilizada para calcular o logaritmo natural de um valor numrico, em base 10.

LOG10() uma funo numrica que calcula o logaritmo natural de um nmero. O logaritmo
natural tem como base o valor 10. Devido ao arredondamento matemtico, os valores
retornados por LOG() podem no coincidir exatamente.

E Sintaxe: LOG10(nNatural)
E Parmetros:

nNatural Valor cujo o logaritmo deve ser encontrado.

E Retorno:

Numrico A funo retorna o logaritmo de nNatural se bem sucedidas. Se nNatural for
negativo, estas funes retornam um indefinido, pelo defeito. Se nNatural for
0, retornam INF(infinito).

SIN()

Funo utilizada para calcular o valor do seno ou seno hiperblico. Devemos informar como
parmetro para a funo um valor que representa o angulo em radianos.

funo SIN().

E Sintaxe: SIN(nAngulo)
E Parmetros:

nAngulo Valor do ngulo em radianos.

E Retorno:

Numrico Retorna o valor do seno do ngulo especificado.

E Situaes invlidas:

(senf, sen) INVALID Sem Domnio
x 7.104760e+002 (senh, senhf) INEXACT+OVERFLOW OVERFLOW

- 166 -

ADVPL Bsico

SQRT()

Funo utilizada para calcular a raiz quadrada de um nmero positivo.

E Sintaxe: SQRT(nValor)
E Parmetros:

nValor Um nmero positivo do qual ser calculada a raiz quadrada.

E Retorno:

Numrico Retorna um valor numrico calculado com preciso dupla. A quantidade de
casas decimais exibidas determinada apenas por SET DECIMALS, sem
importar a configurao de SET FIXED. Um nmero negativo <nValor>
retorna zero.

TAN()

Funo utilizada para calcular o valor da tangente ou tangente hiperblica.

funo cos.

E Sintaxe: TAN(nAngulo)
E Parmetros:

nAngulo Valor do ngulo em radianos.

E Retorno:

Numrico Retorna o valor da tangente do ngulo especificado.

E Situaes invlidas:

INVALID Sem Domnio

- 167 -

ADVPL Bsico

Verificao de tipos de variveis

TYPE()

Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.

E Sintaxe: TYPE(cVariavel)
E 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)
ENDIF

VALTYPE()

Determina o tipo do contedo de uma varivel, a qual no foi definida na funo em execuo.

E Sintaxe: VALTYPE(cVariavel)
E Parmetros

cVariavel Nome da varivel que se deseja avaliar.

Exemplo:

STATIC FUNCTION GETTEXTO(nTamanho, cTitulo, cSay)

LOCAL cTexto :=
LOCAL nColF := 0
LOCAL nLargGet := 0
PRIVATE oDlg

Default cTitulo := "Tela para informar texto"
Default cSay := "Informe o texto:"
Default nTamanho := 1

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

cTexto := Space(nTamanho)
nLargGet := Round(nTamanho * 2.5,0)
nColf := Round(195 + (nLargGet * 1.75) ,0)

- 168 -

ADVPL Bsico

Exemplo (continuao):

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 ({}).

E Sintaxe: ARRAY(nLinhas, nColunas)

E 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.

- 169 -

ADVPL Bsico

AADD()

A funo AADD() permite a insero de um item em um array j existente, sendo que este
item podem ser um elemento simples, um objeto ou outro array.

E Sintaxe: AADD(aArray, xItem)
E Parmetros

aArray Array pr-existente no qual ser adicionado o item definido em xItem
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

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

AADD(aDados,aItem) // Adiciona no array aDados o contedo do array aItem


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




- 170 -

ADVPL Bsico

// Desta forma, o array aDados montando com uma estrutura de 03 linhas e 03 colunas, com
// o contedo definido por variveis externas, mas com a mesma forma obtida com o uso do
// comando: aDados := ARRAY(3,3).

ACLONE()

A funo ACLONE() realiza a cpia dos elementos de um array para outro array integralmente.

E Sintaxe: AADD(aArray)
E 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 ultima posio do array passar
a ser nula.

E Sintaxe: ADEL(aArray, nPosio)
E 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.

- 171 -

ADVPL Bsico

// aItens[2] -> antigo aItens[3], o qual foi reordenado como efeito da excluso do item 1.
// aItens[3] -> contedo nulo, por se tratar do item excludo.

ASIZE()

A funo ASIZE permite a redefinio da estrutura de um array pr-existente, adicionando ou
removendo itens do mesmo.

E Sintaxe: ASIZE(aArray, nTamanho)
E Parmetros

aArray Array pr-existente que ter sua estrutura redimensionada.
nTamanho Tamanho com o qual deseja-se redefinir o array. Se o tamanho for menor do
que o atual, sero removidos os elementos do final do array, j se o
tamanho for maior do que o atual sero inseridos itens nulos ao final do
array.

Exemplo:

// Utilizando o array aItens, o qual teve um elemento excludo pelo uso da funo ADEL()

ASIZE(aItens,Len(aItens-1))

// Neste ponto o array aItens possui 02 elementos, ambos com contedos vlidos.

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.

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

aArray Array pr-existente que ter seu contedo ordenado atravs de um critrio
estabelecido.
nInicio Posio inicial do array para incio da ordenao. Caso no seja informado, o
array ser ordenado a partir de seu primeiro elemento.
nItens Quantos itens, a partir da posio inicial devero ser ordenados. Caso no
seja informado, sero ordenados todos os elementos do array.
bOrdem Bloco de cdigo que permite a definio do critrio de ordenao do array.
Caso bOrdem no seja informado, ser utilizado o critrio ascendente.

- 172 -

ADVPL Bsico

Um bloco de cdigo basicamente uma funo escrita em linha. Desta forma
sua estrutura deve suportar todos os requisitos de uma funo, os quais so
atravs da anlise e interpretao de parmetros recebidos, executar um
processamento e fornecer um retorno.

Com base nesse requisito, pode-se definir um bloco de cdigo com a estrutura
abaixo:

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 ultima 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}

- 173 -

ADVPL Bsico

ASCAN()

A funo ASCAN() permite que seja identificada a posio do array que contm uma
determinada informao, atravs da anlise de uma expresso descrita em um bloco de
cdigo.

E Sintaxe: ASCAN(aArray, bSeek)
E Parmetros

aArray Array pr-existente no qual desejasse identificar a posio que contm a
informao pesquisada.
bSeek 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 o
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.

- 174 -

ADVPL Bsico

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.

E Sintaxe: AINS(aArray, nPosicao)
E 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 trata-lo aps a realizao
deste comando.

- 175 -

ADVPL Bsico

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.

E Sintaxe: EVAL(bBloco, xParam1, xParam2, xParamZ)
E 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 a diviso de Y pela multiplicao de X por N ( 100 / 100) 1

DBEVAL()

A funo DBEval() permite que todos os registro de uma determinada tabela sejam analisados
e para cada registro ser executado o bloco de cdigo definido.

E Sintaxe: Array(bBloco, bFor, bWhile)
E 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

- 176 -

ADVPL Bsico

Exemplo 01

Considerando o trecho de cdigo abaixo:

dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()

While !Eof() .And. X5_FILIAL == xFilial("SX5") .And.; X5_TABELA <= mv_par02

nCnt++
dbSkip()
End

O mesmo pode ser re-escrito com o uso da funo DBEVAL():

dbEval( {|x| nCnt++ },,{||X5_FILIAL==xFilial("SX5") .And. X5_TABELA<=mv_par02})

Exemplo 02


dbSelectArea(SX5)
dbSetOrder(1)
dbGotop()

While !Eof() .And. X5_TABELA == cTabela
AADD(aTabela,{X5_CHAVE, Capital(X5_DESCRI)})
dbSkip()
End

Exemplo 02 (continuao):

O mesmo pode ser re-escrito com o uso da funo DBEVAL():

dbEval({|| aAdd(aTabela,{X5_CHAVE,Capital(X5_DESCRI)})},,{|| X5_TABELA==cTabela})

Na utilizao da funo DBEVAL() deve ser informado apenas um dos dois
parmetros: bFor ou bWhile.

- 177 -

ADVPL Bsico

AEVAL()

A funo AEVAL() permite que todos os elementos de um determinada array sejam analisados
e para cada elemento ser executado o bloco de cdigo definido.

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

aArray Array que ser avaliado na execuo da funo.
bBloco Bloco de cdigo principal, contendo as expresses que sero avaliadas para
cada elemento do array informado.

nInicio Elemento inicial do array, a partir do qual sero avaliados os blocos de
cdigo.
nFim Elemento final do array, at o qual sero avaliados os blocos de cdigo.

Exemplo 01:


AADD(aCampos,A1_FILIAL)
AADD(aCampos,A1_COD)
SX3->(dbSetOrder(2))
For nX:=1 To Len(aCampos)
SX3->(dbSeek(aCampos[nX]))
AADD(aTitulos,AllTrim(SX3->X3_TITULO))
Next nX

O mesmo pode ser re-escrito com o uso da funo AEVAL():

aEval(aCampos,{|x| SX3->(dbSeek(x)),IIF(Found(), AAdd(aTitulos,;
AllTrim(SX3->X3_TITULO)))})

- 178 -

ADVPL Bsico

Manipulao de strings

ALLTRIM()

Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado
como parmetro.

A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left
trim).

E Sintaxe: ALLTRIM(cString)
E Parmetros

cString String que ser avaliada para remoo dos espaos a direita e a 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.

E Sintaxe: ASC(cCaractere)
E Parmetros

cCaractere Caracter 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"

- 179 -

ADVPL Bsico


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 a primeira posio de um caracter ou string dentro de outra string especificada.

E Sintaxe: AT(cCaractere, cString )
E 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

- 180 -

ADVPL Bsico

BITON()

Funo utilizada para ligar determinados bits de uma String passada por parametro para a
funo. Alm da string ser alterada, a funo tambm recebe como parmetro um numrico
que indica o bit de inicio a ser alterado, um numrico que indica a quantidade de bits a serem
alterados(ligados) e o tamanho da string passada.

E Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )
E Parmetros

cValue String no qual desejamos ligar os bits.
nBitIni Indica a partir de qual bit, comear a ser ligados os bits na String
nBitEnd Indica a quantidade de bits que sero ligados a partir do inicio.
nStrLen Representa o tamanho da String passada para a funo.

CHR()

Converte um valor nmero referente a uma informao da tabela ASCII no caractere que esta
informao representa.

E Sintaxe: CHR(nASCII)
E Parmetros

nASCII Cdigo ASCII do caractere

Exemplo:

#DEFINE CRLF CHR(13)+CHR(10) // FINAL DE LINHA

DESCEND()

Funo de converso que retorna a forma complementada da expresso string especificada.
Esta funo normalmente utilizada para a criao de indexadores em ordem decrescente

E Sintaxe: DESCEND ( < cString > )
E Parmetros:

cString Corresponde a seqncia de caracteres a ser analisada.

E Retorno:

Caracter

String complementada da string analisada.

- 181 -

ADVPL Bsico

Exemplo:

// Este exemplo utiliza DESCEND() em uma expresso INDEX para criar um ndice de datas de
// ordem descendente:

USE Sales NEW
INDEX ON DESCEND(DTOS(OrdDate)) TO SalesDate

// Depois, DESCEND() pode ser utilizado para fazer uma pesquisa (SEEK) no ndice
// descendente:

DbSEEK(DESCEND(DTOS(dFindDate)))

GETDTOVAL()

Funo utilizada para retornar um numero formatado, de acordo com o valor passado por
parmetro, sendo que ir apenas manter os valores numricos contidos na string passada por
parmetro, verificando se existe algum caractere '.' retornando um numero fracionrio, na
ordem dos nmeros contidos na string.

A funo muito til quando desejamos utilizar o valor numrico de uma data que est
contida em uma string.

E Sintaxe: GETDTOVAL ( < cDtoVal > )

E Parmetros:

cDtoVal Representa uma string contendo um valor numrico no qual ser convertido.

E Retorno:

Numrico Retorna um dado numrico de acordo com o valor informado em <cDtoVal>.

Exemplo:

GetDtoVal('123456') //retorno 123456.0000
GetDtoVal('1/2/3/4/5/6') //retorno 123456.0000
GetDtoVal('fim.123456') //retorno 0.123456
GetDtoVal('teste') //retorno 0.0

- 182 -

ADVPL Bsico

ISALPHA()

Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres alfabtico, permitindo avaliar se o string especificado comea com um caractere
alfabtico. Um caractere alfabtico consiste em qualquer letra maiscula ou minscula de A
a Z.

E Sintaxe: ISALPHA ( < cString > )

E Parmetros:

cString Cadeia de caracteres a ser examinada.

E Retorno:

Lgico Retorna verdadeiro (.T.) se o primeiro caractere em <cString> for alfabtico,
caso contrrio, retorna falso (.F.).

ISDIGIT()

Funo utilizada para determinar se o caractere mais esquerda em uma cadeia de
caracteres um dgito, permitindo avaliar se o primeiro caractere em um string um dgito
numrico entre zero e nove.

E Sintaxe: ISDIGIT ( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja um digto
entre zero e nove; caso contrrio, retorna falso (.F.).

ISLOWER()

Funo utilizada para determinar se o caractere mais esquerda uma letra minscula,
permitindo avaliar se o primeiro caractere de um string uma letra minscula. o contrrio
de ISUPPER(), a qual determina se a cadeia de caracteres comea com uma letra maiscula.
ISLOWER() e ISUPPER() ambas sao relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.

E Sintaxe: ISLOWER( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja minsculo ,

- 183 -

ADVPL Bsico

ISUPPER()

Funo utilizada para determinar se o caractere mais esquerda uma letra maicula,
permitindo avaliar se o primeiro caractere de um string uma letra maicula. o contrrio de
ISLOWER (), a qual determina se a cadeia de caracteres comea com uma letra minscula.
ISLOWER() e ISUPPER() ambas sao relacionadas s funes LOWER() e UPPER(), que
convertem caracteres minsculos para maisculos, e vice-versa.

E Sintaxe: ISUPPER( < cString > )

E Parmetros:


E Retorno:

Lgico Retorna verdadeiro (.T.) caso o primeiro caractere da cadeia seja maisculo ,

LEN()

Retorna o tamanho da string especificada no parmetro.

E Sintaxe: LEN(cString)
E 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)))

- 184 -

ADVPL Bsico

LOWER()

Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.

E Sintaxe: LOWER(cString)
E Parmetros

cString String que ser convertida para caracteres minsculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

LTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
possuam espaos em branco esquerda. Pode ser o caso de, por exemplo, nmeros
convertidos para cadeias de caracteres atravs da funo STR().

LTRIM() relacionada a RTRIM(), a qual remove espaos em branco direita, e a ALLTRIM(),
que remove espaos tanto esquerda quanto direita.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda as cadeias de caracteres, atravs
da insero de caracteres de preenchimento.

E Sintaxe: LTRIM ( < cString > )
E Parmetros:

cString <cString> a cadeia de caracteres a ser copiada sem os espaos em branco
esquerda.

E Retorno:

Caracter LTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
esquerda foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou toda composta de espaos em branco, LTRIM() retorna uma
cadeia de caracteres nula ("").

- 185 -

ADVPL Bsico

MATHC()

Funo utilizada para realizar operaes matemticas com strings que contm um valor
numrico. MATHC() realiza algumas operaes matemticas como: Soma, Subtrao, Diviso,
Multiplicao e Exponenciao.

A funo ir retornar uma string contendo o resultado da operao matemtica, com uma
especificao de at 18 casas de preciso no numero.

E Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )
E Parmetros:

cNum1 String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.
cOperacao Representa a string que indica a operao que desejamos realizar. Olhar na
tabela para verificar quais valores devem ser informados aqui.
cNum2 String contendo um valor numrico, representando o numero no qual
desejamos realizar uma operao.

E Retorno:

Caracter Retorna uma nova string contendo o resultado matemtico da operao.

OEMTOANSI()

Funo que transforma uma string no Formato OEM / MS-DOS Text para uma string ANSI
Text ( formato do Windows ).

Quando utilizamos um programa baseado no MS-DOS para alimentar uma base de dados , os
acentos e caracteres especiais so gravados como texto OEM . Para tornar possvel a correta
visualizao destes dados em uma interface Windows , utilizamos a funo OemToAnsi() para
realizar a converso.

Ao utilizarmos um programa baseado no Windows para alimentar uma base de dados , o texto
capturado no formato ANSI Text . Caso este texto seja utilizado para alimentar uma base de
dados a ser acessada atravs de um programa MS-DOS , devemos converter o dado para OEM
antes de grav-lo , atravs da funo AnsiToOem().

E Sintaxe: OemToAnsi ( < cStringOEM > )
E Parmetros:

cStringOEM String em formato OEM - MsDos a ser convertida.

E Retorno:

Caracter String convertida para ser exibida no Windows ( Formato ANSI ).

- 186 -

ADVPL Bsico

PADL() / PADR() / PADC()

Funes de tratamento de strings que inserem caracteres de preenchimento para completar
um tamanho previamente especificado em vrios formatos como data ou numricos.

Q PADC() centraliza <cExp>, adicionando caracteres de preenchimento direita e
esquerda.
Q PADL() adiciona caracteres de preenchimento esquerda.
Q PADR() adiciona caracteres de preenchimento direita.

Caso o tamanho de <cExp> exceda o argumento <nTamanho>, todas as funes PAD()
truncam string preenchida ao <nTamanho> especificado.

PADC(), PADL(), e PADR() so utilizadas para exibir cadeias de caracteres de tamanho varivel
em uma rea de tamanho fixo. Elas podem ser usadas, por exemplo, para assegurar o
alinhamento com comandos ?? consecutivos. Outra utilizao exibir textos em uma tela de
tamanho fixo, para certificar-se de que o texto anterior foi completamente sobrescrito.

PADC(), PADL(), e PADR() so o contrrio das funes ALLTRIM(), LTRIM(), e LTRIM(), as
quais eliminam espaos em branco esquerda e direita de cadeias de caracteres.

E Sintaxe: PADL / PADR / PADC ( < cExp > , < nTamanho > , [ cCaracPreench ] )
E Parmetros

cExp Caractere, data, ou numrico no qual sero inseridos caracteres de
preenchimento.
nTamanho Tamanho da cadeia de caracteres a ser retornada.
cCaracPreench Caractere a ser inserido em cExp. Caso no seja especificado, o padro
o espao em branco.

E Retorno:

Caracter Retornam o resultado de <cExp> na forma de uma cadeia de caracteres
preenchida com <cCaracPreench>, para totalizar o tamanho
especificado por <nTamanho>.

RAT()

Retorna a ltima posio de um caracter ou string dentro de outra string especificada.

E Sintaxe: RAT(cCaractere, cString)
E Parmetros

cCaractere Caractere ou string que se deseja verificar
cString String na qual ser verificada a existncia do contedo de cCaractere.

- 187 -

ADVPL Bsico

RTRIM()

Funo para tratamento de caracteres utilizada para formatar cadeias de caracteres que
contenham espaos em branco direita. Ela til quando voc deseja eliminar espaos em
branco direita ao se concatenar cadeias de caracteres. o caso tpico com campos de banco
de dados que so armazenados em formato de tamanho fixo. Por exemplo, voc pode usar
RTRIM() para concatenar o primeiro e o ltimo campos de nome para formar uma cadeia de
caracteres de nome.

LTRIM() relacionada a RTRIM(), que remove espaos em branco direita, e a ALLTRIM(),
que remove espaos em branco direita e esquerda.

O contrrio de ALLTRIM(), LTRIM(), e RTRIM() so as funes PADC(), PADR(), e PADL(), as
quais centralizam, alinham direita, ou alinham esquerda cadeias de caracteres, inserindo
caracteres de preenchimento.

E Sintaxe: RTRIM ( < cString > ) --> cTrimString

E Parmetros:

cString <cString> a cadeia de caracteres a ser copiada sem os espaos em branco
direita.

E Retorno:

Caracter

RTRIM() retorna uma cpia de <cString>, sendo que os espaos em branco
direita foram removidos. Caso <cString> seja uma cadeia de caracteres
nula ("") ou totalmente composta por espaos, RTRIM() retorna uma cadeia
de caracteres nula ("").

SPACE()

Funo de tratamento de caracteres utilizada para retornar uma quantidade especificada de
espaos. A utilizao desta funo tem o mesmo efeito que REPLICATE(' ', <nCont>), e
normalmente utilizada para inicializar uma varivel do tipo caractere, antes que a mesma seja
associada a um GET.

Sintaxe: SPACE ( < nCont > )

E Parmetros:

nCont A quantidade de espaos a serem retornados, sendo que o nmero mximo
65.535 (64K).

E Retorno:

Caracter Retorna uma cadeia de caracteres. Se <nCont> for zero, SPACE()retorna
uma cadeia de caracteres nula ("").

- 188 -

ADVPL Bsico

STRTOKARR()

Funo utilizada para retornar um array, de acordo com os dados passados como parmetro
para a funo. Esta funo recebe uma string <cValue> e um caracter <cToken> que
representa um separador, e para toda ocorrncia deste separador em <cValue> adicionado
um item no array.

E Sintaxe: STRTOKARR ( < cValue > , < cToken > )

E Parmetros:

cValue Representa a cadeia de caracteres no qual desejamos separar de acordo com
<cToken>.
cToken Representa o caracter que indica o separador em <cValue>.

E Retorno:

Array Array de caracteres que representa a string passada como parmetro.

Exemplo:

STRTOKARR('1;2;3;4;5', ';') //retorna {'1','2','3','4','5'}

STRTRAN()

Funo utilizada para realizar a busca da ocorrncia da string, sendo case sensitive.

E Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [
nCount ] )

E Parmetros:

cString Seqncia de caracteres ou campo memo a ser pesquisado.
cSearch Seqncia de caracteres a ser procurada em cString.
cReplace Seqncia de caracteres que deve substituir a string cSearch. Caso no
seja especificado, as ocorrncias de cSearch em cString sero substitudas
por uma string nula ("").
nStart nStart corresponde ao nmero seqencial da primeira ocorrncia de
cSEarch em cString a ser substituda por cReplace. Se este argumento for
omitido , o default 1 ( um ) . Caso seja passado um numero menor que
1, a funo retornar uma string em branco ("").
nCount nCount corresponde ao nmero mximo de trocas que dever ser realizada
pela funo . Caso este argumento no seja especificado, o default
substituir todas as ocorrncias encontradas.

E Retorno:

Code-Block

A funo STRTRAN retorna uma nova string, com as ocorrncias
especificadas de cSearch trocadas para cReplace, conforme
parametrizao.

- 189 -

ADVPL Bsico

STUFF()

Funo que 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.

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

E Parmetros:

cString A cadeia de caracteres destino na qual sero eliminados e inseridos
caracteres.
nPosInicial A posio inicial na cadeia de caracteres destino onde ocorre a
insero/eliminao.
nExcluir A quantidade de caracteres a serem eliminados.
cAdicao A cadeia de caracteres a ser inserida.

E Retorno:

Caracter Retorna a nova string gerada pela funo com as modificaes.

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).

E Sintaxe: SUBSTR(cString, nPosInicial, nCaracteres)
E Parmetros

cString String que se deseja verificar
nPosInicial Posio inicial da informao que ser extrada da string
nCaracteres Quantidade de caracteres que dever ser retornada a partir daquele ponto
(inclusive).

Exemplo:

cCampo := A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_

- 190 -

ADVPL Bsico

TRANSFORM()

Funo de converso que formata valores caractere, data, lgicos e numricos conforme um
string de mscara especificado, a qual inclui uma combinao de strings de template e funes
de picture. Ela faz o mesmo que a clusula PICTURE do comando @...SAY, sendo normalmente
utilizada para formatar dados a serem enviados tela ou impressora.

E Sintaxe: TRANSFORM ( < cExp > , < cSayPicture > )

E Parmetros:

cExp O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
cSayPicture Uma string de caracteres de mscara e template usado para descrever o
formato da cadeia de caracteres a ser retornada.

E Retorno:

- Retorna a converso de <cExp> para uma cadeia de caracteres formatada
conforme a definio em <cSayPicture>.

UPPER()

Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.

E Sintaxe: UPPER(cString)
E Parmetros

cString String que ser convertida para caracteres maisculos.

Exemplo:

cTexto := ADVPL

MSGINFO(Texto:+LOWER(cTexto))

- 191 -

ADVPL Bsico

Manipulao de data / hora

CDOW()

Funo que converte uma data para uma cadeia de caracteres.

E Sintaxe: CDOW( dExp )
E Parmetros:

dExp Data que ser convertida.

E Retorno:

cDayWeek Nome do dia da semana como uma cadeia de caracteres. A primeira letra
maiscula e as demais minsculas.

Exemplo:

dData := DATE() // Resultado: 09/01/90
cDiaDaSemana := CDOW(DATE()) // Resultado: Friday
cDiaDaSemana := CDOW(DATE() + 7) // Resultado: Friday
cDiaDaSemana := CDOW(CTOD("06/12/90")) // Resultado: Tuesday

CMONTH()

Funo de converso de datas que retorna uma cadeia de caracteres com o nome do ms em
ingls.

E Sintaxe: CMONTH( dData )
E Parmetros:

dData Data que ser convertida.

E Retorno:

cMonth Retorna o nome do ms em uma cadeia de caracteres. A primeira letra do
retorno em maiscula e o restante do nome, em minsculas.

Exemplo:

cMes := CMONTH(DATE()) // Resultado: September
cMes := CMONTH(DATE() + 45) // Resultado: October
cMes := CMONTH(CTOD("12/01/94")) // Resultado: December
cMes := SUBSTR(CMONTH(DATE()), 1, 3) + STR(DAY(DATE())) // Resultado: Sep 1

- 192 -

ADVPL Bsico

DATE()

Funo que retorna a data do atual sistema. O formato de sada controlado pelo comando
SET DATE, sendo que o formato padro mm/dd/yy.

E Sintaxe: DATE()
E Parmetros:

Nenhum .

E Retorno:

dData Data do sistema.

Exemplo:

dData := DATE() + 30 // Resultado: 10/01/01
dData := DATE() - 30 // Resultado: 08/02/90
dData := DATE()
cMes := CMONTH(dData) // Resultado: September

DAY()

Funo de converso de datas usada para converter o valor data em um nmero inteiro que
representa o dia do ms. Esta funo pode ser usada em conjunto com CMONTH() e YEAR()
para formatar datas. Pode ser usada tambm em diversos clculos envolvendo datas.

E Sintaxe: DAY( dData )
E Parmetros:


E Retorno:

nDias Se o ms do argumento dData for fevereiro, anos bissextos so
considerados. Se a data do argumento dData for 29 de fevereiro e o ano no
for bissexto, ou se o argumento dData for vazio.

Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
nDia := DAY(DATE()) // Resultado: 1
nDia := DAY(DATE()) + 1 // Resultado: 2
nDia := DAY(CTOD("12/01/94")) // Resultado: 1
// Este exemplo mostra a funo DAY() usada em conjunto com CMONTH() e
YEAR() para formatar o valor da data:
dData := Date()
cData := CMONTH(dData) + STR(DAY(dData)) + "," + STR(YEAR(dData)) // Resultado: June
15, 2001

- 193 -

ADVPL Bsico

DOW()

Funo que converte uma data para o valor numrico que representa o dia da semana. til
quando se deseja fazer clculos semanais. DOW() similar a CDOW(), que retorna o dia da
semana como uma cadeia de caracteres.

E Sintaxe: DOW( dData )
E Parmetros:


E Retorno:

nDia Retorna um nmero entre zero e sete, representando o dia da semana. O
primeiro dia da semana 1 (Domingo) e o ltimo 7 (Sbado). Se a data
for vazia ou invlida, DOW() retorna zero.

Exemplo:

nDiaDaSemana := DOW(DATE()) // Resultado: 3
cDiaDaSemana := CDOW(DATE()) // Resultado: Tuesday
nDiaDaSemana := DOW(DATE() - 2) // Resultado: 1
cDiaDaSemana := CDOW(DATE() - 2) // Resultado: Sunday

DTOC()

Funo para converso de uma data para uma cadeia de caracteres formatada segundo o
padro corrente, definido pelo comando SET DATE. Se for necessria a utilizao de
formatao especial, use a funo TRANSFORM().

Em expresses de ndices de arquivo, use DTOS() no lugar de DTOC() para converter datas
para cadeia de caracteres.

E Sintaxe: DTOC( dData )
E Parmetros:


E Retorno:

cData uma cadeia de caracteres representando o valor da data. O retorno
formatado utilizando-se o formato corrente definido pelo comando SET DATE
FORMAT. O formato padro mm/dd/yy. Para uma data nula ou invlida, o
retorno ser uma cadeia de caracteres com espaos e tamanho igual ao
formato atual.

Exemplo:

cData := DATE() // Resultado: 09/01/90
cData := DTOC(DATE()) // Resultado: 09/01/90
cData := "Today is " + DTOC(DATE()) // Resultado: Today is 09/01/90

- 194 -

ADVPL Bsico

DTOS()

Funo para converso de uma data que pode ser usada para criar expresses de ndice. O
resultado estruturado visando manter a ordem correta do ndice (ano, ms, dia).

E Sintaxe: DTOS( dData )
E Parmetros:


E Retorno:

sData Retorna uma cadeia de caracteres com oito byte de tamanho no formato
yyyymmdd. Quando dData nulo ou invalido, DTOS() retorna uma cadeia
de caracteres com oito espaos. O valor retornado no afetado pela
formato da data corrente.

Exemplo:

cData := DATE() // Resultado: 09/01/90
cData := DTOS(DATE()) // Resultado: 19900901
nLen := LEN(DTOS(CTOD(""))) // Resultado: 8

ELAPTIME()

Funo que retorna uma cadeia de caracteres contendo a diferena de tempo no formato
hh:mm:ss, onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

E Sintaxe: ElapTime( cHoraInicial , cHoraFinal )
E Parmetros:

cHoraInicial Informe a hora inicial no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),
mm os minutos e ss os segundos
CHoraFinal Informe a hora final no formato hh:mm:ss, onde hh a hora ( 1 a 24 ), mm
os minutos e ss os segundos.

E Retorno:

Caracter A diferena de tempo no formato hh:mm:ss, onde hh a hora ( 1 a 24 ),
mm os minutos e ss os segundos.

Exemplo:

cHoraInicio := TIME() // Resultado: 10:00:00
...
<instrues>
...
cElapsed := ELAPTIME(TIME(), cHoraInicio)

- 195 -

ADVPL Bsico

MONTH()

Funo de converso que extrai da data o valor numrico do ms, semelhante a funo que
retorna o nome do ms a partir do valor de dData.

E Sintaxe: MONTH( dData )
E Parmetros:


E Retorno:

Numrico >=0 e <=12 Para uma data vlida.
0 Se a data for nula ou invlida

Exemplo:

nMes := MONTH(DATE()) // Resultado: 9
nMes := MONTH(DATE()) + 1 // Resultado: 10

SECONDS()

Esta funo retorna o nmero de segundos decorridos desde a meia-noite, segundo a hora do
sistema. Est relacionada funo TIME() que retorna a hora do sistema como uma cadeia de
caracteres no formato hh:mm:ss.

E Sintaxe: SECONDS()
E Parmetros:

Nenhum .

E Retorno:

Numrico >=0 e <=86399 Retorna a hora do sistema em segundos. O valor
numrico representa o nmero de segundos decorridos desde a meia-noite,
baseado no relgio de 24 horas e varia de 0 a 86399.

Exemplo:

cHora := TIME() // Resultado: 10:00:00
cSegundos := SECONDS() // Resultado: 36000.00

//Este exemplo usa a funo SECONDS() para cronometrar o tempo decorrido:

LOCAL nStart, nElapsed
nStart:= SECONDS()

- 196 -

ADVPL Bsico

TIME()

Funo que retorna a hora do sistema como uma cadeia de caracteres, e que est relacionada
com SECONDS(), que retorna o valor inteiro representando o nmero de segundos desde a
meia-noite. SECONDS() geralmente usada no lugar de TIME() para clculos.

E Sintaxe: TIME()
E Parmetros:

Nenhum .

E Retorno:

Caracter A hora do sistema como uma cadeia de caracteres no formato hh:mm:ss
onde hh a hora ( 1 a 24 ), mm os minutos e ss os segundos.

Exemplo:

cTime := TIME() // Resultado: 10:37:17
cHora := SUBSTR(cTime, 1, 2) // Resultado: 10
cMinutos := SUBSTR(cTime, 4, 2) // Resultado: 37
cSegundos := SUBSTR(cTime, 7, 2) // Resultado: 17

YEAR()

YEAR() uma funo de converso de data que extrai o valor numrico do ano. YEAR()
membro de um grupo de funes que retornam valores numricos de uma data. O grupo inclui
DAY() e MONTH() que retornam o dia e o ms como valores numricos.

E Sintaxe: YEAR( dData )
E Parmetros:


E Retorno:

Numrico Valor numrico do ano da data especificada em dData incluindo os dgitos
do sculo. O valor retornado no afetado pelos valores especificados pelos
comandos SET DATE ou SET CENTURY.

Para uma data invlida ou nula ser retornado o valor 0.

Exemplo 01:

dAno := YEAR(dData) // Resultado: 2001
dAno := YEAR(dData) + 11 // Resultado: 2012

- 197 -

ADVPL Bsico

Exemplo 02:

// Este exemplo cria uma funo de usurio que usa a funo YEAR() para formatar o valor da
// data:

cData := Mdy(DATE()) // Result: September 20, 1990
FUNCTION Mdy( dDate )
RETURN CMONTH(dDate) + " " + LTRIM(STR(DAY(dDate))) + "," + STR(YEAR(dDate))

Manipulao de variveis numricas

ABS()

Retorna um valor absoluto (independente do sinal) com base no valor especificado no
parmetro.

E Sintaxe: ABS(nValor)
E 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.

E Sintaxe: INT(nValor)
E Parmetros


Exemplo:

STATIC FUNCTION COMPRAR(nQuantidade)

LOCAL nDinheiro := 0.30
LOCAL nPrcUnit := 0.25

- 198 -

ADVPL Bsico


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.

E Sintaxe: NOROUND(nValor, nCasas)
E Parmetros

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.

E Sintaxe: ROUND(nValor, nCasas)
E Parmetros

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

- 199 -

ADVPL Bsico

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).

E Sintaxe: Select(cArea)
E 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.

E Sintaxe: DbGoto(nRecno)
E 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

- 200 -

ADVPL Bsico

DBGOTOP()

Move o cursor da rea de trabalho ativa para o primeiro registro lgico.

E Sintaxe: DbGoTop()
E 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.

E Sintaxe: DbGoBotton()
E 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.

- 201 -

ADVPL Bsico

DBSELECTAREA()

Define a rea de trabalho especificada com sendo a rea ativa. Todas as operaes
subseqentes que fizerem referncia a uma rea de trabalho a utilizao, a menos que a rea
desejada seja informada explicitamente.

E Sintaxe: DbSelectArea(nArea | cArea)
E 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.

E Sintaxe: DbSetOrder(nOrdem)
E 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

- 202 -

ADVPL Bsico

DBORDERNICKNAME()

Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os seus prprios
ndices e no momento da incluso deve criar o NICKNAME para o mesmo.

E Sintaxe: DbOrderNickName(NickName)
E 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 indicando se o
posicionamento foi efetuado com sucesso, ou seja, se a informao especificada na chave de
busca foi localizada na rea de trabalho.

E Sintaxe: DbSeek(cChave, lSoftSeek, lLast)
E Parmetros

cChave
Dados do registro que deseja-se localizar, de acordo com a ordem de busca
previamente especificada pelo comando DbSetOrder(), ou seja, de acordo
com o ndice ativo no momento para a rea de trabalho.
lSoftSeek
Define se o cursor ficar posicionado no prximo registro vlido, em relao
a chave de busca especificada, ou em final de arquivo, caso no seja
encontrada exatamente a informao da chave. Padro .F.
lLast
Define se o cursor ser posicionado no primeiro ou no ltimo registro de um
intervalo com as mesmas informaes especificadas na chave. Padro .F.

Exemplo 01 Busca exata

DbSelectArea(SA1)
DbSetOrder(1) // acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA

IF DbSeek(01 + 000001 + 02 ) // Filial: 01, Cdigo: 000001, Loja: 02

MsgInfo(Cliente localizado, Consulta por cliente)

Else
MsgAlert(Cliente no encontrado, Consulta por cliente)

Endif

- 203 -

ADVPL Bsico

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
acessar novamente a 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.

E Sintaxe: DbSkip(nRegistros)
E 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

- 204 -

ADVPL Bsico

Exemplo 02 Retrocedendo registros

DbSelectArea(SA1)
DbSetOrder(2) // A1_FILIAL + A1_NOME
DbGoBotton() // Posiciona o cursor no final da rea de trabalho ativa

While !BOF() // Enquanto o cursor da rea de trabalho ativa no indicar incio de arquivo
MsgInfo(Voc est no cliente: + A1_NOME)
DbSkip(-1)
End

DBSETFILTER()

Define um filtro para a rea de trabalho ativa, o qual pode ser descrito na forma de um bloco
de cdigo ou atravs de uma expresso simples.

E Sintaxe: DbSetFilter(bCondicao, cCondicao)
E Parmetros

bCondicao Bloco de 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.

- 205 -

ADVPL Bsico

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

E Sintaxe: DbStruct()
E 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.

E Sintaxe: RecLock(cAlias,lInclui)
E 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

- 206 -

ADVPL Bsico

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
ENDIF

A linguagem ADVPL possui variaes da funo RecLock(), as quais so:

E RLOCK()
E 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.

E Sintaxe: MsUnLock()
E 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
ENDIF

- 207 -

ADVPL Bsico

A linguagem ADVPL possui variaes da funo MsUnlock(), as quais so:

E UNLOCK()
E DBUNLOCK()
E 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 da integridade da informao.

E Sintaxe: SoftLock(cAlias)
E 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

- 208 -

ADVPL Bsico

DBDELETE()

Efetua a excluso lgica do registro posicionado na rea de trabalho ativa, sendo necessria
sua utilizao em conjunto com as funes RecLock() e MsUnLock().

E Sintaxe: DbDelete()
E 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.
ENDIF

DBUSEAREA()

Define um arquivo de base de dados como uma rea de trabalho disponvel na aplicao.

E Sintaxe: DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)

E Parmetros

lNovo
Parmetro opcional que permite que se caso o cAlias especificado j
esteja em uso, ele seja fechado antes da abertura do arquivo da base de
dados.
cDriver
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.
cArquivo
Nome do arquivo de base de dados que ser aberto com o alias
especificado.
cAlias Alias para referncia do arquivos de base de dados pela aplicao.
lComparilhado Se o arquivo poder ser utilizado por outras conexes.
lSoLeitura Se o arquivo poder ser alterado pela conexo ativa.

Exemplo:

DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()

- 209 -

ADVPL Bsico

DBCLOSEAREA()

Permite que um alias presente na conexo seja fechado, o que viabiliza seu reuso em outro
operao. Este comando tem efeito apenas no alias ativo na conexo, sendo necessria sua
utilizao em conjunto com o comando DbSelectArea().

E Sintaxe: DbCloseArea()
E 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.

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

cAlias
Alias de referncia da tabela para a qual ser efetuado o controle da
numerao seqencial.
cCampo Nome do campo no qual est implementado o controle da numerao.
cAliasSXE
Parmetro opcional, quando o nome do alias nos arquivos de controle de
numerao no o nome convencional do alias para o sistema ERP.
nOrdem Nmero do ndice para verificar qual a prxima ocorrncia do nmero.

CONFIRMSXE()

Confirma o nmero alocado atravs do ltimo comando GETSXENUM().

E Sintaxe: CONFIRMSXE(lVerifica)
E Parmetros

lVerifica

Verifica se o nmero confirmado no foi alterado, e por conseqncia j
existe na base de dados.

- 210 -

ADVPL Bsico

ROLLBACKSXE()

Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao
disponvel para outras conexes.

E Sintaxe: ROLLBACKSXE()
E 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.

E Sintaxe: ExistChav(cAlias, cConteudo, nIndice)
E 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.

E Sintaxe: ExistCpo(cAlias, cConteudo, nIndice)
E 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.

- 211 -

ADVPL Bsico

NAOVAZIO()

Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio.

E Sintaxe: NaoVazio()
E Parmetros

Nenhum .

NEGATIVO()

Retorna .T. ou .F. se o contedo digitado para o campo negativo.

E Sintaxe: Negativo()
E 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().

E Sintaxe: Pertence(cString)
E 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.

E Sintaxe: Positivo()
E Parmetros

Nenhum .

TEXTO()

Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou
alfanumricos.

E Sintaxe: Texto()
E Parmetros

Nenhum .

- 212 -

ADVPL Bsico

VAZIO()

Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.

E Sintaxe: Vazio()
E 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.

E Sintaxe: GETMV(cParametro)
E 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.

E Sintaxe: GETNEWPAR(cParametro, cPadrao, cFilial)
E Parmetros

cParametro

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.

- 213 -

ADVPL Bsico

PUTMV()

Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.

E Sintaxe: PUTMV(cParametro, cConteudo)
E Parmetros

cParametro
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.

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

cParametro

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.

- 214 -

ADVPL Bsico

Componentes da interface visual

MSDIALOG()

Define o componente MSDIALOG(), o qual utilizado como base para os demais componentes
da interface visual, pois um componente MSDIALOG() uma janela da aplicao.

E Sintaxe:

DEFINE MSDIALOG oObjetoDLG TITLE cTitulo FROM nLinIni,nColIni TO nLiFim,nColFim OF
oObjetoRef UNIDADE

E 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

- 215 -

ADVPL Bsico

MSGET()

Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis
na tela da interface.

E Sintaxe:

@ nLinha, nColuna MSGET VARIAVEL SIZE nLargura,nAltura UNIDADE OF oObjetoRef F3 cF3
VALID VALID WHEN WHEN PICTURE cPicture

E Parmetros

nLinha, nColuna
Posio do objeto MsGet em funo da janela em que ele ser
definido.
VARIAVEL
Varivel da aplicao que ser vinculada ao objeto MsGet, que
definir suas caractersticas e na qual ser armezanado o que for
informado no campo.
nLargura,nAltura Dimenses do objeto MsGet para exibio do texto.
oObjetoRef Objeto dialog no qual o componente ser definido.
cF3 String que define a consulta padro que ser vinculada ao campo.
VALID Funo de validao para o campo.
WHEN
Condio para manipulao do campo, a qual pode ser diretamente
.T. ou .F., ou uma varivel ou uma chamada de funo.
cPicture String contendo a definio da Picture de digitao do campo.

Exemplo:

@ 010,050 MSGET cCGC SIZE 55, 11 OF oDlg PIXEL PICTURE "@R 99.999.999/9999-99";
VALID !Vazio()

- 216 -

ADVPL Bsico

SAY()

Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de
interface.

E Sintaxe:

@ nLinha, nColuna SAY cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef

E 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.

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.

E Sintaxe: BUTTON()

@ nLinha,nColuna BUTTON cTexto SIZE nLargura,nAltura UNIDADE OF oObjetoRef
ACTION AO

E 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.
AO
Funo ou lista de expresses que define o comportamento do boto
quando ele for utilizado.

- 217 -

ADVPL Bsico

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.

E Sintaxe: SBUTTON()

DEFINE SBUTTON FROM nLinha, nColuna TYPE N ACTION AO STATUS OF oObjetoRet

E Parmetros

nLinha, nColuna
Posio do objeto sButton em funo da janela em que ele ser
definido.
TYPE N
Nmero que indica o tipo do boto (imagem) pr-definida que ser
utilizada.
AO
Funo ou lista de expresses que define o comportamento do boto
quando ele for utilizado.
STATUS Propriedade de uso do boto: ENABLE ou DISABLE
oObjetoRet Objeto dialog no qual o componente ser definido.

Exemplo:
ENABLE OF oDlg

E Visual dos diferentes tipos de botes disponveis

- 218 -

ADVPL Bsico

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.

E Sintaxe: AXPESQUI()
E Parmetros

Nenhum .

- 219 -

ADVPL Bsico

AXVISUAL()

Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme
demonstrado no tpico sobre a interface AxCadastro().

E Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;
aButtons, lMaximized )

E Parmetros

cAlias Tabela cadastrada no Dicionrio de Tabelas (SX2) que ser editada
nReg Record number (recno) do registro posicionado no alias ativo.
nOpc
Nmero da linha do aRotina que definir o tipo de edio (Incluso,
Alterao, Excluso, Visualizao).
aAcho
Vetor com nome dos campos que sero exibidos. Os campos de usurio
sempre sero exibidos se no existir no parmetro um elemento com a
expresso "NOUSER".
nColMens Parmetro no utilizado.
cMensagem Parmetro no utilizado.
cFunc
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
aButtons
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
lMaximized Indica se a janela dever ser ou no maximizada

AXINCLUI()

Funo de incluso padro das informaes de um registro, no formato Enchoice, conforme

E Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;

E Parmetros

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

- 220 -

ADVPL Bsico

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
Indica se a enchoice esta sendo criada em uma consulta F3 para utilizar
variveis de memria
cTransact Funo que ser executada dentro da transao da AxFunction()
aButtons
aParam
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 transao da
AxFunction().
aAuto
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser
executada a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as
validaes do SX3
lVirtual
Indica se a Enchoice() chamada pela AxFunction() utilizar variveis de
memria ou os campos da tabela na edio

AXALTERA()

Funo de alterao padro das informaes de um registro, no formato Enchoice, conforme

E Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens, cMensagem,;
cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual, lMaximized)

E Parmetros

Vide documentao de parmetros da funo AxInclui().

- 221 -

ADVPL Bsico

AXDELETA()

Funo de excluso padro das informaes de um registro, no formato Enchoice, conforme

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

E Parmetros

nOpc
cTransact Funo que ser executada dentro da transao da AxFunction()
aCpos Vetor com nome dos campos que podero ser editados
aButtons
aParam
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 transao da
AxFunction().
aAuto
Array no formato utilizado pela funcionalidade MsExecAuto(). Caso seja
informado este array, no ser exibida a tela de interface, e ser
executada a funo EnchAuto().
aAuto[n][1] := Nome do campo
aAuto[n][2] := Contedo do campo
aAuto[n][3] := Validao que ser utilizada em substituio as
validaes do SX3

- 222 -

ADVPL Bsico

Funes visuais para aplicaes

ALERT()

E Sintaxe: AVISO(cTexto)
E Parmetros

cTexto Texto a ser exibido

AVISO()

E Sintaxe: AVISO(cTitulo, cTexto, aBotoes, nTamanho)
E Retorno: numrico indicando o boto selecionado.

E Parmetros

cTitulo Ttulo da janela
cTexto Texto do aviso
aBotoes Array simples (vetor) com os botes de opo
nTamanho Tamanho (1,2 ou 3)

- 223 -

ADVPL Bsico

FORMBACTH()

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

cTitulo Ttulo da janela
aTexto
Array simples (vetor) contendo cada uma das linhas de texto que sero
exibidas no corpo da tela.
aBotoes
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

- 224 -

ADVPL Bsico

MSGFUNCTIONS()

E Sintaxe: MSGALERT(cTexto, cTitulo)
E Sintaxe: MSGINFO(cTexto, cTitulo)
E Sintaxe: MSGSTOP(cTexto, cTitulo)
E Sintaxe: MSGYESNO(cTexto, cTitulo)

E Parmetros

cTexto Texto a ser exibido como mensagem
cTitulo Ttulo da janela de mensagem
MSGALERT

MSGINFO

MSGSTOP

MSGYESNO

- 225 -

ADVPL Bsico

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()).

E Sintaxe: GETAREA()
E Retorno: Array contendo {Alias(),IndexOrd(),Recno()}

E 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.

E Sintaxe: RESTAREA(aArea)
E Parmetros

aArea
Array contendo: {cAlias, nOrdem, nRecno}, normalmente gerado pelo
uso da funo GetArea().

Exemplo:

// ALIAS ATIVO ANTES DA EXECUO DA ROTINA SN3
User Function XATF001()

LOCAL cVar
LOCAL aArea := GetArea()
LOCAL lRet := .T.

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 )

Programação+ADVPL+I - P10Capacitação Interna

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Programação+ADVPL+I - P10Capacitação Interna

Cargado por

Copyright:

Formatos disponibles

Educao Corporativa

También podría gustarte