Escolar Documentos
Profissional Documentos
Cultura Documentos
Advpl Básico
Advpl Básico
Introduo programao e
ADVPL bsico
(Capacitao Interna)
ESTRUTURA DO TREINAMENTO
OBJETIVOS DO CURSO................................................................................................................................. 6
MDULO 01: Introduo programao...................................................................................................... 7
1.
Lgica de Programao............................................................................................................... 7
1.2.
Desenvolvendo algoritmos.......................................................................................................... 8
1.2.1. Estudando algoritmos..................................................................................................................9
1.2.2. Teste de mesa.......................................................................................................................... 11
2.
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.
4.
4.2.
4.3.
Escopo de variveis................................................................................................................... 29
4.4.
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.
6.
7.
8.
Funes............................................................................................................................................. 69
7.1.
7.2.
9.2.
9.3.
O
9.3.1.
9.3.2.
9.3.3.
Configurador do Protheus...................................................................................................... 94
Funcionalidades Abordadas ........................................................................................................ 94
Estruturas bsicas da aplicao ERP Protheus............................................................................... 94
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.
11.1.
11.2.
11.3.
11.4.
12.
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.
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.
13.
13.1.
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.
15.
15.1.
16.
17.
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
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
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
Lgica de programao
determinado objetivo.
tcnica
de
encadear
pensamentos
para
atingir
Seqncia Lgica
Estes pensamentos, podem ser descritos como uma seqncia de instrues, que devem ser
seguidas para se cumprir uma determinada tarefa.
Instrues
Na linguagem comum, entende-se por instrues um conjunto de regras ou normas definidas
para a realizao ou emprego de algo.
Em informtica, porm, instruo a informao que indica a um computador uma ao
elementar a executar. Convm ressaltar que uma ordem isolada no permite realizar o
processo completo, para isso necessrio um conjunto de instrues colocadas em ordem
seqencial lgica.
Por exemplo, se quisermos fazer uma omelete de batatas, precisaremos colocar em prtica
uma srie de instrues: descascar as batatas, bater os ovos, fritar as batatas, etc. evidente
que essas instrues tm que ser executadas em uma ordem adequada no se pode
descascar as batatas depois de frit-las.
Dessa maneira, uma instruo tomada em separado no tem muito sentido; para obtermos o
resultado, precisamos colocar em prtica o conjunto de todas as instrues, na ordem correta.
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:
Chupar uma bala
1. Pegar a bala;
2. Retirar o papel;
3. Chupar a bala;
4. Jogar o papel no lixo.
Somar dois nmeros quaisquer
1. Escreva o primeiro nmero no retngulo A;
2. Escreva o segundo nmero no retngulo B;
3. Some o nmero do retngulo A com nmero do retngulo B e coloque o
resultado no retngulo C.
1.2.1.
Estudando algoritmos
Mascar um chiclete
Utilizar um telefone pblico carto
Fritar um ovo
Trocar lmpadas
Descascar batatas
Jogar o jogo da forca
Calcular a mdia de notas
Jogar o jogo da velha contra o algoritmo
Mascar um chiclete
1.
2.
3.
4.
Pegar o chiclete
Retirar o papel
Mastigar
Jogar o papel no lixo
os
quais
foram
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.
2.
3.
4.
5.
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.
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
1. Enquanto houver notas a serem recebidas:
a. Receber a nota;
2. Some todas as notas recebidas;
3. Divida o total obtido pela quantidade de notas recebidas;
4. Exiba a mdia das notas.
Teste de mesa:
1. Para cada nota informada, receber e registrar na tabela abaixo:
ID
Nota
2. Ao trmino das notas, a tabela dever conter todas as notas informadas, como abaixo:
ID
1
2
3
4
5
6
Nota
8.0
7.0
8.0
8.0
7.0
7.0
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
Indica o incio e o fim de um processamento.
Terminador
Processamento em geral.
Processamento
obtidos
com
um
Exibio
Documento
Indica
um
documento
utilizado
pelo
processamento,
seja
para
entrada
de
informaes ou para exibio dos dados
disponveis aps um processamento.
2.2.1.
Estruturas de deciso
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
Aes anteriores
...
Falso
Anlise da
condio
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo aps a
tomada da
deciso
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.
Aes anteriores
...
Falso
Anlise da
condio 1
Verdadeiro
Ao vinculada a
condio 1
Verdadeiro
Ao vinculada a
condio 2
Verdadeiro
Ao vinculada a
condio N
Falso
Anlise da
condio 2
Falso
Anlise da
condio N
Falso
Continuao do
fluxo aps a
tomada da
deciso
2.2.2.
Estruturas de repetio
Aes anteriores
...
Anlise da
condio
Loop
Falso
Verdadeiro
Ao vinculada ao
resultado
verdadeiro
Continuao do
fluxo
...
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
(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:
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).
Programao de RPC
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.
Linhas de Programa
As linhas existentes dentro de um arquivo texto de cdigo de programa podem ser linhas de
comando, linhas de comentrio ou linhas mistas.
Linhas de Comando
Linhas de comando possuem os comandos ou instrues que sero executadas. Por exemplo:
Local nCnt
Local nSoma := 0
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Linhas de Comentrio
Todas as linhas iniciadas com um sinal de asterisco so consideradas como comentrio. Podese utilizar a palavra NOTE ou dois smbolos da letra "e" comercial (&&) para realizar a funo
do sinal de asterisco. Porm todas estas formas de comentrio de linhas so obsoletas e
existem apenas para compatibilizao com o padro xBase. A melhor maneira de comentar
linhas em ADVPL utilizar duas barras transversais:
// Programa para clculo do total
// Autor: Microsiga Software S.A.
// Data: 2 de outubro de 2001
Outra forma de documentar textos utilizar as barras transversais juntamente com o
asterisco, podendo-se comentar todo um bloco de texto sem precisar comentar linha a linha:
/*
Programa para clculo do total
Autor: Microsiga Software S.A.
Data: 2 de outubro de 2001
*/
Todo o texto encontrado entre a abertura (indicada pelos caracteres /*) e o fechamento
(indicada pelos caracteres */) considerado como comentrio.
Linhas Mistas
O ADVPL tambm permite que existam linhas de comando com comentrio. Isto possvel
adicionando-se as duas barras transversais (//) ao final da linha de comando e adicionando-se
o texto do comentrio:
Local nCnt
Local nSoma := 0 // Inicializa a varivel com zero para a soma
For nCnt := 1 To 10
nSoma += nCnt
Next nCnt
Tamanho da Linha
Assim como a linha fsica, delimitada pela quantidade de caracteres que pode ser digitado no
editor de textos utilizado, existe uma linha considerada linha lgica. A linha lgica, aquela
considerada para a compilao como uma nica linha de comando.
A princpio, cada linha digitada no arquivo texto diferenciada aps o pressionamento da tecla
<Enter>. Ou seja, a linha lgica, a linha fsica no arquivo. Porm algumas vezes, por
limitao fsica do editor de texto ou por esttica, pode-se "quebrar" a linha lgica em mais de
uma linha fsica no arquivo texto. Isto efetuado utilizando-se o sinal de ponto-e-vrgula (;).
If !Empty(cNome) .And. !Empty(cEnd) .And. ; <enter>
!Empty(cTel) .And. !Empty(cFax) .And. ; <enter>
!Empty(cEmail)
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
Neste exemplo existe uma linha de comando para a checagem das variveis utilizadas. Como a
linha torna-se muito grande, pode-se dividi-la em mais de uma linha fsica utilizando o sinal de
ponto-e-vrgula. Se um sinal de ponto-e-vrgula for esquecido nas duas primeiras linhas,
durante a execuo do programa ocorrer um erro, pois a segunda linha fsica ser
considerada como uma segunda linha de comando na compilao. E durante a execuo esta
linha no ter sentido.
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.
#include protheus.ch
/*
+==========================================+
| Programa: Clculo do Fatorial
|
| Autor : Microsiga Software S.A.
|
| Data : 02 de outubro de 2001
|
+==========================================+
*/
User Function CalcFator()
// Clculo do fatorial
nFator := GetFator()
// GetFator funo ilustrativa na qual a varivel recebe a informao do usurio.
If nFator <= 0
Alert(Informao invlida)
Return
Endif
For nCnt := nFator To 1 Step -1
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
Alert("O fatorial de " + cValToChar(nFator) + ;
" " + cValToChar(nResultado))
// Termina o programa
Return
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.
Local
Static
Private
Public
Function Pai()
Local nVar := 10, aMatriz := {0,1,2,3}
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Neste exemplo, a varivel nVar foi declarada como local e atribuda com o valor 10. Quando a
funo Filha executada, nVar ainda existe mas no pode ser acessada. Quando a execuo
da funo Pai terminar, a varivel nVar destruda. Qualquer varivel com o mesmo nome no
programa que chamou a funo Pai no afetada.
Variveis de escopo local so criadas automaticamente cada vez que a funo onde forem
declaradas for ativada. Elas continuam a existir e mantm seu valor at o fim da ativao da
funo (ou seja, at que a funo retorne o controle para o cdigo que a executou). Se uma
funo chamada recursivamente (por exemplo, chama a si mesma), cada chamada em
recurso cria um novo conjunto de variveis locais.
A visibilidade de variveis de escopo locais idntica ao escopo de sua declarao, ou seja, a
varivel visvel em qualquer lugar do cdigo fonte em que foi declarada. Se uma funo
chamada recursivamente, apenas as variveis de escopo local criadas na mais recente ativao
so visveis.
Variveis de escopo static
Variveis de escopo static funcionam basicamente como as variveis de escopo local, mas
mantm seu valor atravs da execuo e devem ser declaradas explicitamente no cdigo com
o identificador STATIC.
O escopo das variveis static depende de onde so declaradas. Se forem declaradas dentro do
corpo de uma funo ou procedimento, seu escopo ser limitado quela rotina. Se forem
declaradas fora do corpo de qualquer rotina, seu escopo afeta a todas as funes declaradas
no fonte.
Neste exemplo, a varivel nVar declarada como static e inicializada com o valor 10:
Function Pai()
Static nVar := 10
.
<comandos>
.
Filha()
.
<mais comandos>
.
Return(.T.)
Quando a funo Filha executada, nVar ainda existe mas no pode ser acessada. Diferente
de variveis declaradas como LOCAL ou PRIVATE, nVar continua a existir e mantm seu valor
atual quando a execuo da funo Pai termina. Entretanto, somente pode ser acessada por
execues subseqentes da funo Pai.
Variveis de escopo private
A declarao opcional para variveis privadas. Mas podem ser declaradas explicitamente com
o identificador PRIVATE.
Adicionalmente, a atribuio de valor a uma varivel no criada anteriormente
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.
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
Function Pai()
Public nVar := 10
<comandos>
.
Filha()
<mais comandos>
.
Return(.T.)
Neste exemplo, nVar criada como public e inicializada com o valor 10. Quando a funo Filha
executada, nVar ainda existe e pode ser acessada. Diferente de variveis locais ou privates,
nVar ainda existe aps o trmino da a execuo da funo Pai.
Diferentemente dos outros identificadores de escopo, quando uma varivel declarada como
pblica sem ser inicializada, o valor assumido falso (.F.) e no nulo (nil).
No ambiente ERP Protheus, existe uma conveno adicional a qual deve ser
respeitada que variveis em uso pela aplicao no sejam incorretamente
manipuladas. Por esta conveno deve ser adicionado o caracter _ antes
do nome de variveis PRIVATE e PUBLIC. Maiores informaes avaliar o
tpico: Boas Prticas de Programao.
Exemplo: Public _cRotina
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:
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.
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
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
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 comuns
Na documentao sobre variveis h uma breve demonstrao de como atribuir valores a uma
varivel da forma mais simples. O ADVPL amplia significativamente a utilizao de variveis
atravs do uso de expresses e funes.
Uma expresso um conjunto de operadores e operandos cujo resultado pode ser atribudo a
uma varivel ou ento analisado para a tomada de decises. Por exemplo:
Local nSalario := 1000, nDesconto := 0.10
Local nAumento, nSalLiquido
nAumento := nSalario * 1.20
nSalLiquido := nAumento * (1-nDesconto)
Neste exemplo so utilizadas algumas expresses para calcular o salrio lquido aps um
aumento. Os operandos de uma expresso podem ser uma varivel, uma constante, um
campo de arquivo ou uma funo.
Operadores Matemticos
Os operadores utilizados em ADVPL para clculos matemticos so:
+
*
/
** ou ^
%
Adio
Subtrao
Multiplicao
Diviso
Exponenciao
Mdulo (Resto da Diviso)
Operadores de String
Os operadores utilizados em ADVPL para tratamento de caracteres so:
+
$
Operadores Relacionais
Os operadores utilizados em ADVPL para operaes e avaliaes relacionais so:
<
>
=
==
<=
>=
<> ou #
ou !=
Comparao
Comparao
Comparao
Comparao
Comparao
Comparao
Comparao
Menor
Maior
Igual
Exatamente Igual (para caracteres)
Menor ou Igual
Maior ou Igual
Diferente
Operadores Lgicos
Os operadores utilizados em ADVPL para operaes e avaliaes lgicas so:
.And.
.Or.
.Not. ou !
E lgico
OU lgico
NO lgico
Operadores de Atribuio
Os operadores utilizados em ADVPL para atribuio de valores a variveis de memria so:
:=
+=
-=
*=
/=
**=
^=
%=
ou
Atribuio Simples
Adio e Atribuio em Linha
Subtrao e Atribuio em Linha
Multiplicao e Atribuio em Linha
Diviso e Atribuio em Linha
Exponenciao e Atribuio em Linha
Mdulo (resto da diviso) e Atribuio em Linha
Atribuio Simples
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
Atribuio Composta
Exemplo
X += Y
X -= Y
X *= Y
X /= Y
X **= Y
X %= Y
Equivalente a
X=X+Y
X=X-Y
X=X*Y
X=X/Y
X = 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
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.
Operadores
Operadores
Operadores
Operadores
Operadores
Operadores
Operadores
de Incremento/Decremento pr-fixado
de String
Matemticos
Relacionais
Lgicos
de Atribuio
de Incremento/Decremento ps-fixado
Exponenciao
Multiplicao e Diviso
Adio e Subtrao
Considere o exemplo:
Local nResultado := 2+10/2+5*3+2^3
O resultado desta expresso 30, pois primeiramente calculada a exponenciao 2^3(=8),
ento so calculadas as multiplicaes e divises 10/2(=5) e 5*3(=15), e finalmente as
adies resultando em 2+5+15+8(=30).
Alterao da Precedncia
4.5.3.
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.
4.5.4.
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:
CTOD()
CVALTOCHAR()
DTOC()
DTOS()
STOD()
STR()
STRZERO()
VAL()
CTOD()
Sintaxe
CTOD(cData)
Descrio
CVALTOCHAR()
Sintaxe
CVALTOCHAR(nValor)
Descrio
DTOC()
Sintaxe
DTOC(dData)
Descrio
DTOS()
Sintaxe
DTOS(dData)
Descrio
STOD()
Sintaxe
STOD(sData)
Descrio
STR()
Sintaxe
STR(nValor)
Descrio
STRZERO()
Sintaxe
STRZERO(nValor, nTamanho)
Descrio
VAL()
Sintaxe
VAL(cValor)
Descrio
Manipulao de strings
As funes mais utilizadas nas operaes de manipulao do contedo de strings so:
ALLTRIM()
ASC()
AT()
CHR()
CSTUFF()
LEN()
RAT()
SUBSTR()
ALLTRIM()
Sintaxe
ALLTRIM(cString)
Retorna uma string sem os espaos direita e esquerda, referente ao
contedo informado como parmetro.
Descrio
ASC()
Sintaxe
ASC(cCaractere)
Descrio
AT()
Sintaxe
AT(cCaractere, cString )
Descrio
CHR()
Sintaxe
CHR(nASCII)
Descrio
LEN()
Sintaxe
LEN(cString)
Descrio
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
STUFF()
Sintaxe
Descrio
SUBSTR()
Sintaxe
Descrio
UPPER()
Sintaxe
UPPER(cString)
Descrio
Retorna uma string com todos os caracteres maisculos, tendo como base a
string passada como parmetro.
ABS()
INT()
NOROUND()
ROUND()
ABS()
Sintaxe
ABS(nValor)
Descrio
INT()
Sintaxe
INT(nValor)
Descrio
NOROUND()
Sintaxe
NOROUND(nValor, nCasas)
Descrio
ROUND()
Sintaxe
Descrio
ROUND(nValor, nCasas)
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.
TYPE()
VALTYPE()
TYPE()
Sintaxe
TYPE(cVariavel)
Descrio
VALTYPE()
Sintaxe
VALTYPE(cVarivel)
Descrio
Estruturas de repetio
Estruturas de deciso
Sintaxe
Parmetros
Varivel
nValorInicial
TO nValorFinal
STEP
nIncremento
Comandos
EXIT
LOOP
Exemplo:
Local nCnt
Local nSomaPar := 0
For nCnt := 0 To 100 Step 2
nSomaPar += nCnt
Next
Alert( "A soma dos 100 primeiros nmeros pares : " + ;
cValToChar(nSomaPar) )
Return
Este exemplo imprime a soma dos 100 primeiros nmeros pares. A soma obtida atravs da
repetio do clculo utilizando a prpria varivel de contador. Como a clusula STEP est
sendo utilizada, a varivel nCnt ser sempre incrementada em 2. E como o contador comea
com 0, seu valor sempre ser um nmero par.
O Comando WHILE...ENDDO
A estrutura de controle WHILE...ENDDO, ou simplesmente o loop WHILE, repete uma seo de
cdigo enquanto uma determinada expresso resultar em verdadeiro (.T.).
Sintaxe
WHILE lExpressao
Comandos...
[EXIT]
[LOOP]
ENDDO
Parmetros
lExpressao
Comandos
EXIT
LOOP
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.
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.
Sintaxe
IF lExpressao
Comandos
[ELSE
Comandos...]
ENDIF
Parmetros
LExpressao
Comandos
Exemplo:
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
Endif
Return
O Comando IF...ELSEIF...ELSE...ENDIF
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro
(.T.).
Sintaxe
IF lExpressao1
Comandos
[ELSEIF lExpressaoX
Comandos]
[ELSE
Comandos...]
ENDIF
Parmetros
lExpressao1
lExpressaoX
Comandos
Exemplo:
Local dVencto := CTOD("31/12/01")
If Date() > dVencto
Alert("Vencimento ultrapassado!")
ElseIf Date() == dVencto
Alert("Vencimento na data!")
Else
Alert("Vencimento dentro do prazo!")
Endif
Return
O Comando DO CASE...ENDCASE
Executa o primeiro conjunto de comandos cuja expresso condicional resulta em verdadeiro
(.T.).
Sintaxe
DO CASE
CASE lExpressao1
Comandos
[CASE lExpressao2
Comandos
...
CASE lExpressaoN
Comandos]
[OTHERWISE
Comandos]
ENDCASE
Parmetros
CASE
lExpressao1
Comandos...
OTHERWISE
Comandos
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
6.1.1.
Inicializando arrays
Local
Local
Local
Local
nCnt
aX[10]
aY := Array(10)
aZ := {0,0,0,0,0,0,0,0,0,0}
For nCnt := 1 To 10
aX[nCnt] := nCnt * nCnt
Next nCnt
Este cdigo preenche o array com uma tabela de quadrados. Os valores sero 1, 4, 9, 16 ...
81, 100. Note que a linha 07 se refere varivel aX, mas poderia tambm trabalhar com aY ou
aZ.
O objetivo deste exemplo demonstrar trs modos de criar um array de tamanho conhecido
no momento da criao do cdigo.
1.
Na linha 02 o array 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.
O terceiro mtodo difere dos anteriores porque inicializa a matriz com os valores
3.
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.
Local
Local
Local
Local
nCnt
aX[0]
aY := Array(0)
aZ := {}
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.
6.1.2.
A linguagem ADVPL possui diversas funes que auxiliam na manipulao de arrays, dentre as
quais podemos citar as mais utilizadas:
ARRAY()
AADD()
ACLONE()
ADEL()
ASIZE()
AINS()
ASORT()
ASCAN()
ARRAY()
Sintaxe
ARRAY(nLinhas, nColunas)
Descrio
AADD()
Sintaxe
AADD(aArray, xItem)
Descrio
ACLONE()
Sintaxe
AADD(aArray)
Descrio
ADEL()
Sintaxe
ADEL(aArray, nPosio)
Descrio
ASIZE()
Sintaxe
ASIZE(aArray, nTamanho)
Descrio
A funo ASIZE permite a redefinio da estrutura de um array prexistente, adicionando ou removendo itens do mesmo.
ASORT()
Sintaxe
Descrio
ASCAN()
Sintaxe
ASCAN(aArray, bSeek)
Descrio
AINS()
Sintaxe
AINS(aArray, nPosicao)
Descrio
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
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.
6.2.1.
Primeira premissa
O ADVPL uma linguagem baseada em funes. Funes tm um valor de retorno. Assim
como o operador de atribuio :=.
Assim, ao invs de escrever:
x := 10 // Atribui o valor 10 varivel chamada X
Alert("Valor de x: " + cValToChar(x))
Pode-se escrever:
// Atribui e ento exibe o valor da varivel X
Alert("Valor de x: " + cValtoChar(X := 10))
A expresso x:=10 avaliada primeiro, e ento seu resultado (o valor de X, que agora 10)
passada para a funo cvaltochar para a converso para caractere, e em seguida para a
funo alert para a exibio. Por causa desta regra de precedncia possvel atribuir um valor
a mais de uma varivel ao mesmo tempo:
Z := Y := X := 0
Por causa dessa regra, essa expresso avaliada como se fosse escrita assim:
Z := ( Y := (X := 0) )
Apesar de o ADVPL avaliar expresses da esquerda para a direita, no caso de atribuies isso
acontece ao contrrio, da direita para a esquerda. O valor atribudo varivel X, que retorna
o valor para ser atribudo varivel Y e assim sucessivamente. Pode-se dizer que o zero foi
"propagado atravs da expresso".
Segunda premissa
Em ADVPL pode-se juntar diversas linhas de cdigo em uma nica linha fsica de comando. Por
exemplo, o cdigo:
If lAchou
Alert("Cliente encontrado!")
Endif
pode ser escrito assim:
If lAchou ; Alert("Cliente encontrado!") ;
Endif
O ponto-e-vrgula indica ao ADVPL que a nova linha de cdigo est para comear. Pode-se
ento colocar diversas linhas lgicas de cdigo na mesma linha fsica atravs do editor de texto
utilizado.
Apesar da possibilidade de se escrever todo o programa assim, em uma nica linha fsica, isto
no recomendado pois dificulta a legibilidade do programa e, conseqentemente, a
manuteno.
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
@00,00 PSAY y := 20
==>
==>
10
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.
==>
20
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
6.2.4.
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
Descrio
DBEVAL()
Sintaxe
Descrio
AEVAL()
Sintaxe
Descrio
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 ...
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.
Function()
User Function()
Static Function()
Main Function()
Function()
Funes ADVPL convencionais, restritas ao desenvolvimento da rea de Inteligncia Protheus
da Microsiga.
O interpretador ADVPL distingue nomes de funes do tipo Function() com at dez caracteres.
A partir do dcimo caracter, apesar do compilador no indicar quaisquer tipos de erros, o
interpretador ignorar os demais caracteres.
Exemplo:
// Fonte MATA100INCL.PRW
#INCLUDE "protheus.ch"
Function MATA100INCL01()
ALERT("01")
Return
Function MATA100INCL02()
ALERT("02")
Return
Ao executar a funo MATA100INCL01() ser exibida a mensagem 01, mas ao executar a
funo MATA100INCL02() tambm ser exibida a mensagem 01, pois o interpretador
considera o nome da funo como MATA100INC.
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.
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()
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()
Avaliando a funo CalcFator() descrita anteriormente podemos verificar que a mesma recebe
como parmetro para sua execuo a varivel nFator.
Com base nesta funo podemos descrever duas forma de passagem de parmetros por
contedo:
Passagem de contedos diretos
Passagem de variveis como contedos
Exemplo 01 Passagem de contedos diretos
User Function DirFator()
Local nResultado := 0
nResultado := CalcFator(5)
Function CalcFator(nFator)
...
Passagem de parmetros por referncia Duas variveis x uma nica rea de memria
Desta forma a funo chamada tem acesso no apenas ao contedo, mas 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.
Se este tratamento no fosse realizado e com isso o parmetro nFator no fosse informado,
ocorreria o seguinte evento de erro:
Exemplo:
User Function CalcFator(nFator)
Local nCnt
Local nResultado := 0
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
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 prprocessador, o qual executado pelo compilador antes da execuo do processo de
compilao propriamente dito.
Portanto, o pr-processador modifica o programa fonte, entregando para o compilador um
programa modificado de acordo com as diretivas de compilao, as so iniciadas pelo caractere
#.
As diretivas podem ser colocadas em qualquer parte do programa, sendo que as
implementadas pela linguagem ADVPL so:
#INCLUDE
#DEFINE
#IFDEF
#IFNDEF
#ELSE
#ENDIF
#COMMAND
Diretiva: #INCLUDE
A diretiva #INCLUDE indica em que arquivo de extenso CH (padro ADVPL) esto os UDCs
a serem utilizados pelo pr-processador.
A aplicao ERP possui diversos includes, os quais devem ser utilizados segundo a aplicao
que ser desenvolvida, o que permitir a utilizao de recursos adicionais definidos para a
linguagem, implementados pela rea de Tecnologia da Microsiga.
Os includes mais utilizados nas aplicaes ADVPL desenvolvidas para o ERP so:
PROTHEUS.CH: diretivas de compilao 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.
DIALOG.CH
FONT.CH
INI.CH
PTMENU.CH
PRINT.CH
Fique atento
TCQUERY
CREATE RPCCONN
CLOSE RPCCONN
PREPARE ENVIRONMENT
RESET ENVIRONMENT
OPEN REMOTE TRANSACTION
CLOSE REMOTE TRANSACTION
CALLPROC IN
OPEN REMOTE TABLES
CREATE XMLSTRING
CREATE XMLFILE
SAVE XMLSTRING
SAVE XMLFILE
- 80 Introduo programao e ADVPL Bsico
o
o
o
ADDITEM TAG
ADDNODE NODE
DELETENODE
Os recursos de tratamentos de e-mails, integrao com a ferramenta
TOPCONNECT (DbAcess), preparao de ambientes e manipulao de
arquivos e strings do padro XML sero abordados no curso de ADVPL
Avanado.
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.
#IFDEF SPANISH
#DEFINE STR0001 Hola !!!
#ELSE
#IFDEF ENGLISH
#DEFINE STR0001 Hello !!!
#ELSE
#DEFINE STR0001 Ol !!!
#ENDIF
#ENDIF
A aplicao ERP disponibiliza a varivel de escopo PUBLIC __LANGUAGE, a qual contm uma string que identifica o idioma em
uso pelo sistema, cujo os contedos possveis so:
PORTUGUESE
SPANISH
ENGLISH
Banco de Dados: verifica as variveis AXS e TOP para determinar se o banco de dados
em uso pela aplicao est no formado ISAM (DBF, ADS, CTREE, etc.) ou se est
utilizando a ferramenta TOPCONNECT (DbAcess).
#IFDEF TOP
cQuery := SELECT * FROM +RETSQLNAME(SA1)
dbUseArea(.T., "TOPCONN", TcGenQry(,,cQuery), SA1QRY,.T.,.T.)
#ELSE
DbSelectArea(SA1)
#ENDIF
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.> )
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
- 84 Introduo programao e ADVPL Bsico
sintaxe; permite o debug (execuo passo a passo do programa, verificando o contedo das
variveis) e fornece assistentes (modelos) de programas.
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:
Protheus Server / TOTVS AppServer: Responsvel pela comunicao entre o cliente,
o banco de dados e o RPO. O nome do executvel depende da verso do sistema
(TOTVSAPPSERVER.EXE) sendo que as plataformas ISAM suportadas pelo Protheus
Server so DBF e CTREE.
Protheus Remote / TOTVS SmartClient: Instalado no Server ou na estao.
nome tambm depende da verso do sistema (TOTVSSMARTCLIENT.EXE).
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.
Destino:
c:\protheus\bin\appserver\totvsappserver.exe
- console
Iniciar em:
c:\protheus\bin\appserver
-Console ou -Debug
Executado como uma JanelaConsole, as informaes recebidas das conexes com o TOTVS
Application Server conectados so exibidas diretamente na tela do console do TOTVS
Application Server, bem como informaes de No Conformidades.
-Install
Se o TOTVS Application Server, no for instalado como um Servio do NT, durante a
Instalao, isto pode ser realizado, executando-o com a opo de Linha de Comando.
-Remove
Para remov-lo da Lista de Servios do NT, pode-se execut-lo com a opo de Linha de
Comando.
Destino:
c:\protheus\bin\smartclient\totvssmartcliente.exe
M
Iniciar em:
c:\protheus\bin\smartclient
-Q (Quiet)
Indica que o TOTVS Smart Client, no dever mostrar o Splash (Imagem de Apresentao) e a
tela de identificao de Parmetros Iniciais, necessita ser acompanhada da (Clusula P).
-P (Main Program)
Identifica o Programa (APO) Inicial.
-E (Environment)
Nome da Seo de Environment, no (Ini do Server), que ser utilizada, para definies gerais.
-C (Connection)
Nome da Seo de Conexo, que ser utilizada, para a conexo ao TOTVS Application Server.
-M (AllowMultiSession)
Permite mltiplas instncias (Cpias) do TOTVS Smart Client, na mesma mquina, o que por
Default no permitido.
Os parmetros que configuram o local do RPO, o Banco de Dados (ISAM ou SQL), os arquivos
de menus, configuraes e customizaes do sistema no arquivo INI so:
SourcePath: Indica o local de origem dos objetos. o endereo do Repositrio
Objetos (Exemplo: SourcePath=C:\PROTHEUS\APO)
de
RootPath: Aponta para a pasta raiz (inicial), a partir da qual sero localizados os dados
(no caso de ISAM), bem como o prprio Dicionrio de Dados
(Exemplo:
RootPath=C:\PROTHEUS\PROTHEUS_DATA)
StartPath: Indica qual a pasta dentro da pasta raiz (informada no parmetro
RootPath) que contm os arquivos de menus, os arquivos de configuraes e os
arquivos de customizaes
(SXs)
do
sistema
Protheus
(Exemplo:
StartPath=\SYSTEM\).
No h necessidade de que os parmetros estejam em ordem nos arquivos de configurao
(.ini). Alm dos parmetros j detalhados, existem outros que podem indicar a verso do
sistema, o tipo de banco de dados, linguagem do pas em que est sendo utilizado e as
mscaras de edio e formatao.
[ENVIRONMENT]
SOURCEPATHC:\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
[CONFIG]
LASTMAINPROG=SIGACFG
LANGUAGE=1
[DRIVERS]
ACTIVE=TCP
[TCP]
SERVER=172.16.72.41
PORT=1234
Funcionalidades Abordadas
9.3.2.
SXR
Descrio
Cadastro de empresas e filiais do sistema
Arquivo de usurios, grupos e senhas do sistema
ndices dos arquivos
Perguntas e respostas
Mapeamento de tabelas
Dicionrio de Dados
Agenda do Schedule de processos
Tabelas
Parmetros
Gatilhos de Interface
Fora de uso
Relacionamentos entre tabelas
Pastas cadastrais apontadas no SX3
Consulta por meio da tecla F3 (Consulta Padro)
Controle do Schedule de processos
Seqncia de documentos (+1)
Seqncia de documentos (Prximo)
Tamanho padro para campos apontado pelo SX3
Resposta de Perguntas (SX1) por usurios
Controle de LOGs por tabela
Histrico de Logs cadastrados no SXO
Cadastro de filtros inteligentes da mbrowse (contm as
informaes necessrias para a criao do filtro).
Cadastro de relacionamento entre programa x filtro
(utilizada internamente pelo Protheus para verificar em
quais programas os filtros podero ser utilizados).
SXS
SXT
Identificao
ATIVO FIXO
COMPRAS
CONTABILIDADE
ESTOQUE E CUSTOS
FATURAMENTO
FINANCEIRO
LIVROS FISCAIS
PLANEJAMENTO E CONTROLE DA PRODUO
GESTO DE PESSOAL
FATURAMENTO DE SERVIOS
VECULOS
CONTROLE DE LOJAS/AUTOMAO COMERCIAL
CALL CENTER
OFICINAS
PONTO ELETRNICO
EASY IMPORT CONTROL
TERMINAL
MANUTENO DE ATIVOS
RECRUTAMENTO E SELEO DE PESSOAL
INSPEO DE ENTRADA QUALIDADE
METODOLOGIA QUALIDADE
O nome de cada tabela no Protheus constitudo de seis dgitos, os quais so utilizados para
formar a seguinte representao:
F
Onde:
F
SF
A tabela a seguir demonstra algumas das principais famlias de tabelas utilizadas pela
aplicao ERP Protheus:
Famlia
S
S
S
S
S
S
S
S
S
A
C
C
C
C
D
E
G
J
N
P
Q
R
T
W
Z
G
H
I
N
R
X
Z
T
V
W
-
Descrio
Tabelas pertencentes ao sistema bsico, tambm chamado Classic
Cadastros de entidades compartilhadas entre os ambientes
(Clientes, Fornecedores, Bancos entre outros).
Cadastros dos ambientes de Materiais (Produtos, Saldos entre
outros).
Arquivos de movimentaes diversas utilizados pelos ambientes de
Materiais (Solicitao ao Almoxarifado, Solicitao de Compras,
Pedido de Compras, Pedido de Vendas, Ordens de Produo entre
outros).
Arquivos de movimentaes de estoque (Itens de notas fiscais de
entrada e sada, movimentos internos de estoque entre outros).
Cadastros e movimentaes do ambiente Financeiro.
Cadastros e movimentaes Fiscais (Cabealhos das notas fiscais
de entrada e sada, cadastro de tipos de entrada e sada, livros
fiscais, entre outros).
Cadastros do ambiente de Planejamento e Controle de Produo
Movimentos do ambiente de Planejamento e Controle de Produo
Cadastros e movimentos do ambiente Contbil (descontinuado)
Cadastros e movimentos do ambiente Ativo Fixo
Cadastros e movimentos do ambiente Gesto de Pessoal
Tabelas de configurao do sistema
Tabelas livres para utilizao e projetos especficos em clientes.
Gesto de Projetos
Contabilidade Gerencial
Contabilidade Gerencial
Contabilidade Gerencial
Contabilidade Gerencial
Transportadoras e derivados
Comrcio exterior e derivados
Gesto Hospitalar
Gesto Educacional
Servios Pblicos
Reservado para projetos da fbrica de software
Qualidade e derivados
Recursos Humanos e derivados
Plano de Sade
Workflow
Tabelas livres para utilizao e projetos especficos em clientes em
adio a famlia SZ.
- 96 Introduo programao e ADVPL Bsico
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.
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.
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:
9.4.1.
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.
9.4.2.
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.
boto Incluir (
). Ao utilizar esta opo ser exibida a tela para definio dos dados
referentes nova tabela que ser criada:
).
O nome da tabela preenchido automaticamente, adicionando 990. Esse dado referese empresa 99 (Teste Matriz) a qual est sendo adicionado tabela.
O Path refere-se pasta que conter efetivamente os dados das tabelas, quando ISAM,
nas verses com banco de dados relacional no so utilizadas. Essa pasta ser criada
dentro da pasta indicada na configurao do sistema como ROOTTPATH.
O modo de acesso compartilhado indica que o sistema possibilitar o uso simultneo da
tabela por duas ou mais filiais. Se for compartilhado o campo Filial fica em branco. Se
for exclusivo, grava-se o cdigo da filial ativa e somente ela tem acesso ao registro.
Aps a confirmao, a tabela criada passa a fazer parte do cadastro do Dicionrio de
Dados, contendo somente o campo FILIAL, o qual criado como padro pela
- 103 Introduo programao e ADVPL Bsico
funcionalidade do mdulo.
9.4.3.
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).
2. Aps a seleo da opo Dicionrio de Dados sero exibidas as tabelas j cadastradas
no arquivo de sistema SX2.
opo Incluir (
). Ao utilizar esta opo ser exibida a tela para definio dos dados
referentes ao novo campo que ser criado:
boto Confirmar (
).
).
).
Guia: Campo
O campo Decimal ser solicitado somente para os campos de tipo numrico.
O formato ! indica que o caractere ser sempre maisculo, independente da ao
do usurio. O formato @! indica que essa caracterstica estende-se por todo 20
o
campo.
O contexto real indica que o campo existir efetivamente no banco de dados e o
contexto virtual significa que o campo existir apenas no dicionrio de dados e no
fisicamente.
A propriedade alterar indica que o campo pode ser alterado.
Nesta janela, os dados esto classificados em seis pastas com objetivos de
preenchimento bem especficos:
Guia: Informaes
Contm as informaes a respeito dos ttulos.
Ttulo: a legenda que aparece nas telas/relatrios. H inclusive trs campos para
esta finalidade: em portugus, espanhol e ingls. Esta propriedade pode ser alterada
vontade, pois no interfere em nenhum processamento.
Descrio e Help: So propriedades que objetivam documentar o campo.
Guia: Opes
Contm os dados que facilitam a digitao.
Guia: Validaes
Representam as regras de validao do campo.
Validaes: Nesta propriedade, escreve-se uma funo de validao do campo que
est sendo digitado. Existe um conjunto de funes disponveis no ADVPL apropriadas
para esse caso.
Todas as validaes informadas sero executadas no momento do preenchimento do
prprio campo. Uma validao pode ser uma expresso lgica ou uma funo de
usurio que retorna um valor lgico Verdadeiro ou Falso. O sistema s permitir o
avano para o prximo campo quando o respectivo preenchimento resultar Verdadeiro
seja na expresso ou no retorno da funo.
Guia: Uso
Descreve a forma de utilizao do campo.
Guia: Mdulos
Relaciona todos os mdulos em que o campo ser utilizado.
9.4.4.
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).
2. Aps a seleo da opo Dicionrio de Dados sero exibidas as tabelas j cadastradas
no arquivo de sistema SX2.
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:
Confirmar (
).
).
).
O campo relativo filial sempre faz parte dos ndices, com exceo do SM2, para que
os registros nas tabelas estejam agrupados por filiais, independente desta tabela ser
compartilhada entre as filiais.
Uma tabela poder ter vrios ndices cadastrados no Dicionrio de Dados. Em
determinado momento, porm, apenas um deles oferecer acesso ao registro. Essa
ordem pode ser alterada em tempo de execuo pelos programas da aplicao, atravs
do comando DBSetOrder(), ou atravs da definio de uma ordem especfica na
utilizao de queries para acesso as dados diretamente em bancos de dados de
ambientes TOPCONNECT (DbAcess).
9.4.5.
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.
o boto Incluir (
Confirmar (
).
Pode haver vrios gatilhos para o mesmo campo. A ordem de execuo determinada
pelo campo Seqncia.
Os tipos do Gatilho Primrio, Estrangeiro e de Posicionamento definem se o Contra
Domnio um campo da mesma tabela, de outra tabela ou se o gatilho deve realizar
um posicionamento, respectivamente.
A regra pode ser uma expresso que resulta em um valor a ser preenchido no Contra
Domnio.
O posicionamento igual a Sim indica que ser executado um comando de busca do
registro de acordo com a chave indicada.
O Alias, a Ordem e a Chave descrevem a tabela envolvida no gatilho, seu ndice e a
chave para que a funcionalidade se posicione no registro adequado.
9.4.6.
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.
boto Incluir (
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.
boto Confirmar (
).
10.
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:
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:
Se o programa no manipula arquivos, pode-se cham-lo diretamente do DEV-Studio
(nome no lado direito da barra de ferramentas);
Se o programa manipula tabelas existem duas opes:
Adicionar o programa no menu de um dos ambientes e executa-lo atravs do
Remote.
Realizar a preparao do ambiente na prpria rotina, permitindo sua execuo
diretamente pelo DEV-Studio.
No se pode compilar um programa com o Remote e o Monitor abertos, tenha este
finalizado ou no por erro.
Anlise e depurao de erros
Para identificar as causas de erros, a ferramenta DEV-Studio possui diversos recursos que
auxiliam o DEBUG.
A ao de DEBUG necessita que o programa seja executado a partir do DEV-Studio, sendo
necessrio observar as seguintes regras:
Definir e marcar os pontos de parada mais adequados a anlise do fonte;
Executar a rotina atravs do DEV-Studio, selecionando seu nome diretamente, ou o
mdulo que contm a opo ou a ao que ir execut-la;
A partir do momento em que o DEV-Studio pausar o processamento em um dos pontos
de parada especificados previamente podem ser utilizadas as janelas de visualizao
disponveis no DEV-Studio, que so:
Variveis Locais
Variveis Privates
Variveis Publics
Variveis Statics
Janela da Watchs
Janela de Tabelas e Campos
Pilha de Chamadas
Atravs da Janela de Watchs possvel determinar quais variveis devem ser exibidas;
- 118 Introduo programao e ADVPL Bsico
11.1.
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.
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.
SELECT()
DBSELECTAREA()
DBSETORDER()
DBSEEK() E MSSEEK()
DBSKIP()
DBGOTO()
DBGOTOP()
DBGOBOTTON()
DBSETFILTER()
RECLOCK()
SOFTLOCK()
MSUNLOCK()
DBDELETE()
DBUSEAREA()
DBCLOSEAREA()
- 122 Introduo programao e ADVPL Bsico
DBRLOCK()
Sintaxe
Descrio
DBRLOCK(xIdentificador)
Funo de base de dados, que efetua o lock (travamento) do registro
identificado pelo parmetro xIdentificador. Este parmetro pode ser o
Recno() para tabelas em formado ISAM, ou a chave primria para bancos de
dados relacionais.
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
DBCOMMITALL()
Sintaxe
DBCOMMITALL()
Descrio
DBDELETE()
Sintaxe
DbDelete()
Descrio
DBGOTO()
Sintaxe
DbGoto(nRecno)
Descrio
DBGOTOP()
Sintaxe
DbGoTop()
Descrio
DBGOBOTTON()
Sintaxe
DbGoBotton()
Descrio
DBRLOCKLIST()
Sintaxe
DBRLOCKLIST()
Descrio
DBSEEK() E MSSEEK()
Sintaxe
Descrio
DBSKIP()
Sintaxe
DbSkip(nRegistros)
Descrio
DBSELECTAREA()
Sintaxe
DbSelectArea(nArea | cArea)
Descrio
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
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()
Mesma funcionalidade da funo UNLOCK(), s que recomendada para
ambientes de rede nos quais os arquivos so compartilhados.
Descrio
Libera o travamento do registro posicionado na rea de trabalho ativa e
confirma as atualizaes efetuadas naquele registro.
DBUNLOCKALL()
Sintaxe
DBUNLOCKALL()
Descrio
DBUSEAREA()
Sintaxe
Descrio
DbUseArea(lNovo,
cDriver,
cArquivo,
cAlias,
lComparilhado,;
lSoLeitura)
Define um arquivo de base de dados como uma rea de trabalho disponvel
na aplicao.
MSUNLOCK()
Sintaxe
MsUnLock()
Descrio
posicionado
confirmando
as
RECLOCK()
Sintaxe
RecLock(cAlias,lInclui)
Descrio
RLOCK()
Sintaxe
RLOCK() lSucesso
Descrio
SELECT()
Sintaxe
Descrio
Select(cArea)
Determina o nmero de referncia de um determinado alias em um
ambiente de trabalho. Caso o alias especificado no esteja em uso no
ambiente, ser retornado o valor 0 (zero).
SOFTLOCK()
Sintaxe
SoftLock(cAlias)
Permite a reserva do registro posicionado na rea de trabalho ativa de forma
que outras operaes, com exceo da atual, no possam atualizar este
registro. Difere da funo RecLock() pois no gera uma obrigao de
atualizao, e pode ser sucedido por ele.
Descrio
UNLOCK()
Sintaxe
UNLOCK()
Descrio
11.3.
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
11.4.
Semforos
Para definir o conceito do que um semforo de numerao deve-se avaliar a seguinte
seqncia de eventos no sistema:
Ao ser fornecido um nmero, ele permanece reservado at a concluso da operao
que o solicitou;
Se esta operao for confirmada, o nmero indisponibilizado, mas se a operao for
cancelada, o nmero voltar a ser disponvel mesmo que naquele momento nmeros
maiores j tenham sido oferecidos e utilizados.
Com isso, 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
Descrio
CONFIRMSXE()
Sintaxe
CONFIRMSXE(lVerifica)
Descrio
ROLLBACKSXE()
Sintaxe
ROLLBACKSXE()
Descrio
12.
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:
12.1.
12.1.1.
VAZIO()
NAOVAZIO()
EXISTCPO()
EXISTCHAV()
PERTENCE()
POSITIVO()
NEGATIVO()
TEXTO()
EXISTCHAV()
Sintaxe
Descrio
Funo utilizada normalmente para verificar se um determinado cdigo de
cadastro j existe na tabela na qual a informao ser inserida, como por
exemplo o CNPJ no cadastro de clientes ou fornecedores.
EXISTCPO()
Sintaxe
Descrio
Funo utilizada normalmente para verificar se a informao digitada em um
campo, a qual depende de outra tabela, realmente existe nesta outra tabela,
como por exemplo o cdigo de um cliente em um pedido de venda.
NAOVAZIO()
Sintaxe
NaoVazio()
Descrio
NEGATIVO()
Sintaxe
Negativo()
Descrio
PERTENCE()
Sintaxe
Pertence(cString)
Descrio
POSITIVO()
Sintaxe
Positivo()
Descrio
TEXTO()
Sintaxe
Texto()
Descrio
VAZIO()
Sintaxe
Vazio()
Descrio
12.1.2.
Funcionalidade
Permite apenas caracteres alfabticos.
Exibe CR depois de nmeros positivos.
Exibe numrico com o ponto e vrgula invertidos (formato Europeu).
Insere caracteres diferentes dos caracteres de template na exibio, mas no os
insere na varivel do GET.
Permite rolamento horizontal do texto dentro do GET, <n> um nmero inteiro
que identifica o tamanho da regio.
Exibe DB depois de nmeros negativos.
Exibe zeros como brancos.
Exibe nmeros negativos entre parnteses com os espaos em branco iniciais.
Exibe nmeros negativos entre parnteses sem os espaos em branco iniciais.
Converte caracteres alfabticos para maisculo.
Templates
Contedo Funcionalidade
X
Permite qualquer caractere.
9
Permite apenas dgitos para qualquer tipo de dado, incluindo o sinal para
numricos.
#
Permite dgitos, sinais e espaos em branco para qualquer tipo de dado.
!
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
SAY e PSAY
Funes
Contedo
C
E
R
X
Z
(
!
Funcionalidade
Exibe CR depois de nmeros positivos
Exibe numrico com o ponto e a vrgula invertidos (formato Europeu)
Insere caracteres diferentes dos caracteres de template
Exibe DB depois de nmeros negativos
Exibe zeros como brancos
Envolve nmeros negativos entre parnteses
Converte todos os caracteres alfabticos para maisculo
Templates
Contedo
X
9
#
!
*
.
,
Funcionalidade
Exibe dgitos para qualquer tipo de dado
Exibe 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
12.2.
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:
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
de
de
de
de
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.
12.3.
o
o
o
12.3.1.
GETMV()
SUPERGETMV()
GETNEWPAR()
PUTMV()
GETMV()
Sintaxe
GETMV(cParametro)
Descrio
GETNEWPAR()
Sintaxe
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
SUPERGETMV()
Sintaxe
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.
12.4.
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:
Complementar uma validao realizada pela aplicao;
Complementar as atualizaes realizadas pelo processamento em tabelas padres do
ERP;
Implementar a atualizao de tabelas especificas durante o processamento de uma
rotina padro do ERP;
Executar uma ao sem processos de atualizaes, mas que necessite utilizar as
informaes atuais do ambiente durante o processamento da rotina padro para
determinar as caractersticas do processo;
Substituir um processamento padro do sistema por uma regra especfica do cliente no
qual o mesmo ser implementado.
Premissas e Regras
Um ponto de entrada no deve ser utilizado para outras finalidades seno para as quais
o mesmo foi pr-definido, sob pena de causar a perda da integridade das informaes
da base de dados ou provocar eventos de erro durante a execuo da rotina padro.
Um ponto de entrada deve ser transparente para o processo padro, de forma que
todas as tabelas acessadas pelo ponto de entrada e que sejam utilizadas pela rotina
padro, devero ter sua situao imediatamente anterior execuo do ponto
restaurada ao trmino do mesmo, e para isto recomenda-se o uso das funes
GETAREA() e RESTAREA().
Como um ponto de entrada no executado da forma tradicional, ou seja, ele no
chamado como uma funo, ele no recebe parmetros. A aplicao ERP disponibiliza
uma varivel de sistema denominada PARAMIXB, a qual recebe os parmetros da
funo chamadora e os disponibiliza para serem utilizados pela rotina customizada.
A varivel PARAMIXB no possui um padro de definio nos cdigos fontes da
aplicao ERP, desta forma seu tipo pode variar 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.
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.
Os componentes da interface visual que sero tratados neste tpico, utilizando a sintaxe
ADVPL so:
MSDIALOG()
MSGET()
SAY()
BUTTON()
SBUTTON()
BUTTON()
Sintaxe
Descrio
MSDIALOG()
Sintaxe
Descrio
MSGET()
Sintaxe
Descrio
SAY()
Sintaxe
Descrio
SBUTTON()
Sintaxe
Descrio
13.2.
13.2.1.
AxCadastro()
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Parmetros
cAlias
cTitulo
Ttulo da Janela
cVldExc
cVldAlt
Exemplo:
#include "protheus.ch"
User Function XCadSA2()
Local
Local
Local
Local
cAlias := "SA2"
cTitulo := "Cadastro de Fornecedores"
cVldExc := ".T."
cVldAlt := ".T."
dbSelectArea(cAlias)
dbSetOrder(1)
AxCadastro(cAlias,cTitulo,cVldExc,cVldAlt)
Return
13.2.2.
MBrowse()
Browse padro para visualizao das informaes da base de dados, de acordo com as
configuraes do SX3 Dicionrio de Dados (campo browse).
Parmetros
nLin1, nCol1,
nLin2, nCol2
cAlias
cCadastro
AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir"
,"AxInclui" ,0,3})
AADD(aRotina,{"Alterar"
,"AxAltera",0,4})
AADD(aRotina,{"Excluir"
,"AxDeleta",0,5})
Exemplo:
#include "protheus.ch"
User Function MBrwSA2()
Local cAlias := "SA2"
Private cCadastro := "Cadastro de Fornecedores"
Private aRotina
:= {}
AADD(aRotina,{"Pesquisar" ,"AxPesqui",0,1})
AADD(aRotina,{"Visualizar" ,"AxVisual",0,2})
AADD(aRotina,{"Incluir"
,"AxInclui",0,3})
AADD(aRotina,{"Alterar"
,"AxAltera",0,4})
AADD(aRotina,{"Excluir"
,"AxDeleta",0,5})
dbSelectArea(cAlias)
dbSetOrder(1)
mBrowse(6,1,22,75,cAlias)
Return
Pesquisar
Visualizar
Incluir
Alterar
Excluir
Livre
13.2.3.
AxFunctions()
AXPESQUI()
AXVISUAL()
AXINCLUI()
AXALTERA()
AXDELETA()
AXALTERA()
Sintaxe
Descrio
AXDELETA()
Sintaxe
Descrio
AXINCLUI()
Sintaxe
Descrio
AXPESQUI()
Sintaxe
AXPESQUI()
Descrio
AXVISUAL()
Sintaxe
Descrio
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:
15.
Capitulao de Palavras-Chave
15.1.
Palavras em maisculo
16.
Tipo de dado
Array
Bloco de cdigo
Caracter
Data
Lgico
Numrico
Objeto
Indefinido
Exemplo
aValores
bSeek
cNome
dDataBase
lContinua
nValor
oMainWindow
xConteudo
17.
Palavras reservadas
AADD
ABS
ASC
AT
BOF
BREAK
ENDIF
LTRIM
SPACE
CTOD
FILE
PCOUNT
TRANSFORM
DOW
IIF
CATCH
DTOS
ELSE
ELSEIF
EMPTY
ENDCASE
ENDDO
LOWER
SETPOS
COL
FIELDNAME
PCOL
TIME
DEVPOS
IF
RECNO
THROW
INKEY
INT
LASTREC
LEN
LOCK
LOG
SELECT
CMONTH
FCOUNT
MONTH
SUBSTR
DELETED
FUNCTION
RECCOUNT
UPPER
Palavras reservadas no
procedimentos ou funes;
REPLICATE
RLOCK
ROUND
ROW
RTRIM
SECONDS
CHR
EXP
MIN
STR
DAY
FOUND
PROW
TYPE
TRY
podem
ser
VAL
VALTYPE
WHILE
WORD
YEAR
CDOW
EOF
MAX
SQRT
DATE
FLOCK
PROCEDURE
TRIM
DTOC
AS
utilizadas
para
variveis,
LISTAS DE EXERCCIOS
Mdulo 01: Introduo programao
01
02
01
02
03
04
05
06
07
08
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
11
01
02
03
04
05
06
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
Colaboradores
Reviso 01
Arnaldo Raymundo Junior
Luis Akira Tamura
Mrcia Satiko Sasaki Tokura
Patricia Lopes Legas
Robson Luiz Estefani Gonalves
Srgio Sueo Fuzinaka
Data: 10.2007
CSA
Educao Corporativa
ACR-N1_FRAMEW1
Educao Corporativa
Fbrica de Software
Inteligncia Protheus
Educao Corporativa
Sintaxe: CTOD(cData)
Parmetros
cData
Exemplo:
cData := 31/12/2006
dData := CTOD(cData)
IF dDataBase >= dData
MSGALERT(Data do sistema fora da competncia)
ELSE
MSGINFO(Data do sistema dentro da competncia)
ENDIF
CVALTOCHAR()
Realiza a converso de uma informao do tipo numrico em uma string, sem a adio de
espaos a informao.
Sintaxe: CVALTOCHAR(nValor)
Parmetros
nValor
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
DTOC()
Realiza a converso de uma informao do tipo data para em caracter, sendo o resultado no
formato DD/MM/AAAA.
Sintaxe: DTOC(dData)
Parmetros
dData
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.
Sintaxe: DTOS(dData)
Parmetros
dData
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.
Sintaxe: STOD(sData)
Parmetros
sData
Exemplo:
sData := LERSTR(01,08) // Funo que realiza a leitura de uma string de um txt previamente
// aberto
dData := STOD(sData)
STR()
Realiza a converso de uma informao do tipo numrico em uma string, adicionando espaos
direita.
Sintaxe: STR(nValor)
Parmetros
nValor
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
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.
nTamanho
Exemplo:
FOR nPercorridos := 1 to 10
MSGINFO(Passos percorridos: +CvalToChar(nPercorridos))
NEXT nPercorridos
VAL()
Realiza a converso de uma informao do tipo caracter em numrica.
Sintaxe: VAL(cValor)
Parmetros
cValor
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)
Matemticas
ACOS()
Funo utilizada para calcular o valor do arco co-seno.
Sintaxe: ACOS(nValor)
Parmetros:
nValor
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.
Sintaxe: CELLING(nMax)
Parmetros
nMax
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().
Sintaxe: COS(nAngulo)
Parmetros:
nAngulo
Retorno:
Numrico
Situaes invlidas:
Entrada
QNAN,IND
(cosf, cos)
x 7.104760e+002 (cosh, coshf)
Exceo apresentada
None
INVALID
INEXACT+OVERFLOW
Significado da Exceo
Sem Domnio
Sem Domnio
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.
Sintaxe: LOG10(nNatural)
Parmetros:
nNatural
Retorno:
Numrico
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.
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo SIN().
Sintaxe: SIN(nAngulo)
Parmetros:
nAngulo
Retorno:
Numrico
Situaes invlidas:
Entrada
QNAN,IND
(senf, sen)
x 7.104760e+002 (senh, senhf)
Exceo apresentada
None
INVALID
INEXACT+OVERFLOW
Significado da Exceo
Sem Domnio
Sem Domnio
OVERFLOW
SQRT()
Funo utilizada para calcular a raiz quadrada de um nmero positivo.
Sintaxe: SQRT(nValor)
Parmetros:
nValor
Retorno:
Numrico
TAN()
Funo utilizada para calcular o valor da tangente ou tangente hiperblica.
Importante: Se x >= 2^63 ou x <= -2^63 ocorre perda significante na chamada da
funo cos.
Sintaxe: TAN(nAngulo)
Parmetros:
nAngulo
Retorno:
Numrico
Situaes invlidas:
Entrada
QNAN,IND
Exceo apresentada
None
INVALID
Significado da Exceo
Sem Domnio
Sem Domnio
Sintaxe: TYPE(cVariavel)
Parmetros
cVariavel
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.
Sintaxe: VALTYPE(cVariavel)
Parmetros
cVariavel
Exemplo:
STATIC FUNCTION GETTEXTO(nTamanho, cTitulo, cSay)
LOCAL cTexto
LOCAL nColF
LOCAL nLargGet
PRIVATE oDlg
:=
:= 0
:= 0
Default cTitulo
Default cSay
Default nTamanho
:= Space(nTamanho)
:= Round(nTamanho * 2.5,0)
:= Round(195 + (nLargGet * 1.75) ,0)
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
ACTIVATE MSDIALOG oDlg CENTERED
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 ({}).
Parmetros
nLinhas
nColunas
Exemplo:
aDados := Array(3,3) // Cria um array de trs linhas, cada qual com 3 colunas.
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.
xItem
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
AADD(aItem, cVariavel2) // Adiciona um elemento no array aItem de acordo com o cVariavel2
AADD(aItem, cVariavel3) // Adiciona um elemento no array aItem de acordo com o cVariavel3
//
//
//
//
Neste ponto o array a Item possui 03 elementos os quais podem ser acessados com:
aItem[1] -> corresponde ao contedo de cVariavel1
aItem[2] -> corresponde ao contedo de cVariavel2
aItem[3] -> corresponde ao contedo de cVariavel3
Exemplo (continuao):
//
//
//
//
//
Neste ponto, o array a aDados possui apenas um elemento, que tambm um array
contendo 03 elementos:
aDados [1][1] -> corresponde ao contedo de cVariavel1
aDados [1][2] -> corresponde ao contedo de cVariavel2
aDados [1][3] -> corresponde ao contedo de cVariavel3
AADD(aDados, aItem)
AADD(aDados, aItem)
// Neste ponto, o array aDados possui 03 elementos, aonde cada qual um array com outros
// 03 elementos, sendo:
// aDados [1][1] -> corresponde ao contedo de cVariavel1
// aDados [1][2] -> corresponde ao contedo de cVariavel2
// aDados [1][3] -> corresponde ao contedo de cVariavel3
// aDados [2][1] -> corresponde ao contedo de cVariavel1
// aDados [2][2] -> corresponde ao contedo de cVariavel2
// aDados [2][3] -> corresponde ao contedo de cVariavel3
// aDados [3][1] -> corresponde ao contedo de cVariavel1
// aDados [3][2] -> corresponde ao contedo de cVariavel2
// aDados [3][3] -> corresponde ao contedo de cVariavel3
- 169 Guia de Referncia Rpida
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.
Sintaxe: AADD(aArray)
Parmetros
aArray
Array pr-existente que ter seu contedo copiado para o array especificado.
Exemplo:
// Utilizando o array aDados utilizado no exemplo da funo AADD()
aItens := ACLONE(aDados)
// Neste ponto, o array aItens possui exatamente a mesma estrutura e informaes do array
// aDados.
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.
nPosio
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.
- 170 Guia de Referncia Rpida
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.
nTamanho
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.
ASORT()
A funo ASORT() permite que os itens de um array sejam ordenados a partir de um critrio
pr-estabelecido.
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:
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.
Exemplo:
aAlunos := {Mrcio, Denis, Arnaldo, Patrcia}
bSeek := {|x| x == Denis}
nPosAluno := aScan(aAlunos,bSeek) // retorno esperado 2
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.
nPosicao
Exemplo:
aAlunos := {Edson, Robson, Renato, Tatiana}
AINS(aAlunos,3)
// Neste ponto o array aAlunos ter o seguinte contedo:
// {Edson, Robson, nulo, Renato, Tatiana}
xParamZ
Exemplo:
nInt := 10
bBloco := {|N| x:= 10, y:= x*N, z:= y/(x*N)}
nValor := EVAL(bBloco, nInt)
//
//
//
//
//
//
//
//
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.
bFor
bWhile
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
Considerando o trecho de cdigo abaixo:
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})
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.
bBloco
nInicio
nFim
Exemplo 01:
Manipulao de strings
ALLTRIM()
Retorna uma string sem os espaos direita e esquerda, referente ao contedo informado
como parmetro.
A funo ALLTRIM() implementa as aes das funes RTRIM (right trim) e LTRIM (left
trim).
Sintaxe: ALLTRIM(cString)
Parmetros
cString
String que ser avaliada para remoo dos espaos 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.
Sintaxe: ASC(cCaractere)
Parmetros
cCaractere
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"
Case (Asc(cLetra) > 199 .and. Asc(cLetra) < 204) .or.;
(Asc(cLetra) > 231 .and. Asc(cLetra) < 236)
cLetra := "E"
Exemplo (continuao):
Case (Asc(cLetra) > 204 .and. Asc(cLetra) < 207) .or.;
(Asc(cLetra) > 235 .and. Asc(cLetra) < 240)
cLetra := "I"
Case (Asc(cLetra) > 209 .and. Asc(cLetra) < 215) .or.;
(Asc(cLetra) == 240) .or. (Asc(cLetra) > 241 .and. Asc(cLetra) < 247)
cLetra := "O"
Case (Asc(cLetra) > 216 .and. Asc(cLetra) < 221) .or.;
(Asc(cLetra) > 248 .and. Asc(cLetra) < 253)
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.
cString
Exemplo:
STATIC FUNCTION NOMASCARA(cString,cMascara,nTamanho)
LOCAL cNoMascara
LOCAL nX := 0
:= ""
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.
Sintaxe: BITON ( < cValue > , < nBitIni > , < nBitEnd > , < nStrLen > )
Parmetros
cValue
nBitIni
nBitEnd
nStrLen
CHR()
Converte um valor nmero referente a uma informao da tabela ASCII no caractere que esta
informao representa.
Sintaxe: CHR(nASCII)
Parmetros
nASCII
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
Retorno:
Caracter
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.
Parmetros:
cDtoVal
Retorno:
Numrico
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
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.
Parmetros:
cString
Retorno:
Lgico
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.
Parmetros:
cString
Retorno:
Lgico
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.
Parmetros:
cString
Retorno:
Lgico
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.
Parmetros:
cString
Retorno:
Lgico
LEN()
Retorna o tamanho da string especificada no parmetro.
Sintaxe: LEN(cString)
Parmetros
cString
Exemplo:
cNome := ALLTRIM(SA1->A1_NOME)
MSGINFO(Dados do campo A1_NOME:+CRLF
Tamanho: + CVALTOCHAR(LEN(SA1->A1_NOME))+CRLF
Texto: + CVALTOCHAR(LEN(cNome)))
LOWER()
Retorna uma string com todos os caracteres minsculos, tendo como base a string passada
como parmetro.
Sintaxe: LOWER(cString)
Parmetros
cString
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.
Retorno:
Caracter
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.
Sintaxe: MATHC ( < cNum1 > , < cOperacao > , < cNum2 > )
Parmetros:
cNum1
cOperacao
cNum2
Retorno:
Caracter
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().
Retorno:
Caracter
cExp
nTamanho
cCaracPreench
Retorno:
Caracter
RAT()
Retorna a ltima posio de um caracter ou string dentro de outra string especificada.
cString
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.
Parmetros:
cString
Retorno:
Caracter
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 > )
Parmetros:
nCont
Retorno:
Caracter
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.
Parmetros:
cValue
cToken
Retorno:
Array
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.
Sintaxe: STRTRAN ( < cString > , < cSearch > , [ cReplace ] , [ nStart ] , [
nCount ] )
Parmetros:
cString
cSearch
cReplace
nStart
nCount
Retorno:
Code-Block
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.
Parmetros:
nExcluir
cAdicao
cString
nPosInicial
Retorno:
Caracter
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).
nPosInicial
nCaracteres
Exemplo:
cCampo := A1_NOME
nPosUnder := AT(cCampo)
cPrefixo := SUBSTR(cCampo,1, nPosUnder) // A1_
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.
Parmetros:
cExp
cSayPicture
O valor a ser formatado. Esta expresso pode ser qualquer tipo de dados
vlidos, exceto vetor, bloco de cdigo, e NIL.
Uma string de caracteres de mscara e template usado para descrever o
formato da cadeia de caracteres a ser retornada.
Retorno:
UPPER()
Retorna uma string com todos os caracteres maisculos, tendo como base a string passada
como parmetro.
Sintaxe: UPPER(cString)
Parmetros
cString
Exemplo:
cTexto := ADVPL
MSGINFO(Texto:+LOWER(cTexto))
dExp
Retorno:
cDayWeek
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.
Sintaxe: CMONTH( dData )
Parmetros:
dData
Retorno:
cMonth
Exemplo:
cMes
cMes
cMes
cMes
:=
:=
:=
:=
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.
Sintaxe: DATE()
Parmetros:
Nenhum
Retorno:
dData
Data do sistema.
Exemplo:
dData := DATE() // Resultado: 09/01/01
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.
Retorno:
nDias
Exemplo:
// Estes exemplos mostram a funo DAY() de diversas maneiras:
dData := DATE() // Resultado: 09/01/01
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
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.
Retorno:
nDia
Exemplo:
dData := DATE() // Resultado: 09/01/01
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.
Retorno:
cData
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
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).
Retorno:
sData
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.
Retorno:
Caracter
Exemplo:
cHoraInicio := TIME() // Resultado: 10:00:00
...
<instrues>
...
cElapsed := ELAPTIME(TIME(), cHoraInicio)
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.
Retorno:
Numrico
Exemplo:
dData := DATE() // Resultado: 09/01/01
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.
Sintaxe: SECONDS()
Parmetros:
Nenhum
Retorno:
Numrico
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()
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.
Sintaxe: TIME()
Parmetros:
Nenhum
Retorno:
Caracter
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.
Retorno:
Numrico
Exemplo 01:
dData := DATE() // Resultado: 09/20/01
dAno := YEAR(dData) // Resultado: 2001
dAno := YEAR(dData) + 11 // Resultado: 2012
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))
nValor
Exemplo:
nPessoas := 20
nLugares := 18
IF nPessoas < nLugares
MSGINFO(Existem +CVALTOCHAR(nLugares- nPessoas)+disponveis)
ELSE
MSGSTOP(Existem +CVALTOCHAR(ABS(nLugares- nPessoas))+faltando)
ENDIF
INT()
Retorna a parte inteira de um valor especificado no parmetro.
Sintaxe: INT(nValor)
Parmetros
nValor
Exemplo:
STATIC FUNCTION COMPRAR(nQuantidade)
LOCAL nDinheiro := 0.30
LOCAL nPrcUnit := 0.25
Exemplo (continuao):
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.
nCasas
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.
nCasas
Exemplo:
nBase := 2.985
nValor := ROUND(nBase,2) 2.99
Manipulao de arquivos
SELECT()
Determina o nmero de referncia de um determinado alias em um ambiente de trabalho.
Caso o alias especificado no esteja em uso no ambiente, ser retornado o valor 0 (zero).
Sintaxe: Select(cArea)
Parmetros
cArea
Exemplo:
nArea := Select(SA1)
ALERT(Referncia do alias SA1: +STRZERO(nArea,3)) // 10 (proposto)
DBGOTO()
Move o cursor da rea de trabalho ativa para o record number (recno) especificado, realizando
um posicionamento direto, sem a necessidade uma busca (seek) prvio.
Sintaxe: DbGoto(nRecno)
Parmetros
nRecno
Exemplo:
DbSelectArea(SA1)
DbGoto(100) // Posiciona no registro 100
IF !EOF() // Se a rea de trabalho no estiver em final de arquivo
MsgInfo(Voc est no cliente:+A1_NOME)
ENDIF
DBGOTOP()
Move o cursor da rea de trabalho ativa para o primeiro registro lgico.
Sintaxe: DbGoTop()
Parmetros
Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbGoTop()
While !BOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(-1)
End
DBGOBOTTON()
Move o cursor da rea de trabalho ativa para o ltimo registro lgico.
Sintaxe: DbGoBotton()
Parmetros
Nenhum
Exemplo:
nCount := 0 // Varivel para verificar quantos registros h no intervalo
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbGoBotton()
While !EOF() // Enquanto no for o incio do arquivo
nCount++ // Incrementa a varivel de controle de registros no intervalo
DbSkip(1)
End
MsgInfo(Existem :+STRZERO(nCount,6)+ registros no intervalo).
// Retorno esperado :000001, pois o DbGoBotton posiciona no ltimo registro.
DBSELECTAREA()
Define a rea de trabalho especificada 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.
nArea
cArea
Sintaxe: DbSetOrder(nOrdem)
Parmetros
nOrdem
Nmero de referncia da ordem que deseja ser definida como ordem ativa
para a rea de trabalho.
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // De acordo com o arquivo SIX -> A1_FILIAL+A1_COD+A1_LOJA
DBORDERNICKNAME()
Define qual ndice criado pelo usurio seja utilizado. O usurio pode incluir os seus prprios
ndices e no momento da incluso deve criar o NICKNAME para o mesmo.
Sintaxe: DbOrderNickName(NickName)
Parmetros
NickName
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.
Sintaxe: DbSeek(cChave, lSoftSeek, lLast)
Parmetros
cChave
lSoftSeek
lLast
Sintaxe: DbSkip(nRegistros)
Parmetros
nRegistros
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.
cCondicao
DBSTRUCT()
Retorna um array contendo a estrutura da rea de trabalho (alias) ativo. A estrutura ser um
array bidimensional conforme abaixo:
ID*
Nome campo
Tipo campo
Tamanho
Decimais
*ndice do array
Sintaxe: DbStruct()
Parmetros
Nenhum
Exemplo:
cCampos :=
DbSelectArea(SA1)
aStructSA1 := DbStruct()
FOR nX := 1 to Len(aStructSA1)
cCampos += aStructSA1[nX][1] + /
NEXT nX
ALERT(cCampos)
RECLOCK()
Efetua o travamento do registro posicionado na rea de trabalho ativa, permitindo a incluso
ou alterao das informaes do mesmo.
Sintaxe: RecLock(cAlias,lInclui)
Parmetros
cAlias
lInclui
Exemplo 01 - Incluso
DbSelectArea(SA1)
RecLock(SA1,.T.)
SA1->A1_FILIAL := xFilial(SA1) // Retorna a filial de acordo com as configuraes do ERP
SA1->A1_COD := 900001
SA1->A1_LOJA := 01
MsUnLock() // Confirma e finaliza a operao
Exemplo 02 - Alterao
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
ENDIF
MSUNLOCK()
Libera o travamento (lock) do registro posicionado confirmando as atualizaes efetuadas
neste registro.
Sintaxe: MsUnLock()
Parmetros
Nenhum
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found() // Avalia o retorno do ltimo DbSeek realizado
RecLock(SA1,.F.)
SA1->A1_NOME := CLIENTE CURSO ADVPL BSICO
SA1->A1_NREDUZ := ADVPL BSICO
MsUnLock() // Confirma e finaliza a operao
ENDIF
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.
Sintaxe: SoftLock(cAlias)
Parmetros
cAlias
Exemplo:
cChave := GetCliente() // Funo ilustrativa que retorna os dados de busca de um cliente
DbSelectArea(SA1)
DbSetOrder(1)
DbSeek(cChave)
IF Found()
SoftLock() // Reserva o registro localizado
lConfirma := AlteraSA1() // Funo ilustrativa que exibe os dados do registro
// posicionado e pemite a alterao dos mesmos.
IF lConfirma
RecLock(SA1,.F.)
GravaSA1() // Funo ilustrativa que altera os dados conforme a AlertaSA1()
MsUnLock() // Liberado o RecLock() e o SoftLock() do registro.
Endif
Endif
DBDELETE()
Efetua a excluso lgica do registro posicionado na rea de trabalho ativa, sendo necessria
sua utilizao em conjunto com as funes RecLock() e MsUnLock().
Sintaxe: DbDelete()
Parmetros
Nenhum
Exemplo:
DbSelectArea(SA1)
DbSetOrder(1) // A1_FILIAL + A1_COD + A1_LOJA
DbSeek(01 + 900001 + 01) // Busca exata
IF Found()
RecLock(SA1,.F.) // Define que ser realizada uma alterao no registro posicionado
DbDelete() // Efetua a excluso lgica do registro posicionado.
MsUnLock() // Confirma e finaliza a operao
ENDIF
DBUSEAREA()
Define um arquivo de base de dados como uma rea de trabalho disponvel na aplicao.
Sintaxe: DbUseArea(lNovo, cDriver, cArquivo, cAlias, lComparilhado,;
lSoLeitura)
Parmetros
lNovo
cDriver
cArquivo
cAlias
lComparilhado
lSoLeitura
Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
DBCLOSEAREA()
Permite que um alias presente na conexo seja fechado, o que viabiliza 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().
Sintaxe: DbCloseArea()
Parmetros
Nenhum
Exemplo:
DbUserArea(.T., DBFCDX, \SA1010.DBF, SA1DBF, .T., .F.)
DbSelectArea(SA1DBF)
MsgInfo(A tabela SA1010.DBF possui: + STRZERO(RecCount(),6) + registros.)
DbCloseArea()
cCampo
cAliasSXE
nOrdem
CONFIRMSXE()
Confirma o nmero alocado atravs do ltimo comando GETSXENUM().
Sintaxe: CONFIRMSXE(lVerifica)
Parmetros
lVerifica
ROLLBACKSXE()
Descarta o nmero fornecido pelo ltimo comando GETSXENUM(), retornando a numerao
disponvel para outras conexes.
Sintaxe: ROLLBACKSXE()
Parmetros
Nenhum
Validao
EXISTCHAV()
Retorna .T. ou .F. se o contedo especificado existe no alias especificado. Caso exista ser
exibido um help de sistema com um aviso informando da ocorrncia.
Funo utilizada normalmente para verificar se um determinado cdigo de cadastro j existe
na tabela na qual a informao ser inserida, como por exemplo o CNPJ no cadastro de
clientes ou fornecedores.
cConteudo
nIndice
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.
cAlias
cConteudo
nIndice
NAOVAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento no est vazio.
Sintaxe: NaoVazio()
Parmetros
Nenhum
NEGATIVO()
Retorna .T. ou .F. se o contedo digitado para o campo negativo.
Sintaxe: Negativo()
Parmetros
Nenhum
PERTENCE()
Retorna .T. ou .F. se o contedo digitado para o campo est contido na string definida como
parmetro da funo. Normalmente utilizada em campos com a opo de combo, pois caso
contrrio seria utilizada a funo ExistCpo().
Sintaxe: Pertence(cString)
Parmetros
cString
POSITIVO()
Retorna .T. ou .F. se o contedo digitado para o campo positivo.
Sintaxe: Positivo()
Parmetros
Nenhum
TEXTO()
Retorna .T. ou .F. se o contedo digitado para o campo contm apenas nmeros ou
alfanumricos.
Sintaxe: Texto()
Parmetros
Nenhum
VAZIO()
Retorna .T. ou .F. se o contedo do campo posicionado no momento est vazio.
Sintaxe: Vazio()
Parmetros
Nenhum
Parmetros
GETMV()
Retorna o contedo do parmetro especificado no arquivo SX6, considerando a filial
parametrizada na conexo. Caso o parmetro no exista ser exibido um help do sistema
informando a ocorrncia.
Sintaxe: GETMV(cParametro)
Parmetros
cParametro
GETNEWPAR()
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.
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.
cParametro
cPadrao
cFilial
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
PUTMV()
Atualiza o contedo do parmetro especificado no arquivo SX6, de acordo com as
parametrizaes informadas.
cConteudo
SUPERGETMV()
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.
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.
cParametro
lHelp
cPadrao
cFilial
Define para qual filial ser efetuada a consulta do parmetro. Padro filial
corrente da conexo.
Sintaxe:
Parmetros
oObjetoDLG
cTitulo
nLinIni, nColIni
nLiFim, nColFim
oObjetoRef
UNIDADE
Exemplo:
DEFINE MSDIALOG oDlg TITLE cTitulo FROM 000,000 TO 080,300 PIXEL
ACTIVATE MSDIALOG oDlg CENTERED
MSGET()
Define o componente visual MSGET, o qual utilizado para captura de informaes digitveis
na tela da interface.
Sintaxe:
Parmetros
nLinha, nColuna
VARIAVEL
nLargura,nAltura
UNIDADE
oObjetoRef
cF3
VALID
WHEN
cPicture
Exemplo:
@ 010,050 MSGET cCGC
VALID !Vazio()
SAY()
Define o componente visual SAY, o qual utilizado para exibio de textos em uma tela de
interface.
Sintaxe:
Parmetros
nLinha, nColuna
cTexto
nLargura,nAltura
UNIDADE
oObjetoRef
Exemplo:
@ 010,010 SAY
BUTTON()
Define o componente visual Button, o qual permite a incluso de botes de operao na tela
da interface, os quais sero visualizados somente com um texto simples para sua identificao.
Sintaxe: BUTTON()
Parmetros
nLinha,nColuna
cTexto
nLargura,nAltura
UNIDADE
oObjetoRef
AO
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) prdefinido.
Sintaxe: SBUTTON()
Parmetros
nLinha, nColuna
TYPE N
AO
STATUS
oObjetoRet
Exemplo:
DEFINE SBUTTON FROM 020, 120 TYPE 2 ACTION (nOpca := 2,oDlg:End());
ENABLE OF oDlg
Interfaces de cadastro
AXCADASTRO()
Sintaxe
Descrio
MBROWSE()
Sintaxe
Descrio
AXPESQUI()
Funo de pesquisa padro em registros exibidos pelos browses do sistema, a qual posiciona o
browse no registro pesquisado. Exibe uma tela que permite a seleo do ndice a ser utilizado
na pesquisa e a digitao das informaes que compe a chave de busca.
Sintaxe: AXPESQUI()
Parmetros
Nenhum
AXVISUAL()
Funo de visualizao padro das informaes de um registro, no formato Enchoice, conforme
demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AXVISUAL(cAlias, nReg, nOpc, aAcho, nColMens, cMensagem, cFunc,;
aButtons, lMaximized )
Parmetros
cAlias
nReg
nOpc
aAcho
nColMens
Parmetro no utilizado.
cMensagem
Parmetro no utilizado.
cFunc
aButtons
lMaximized
Funo que dever ser utilizada para carregar as variveis que sero
utilizadas pela Enchoice. Neste caso o parmetro lVirtual definido
internamente pela AxFunction() executada como .T.
Botes adicionais para a EnchoiceBar, no formato:
aArray[n][1] -> Imagem do boto
aArray[n][2] -> bloco de cdigo contendo a ao do boto
aArray[n][3] -> ttulo do boto
Indica se a janela dever ser ou no maximizada
AXINCLUI()
Funo de incluso padro das informaes de um registro, no formato Enchoice, conforme
demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AxInclui(cAlias, nReg, nOpc, aAcho, cFunc, aCpos, cTudoOk, lF3,;
cTransact, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
cAlias
nReg
nOpc
aAcho
cFunc
aCpos
cTudoOk
cTransact
aButtons
aParam
aAuto
lVirtual
lMaximized
AXALTERA()
Funo de alterao padro das informaes de um registro, no formato Enchoice, conforme
demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AXALTERA(cAlias, nReg, nOpc, aAcho, aCpos, nColMens, cMensagem,;
cTudoOk, cTransact, cFunc, aButtons, aParam, aAuto, lVirtual, lMaximized)
Parmetros
AXDELETA()
Funo de excluso padro das informaes de um registro, no formato Enchoice, conforme
demonstrado no tpico sobre a interface AxCadastro().
Sintaxe: AXDELETA(cAlias, nReg, nOpc, cTransact, aCpos, aButtons, aParam,;
aAuto, lMaximized)
Parmetros
cAlias
nReg
nOpc
cTransact
aCpos
aButtons
aParam
aAuto
lMaximized
Sintaxe: AVISO(cTexto)
Parmetros
cTexto
AVISO()
Parmetros
cTitulo
Ttulo da janela
cTexto
Texto do aviso
aBotoes
nTamanho
Tamanho (1,2 ou 3)
FORMBACTH()
aBotoes
Ttulo da janela
Array simples (vetor) contendo cada uma das linhas de texto que sero
exibidas no corpo da tela.
Array com os botes do tipo SBUTTON(), com a seguinte estrutura:
{nTipo,lEnable,{|| Ao() }}
bValid
nAltura
nLargura
MSGFUNCTIONS()
Sintaxe:
Sintaxe:
Sintaxe:
Sintaxe:
MSGALERT(cTexto, cTitulo)
MSGINFO(cTexto, cTitulo)
MSGSTOP(cTexto, cTitulo)
MSGYESNO(cTexto, cTitulo)
Parmetros
cTexto
cTitulo
MSGALERT
MSGINFO
MSGSTOP
MSGYESNO
Sintaxe: GETAREA()
Retorno: Array contendo {Alias(),IndexOrd(),Recno()}
Parmetros
Nenhum
RESTAREA()
Funo utilizada para devolver a situao do ambiente salva atravs do comando GETAREA().
Deve-se observar que a ltima rea restaurada a rea que ficar ativa para a aplicao.
Sintaxe: RESTAREA(aArea)
Parmetros
aArea
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 )