ADVPL - OOP Organon

Ewerton Alex Vicentin
________________________________________________
PROGRAMAÇÃO ADVPL OOP
2005 – Campinas – SP – Brasil

organon TI Consultoria e Treinamento
Índice
______________________________________________________________________________________________________________
Prefácio .........................................................................................................8
O Que é Fazer um Programa com Inteligência................................................................... 8
Programando Simples, mas Certo ...................................................................................... 9
Erros que Podem ser Evitados .......................................................................................... 10
A Importância de Programas Documentados ................................................................... 10
Cabeçalho de Programa / Função ..................................................................................... 11
Padrão de Desenvolvimento – ORGANON TI Campinas.....................12
Nomenclatura de Variáveis .............................................................................................. 12
Índices............................................................................................................................... 12
Operadores Básicos ...................................................................................13
Criação de Variáveis..................................................................................13
A Declaração .................................................................................................................... 14
O Tipo de Variável ........................................................................................................... 14
Tipos Existentes................................................................................................................ 14
Public ............................................................................................................................ 14
Private........................................................................................................................... 14
Local ............................................................................................................................. 14
Static ............................................................................................................................. 15
Inicialização...................................................................................................................... 15
Padronização de Variáveis ............................................................................................... 15
Criando uma Variável Utilizando a Função CRIAVAR() ............................................... 15
Declarando e utilizando vetores e matrizes ...................................................................... 16
Utilizando Estruturas de Controle ..........................................................17
While... ............................................................................................................................. 17
For..................................................................................................................................... 17
If… ................................................................................................................................... 18
If ().................................................................................................................................... 18
Do Case ............................................................................................................................ 18
Problemas com Looping de Programas ............................................................................ 19
Comandos definidos pelo usuário (UDC’s).............................................20
Uso de Strings................................................................................................................... 21
Funções para Manipulação de Mensagens ..............................................22
MsAlert............................................................................................................................. 22
MsgStop............................................................................................................................ 22
MsgInfo ............................................................................................................................ 22
MsgBox ............................................................................................................................ 23
MsgYesNo ........................................................................................................................ 23
Funções para Manipulação de Strings.....................................................24
SubStr ............................................................................................................................... 24
Len .................................................................................................................................... 24
Trim .................................................................................................................................. 24
LTrim................................................................................................................................ 24
AllTrim ............................................................................................................................. 24
Val .................................................................................................................................... 24
DtoC ................................................................................................................................. 25
Oficina AdvPl Object Página: 1
Capital............................................................................................................................... 25
Funções para Manipulação de Datas.......................................................25
CtoD ................................................................................................................................. 25
Day ................................................................................................................................... 25
Month ............................................................................................................................... 25
Year .................................................................................................................................. 25
DOW................................................................................................................................. 26
Funções para Manipulação de Números..................................................26
Int...................................................................................................................................... 26
Str ..................................................................................................................................... 26
StrZero .............................................................................................................................. 26
Round ............................................................................................................................... 26
Funções Básicas para Criação de Telas...................................................27
@...To...Dialog ................................................................................................................. 27
Activate Dialog................................................................................................................. 27
@ ...TO ............................................................................................................................. 27
@... GET........................................................................................................................... 28
@... SAY .......................................................................................................................... 28
@...Button......................................................................................................................... 28
@...BmpButton................................................................................................................. 29
@...CheckBox...Var.......................................................................................................... 29
@...ComboBox...Itens...Size ............................................................................................ 29
@...Radio .......................................................................................................................... 30
@... Bitmap... Size............................................................................................................ 30
@..To...MultiLine............................................................................................................. 30
Enchoicebar ...................................................................................................................... 31
AxCadastro ....................................................................................................................... 31
MarkBrowse ..................................................................................................................... 32
MBrowse .......................................................................................................................... 32
Modelo2............................................................................................................................ 33
Modelo3............................................................................................................................ 34
Funções para Manipulação de Réguas de Processamento.....................34
Processa ............................................................................................................................ 34
ProcRegua......................................................................................................................... 34
IncProc.............................................................................................................................. 35
RptStatus........................................................................................................................... 35
SetRegua........................................................................................................................... 35
IncRegua........................................................................................................................... 36
Funções para Criação de Relatórios Padronizados ...............................36
Variáveis de Relatórios..................................................................................................... 36
Cabec ................................................................................................................................ 37
PSay.................................................................................................................................. 38
SetPrint ............................................................................................................................. 38
SetDefault ......................................................................................................................... 38
Funções para Tratamento de Usuários do Sistema................................39
AllUsers ............................................................................................................................ 39
AllGroups ......................................................................................................................... 40
PswAdmin ........................................................................................................................ 41
PswID ............................................................................................................................... 41
PswName .......................................................................................................................... 42
PswSeek............................................................................................................................ 42
PswOrder .......................................................................................................................... 42
PswRet ........................................................................................................42
Funções Genéricas do ADVPL ..................................................................43
Aleatorio ........................................................................................................................... 43
CGC .................................................................................................................................. 43
Condicao........................................................................................................................... 44
ConvMoeda ...................................................................................................................... 44
DataValida ........................................................................................................................ 45
Digito11 ............................................................................................................................ 45
EANDigito........................................................................................................................ 45
Entre ................................................................................................................................. 46
Extenso ............................................................................................................................. 46
Formula............................................................................................................................. 46
GetArea............................................................................................................................. 47
GetMV .............................................................................................................................. 47
Help .................................................................................................................................. 47
LetterOrNum .................................................................................................................... 48
MesExtenso ...................................................................................................................... 48
NaoVazio .......................................................................................................................... 48
Negativo ........................................................................................................................... 49
Pergunte ............................................................................................................................ 49
Pertence ............................................................................................................................ 49
PesqPict ............................................................................................................................ 50
PesqPictQt ........................................................................................................................ 50
Positivo ............................................................................................................................. 50
RestArea ........................................................................................................................... 51
Tabela ............................................................................................................................... 51
Variação............................................................................................................................ 51
Vazio................................................................................................................................. 51
XFilial............................................................................................................................... 52
Funções para Tratamento de Bases de Dados.........................................52
AbreExcl........................................................................................................................... 52
Contar ............................................................................................................................... 53
CriaTrab............................................................................................................................ 53
DbSelectArea.................................................................................................................... 54
DbSetOrder....................................................................................................................... 54
DbSeek ............................................................................................................................. 54
DbSkip .............................................................................................................................. 55
RecLock............................................................................................................................ 55
MSUnlock......................................................................................................................... 55
ExistChav ......................................................................................................................... 55
ExistCpo ........................................................................................................................... 56
ExistIni ............................................................................................................................. 56

IndRegua........................................................................................................................... 57
Posicione........................................................................................................................... 57
RetIndex ........................................................................................................................... 57
Tabela ............................................................................................................................... 58
TamSX3............................................................................................................................ 58
Índices............................................................................................................................... 58
Criando e Deletando Arquivos de Índice (Temporários.) ............................................... 59
Utilizando Querys no lugar de índices temporários ......................................................... 59
Cuidados com Posicionamento de Registros.................................................................... 59
Conceito de Filial e Compartilhamento de Arquivos ....................................................... 61
Arquivos Compartilhados............................................................................................. 61
Arquivos Exclusivos..................................................................................................... 61
Técnicas para Filtragem.................................................................................................... 62
Chaves Primárias .............................................................................................................. 62
Chaves Estrangeiras.......................................................................................................... 62
Integridade Referencial..................................................................................................... 62
Funções para Tratamento do Módulo de Contabilidade .......................63
CalcSaldo.......................................................................................................................... 63
Credito .............................................................................................................................. 64
Debito ............................................................................................................................... 64
MovimCC ......................................................................................................................... 64
Movimento ....................................................................................................................... 64
Orcado .............................................................................................................................. 65
OrcadoCC ......................................................................................................................... 65
Periodo.............................................................................................................................. 65
Saldo ................................................................................................................................. 66
SaldoCC............................................................................................................................ 66
SaldoCusto........................................................................................................................ 66
SomaSaldo ........................................................................................................................ 67
SumMovimCC.................................................................................................................. 67
SomaContas ...................................................................................................................... 67
Funções para Tratamento do Módulo de Estoque/Custos.....................68
CalcEst.............................................................................................................................. 68
Estrut................................................................................................................................. 68
SaldoSB2 .......................................................................................................................... 68
Funções do Módulo Financeiro.................................................................69
FuncaMoeda ..................................................................................................................... 69
Media ................................................................................................................................ 69
RecMoeda......................................................................................................................... 69
SldBco .............................................................................................................................. 70
SldCliente ......................................................................................................................... 70
SldFornece ........................................................................................................................ 70
SldPagar............................................................................................................................ 70
SldReceber........................................................................................................................ 71
XMoeda ............................................................................................................................ 71
Pontos de Entrada......................................................................................71
Objetivo dos Pontos de Entrada ....................................................................................... 71

Quando criar um Ponto de Entrada................................................................................... 72

Procedimentos para sua criação........................................................................................ 72
Usando Rotinas Automáticas ..................................................................72
Controle de Semáforo ................................................................................73
GetSX8Num ..................................................................................................................... 74
ConfirmSX8 ..................................................................................................................... 74
RollBackSX8 .................................................................................................................... 74
Programando para Banco de Dados ........................................................75
Controle de Transação (TTS) ........................................................................................... 75
Quando usar...................................................................................................................... 75
Como usar......................................................................................................................... 75
Onde não usar ................................................................................................................... 75
Portabilidade..................................................................................................................... 76
Dicas Importantes – DBF versus SQL ............................................................................. 76
Função da coluna R_E_C_N_O_ ..................................................................................... 77
Limite de registros ............................................................................................................ 77
Renumeração da coluna RECNO ..................................................................................... 78
Controle dos registros deletados (Coluna D_E_L_E_T_)............................................... 78
Comandos do TOPCONNECT......................................................................................... 78
TcQuery ............................................................................................................................ 78
TcSQLExec ...................................................................................................................... 79
TcSetField......................................................................................................................... 79
TcSPExec ......................................................................................................................... 79
Performance com SGDB - Otimizando seu código......................................................... 80
Leitura Sequencial ............................................................................................................ 80
Introdução à Linguagem Orientada a Objetos.......................................81
Conceitos Básicos da OOP .......................................................................81
Classe................................................................................................................................ 81
Objeto ............................................................................................................................... 81
Mensagem......................................................................................................................... 81
Método.............................................................................................................................. 82
Método CONSTRUCTOR ........................................................................................... 82
Método DESTRUCTOR .............................................................................................. 82
Eventos ............................................................................................................................. 82
Herança............................................................................................................................. 82
Encapsulamento................................................................................................................ 83
Criação de Janelas padrão OOP ..............................................................84
Sintaxe do método Constructor da classe TWindow:....................................................... 85
Propriedades dos objetos da classe TWindow.................................................................. 85
Principais propriedades de estilo de janela................................................................... 85
Tabela de cores padrão ................................................................................................. 86
Métodos da classe TWindow............................................................................................ 87
Sintaxe do método Activate.......................................................................................... 87
Exemplo de Código Fonte para Criação de um Objeto de Janela .................................... 88
Caixas de Diálogo no padrão OOP .........................................................89
Sintaxe do método Constructor da classe TDialog:.......................................................... 89
Propriedades dos objetos da classe TWindow.................................................................. 89
Principais propriedades de estilo de caixas de diálogo................................................. 89

Tabela de cores padrão ................................................................................................. 90
Métodos da classe TDialog............................................................................................... 91
Sintaxe do método Activate.......................................................................................... 91
Exemplo de Código Fonte para Criação de Objeto de Janela .......................................... 92
Objetos de Controle ...................................................................................93
Botões ............................................................................................................................... 93
Sintaxe da Classe TBUTTON ...................................................................................... 93
Sintaxe da Classe SBUTTON ...................................................................................... 94
Exemplos de Código Fonte para Criação de um Objetos de botões................................. 95
Código Fonte exemplo para criação de botões simples................................................ 95
Código fonte exemplo para criação de botões com bitmap.......................................... 96
Rótulos de Texto............................................................................................................... 98
Sintaxe da Classe TSAY .............................................................................................. 98
Seleção de fontes para o objeto de rótulo de texto ....................................................... 98
Código fonte exemplo para criação de rótulos. .......................................................... 100
Caixas de Texto .............................................................................................................. 101
Sintaxe da Classe TGET............................................................................................. 101
Código fonte exemplo para criação de caixas de texto. ............................................. 102
CheckBox ....................................................................................................................... 103
Sintaxe da Classe TCheckBox.................................................................................... 103
Código fonte exemplo para criação de CheckBoxes .................................................. 104
ComboBox...................................................................................................................... 105
Sintaxe da Classe TComboBox .................................................................................. 105
Código fonte exemplo para criação de ComboBoxes ................................................ 106
ListBox ........................................................................................................................... 107
Sintaxe da Classe TListBox........................................................................................ 107
Código fonte exemplo para criação de ListBoxes...................................................... 108
Radio Button................................................................................................................... 109
Sintaxe da Classe TRadMenu..................................................................................... 109
Código fonte exemplo para criação de Radio Button................................................. 110
Folders ............................................................................................................................ 111
Sintaxe da Classe TFolder .......................................................................................... 111
Métodos importantes da classe TFolder ..................................................................... 112
Código fonte exemplo para criação de múltiplos Folders com vários objetos dentro 112
Browse ............................................................................................................................ 113
Sintaxe da Classe TWBrowse .................................................................................... 113
Código fonte exemplo para criação de browse completo........................................... 114
Criação de janelas mestre-detalhe OOP ............................................... 116
Modelo 3......................................................................................................................... 116
Sintaxe da classe MSMGET....................................................................................... 117
Construindo um código fonte para criação de um modelo 3...................................... 118
Sintaxe da classe MsGetDados................................................................................... 119
Sintaxe da Classe MSGETDB.................................................................................... 125
Criação de relatórios com qualidade gráfica ........................................ 127
Classe TMSPRINTER.................................................................................................... 127
Sintaxe da Classe TMSPRINTER .............................................................................. 127

Principais métodos da classe TMSPRINTER ............................................................ 127

Principais métodos para impressão de dados ............................................................. 127
Código fonte exemplo para impressão de relatórios com qualidade gráfica .............. 129
Rotinas de Web......................................................................................... 130
Envio de e-mail pelo sistema (Send Mail) através de SMTP ......................................... 130
Função para conectar-se ao servidor .......................................................................... 130
Função para envio da mensagem................................................................................ 130
Função para desconectar-se do servidor..................................................................... 130
Código fonte exemplo para envio de e-mails pelo sistema ........................................ 131
Workflow .................................................................................................. 132
Objetivos......................................................................................................................... 132
Requisitos ....................................................................................................................... 132
Software Necessário para Instalação .............................................................................. 132
Servidor de E-mail...................................................................................................... 133
Clientes de E-mail ...................................................................................................... 133
Parâmetros de Configuração........................................................................................... 133
Desenvolvimento ............................................................................................................ 136
Construindo uma página HTML..................................................................................... 136
Criação do Processo ................................................................................................. 137
Definindo o Assunto do E-mail (propriedade cSubject) ............................................ 137
Definindo o(s) Destinatário(s) com cópia do E-mail (propriedade cCC).................. 137
Definindo o(s) Destinatário(s) com cópia oculta do E-mail (propriedade cBCC) ..... 137
Definindo o HTML no corpo da mensagem............................................................... 138
Definindo a Função de TimeOut (propriedade bTimeOut) ........................................ 138
Iniciando o Processo................................................................................................... 138
Pegando o valor de retorno de um objeto dentro do HTML ...................................... 138
Finalizando o Processo. .............................................................................................. 138
Ativando o Workflow..................................................................................................... 139
Agendando o Envio de Emails ....................................................................................... 140
Rastreabilidade ............................................................................................................... 140
Outros Exemplos de Uso do Workflow.......................................................................... 141
Exemplo de Atualização de Preços ................................................................................ 144
Construindo o HTML ................................................................................................. 144
Criando o Ponto de Entrada com o Processo do Workflow ....................................... 146
Rotina de Exemplo de Envio e Retorno do workflow................................................ 146
Configurando o ambiente do Apx / MPx para o Workflow. ...................................... 147

Prefácio
Para muitos profissionais de desenvolvimento, entrar ou se aprimorar no
desenvolvimento de rotinas ADVPL é garantia de galgar melhores oportunidades
profissionais.
O Objetivo principal desse material é fornecer subsídios para o programador

experiente ou não no desenvolvimento em AdvPl (Advanced Protheus Language),
um diferencial tecnológico permitindo o desenvolvimento de aplicações mais
poderosas e mais amigáveis para o usuário final.
Nossa metodologia de trabalho consiste em apresentar de forma clara novas

opções à programação utilizando-se dos recursos de orientação a objetos, acesso a
bancos relacionais e muito mais...
Para que possamos obter o maior índice de aproveitamento, desenvolvemos

laboratórios práticos que envolverão os alunos nas tarefas de compilação e
depuração dos programas, tentamos evitar a árdua tarefa de digitar os códigos
fonte utilizados nos testes, direcionando o tempo do curso para o efetivo
aprendizado da ferramenta.
Os conceitos de funcionamento do sistema são importantes para que os

programadores possam entender o processo de compilação e execução das rotinas.
Seja bem vindo ao mundo dos programadores que fazem diferença!!!
O Que é Fazer um Programa com Inteligência

Precisamos entender, antes de mais nada, o que é inteligência.
Segundo o dicionário Michaelis, inteligência significa:

Faculdade de entender, pensar, raciocinar e interpretar;
Compreensão, conhecimento profundo.
De acordo com essa definição, se pretendemos utilizar nosso bem mais precioso
em nosso trabalho, vamos precisar desenvolver alguns hábitos:
Devemos estudar o programa antes de começar a desenvolver. Imagine prestar um

concurso ou fazer uma prova sem estudar. Vai ganhar um zero na certa! No
programa não será diferente!
Fazer um levantamento dos programas que sofrerão as conseqüências das

alterações realizadas. Todos esses programas deverão ser testados juntamente com
o programa alterado.

Antes de criar uma função, consulte o Guia Eletrônico Organon de AdvPl ou os

colegas de trabalho, pois esta função já pode ter sido criada.
Ao criar uma função, certifique-se de que no cabeçalho conste algumas

informações básicas como: descrição da função, sintaxe, definição dos parâmetros
e autor. É comum ao desenvolver uma função, utilizarmos outra já pronta como
exemplo, e neste momento o “copiar/colar” nos faz esquecer de alterar estas
informações.
Imagine se alguém desenvolver uma função inconsistente e esquecer de trocar o

seu nome no cabeçalho. Devemos assumir a responsabilidade de nossos atos.
Ao fazer a documentação das alterações realizadas, certifique-se de que as

informações estão claras, não só para o seu entendimento mas para que os colegas
não percam tempo tentando entender-las.
Ao realizar os testes, defina critérios. Antes de começar defina onde quer chegar.
Não basta consistir suas alterações. O fato de suas alterações estarem funcionando
como previstas não garante a não existência de erros.
Não limite-se a testar sua alteração na base que você utilizou durante o
desenvolvimento, pois você criou o ambiente perfeito para que o programa
funcione.
Pode parecer um pouco trabalhoso passar por estes processos no decorrer do

desenvolvimento do sistema, mas se medidas como estas não forem tomadas, o
que era extremamente simples se tornará extremamente trabalhoso.
Programando Simples, mas Certo

Qual profissional da área de informática ainda não se deparou com um código
fonte que parecia estar escrito em outro dialeto mesmo com todo conhecimento
adquirido naquela linguagem, este fato geralmente ocorre pela má utilização de
sintaxes complexas que nem sempre significam um bom funcionamento do
sistema.
Um profissional da área de informática não possui nenhum modelo padrão para

desenvolver os seus algoritmos, porém é necessária a aplicação da ética
profissional para que se possa desenvolver algoritmos de maneira simples e
correta, este conceito se baseia nos seguintes aspectos:
Entender qual o objetivo do processo em questão

Analisar a melhor forma de desenvolver um algoritmo que seja de fácil
manutenção.
Utilizar comandos e sintaxes que utilizem o máximo de simplicidade e clareza
possível.
Erros que Podem ser Evitados

Existem alguns erros que com um pouco de atenção, podem ser evitados, tais
como:
• Verifique se a variável está declarada antes do uso;
• Ao declarar uma variável, verifique qual a necessidade de ter essa variável e

qual o tipo e a sua classe;
• Classifiquem as funções e os procedimentos conforme a necessidade, como

por exemplo, na declaração de um array, defina o seu tamanho e no uso
verifique se o elemento existe;
• Salve a ordem e a área e o registro do arquivo que será utilizado para que
no final do processo se recupere estes valores;
• Evite retornar da função antes do seu final, ou seja, crie preferencialmente

um único retorno;
• Valide sempre o retorno no caso de um do ponto de entrada;
• Quando for gravar um arquivo que utiliza campos de outros arquivos,

posicione todos os arquivos e registros antes de iniciar a gravação, e
descreva o alias do campo;
• Utilize de arquivo CH nas strings para localização;
• Quando possível utilize a linguagem SQL, pois minimiza o tempo de

execução em muitos processos.
A Importância de Programas Documentados

Todos sabemos o quanto é difícil elaborar e manter uma documentação técnica
atualizada. Diante desse cenário, o que nos resta? Obviamente que pelo menos os
programas sejam documentados, bem documentados.
Documentar bem, não significa que tenhamos que escrever dezenas de linhas de
comentários a cada linha de código. Significa que os comentários têm passar
alguma informação relevante. Vemos comentários assim: “compara A com B” e só.
Isso é óbvio, a leitura do código já nos diz isso. A documentação deve se ater a
conceitos, por exemplo: “Se A for maior que B, o arquivo de saldos será atualizado,
caso contrário o registro será rejeitado para que o saldo não fique negativo.”. Isto
sim transmite alguma informação.

Também se pode utilizar desse recurso para fazer lembretes a fatos importantes
que, se forem deixados de lado, podem comprometer o funcionamento das rotinas.
Por exemplo: “Ao acionar esta função, o arquivo XXX DEVE estar posicionado no
índice 1”.
E os cabeçalhos? Quantos programas são “aproveitados” e nem sequer o nome do

autor é trocado? Se o analista X tivesse escrito todos programas que aparece como
autor ele deveria ter começado na época do Charles Babage. O cabeçalho das
funções deve conter o nome do autor, data de criação, uma descrição sumária de
sua funcionalidade, a sintaxe e por último, mas não menos importante, a descrição
dos argumentos de entrada e saída. A respeito desse último item deve-se ter
especial atenção nas manutenções, pois novos argumentos são criados e nem
sempre são declarados nessa seção da documentação do cabeçalho, isso é muito
grave.
No IDE do PROTHEUS existem opções bastante interessantes para nos auxiliar

nessa tarefa. Experimente as opções Inserir, Documentação de cabeçalho e Inserir,
Documentação de Explicação.
Existe ainda um tipo de documentação que nem sempre é observada, é aquela

inerente ao próprio código. Programas cujas variáveis são declaradas como nX,
cVAR1, dAUX, nNUM, etc., são extremamente difíceis de entender e pior, manter.
É conveniente que os nomes das variáveis retratem seu uso ou destino. Por
exemplo: dDataDe ou dDataAte. Segundo as convenções da ORGANON TI,
variáveis do tipo DATA por exemplo devem ser iniciadas pela letra “d”. O restante
deve ser utilizado para representar o que a variável realmente acumulará.
Enfim, como foi dito, não é preciso escrever um livro a cada programa, basta ser
objetivo e se colocar na posição de quem não conhece o programa tão pouco o
assunto. Algum dia você mesmo poderá estar nessa posição.
Cabeçalho de Programa / Função

O cabeçalho do programa é utilizado para identificar informações gerais sobre a
rotina, seu autor, data, entre outras informações. É importante que esteja
preenchida de forma correta e atualizada. Lembre-se de que nada adianta um
cabeçalho que não informe nada ou pior ainda, com informações errôneas.
Lembre-se que um bom livro começa com um bom prefácio, e um bom programa
começa com um cabeçalho útil e legível.
A manutenção/atualização do cabeçalho é de responsabilidade da última pessoa

que alterou o fonte. O cabeçalho de programa sugerido pela ORGANON TI
contém: rotina, autor, data do desenvolvimento, comentário sintético e sintaxe.

Padrão de Desenvolvimento – ORGANON TI Campinas

A ORGANON TI Campinas trabalha com um padrão de desenvolvimento em
relação à nomenclatura, seja de variáveis, rotinas, campos ou índices que difere do
padrão adotado pela Microsiga matriz para que, em uma atualização de versão, em
qualquer uma das situações acima, não coincida com qualquer novo nome adotado
pela mesma.
Nomenclatura de Variáveis
O nome das variáveis deve ter sempre no seu início o caracter “_” (underline).
Além disso, deve-se ter um caracter que identifique se essa variável é do tipo
caracter, numérica, data ou lógica. Sugerimos a letra “C” para referenciar uma
variável do tipo caracter, “N” uma variável do tipo numérico, “D” uma variável do
tipo data, “L” do uma variável do tipo lógica e “A” uma variável do tipo array . O
final do nome fica a critério do programador, sempre tendo o bom-senso de
escolher algo que tem a ver com o tipo de dado que ela irá referenciar. Veja modelo
abaixo:
Caracter: _cNome
Numérica: _nTotal
Data: _dSaida
Lógica: _lEof
Array: _aCampos
Obs: Vale observar que o total de caracteres do nome não deve ultrapassar 8
posições e a primeira letra após o caracter identificador (C, N, D, L e A) deve ser
maiúscula.
Índices
A criação do índice e o uso do mesmo nas rotinas devem receber um tratamento
especial. Na criação, os primeiros campos como o alias do arquivo, ordem, chave
do índice e descrição do mesmo, recebem informações normais. O campo PROPRI
deve ser preenchido com o caracter “U” (usuário) e o campo NICKNAME deve ser
preenchido obedecendo a seguinte regra:
O tratamento do índice de usuário para tabelas padrão na rotina, ao invés do

tradicional “DBSETORDER()” deve obedecer a seguinte regra:
dbSetNickName(alias,nickname)
dbOrderNickName(nickname)
Ex:
dbSelectArea(“SA1”)
dbSetNickName(“SA1”, “SA12”)
dbOrderNickName(“SA12”)

Operadores Básicos
Pode-se utilizar os seguintes operadores no ADVPL:
Tipo Ação
= Igualdade
!= ou <> ou # Diferença
:= Atribuição
== Igualdade absoluta
> Maior que
>= Maior e igual a
< Menor que
<= Menor igual a
+ Adição
- Subtração
* Multiplicação
/ Divisão
** ou ^ Exponenciação
SQRT(argumento) Raiz Quadrada
.AND. E lógico
.OR. OU lógico
.NOT. ou ! Não lógico
& Macro Substituição
Sintaxes para cálculos:
_nCont := _nCont + 1 ou _nCont += 1 ou _nCont++ (incremento)

_nCont := _nCont – 1 ou _nCont -= 1 ou _nCont-- (decremento)
_nTotal := _nPreco + (_nImp * _nAliq)
Criação de Variáveis
Na criação de uma variável deve-se ter em mente alguns pontos fundamentais:
• A declaração
• O tipo de variável
• A função CRIAVAR()
• A inicialização
• Padronização de variáveis

A Declaração
Deve ser feita preferencialmente sempre no início da rotina que for utilizá-la, como
no exemplo:
Function a910VerCod()
Local _cCod910 := “001”
Return
O Tipo de Variável
O tipo de variável serve para identificar a utilização que a mesma terá no decorrer
da rotina. Toda variável deve estar tipada durante sua criação. Quando
programamos nativamente em “C”, isto se torna obrigatório. Devemos fazer o
mesmo no AP5, pois isto demonstra que a variável foi conscientemente declarada.
Tipos Existentes
Public
Esta variável será inicializada em um valor lógico falso (.F.) até que seja atribuído
um valor específico a ela. Esta variável permanece definida por toda a duração da
aplicação e pode ser vista (assim como usada, alterada e avaliada) por qualquer
função. Esta variável gera um token (indicação) na tabela de símbolos, isto significa
que o módulo principal conterá símbolos para esta classe de variável, o que, por
sua vez, ocupa mais espaço de memória. Deve-se evitar a utilização deste tipo, a
não ser em casos extremos.
Private
Esta variável será inicializada em valor nulo (NIL) e uma vez declarada,
permanecerá assim durante toda a duração do fluxo da função, até que este volte
ao procedimento inicial que a chamou. Em essência, uma variável de memória
PRIVATE inicializada logo no início do Protheus, agirá como um variável PUBLIC.
Esta variável pode ser vista por uma sub-rotina da função e modificada de maneira
correspondente. Esta variável também gera um token na tabela de símbolos
comentada acima.
Local
Esta variável de memória será inicializada com valor nulo (NIL) e só é visível
dentro da função que a inicializa, mesmo que esta última, contenha funções
incorporadas a seu conteúdo. Este tipo de variável é o mais adequado a ser
utilizado em funções, pois não gera símbolos na tabela de símbolos, por
conseqüência ocupa pouco espaço de memória e, o compilador avalia as variáveis
LOCAL e STATIC mais rapidamente que os outros tipos (PUBLIC e PRIVATE).
Cuidado para não sucumbir à teoria de que se pode obter economia de memória,
mudando qualquer referência PRIVATE para uma referência LOCAL. Se você fizer

isso, as funções podem não funcionar corretamente, embora funcionassem na

versão anterior às alterações.
Static
A variável STATIC é idêntica à classe de armazenamento LOCAL, com uma
exceção. Uma variável STATIC é retida dentro de sua sub-rotina, mesmo depois
que o fluxo da função a tenha deixado. Isto é particularmente útil para funções
independentes tipo “caixa-preta”, que contém seu próprio conjunto de variáveis
exclusivas e devem manter esses valores de interação em interação.
Inicialização
Quando não atribuímos nenhum valor a uma variável no momento de sua
declaração, corremos o risco de utilizá-la com valor “NIL” e causar erros fatais. Por
isso, a inicialização de uma variável é de extrema importância.
Padronização de Variáveis
É importante que ao lermos o nome de uma variável, possamos saber se o seu tipo
é numérico, caracter, data ou lógico. O nome da variável de get não deve coincidir
com uma variável de outro programa, pois toda variável de get possui um help
específico.
Exemplo:
a variável dBaixa (get da baixa no programa de Títulos a Receber), já possui um
texto help que indica seu conteudo e não deverá ser criada outra variável para
outra finalidade com este mesmo nome.
Para tanto, definimos a seguinte padronização :
N ⇒ Numéricas
L ⇒ Lógicas
D ⇒ Data
C ⇒ Caracter
A ⇒ Array (matriz)
O ⇒ Objeto
U ⇒ Sem definição
Criando uma Variável Utilizando a Função CRIAVAR()

Esta função cria uma variável, retornando o valor do campo, de acordo com o
dicionário de dados. Avalia o inicializador padrão e retorna o conteúdo de acordo
com o tipo de dado definido no dicionário.
Sintaxe
_uRet := CriaVar(_cCampo,_lIniPad,_cLado)

Onde :
_uRet ⇒ tipo de retorno de acordo com o dicionário de dados,

considerando inicializador padrão.
_cCampo ⇒ Nome do campo
_lIniPad ⇒ Indica se considera (.T.) ou não (.F.) o inicializador padrao
(X3_RELACAO)
_cLado ⇒ Lado para inicializaçäo padrão
Declarando e utilizando vetores e matrizes

Declaração de arrays aceita são:
Local _aDupl := {} ou
Local _aDupl := Array(5,3)
Onde: 5 = número de linhas

3 = número de colunas
Ex.:
Local _nDup := 0
While !Eof() .and. _lCondicao

//Processamento
Aadd( _aDupl, {E1_NUM, E1_VALOR,E1_VENCTO} )
Ou
_nDup += 1
_aDupl [nDup,1] := E1_NUM
_aDupl [nDup,2] := E1_VALOR
_aDupl [nDup,3] := E1_VENCTO
dbSkip()
End

Utilizando Estruturas de Controle

While...
Exit ou
Loop
EndDo
Exemplo:
_lCond := .T.
While _lCond
// Processamento de seu programa
_lCond := .F.
End
Este Comando acima será executado até que a sua condição se torne Verdadeira a
partir do registro do corrente. Nesta condição poderemos utilizar quaisquer dos
operadores lógicos descritos acima.
For....
Exit ou
Loop
Next
Exemplo:
Local _nMaximo
Local _nContador
_nMaximo := 1000
For _nContador := 1 To _nMaximo

Next
Este Comando acima será executado até que a variável nContador se torne igual a
Variável _nMaximo a partir do registro do corrente, neste caso poderemos ter
quantos For quiser dentro de um outro For. Nesta condição poderemos utilizar
quaisquer dos operadores lógicos descritos acima.

If…
ElseIf ou
Else
EndIf
Exemplo:
If _lCondição
// Processamento de seu programa caso a Condição acima
seja verdadeira .
Else
// Processamento de seu programa caso a cCondição acima
seja falsa .
EndIf
Este Comando acima será executado caso a condição especificada for verdadeira e
também caso a condição seja falsa a partir do registro do corrente. Nesta condição
poderemos utilizar quaisquer dos operadores lógicos descritos acima.
If ()
Exemplo:
IF(_lCondição, Processamento A , Processamento B)
Este comando é igual ao item acima, no entanto, é geralmente utilizado em linhas

de Gatilho / Lançamento Padrão e outros processamentos.
Caso a Condição seja verdadeira ele irá executar o Processamento A.
Caso a Condição seja falsa ele irá executar o Processamento B.
Agora que conhecemos os operadores lógicos , como devemos definir nossas

variáveis, nossas condições que permitem processar mais de um registro, bem
como comandos que permitirão montar condições para efetuar possíveis filtros em
nossos programas; partiremos para a segunda fase a qual nos mostrará os
comandos que poderemos utilizar dentro de nossos programas.
Do Case
OtherWise
EndCase
Exemplo:
Do Case
Case _lCondição
Case _lCondição
Case _lCondição
Otherwise

EndCase
Este Comando acima será executado somente se a condição se torne Verdadeira a

partir do registro do corrente, neste caso poderemos ter N Case dentro de um Do
Case. Nesta condição poderemos utilizar quaisquer dos operadores lógicos
descritos acima.
Problemas com Looping de Programas

O Protheus utiliza a tecnologia Cliente/Servidor. Isto significa que o aplicativo não
é mais executado individualmente em cada máquina, ele será executado no
servidor do aplicativo. Até a versão 4.07 um programa travado significava que
apenas a estação estava comprometida (o executável estava na memória da
estação). Com o Protheus, todo o processamento está no Server e quando o
programa está em looping estaremos gradativamente “usando todo a CPU do
Server” e consequentemente parando todo o processamento.
Se ao desenvolvermos uma rotina e a mesma entrar em looping (tiver apenas uma

entrada e não tiver uma saída do processamento), este processamento utilizará
todos os recursos do servidor comprometendo (reduzindo drasticamente a
performance do aplicativo), ou até impedindo, o uso do aplicativo por todos os
demais usuários.
Se isso acontecer em uma empresa onde existem apenas 5 usuários, o

administrador da rede poderá reiniciar o servidor, porém onde existe um número
considerável de usuários poderá haver um prejuízo para a empresa que utiliza
nosso sistema.
Exemplo:
dbSeek(xFilial(“SE1”)+DTOS(_dDtIni))
Do While SE1->(!Eof())
…
…
---------- Falta um DbSkip()
Enddo
No exemplo acima, a rotina ficará em looping (pois falta um comando de saída da

rotina, um DbSkip() seria o mais apropriado), utilizando todos os recursos de
processamento do servidor, fazendo com que o mesmo pare de funcionar.

Outro exemplo:
_aCampos := {}
Do while .T.
Aadd(_aCampos, “Teste”)
Enddo
No exemplo acima o caso é ainda mais crítico, pois além utilizar todo o recurso de
processamento do servidor, em dado momento haverá uma queda do aplicativo,
devido a limitação da variável tipo Array, criada acima. E quando este limite for
ultrapassado, o sistema será interrompido abruptamente e todos os demais
usuários ficarão impossibilitados de utilizarem o sistema.
Comandos definidos pelo usuário (UDC’s)

Este recurso cria novas e infinitas possibilidades para modificar a maneira pela
qual escrevemos o código de uma função e a maneira pela qual podemos resolver
problemas complexos. Ele ajuda a facilitar a manutenção do código, e a
implementação de normas.
Estes comandos são traduzidos, analisados e modificados antes que o compilador

comece a trabalhar para gerar um arquivo objeto. O responsável por esta tradução
é o pré-processador que é um tradutor inteligente que atua antes da geração do
código objeto.
Em sua maioria, isto se resume a encontrar os comandos no código fonte e traduzi-

los para instruções e funções equivalentes que se acham no corpo da função ou no
conteúdo de arquivos “.CH” (arquivos de cabeçalho). Este tipo de arquivo (.CH),
contém diversos comandos que serão utilizados por todas as funções que
contenham a instrução “include” em seu código.
Estes mesmos comandos poderiam estar embutidos na função, mas para facilitar a
manutenção, um único arquivo “.CH”, pode ser incluído (comando include) em
várias funções ao mesmo tempo. Não há a necessidade de colocar o comando
include em cada função. Uma única menção ao “.CH” no arquivo “.PR?”, servirá
ao propósito de todas as funções nele embutidas.
Estes comandos são diretivas do pré-processador e começam sempre com o

caracter “#” diretamente à sua frente e devem estar escritos em caracteres tipo
caixa alta. Os mais utilizados no Protheus são:
#DEFINE
#IFDEF, ou #IFNDEF
#ELSE
#ENDIF
#INCLUDE

Cada um destes comandos pode ser colocado em qualquer parte do arquivo fonte,
que será lido pelo pré-processador. No entanto, para facilitar a visualização da
existência destes comandos e manutenção da função, estes comandos devem ser
colocados no início do fonte.
O pré-processador substituirá, cada ocorrência da constante no fonte, será

substituída pela expressão ou valor, que estiver contida diretamente à frente da
mesma. A exemplo de sintaxe e código fonte para este comando é:
#DEFINE _TESC 27
#DEFINE _LESC lastkey()
If _nLastkey == _TESC
RETURN
EndIf
Esta diretiva é muito útil quando temos um valor constante várias vezes repetido
dentro do código fonte, que poderá ser alterado com freqüência no decorrer da
vida útil da função.
#IFDEF ou #IFNDEF <CONSTANTE>

<instruções>
#ELSE
<outras instruções>
#ENDIF
Esta diretiva do pré-processador permite que você prepare aplicações para

compilação condicional, ou em outras palavras, se a <constante>, definida
anteriormente via diretiva DEFINE ou pelo Protheus foi definida (IFDEF), as
<instruções> serão incorporadas ao código objeto e as <outras instruções>, serão
desprezadas. Mas se a <constante> não foi definida <IFNDEF> as <instruções>
serão incorporadas e as <outras instruções> serão desprezadas.
#INCLUDE “<ARQUIVO>”
Uma instrução INCLUDE diz ao pré-processador para inserir o conteúdo de outro

arquivo em um local determinado dentro da função. Este arquivo especificado,
deve focalizar outras instruções do pré-processador que possam ser comuns a
diversos módulos da rotina.
Uso de Strings
Para que o sistema possa ser utilizado em outros países com línguas diferentes ao
invés de inserirmos diretamente os textos nos utilizamos o recurso de strings, onde

através de um include acessaremos o texto em três línguas diferentes (Português,

Espanhol e Inglês) dependendo da forma da compilação.
É convencionado que o nome do include seja o mesmo nome do fonte para que a
manutenção seja o mais simples possível.
Exemplo:
Relatório ⇒ PROG001.PRW
Include ⇒ PROG001.CH
Funções para Manipulação de Mensagens

MsAlert
Abre uma caixa de diálogo padronizada para o usuário referente a uma
informação.
Sintaxe
MsAlert(cMens)
Parâmetros
cTexto – Texto a ser exibido
Exemplo
MsAlert(“TEXTO A SER EXIBIDO.”)
MsgStop
Abre uma caixa de diálogo padronizada para o usuário referente a uma parada
crítica.
Sintaxe
MsgStop (cMens):
Parâmetros
cMens - define a mensagem apresentada no interior da janela
Exemplo
cMens := “Atenção, Curso de Introdução de ADVPL”
MsgStop(cMens)
MsgInfo
Abre uma caixa de diálogo padronizada para o usuário referente a uma
informação.
Sintaxe
MsgInfo(cMens, cTitulo):
Parâmetros
cTitulo - define título da janela
Exemplo
cMens := “Atenção, Curso de Introdução de ADVPL”

MsgStop(cMens, “Informcação”)
MsgBox
Abre uma caixa de diálogo padronizada para informar o usuário de um Erro
decisão a ser tomada ou apenas uma informação.
Sintaxe
MsgBox(cMens,cTitulo,cTpCaixa):
Parâmetros
cMens := define a mensagem apresentada no interior da janela
cTitulo := título da janela
cTpCaixa := tipo da caixa padronizada
As caixas assumem o tamanho da mensagem.

Tipos de Caixa:
o STOP - Bitmap para advertência, tem um botão “Ok”. Retorna Nil.
o INFO - Bitmap exclamação, tem um botão “Ok”. Retorna Nil.
o ALERT - Bitmap para advertência, tem um botão “Ok”. Retorna Nil.
o YESNO - Bitmap interrogação, tem dois botões “Sim” e “Não”,
Retorna .T. ou .F.
o RETRYCANCEL – Bitmap interrogação, tem dois botões “Repetir” e
“Cancelar”, retorna .T. ou .F.
Exemplo
Local _cMens := “Atenção, Curso de Introducao de ADVPL”)
MsgBox(_cMens,”Informação”,”INFO”)
MsgYesNo
Abre uma caixa de diálogo padronizada para o usuário referente a uma pergunta,
a qual deverá ser informado “S”=Sim ou “N”=Não.
Sintaxe
MsgYesNo(cMens)
Parâmetros
Retorno
.T. para sim, .F. para não.
Exemplo
Local cMens := “Confirma o Processamento da Rotina?”
lResp := MsgYesNo(cMens)
If lResp
//Processamento
Endif

Funções para Manipulação de Strings

SubStr
Retorna uma parte de uma string.
Sintaxe
SubStr(cArg1,nArg2,nArg3)
Parâmetros
cArg1 – campo ou variável tipo string
nArg2 – posição inicial na string
nArg3 – quantidade de caracteres a retornar
Len
Retorna o tamanho da string, onde:
Sintaxe
Len(nArg1)
Parâmetros
nArg1 - Variável ou campo tipo string
Trim
Retorna uma string sem os espaços à direita, onde:
Sintaxe
Trim(cArg1) ou RTRIM(cArg1)
Parâmetros
cArg1 - Variável ou campo tipo string
LTrim
Retorna uma string sem os espaços à esquerda, onde:
Sintaxe
LTrim(cArg1)
Parâmetros
_cArg1 - Variável ou campo tipo string
AllTrim
Retorna uma string sem espaços à esquerda e à direita, onde:
Sintaxe
AllTrim(cArg1)
Parâmetros
cArg1 - Variável ou campo tipo string
Val
Retorna um valor a partir de um campo ou variável string, onde:
Sintaxe
Val(arg1)
Parâmetros

cArg1 - Variável ou campo tipo caracter
DtoC
Sintaxe
DtoC(dArg1)
Retorna uma string a partir de uma variável ou campo tipo data, onde:
Parâmetros
dArg1 - variável ou campo tipo data
Capital
Transforma as letras iniciais em Maiúsculas e as demais em Minúsculas.
Sintaxe
Capital(cTexto)
Parâmetros
cTexto - Texto a ser convertido
Exemplo
cCapital := Capital(“TEXTO MAIUSCULO”)
Funções para Manipulação de Datas

CtoD
Retorna uma data a partir de um campo ou variável tipo caracter com formato
data.
Sintaxe
CtoD(cArg1)
Parâmetros
cArg1 - variável ou campo tipo caracter
Day
Retorna o dia a partir de um campo ou variável tipo data, onde:
Sintaxe
Day(dArg1)
Parâmetros
dArg1 := variável ou campo tipo data
Month
Retorna o mes a partir de um campo ou variável tipo data, onde:
Sintaxe
Month(dArg1)
Parâmetros
Year
Retorna o ano a partir de um campo ou variável tipo data, onde:
Sintaxe
Year(dArg1)
Parâmetros
DOW
Retorna um número equivalente ao dia da semana (1=domingo,7=sábado),
onde:
Sintaxe
DOW(dArg1)
Parâmetros
dArg1 - Variável ou campo tipo data
Funções para Manipulação de Números

Int
Retorna o inteiro da expressão passada como parâmetro, onde:
Sintaxe
Int(nArg1)
Parâmetros
nArg1 - Variável ou campo tipo numérica
Str
Retorna uma string de um campo ou variável numérica, onde:
Sintaxe
Str(nArg1)
Parâmetros
StrZero
Retorna uma string de um campo ou variável numérica, com zeros significativos
ao invés de brancos, onde:
Sintaxe
StrZero(nArg1):
Parâmetros
Round
Retorna um campo numérico arredondado com (nArg2) número de casas
decimais, onde:
Sintaxe
Round(nArg1,nArg2):
Parâmetros
nArg1 - Variável ou campo tipo numérico
nArg2 - Número de casas decimais

Funções Básicas para Criação de Telas

@...To...Dialog
Define uma nova janela na área de trabalho.
Sintaxe
@ nLinha1,nColuna1 TO nLinha2,nColuna2 DIALOG cVar TITLE cTítulo
Parâmetros
nLinha1 – Número da linha superior
nColuna1 – Número da coluna superior
nLinha2 – Número da linha inferior
nColuna2 – Número da coluna inferior
cVar – Variável que recebera as definições da nova janela
cTítulo – Titulo da Janela
Comentários
Deve ser utilizada sem conjunto com o comando ACTIVATE DIALOG.
Activate Dialog
Ativa uma janela previamente definida na função Dialog e executa os GETs, botões
e outros objetos.
Sintaxe
ACTIVATE DIALOG cVar <CENTERED> [On Init cFuncInit] [Valid
cFuncValid]
Parâmetros
cVar – Variável utilizada na função Dialog para definição da janela.
cFuncInit – Função executada automaticamente na abertura do diálogo na
tela (Opcional).
cFuncValid– Função executada para validar o fechamento da janela de
diálogo.
Deve retornar um valor lógico (.T. ou .F.) (Opcional)
@ ...TO
Desenha um box 3D.
Sintaxe
@ nLInha1,nColuna1 TO nLinha2,nColuna2 <TITLE> cTítulo
Parâmetros
cTítulo – Titulo apresentado na linha superior (opcional)
Comentários
A cláusula TITLE é opcional. Se for omitida, o box não terá título.

@... GET
Executa um Get, diferenciado pela cláusula <F3>.
Sintaxe
@ nLinha,nColuna GET cVar <PICTURE> cMáscara <VALID>
cFunção <F3> cConsulta
Parâmetros
nLinha – Número da Linha em que o Get será posicionado
nColuna – Número da Coluna em que o Get será posicionado
cVar – Variável a ser editada
cMáscara – Define a máscara de edição (opcional)
cFunção – Função que retorna valor lógico para validação da edição
(opcional)
cConsulta – Definição (SXB) da consulta <F3> associada ao conteúdo de
cVar
Comentários
Os códigos utilizados na cláusula <F3> devem ser obtidos através
do arquivo (SXB). Não é necessário utilizar o comando READ após
a definição dos Gets.
@... SAY
Executa um Say.
Sintaxe
@ nLinha,nColuna SAY cTexto
Parâmetros
nLinha – Número da Linha em que o Get será posicionado
nColuna – Número da Coluna em que o Get será posicionado
cTexto – Variável a ser editada
Comentários
Função utilizada para exibir um texto tipo label em uma janela ou caixa de
diálogo.
@...Button
Cria um botão com texto.
Sintaxe
@ nLinha,nColuna BUTTON cTexto SIZE nAltura,nLargura ACTION
cFunção Object oBtn
Parâmetros
nLinha – Número da linha superior
nColuna – Número da coluna superior
cTexto – Texto que será apresentado no botão. Deve incluir um “_” antes
da letra que utilizada como Hot Key. Ex.: ( “_Salvar”,”Edi_Tar”)
nAltura – Altura do botão
nLargura – Largura do botão

cFunção – Função que será executada

Object oBtn – Objeto associado ao botão.
@...BmpButton
Cria um botão de bitmap padrão do Protheus.
Sintaxe
@ nLinha,nColuna BMPBUTTON TYPE nBotao ACTION cFuncao OBJECT
oBtn
Parâmetros
nBotao – Número do botão padronizado
cFuncao – Função que será executada
oBtn – Objeto associado ao botão
@...CheckBox...Var
Cria uma caixa de verificação para definir entre Sim/Não ou Falso/Verdadeiro.
Sintaxe
@ nLinha,nColuna CHECKBOX cDesc VAR lSeleção Object oCbx
Parâmetros
cDesc – Descrição da caixa. Ex. “Atualiza Estoque ?”
lSeleção – Variável Lógica que identifica se a caixa foi ou não selecionada
oCbx – Objeto associado ao Checkbox
Retorno
A variável <lSeleção> recebe “.T.” se for selecionada ou “.F.”, se vazia.
Comentários
Pode ser utilizada uma seqüência de CHECKBOX para determinar um
conjunto de configurações onde vários itens podem ser
marcados/desmarcados. Deve ser definida uma variável <lSeleção> para
cada CHECKBOX definida.
@...ComboBox...Itens...Size
Esta função é semelhante a LISTBOX, mas pode ser utilizada em pequenos
espaços, pois os itens só serão mostrados quando a caixa for seleciona.
Sintaxe
@ nLinha,nColuna COMBOBOX cCont ITENS aArray SIZE
nAltura,nLargura Object oCbx
Parâmetros
cCont – Conteúdo caracter do item selecionado na Matriz [1]
aArray – Array, Matriz [1] com os itens para seleção
nAltura – Altura para definir o tamanho da caixa
nLargura – Largura para definir o tamanho da caixa

oCbx – Objeto relacionado ao botão
Retorno
O item selecionado pode ser obtido por <cCont>
Comentários
Os itens da Matriz [1] devem ser tipo “C” caracter.
@...Radio
Cria uma caixa de seleção semelhante a CHECKBOX, todos os itens são
apresentados mas apenas um pode ser selecionado.
Sintaxe
@ nLinha,nColuna RADIO aArray VAR nPos Object oRdx
Parâmetros
aArray – Matriz [1] com os Itens
nPos – Contém a posição na Matriz[1] do item selecionado
oRdx – Objeto associado à Radiobox()
Retorno
O item selecionado pode ser obtido por - “Matriz [n3]”
Comentários
Os itens da Matriz [1] devem ser do tipo “C” caracter. Pode ser utilizada
para definir uma característica em um conjunto. Ex.Tipo da Condição de
pagamento
• Tipo 1
• Tipo 2
• Tipo 3
@... Bitmap... Size

Define a área em que será mostrado um BITMAP na janela.
Sintaxe
@ nLinha,nColuna BITMAP SIZE nAltura,nLargura FILE cArq
Parâmetros
nLinha – Número da Linha superior
nColuna – Número da Coluna superior
nAltura – Altura de apresentação do BITMAP
nLargura – Largura de apresentação do BITMAP
@..To...MultiLine
Ativa Browse para edição de múltiplos itens padrão Protheus (GetDados)
Sintaxe
@ nLinha1,nColuna1 TO nLinha2,nColuna2 MULTILINE <<MODIFY>>
<<DELETE>> <<VALID>> cFunção <<FREEZE>> nColuna
Parâmetros

cFunção – Função a ser executada para validar mudança de linha
<opcional>
nColuna – Número de colunas “Congeladas à esquerda” <opcional>
Comentários
As cláusulas opcionais permitidas controlam as Alterações, Exclusões e Validações
nas mudanças de linha e congelamento de colunas respectivamente. Devem ser
criadas obrigatoriamente as matrizes aHeader [n][n] e aCols[n][n] antes da
definição da MULTILINE, sendo que aHeader [n][n] contém informações sobre os
campos que serão editados (SX3) e aCols [n][n] contém os dados referentes aos
campos que serão editados.
Enchoicebar
Cria barra de botões padrão na janela
Sintaxe
EnchoiceBar( oDlg, bOk, bCancel, [lMessageDel] , [aButtons] )
Parâmetros
oDlg - Janela onde a barra será criada.
bOk - Bloco executado quando clicado botão Ok.
bCancel – Bloco executado quando clicado cancelar.
lMessageDel – Indica se ao clicar no botão Ok aparecerá uma tela de
confirmação de exclusão. Valor padrão falso.
AButtons - Vetor com informações para criação de botões adicionais na
barra no formato {bitmap, bloco de código, mensagem}.
Descrição
Esta função cria uma barra com botões padrão e outros passados como parâmetro
na janela tambem passada por parâmetro. A EnchoiceBar dever ser chamada antes
do ACTIVATE da janela.
AxCadastro
Geração de modelo 1. Rotina para criação e manutenção de cadastros no padrão do
Protheus, contendo as opções padronizadas: PESQUISA, INCLUSÃO,
ALTERAÇÃO, VISUALIZAÇÃO e EXCLUSÃO.
Disponibiliza o Browse e todas as funções de cadastramento padrão.
Sintaxe
AxCadastro(cAlias,cTitulo,cDel,cOk)
Parâmetros
cAlias – Alias do arquivo. Deve obrigatoriamente ter sua estrutura definida
no SX3.
cTitulo – Título da Janela.
cDel – Função para validar a exclusão.
cOk – Função para validar a Inclusão/Alteração.
Comentários
Deve ser utilizada para editar arquivos específicos (Família SZ?), sendo
seme-lhante aos cadastros de Clientes, Fornecedores e etc...
Exemplo
AxCadastro(“SZ1”,”Cadastro de Descontos”,”.T.",”.T.”)
MarkBrowse
Monta um browse padrão do sistema, permitindo marcar e desmacar linhas.
Sintaxe
MarkBrowse(cAlias,cCampo,cCpo,aCampos,lMarc,cMarca,cCtrlM,lBotoes,c
TopFun,cBotFun,aCoord)
Parâmetros
cAlias – Álias do arquivo
cCampo – Campo que estabelece relação com a culuna de marca
cCpo – Campo que se estiver vazio muda a cor da linha
aCampos – Array com os campos para montar o browse
lMarc – Flag para inicializar marcado ou não
cMarca – Marca obtida com a função Getmark
cCtrlM – Função para ser executada no Alt_M
lBotoes – Parâmetro obsoleto
cTopFun – Função filtro para estabelecer o primeiro registro
cBotFun – Função filtro para estabelecer o último registro
aCoord – Array com as coordenadas da MarkBrowse.
Exemplo
cMarca := GetMark()
cCadastro := “Escolher Clientes”
aRotina := { { “Pesquisar”,”AxPesqui”,0,1}, ;
{“Visualizar”,”AxVisual”,0,2}}
MarkBrow(“SA1”,”A1_OK”,”SA1->A1_OK”,,,cMarca)
MBrowse
Monta um browse padrão do sistema, conforme os parâmetros.
Sintaxe
mBrowse(nLinha1, nColuna1, nLinha2, nColuna2, cAlias, aFixe, cCpo, nPar,
cCor, n Opc)
Parâmetros
nLinha1 – Número da linha inicial
nColuna1 – Número da coluna inicial
nLinha2 – Número da linha final
nColuna2 – Número da coluna final
cAlias – Alias do arquivo
aFixe – Array contendo os campos fixos (a serem mostrados em primeiro
lugar no browse)
cCpo – Campo a ser tratado. Quando vazio, muda a cor da linha
nPar – Parâmetro obsoleto
cCor – Função que retorna um valor lógico, muda a cor da linha

nOpc – Define qual opção do aRotina que será utilizada no double click
Exemplo
cCadastro := “Cadastro de Orcamentos”
aRotina := {{“Pesquisar”,”AxPesqui”,0,1},;
{“Incluir”,’ExecBlock(“DEMOA”,.F.)’,0,3},;
{“Altera”,’ExecBlock(“DEMOB”)’,0,4},;
{“Excluir”,’ExecBlock(“DEMOC”,.F.)’,0,5}}
MBrowse(6, 1, 22, 75, “SA1”)
Modelo2
Exibe formulário para cadastro segundo o modelo 2 (como a rotina de Pedidos de
Compra).
Sintaxe
M o d e l o 2 (c T í t u l o ,a C a b e c ,a R o d a p é ,a G d ,n O p ,c L O k ,
c T O k , [aGetsGD,bF4,cIniCpos,nMax,aCordw,lDelget])
Parâmetros
cTítulo – Título da janela
aCabec – Array com os campos do cabeçalho
aRodapé – Array com os campos do rodapé
aGd – Array com as posições para edição dos itens (GETDADOS)
nOp – Modo de operação (3 ou 4 altera e inclui itens, 6 altera mas não
inclui itens, qualquer outro número só visualiza os itens)
cLOk – Função para validação da linha
cTOk – Função para validação de todos os dados (na confirmação)
aGetsGD – Array Gets editáveis (GetDados)
Default = Todos.
bF4 – Codeblock a ser atribuído a tecla F4.
Default = Nenhum.
cIniCpos – String com o nome dos campos que devem ser inicializados ao
teclar seta para baixo (GetDados).
nMAx – Limita o número de linhas (GetDados). Default = 99.
aCordw – Array com quatro elementos numéricos, correspondendo às coor-
denadas linha superior, coluna esquerda, linha interior e coluna
direita, definindo a área de tela a ser usada. Default = Área de
Dados Livre.
lDelget – Determina se as linhas podem ser deletadas ou não (GetDados)
Default = .T.
Retorna
lRet – Retorna .T. se for confirmado

Modelo3
Executa cadastro semelhante ao cadastro de Pedidos de Venda, cabeçalho variável
com itens.
Sintaxe
Modelo3(cTitulo,cAliasEnchoice,cAliasGetD,aCpoEnchoice,cLinOk,cTudOk,
nOpcE,nOpcG,cFieldOk, [lVirtual,nLinhas,aAltEnchoice])
Parâmetros
cTitulo – Título da janela
cAliasEnchoice – Álias do cabeçalho
cAliasGetd – Álias dos itens
aCpoEnchoice – Array com os campos que serão mostrados
cLinOk – Função para validar a mudança de linha nos itens.
cTudOk – Função para validar todos os itens.
nOpce – Número da opção do menu para o cabeçalho (Enchoice)
nOpcG – Número da opção do menu para o itens (GetDados)
cFieldOk – Função para validar os campos dos itens (GetDados)
lVirtual – Permite visualizar campos virtuais na enchoice. Default = .F.
nLinhas – Limita o número máximo de linhas (GetDados) Default = 99.
aAltEnchoice – Array com campos alteráveis (Enchoice) Default = Todos.
Retorna
lRet – Retorno da função modelo3. Se .T. a operação foi confirmada.
Funções para Manipulação de Réguas de Processamento

Processa
Executa função que conterá a barra de processamento.
Sintaxe
Processa(bBlock,cTítulo,cMsg)
Parâmetros
bBlock := Bloco de código que define a função a ser executada.
cTítulo := Título do diálogo de processamento.
cMsg := Mensagem do diálogo de processamento.
Exemplo
Processa( { || Nome_func() },”Processamento da Rotina Principal” )
ProcRegua
Inicializa a régua padrão de processamentos pode ser utilizada no ADVPL.
Esta função deverá ser utilizada em conjunto com a função Processa(). Deve ser
informado o valor final da régua de processamento.
Sintaxe
ProcRegua(bBlock) => RptStatus(bBlock, cTítulo, cMsg)
Parâmetros
bBlock – Bloco de código que define a função a ser executada.
cTítulo – Título do diálogo de processamento.

cMsg – Mensagem do diálogo de processamento.

Comentários
Pode ser utilizada com os parâmetros:
ProcRegua( { | | Execute(“Nome da Função”) } )
IncProc
Incrementa régua padrão de processamento.
Sintaxe
IncProc()
Parâmetros
Nenhum
Retorno
Nenhum
Exemplo
ProcRegua(1000)
For i:= 1 to 1000
IncProc()
Next
RptStatus
Executa função de detalhe do relatório.
Sintaxe
RptStatus(bBlock) => RptStatus(bBlock, cTítulo, cMsg)
Parâmetros
bBlock – Bloco de código que define a função a ser executada.
cTítulo – Título do diálogo de processamento.
cMsg – Mensagem do diálogo de processamento.
Comentários
Pode ser utilizada com os parâmetros:
RptStatus( { | | Execute(“Nome da Função”) } )
SetRegua
Inicializa régua padrão em relatórios.
Sintaxe
SetRegua(nRegs)
Parâmetros
nRegs – Número de registros que serão processados.
Retorno
Nenhum
Exemplo
DbSelectArea(“SA1”)
SetRegua(LastRec())
While ( ! Eof() )
@ Li, 001 PSAY SA1->A1_NOME
DbSkip()
IncRegua()
EndDo
Comentário
Ver também incRegua.
IncRegua
Incrementa régua padrão de processamento em relatórios.
Sintaxe
IncRegua()
Parâmetros
Nenhum
Retorno
Nenhum
Exemplo
SetRegua(LastRec())
While ( ! Eof() )
@ nLin, 001 PSAY SA1->A1_NOME
DbSkip()
IncRegua()
EndDo
Comentário
Ver também SetRegua()
Funções para Criação de Relatórios Padronizados

Variáveis de Relatórios
Na criação de um relatório algumas variáveis e seus tipos são convencionados para
a utilização da biblioteca de funções de relatório. Quando utilizamos a ferramenta
de geração de código do IDE, as variáveis abaixo são criadas automaticamente.
Variável Tipo Conteúdo

_cNrel Local Nome default do relatório em disco
_cBCont Local Contador
_cCabec1 Local 1ª linha do cabeçalho do relatório
_cTamanho Local Tamanho do Relatório (P = Pequeno 80 Colunas, M= Médio
132 colunas),
G = (Grande 220 colunas)
_nLimite Local Quantidade de colunas no relatório (80, 132, 220).
_cTitulo Local Titulo do Relatório
_cDesc1 Local 1ª linha da descrição do relatório


_aReturn Private Array com as informações para a tela de configuração da
impressão
_cNomeprog Private Nome do programa do relatório
_cString Private Alias do arquivo principal do relatório para o uso de filtro
_nLi Private Controle das linhas de impressão. Seu valor inicial é a
quantidade máxima de linhas por página utilizada no
relatório.
_nM_Pag Private Controle do número de páginas do relatório.
_aOrd Private Array contendo as ordens de layout para a impressão. Caso
não existam várias ordens este array deve estar vazio. Ex.:
aOrd:= {Código, Descrição, Telefone} -> O layout do
relatório vai depender da ordem selecionada na tela de
configuração de impressão.
_nLastKey Private Utilizado para controlar o cancelamento da impressão do
relatório.
_cPerg Private Nome da pergunte a ser exibida para o usuário.
_aLinha Private Array que contem informações para a impressão de
relatórios cadastrais
Cabec
Esta função imprime, na impressora selecionada, o cabeçalho padrão dos relató-
rios do SIGA Advanced. Devolve o número da última linha impressa para que seja
dada continuidade ao relatório.
Sintaxe
Cabec(cTítulo, cTexto1, cTexto2, cProg, cLargura, cControle)
Parâmetros
cTítulo – Título do Relatório
cTexto1 – Extenso da primeira linha do cabeçalho
cTexto2 – Extenso da segunda linha do cabeçalho
cProg – Nome do Programa
cLargura – Largura do relatório (P/ M/ G)
cControle – Caractere de controle da impressora (numérico)
Retorna
nLinha – Número da última linha impressa no cabeçalho
Exemplo
cTitulo := “Relação dos Adiantamentos”
cCabec1 := “Código Item Conta Contábil CCusto Projeto Data Valor”
cCabec2 := “----------- ------- ----------------------- ------------ ------------ -------- ------”
cPrograma := “ATRF090”
cTamanho := “P”
nCaracter := 15
cRel:=SetPrint(cAlias, cPrograma , , @cTitulo, cDesc1, cDesc2, cDesc3 , .T., aOrd )
SetDefault(aReturn, cString)

nLinha:=Cabec(cTitulo, cCabec1, cCabec2, cPrograma, cTamanho, nCaracter)
PSay
Este comando permite que você imprima o conteúdo de variáveis ou campos em
uma impressora, bem como em disco. Deverá se utilizado sempre com outros
comandos, tais como: @, linha, coluna, conteúdo a ser impresso (campo ou
variável), máscara de impressão, etc.
Sintaxe
Psay cArg
Parâmetro
cArq – Argumento a ser impresso no relatório
Exemplo
nLin := 02
cEmpresa := "ORGANON TI Campinas "
@ nLin,10 PSay cEmpresa
@ nLin, 110 PSAY SA1->A1_CGC Picture"@R 99.999.999/9999-99"
SetPrint
Esta função possibilita a alteração de determinados padrões dos relatórios. Ela
funciona em conjunto com a função SetDefault.
Sintaxe
SetPrint(cAlias, cNomeRel, cPerg, cDesc1, cDesc2, cDesc3, cDesc4, lDic,
aOrdem, lComp, cClass)
Parâmetro
cAlias - Alias do Arquivo Principal (se existir)
cNomeRel - Nome padrão do relatório
cPerg - Nome do grupo de perguntas
cDesc1 , cDesc4 - Descrição do Relatório
lDic - Habilita o Dicionário de Dados
aOrdem - Array contendo as ordens de indexação do arquivo principal.
lComp - Habilita a alteração da compressão do relatório
cClass - Classificação do Relatório por Tamanho ( “G”, “M” ou “P” )
P – 80 colunas
M – 132 colunas
G – 220 colunas
Exemplo
_cNomeRel := SetPrint(_cString, _cNomeRel, _cPerg, @_ctitulo,
_cDesc1_cDesc2, _cDesc3,.F., _aOrd,.F.,_cTamanho)
SetDefault
Esta função habilita os padrões de relatório alterados pela função SetPrint
Sintaxe
SetDefault(_aArray, _cAlias)
Parâmetros
aArray - Array aReturn, preenchido pelo SetPrint
[1] Reservado para Formulário

[2] Reservado para Nº de Vias
[3] Destinatário
[4] Formato => 1-Comprimido 2-Normal
[5] Mídia => 1-Disco 2-Impressora
[6] Porta ou Arquivo 1-LPT1... 4-COM1...
[7] Expressão do Filtro
[8] Ordem a ser selecionada
[9]..[10]..[n] Campos a Processar (se houver)
cAlias := Alias do arquivo a ser impresso.
Funções para Tratamento de Usuários do Sistema

AllUsers
Retorna vetor contendo informações dos usuários do sistema.
Sintaxe
AllUsers()
Descrição
A função AllUsers() retorna um vetor principal onde cada elemento refere-se a um

usuário do sistema, estes elementos são compostos de um vetor multidimensional
subdividindo as informações dos usuários. Sua estrutura é composta de:
Elemento Descrição Tipo Qtd.

1
1 ID C 6
2 Nome C 15
3 Senha C 6
4 Nome Completo C 30
5 Vetor com nº últimas senhas A --
6 Data de validade D 8
7 Quantas vezes para expirar N 4
8 Autorizado a alterar a senha L 1
9 Alterar a senha no próximo logon L 1
10 Vetor com os grupos A --
11 ID do superior C 6
12 Departamento C 30
13 Cargo C 30
14 E-Mail C 130
15 Número de acessos simultâneos N 4
16 Data da última alteração D 8
17 Usuário bloqueado L 1
18 Número de dígitos para o ano N 1
19 Listner de ligações L 1
20 Ramal C 4
2
1 Vetor com horários de acesso A --
2 Idioma N 1
3 Diretório C 100
4 Impressora C --
5 Acessos C 512
6 Vetor com empresas A --
7 Ponto de entrada C 10
8 Tipo de impressão N 1
9 Formato N 1
10 Ambiente N 1
11 Prioridade p/ config. do grupo L 1
12 Opção de impressão C 50
13 Acesso a outros dir de impressão L 1
3
1 Módulo+nível+menu C
AllGroups
Retorna vetor contendo informações dos grupos de usuários.
Sintaxe
AllGroups()
Descrição
A função AllGroups() retorna um vetor principal onde cada elemento refere-se a

um grupo de usuários do sistema, estes elementos são compostos de um vetor
multidimensional subdividindo as informações dos grupos. Sua estrutura é
composta de:
Elemento Descrição Tipo Qtd.

1
1 ID C 6
2 Nome C 20
3 Vetor com horários de acesso A
4 Data de validade D 8
5 Quantas vezes para expirar N 4
6 Autorizado a alterar a senha L 1
7 Idioma N 1
8 Diretório C 100
9 Impressora C
10 Acessos C 512
11 Vetor com empresas A
12 Data da última alteração D 8
13 Tipo de impressão N 1
14 Formato N 1
15 Ambiente N 1
16 Opção de impressão L 1
17 Acesso a outros Dir de impressão L 1
2
1 Modulo+nível+menu C
PswAdmin
Verifica se um usuário é Administrador.
Sintaxe
PswAdmin( cUsuario, cSenha )
Parâmetros
cUsuario – Nome do Usuário
cSenha - Senha do Usuário
Descrição
Esta função retorna um valor lógico, se for usuário administrador verdadeiro (.T.),
caso contrário falso (.F.)
PswID
Retorna o ID do usuário ou do grupo de usuário.
Sintaxe
PswID()
Descrição

Utilizada para retornar o ID do usuário ou do grupo de usuários após ter

posicionado o arquivo de senha com a função PswSeek().
PswName
Verifica senha de usuário.
Sintaxe
PswName( cSenha )
Parâmetros
cSenha – Senha do usuário.
Descrição
A função PswName() verica se a senha informada no parametro cSenha pertence
ao usuário posicionado no arquivo de senha, se pertencer retornará verdadeiro(.T.)
PswSeek
Pesquisa e posiciona o arquivo de senhas.
Sintaxe
PswSeek( cID, [lUsuario] )
Parâmetros
cID – Id do usuário
lUsuario – Opcional – Se .T. pesquisa usuários, .F. pesquisa grupo de
usuários
Descrição
A função PswSeek() pesquisa e posiciona o arquivo de senhas conforme a ordem
de indexação e o parametro lUsuario, se encontrar o usuário ou grupo de usuários
retorna verdadeiro (.T.).
PswOrder
Pesquisa e posiciona o arquivo de senhas.
Sintaxe
PswOrder( nOrdem )
Parâmetros
nOrdem – Ordem de pesquisa, onde 1 pesquisa grupo de usuários, 2
pesquisa usuários.
Descrição
A função PswOrder() seleciona a ordem de pesquisa no arquivo de senhas, onde
escolhe-se pesquisar por grupos ou usuários.
PswRet
Retorna vetor contendo informações do Usuário ou do Grupo de Usuários.
Sintaxe
PswRet()
Descrição
A função PswRet() retorna dois tipos de vetores distintos, de acordo com o
posicionamento do arquivo de senha. Se no segundo parametro da função
PswSeek() for informado .T. a PswRet() retornará um vetor com informações do
Usuários, caso contrário retornará informações do Grupo de Usuários.
Funções Genéricas do ADVPL

Aleatorio
Gera um número aleatório de acordo com a semente passada. Esta função retorna
um número aleatório menor ou igual ao primeiro parâmetro informado, usando
como semente o segundo parâmetro. É recomendado que esta semente seja sempre
o último número aleatório gerado por esta função.
Sintaxe
Aleatorio(nMax,nSeed)
Parâmetros
nMax – Número máximo para a geração do número aleatório
nSeed – Semente para a geração do número aleatório
Retorna
nRet – Número aleatório retornado
Exemplo
nSeed := 0
For i := 1 to 100
nSeed := Aleatorio(100,nSeed)
MSAlert(Str(i,3)+” numero aleatorio gerado: “+Str(nSeed,3))
Next i
Return
CGC
Consiste o CGC digitado, tomando como base o algoritmo nacional para
verificação do dígito de controle. Esta função procede um cálculo do dígito
verificador do número do Cadastro Geral de Contribuintes do Ministério da
Fazenda. É utilizado o dígito padrão módulo 11 para verificar se as duas últimas
posições da string passada, correspondem a dígitos verificadores válidos.
Calculando primeiro o dígito das 12 primeiras posições e agregando o dígito
encontrado ao fim da string, calcula o dígito das 13 posições, obtendo o segundo
dígito. Retorna uma expressão lógica verdadeira se as duas últimas posições do
CGC digitado coincidem com o calculado.
Sintaxe
CGC(ExpC1)
Parâmetros
ExpC1 – String de caracteres representando o número do C.G.C. sem pontos
e traços separadores. Caso este argumento não seja passado para a função,
esta considerará o GET corrente.
Retorna
ExpL1 – Expressão lógica .T. se o CGC é válido (dígito verificador confere)
ou .F. se o dígito verificador não confere.
Exemplos
Local cCGC := Space(14)
@ 10,16 GET cCGC Picture “@R 99.999.999/9999-99” Valid CGC(cCGC)

A máscara do CGC deve vir com @R, para não inserir os pontos e a barra no
CGC, o que impossibilita a validação.
Condicao
Esta função permite avaliar uma condição de pagamento, retornando um array
multidimensional com informações referentes ao valor e vencimento de cada
parcela, de acordo com a condição de pagamento.
Sintaxe
Condicao(nValTot,cCond,nVIPI,dData,nVSol)
Parametros
nValTot – Valor total a ser parcelado
cCond – Código da condição de pagamento
nVIPI – Valor do IPI, destacado para condição que obrigue o pagamento do
IPI na 1ª parcela
dData – Data inicial para considerar
Retorna
aRet – Array de retorno ( { {VALOR,VENCTO} , ... } )
Exemplo
nValTot := 2500
cCond := “002” // Tipo 1, Duas vezes
aParc := Condicao(nValTot,cCond,,dDataBase)
ConvMoeda
Converte o valor informado para a moeda selecionada.
Sintaxe
ConvMoeda(dData1,dData2,nValor,cMoeda)
Parâmetros
dData1 – Data de emissão
dData2 – Data de vencimento
nValor – Valor a ser convertido
cMoeda – Para qual moeda deverá converter
Retorna
ExpN1 – Valor convertido (devolvido pela função)
Comentários
Esta função converte o valor definido por nValor para a moeda especificada
em cMoeda na data dData.
A data dData2 não é utilizada.
O valor nValor é considerado em moeda 1.
Exemplos
nValor1 := ConvMoeda( D1_DTDIGIT, , D1_TOTAL, cMoeda )
nValor2 := ConvMoeda( D2_EMISSAO, , D2_TOTAL, cMoeda )

DataValida
Retorna uma data válida que não seja sábado, domingo ou feriado, a partir de uma
data qualquer informada. É uma função útil para a geração de vencimentos reais
para títulos, por exemplo.
Sintaxe
DataValida(dData)
Parametros
dData – Data informada para validação.
Retorna
dDtVld – Retorna a Data validada.
Exemplo
dVencRea := DataValida(dVencto)
Digito11
Cálculo de dígito verificador em módulo 11.
Sintaxe
Digito11(cCalc,cDigito)
Parâmetros
cCalc – String para calcular o dígito
cDigito – Dígito de verificação
Retorna
ExpL1 – Valor Lógico de Retorno (.T. ou .F.)
Comentários
Esta função calcula o dígito de verificação de cCalc e o compara com
cDigito, verificando a consistência.
Exemplos
Digito11(cCodigo,cDigito)
EANDigito
Calcula o dígito de controle para o código EAN usado em códigos de barras.
Sintaxe
EanDigito(cCod)
Parâmetros
cCod – Código de barras para o cálculo do dígito. É obrigatório o tamanho
de 12 dígitos.
Retorna
cEan – Retorna o código EAN de 13 dígitos, sendo que a última posição é o
dígito calculado.
Exemplo
cCod := EanDigito(PADL(AllTrim(M->B1_CODBAR),12,”0"))
cDig := Substr(cCod,12,1)

Entre
Verifica se o conteúdo do campo está entre o conteúdo de duas expressões (ExpX1
<= cCampo <= ExpX2). Se verdadeiro, retorna .T..Usado normalmente em
validações de campos digitados.
Sintaxe
Entre(ExpX1,ExpX2,cCampo)
Parâmetros
ExpX1 – Expressão a comparar >=
ExpX2 – Expressão a comparar <=
cCampo – Nome do Campo
Retorna
Exemplos
If Entre(“A1”,”A9",cSerie)
Extenso
Gera o extenso de um valor numérico. Esta função retorna um valor, dinheiro ou
quantidade, por extenso. Usada para a impressão de cheques, valor de duplicatas,
etc.
Sintaxe
Extenso(nValor,lQtd,nMoeda)
Parametros
nValor – Valor a ser gerado o extenso.
lQtd – Verdadeiro (.T.) indica que o valor representa uma quantidade.
Falso (.F.) indica que o valor representa dinheiro. Se não for especificado, o
default é falso (.F.).
nMoeda - Qual moeda do sistema deve ser o extenso.
Retorna
cValor – Retorna o valor por extenso.
Exemplo
nValor := SF2->F2_VALFAT
cExtenso := PADR(Extenso(nValor),200,”*”)
Formula
Interpreta uma fórmula cadastrada. Esta função interpreta uma fórmula, previa-
mente cadastrada no Arquivo SM4 através do Módulo Configurador, e retorna o
resultado com tipo de dado de acordo com a própria fórmula.
Sintaxe
Formula(cFormula)
Parâmetros
cFormula – Código da fórmula cadastrada no SM4.
Retorna
uRet – Retorno, com tipo de dado de acordo com a fórmula.
Exemplo

CTexto := Formula(“F01”)
GetArea
Salva a área corrente para um array. Essa função salva o alias corrente, a ordem e o
recno posicionado.
Sintaxe
aArray := Alias->(GetArea())
Parâmetros
Nenhum
Exemplo
aArray := GetArea()
aArray := SA1->(GetArea())
Ver também
Função RestArea( )
GetMV
Recupera o conteúdo de parâmetros originados em SX6.
Sintaxe
GetMV(cParam)
Parâmetros
cParam – Nome do parâmetro a ser pesquisado no SX6
Retorna
ExpX1 – Conteúdo do parâmetro devolvido pela função
Exemplos
cTabVista := GETMV(“MV_TABVIST”)
cColICMS := GETMV(“MV_COLICMS”)
Help
Esta função exibe a ajuda especificada para o campo e permite sua edição. Se for
um help novo, escreve-se o texto em tempo de execução.
Sintaxe
Help(cHelp,nLinha,cTítulo,cNil,cMensagem,nLinMen,nColMen)
Parâmetros
cHelp – Nome da Rotina chamadora do help (sempre branco)
nLinha – Número da linha da rotina chamadora (sempre 1)
cTítulo – Título do help
cNil – Sempre NIL
cMensagem – Mensagem adicional ao help
nLinMen – Número de linhas da Mensagem (relativa à janela)
nColMen – Número de colunas da Mensagem (relativa à janela)
Retorna
Nada
Exemplo
If Empty(cArqs)
dbSelectArea(cAlias)
RecLock(cAlias,.F.)
dbDelete()
MSUnlock()
Else
Help(“ “,1,”NaoExclui”,,cArqs,4,1)
Endif
LetterOrNum
Verifica se determinado caracter é uma letra ou um número.
Sintaxe
LetterOrNum(cChar)
Parâmetros
cChar – Caracter para verificação.
Retorna
lAlfa – Retorna Verdadeiro (.V.) se o caracter informado for uma letra ou um
número.
Exemplo
If LetterOrNum(cCh)
//Processamento
Endif
MesExtenso
Retorna o nome do mês por extenso.
Sintaxe
MesExtenso(nMes)
Parâmetros
nMes – Número do mês (1 a 12). Se “nMes” não for informado, é assumido o
mês da data base do sistema. Esta variável também pode ser caracter (“1” ou
“2”) ou do tipo data.
Retorna
cNome – Nome do mês retornado por extenso.
Exemplo
MesExtenso(dDataBase)+” de “+StrZero(Year(dDataBase),4)
NaoVazio
Verifica se o campo não está vazio.
Sintaxe
NaoVazio(cCpo)
Parâmetros
cCpo – Campo a verificar
Retorna
Exemplo
@ 5,10 MsGet cCodigo Valid NaoVazio(cCodigo)
Negativo
Verifica se é negativo.
Sintaxe
Negativo(nCpo)
Parâmetros
nCpo – Campo a verificar
Retorna
ExpL1 – Se o valor de nCpo for menor que 0, é retornado .T., caso contrário
será retornado .F..
Exemplos
If Negativo (nValTitulo)
@ 5,10 Say “Valor invalido”
Loop
EndIf
Pergunte
Esta função permite acessar e editar um grupo de perguntas do arquivo SX1.
Mostra uma tela contendo as perguntas gravadas em SX1 a serem respondidas ou
confirmadas pelo usuário.
Sintaxe
Pergunte(cGrupo, lVar)
Parâmetros
cGrupo – Nome do Grupo de perguntas.
lVar – .F. - devolve o conteúdo das variáveis, não apresentando a janela de
perguntas; .T. - permite a alteração das variáveis, apresentando a janela.
Retorna
ExpL1 – .T. se o grupo de perguntas existe.
Exemplos
pergunte(“AFR090”,.T.)
Pertence
Verifica se o campo está contido em outro.
Sintaxe
Pertence(cString,cCampo)
Parâmetros
cString – String que deve estar contida no cCampo
cCampo – Campo a verificar
Retorna
Exemplo
@ 09,19 MsGet cTipo Picture “@!” Valid Pertence(“CL\VD\PD”,cTipo)

PesqPict
Pesquisa, no dicionário de dados, qual a picture usada em um determinado campo,
seja para a edição em tela ou para a impressão de relatórios.
Sintaxe
PesqPict(cAlias,cCampo,nTam)
Parâmetros
cCampo – Nome do campo
nTam – Opcional, para campos numéricos, será usado como o tamanho do
campo para definição da picture. Se não informado, e usado o tamanho
padrão no dicionário de dados.
Retorna
cPic – Picture do campo
Exemplo
@ nLin,20 PSay “Total: “
@ nLin,27 PSay SF2->F2_VALBRUT Picture PesqPict(“SF2”,”F2_VALBRUT”)
PesqPictQt
Devolve a Picture de um campo de quantidade, de acordo com o dicionário de
dados. Esta função geralmente é utilizada quando há pouco espaço disponível para
impressão de valores em relatórios, quando o valor nEdição não é informado, ela
tem o comportamento semelhante ao da função “X3Picture”, pois busca o tamanho
do campo no dicionário de dados.
Sintaxe
PesqPictQt(cCampo,nEdição)
Parâmetros
cCampo – Nome do campo a verificar a picture
nEdição – Espaço disponível para edição
Retorna
ExpC – Picture ideal para o espaço definido por nEdição, sem a separação
dos milhares por vírgula
Exemplo
@ nLin,10 PSay SB2->B2_QATU Picture PesqPictQt (“B2_QATU”,8)
Positivo
Verifica se é positivo.
Sintaxe
Positivo(nCampo)
Parâmetros
nCampo – Campo a verificar
Retorna
Comentários
Se cCampo for maior ou igual ( >= ) a zero a função retorna .T.

Caso contrário retorna .F.

Exemplo
@ 09,07 MsGet nValor Picture “999999” Valid Positivo ( nValor )
RestArea
Restaura a área RestArea a partir do array.
Sintaxe
RestArea(aArray)
Parâmetros
aArray – Expressão Array para restauração
Exemplo
aArray:=GetArea()
RestArea(aArray)
Ver também
Função GetArea()
Tabela
Devolve o conteúdo da tabela de acordo com a chave. Esta função é usada para a
obtencao do conteúdo de uma determinada tabela, na chave especificada.
Retorna o conteudo, possibilitando inclusive a exibição de um “help” caso a tabela
não exista.
Sintaxe
Tabela(cTab,cChav,lPrint)
Parâmetros
cTab – Número da tabela a pesquisar (deve ser informado como caracter).
cChav – Chave a pesquisar na tabela informada.
lPrint – Indica se deve (.T.) ou não (.F.) exibir o help ou a chave NOTAB
se a tabela não existir.
Retorna
cRet – Conteúdo da tabela na chave especificada. Retorna nulo caso a tabela
não exista ou a chave não seja encontrada.
Variação
Retorna a variação em percentual entre dois valores.
Sintaxe
Variação(nFator1,nFator2)
Parâmetros
nFator1 – Primeiro fator comparativo
nFator2 – Segundo fator comparativo
Exemplo
Variacao(100000,50000)
Vazio
Verifica se o campo está vazio.
Sintaxe
Vazio(cCampo)
Parâmetros
cCampo – Campo a verificar
Retorna
Comentários
Retorna .T. se ExpC1 estiver vazio.
Exemplo
@ 9,10 MsGet cCodigo Valid !Vazio(cCodigo)
XFilial
Retorna a filial utilizada por determinado arquivo. Esta função é utilizada para
permitir que pesquisas e consultas em arquivos trabalhem somente com os dados
da filial corrente, dependendo é claro se o arquivo está compartilhado ou não
(definição que é feita através do Módulo Configurador). É importante verificar que
esta função não tem por objetivo retornar apenas a filial corrente, mas retorná-la
caso o arquivo seja exclusivo. Se o arquivo estiver compartilhado, a função xFilial
retornará dois espaços em branco.
Sintaxe
xFilial(cAlias)
Parâmetros
cAlias – Alias do arquivo desejado. Se não for especificado, o arquivo
tratado será o da área corrente.
Retorna
cFilArq – Retorna a Filial para o arquivo desejado.
Exemplo
cFilial := xFilial(“SB1”)
Funções para Tratamento de Bases de Dados

AbreExcl
Fecha o arquivo e reabre exclusivo. Esta função fecha o arquivo cujo alias está
expresso em <cAlias> e o reabre em modo exclusivo para proceder operações em
que isto é necessário, como por exemplo, PACK. Entretanto, é preferível utilizar o
depurador do sistema para proceder estas operações. Se outra estação estiver
usando o arquivo, o retorno será .F..
Sintaxe
AbreExcl(cAlias)
Parâmetros
cAlias – Nome do Alias do Arquivo. Deve ter obrigatóriamente sua
estrutura definida no SX3.
Exemplo
IF AbreExcl(“SI2”)

Pack
ENDIF
AbreExcl( )
dbGoTop( )
Contar
Conta o número de registros de acordo com a condição determinada.
Sintaxe
Contar(cAlias, cCond)
Parâmetros
cALias – Alias do arquivo
cCond – Condição para a contagem
Exemplo
Contar(“SC1”,“C1_DATPRF < dDataBase”)
CriaTrab
Cria arquivo de trabalho temporário.
Sintaxe
CriaTrab(aArray,lDbf)
Parâmetros
aArray – Array multidimensional contendo os campos a criar {Nome, Tipo,
Tamanho, Decimal}
lDbf – Determina se o arquivo de trabalho deve ser criado ( .T.) ou não (.F. )
Retorna
ExpC1 – Nome do Arquivo gerado pela função.
Comentários
Esta função retorna o nome de um arquivo de trabalho que ainda não exista.
Caso lDbf = .T., a função criará um arquivo DBF com este nome e a estrutura
definida em aArray.
Caso lDbf = .F., a função não criará arquivo de nenhum tipo, apenas
fornecerá um nome válido.
Exemplos
//Exemplo para criar arquivo temporário simples
cArq := CriaTrab(NIL, .F.)
cIndice := “C9_AGREG+”+IndexKey()
Index on &cIndice To &cArq
// Exemplo para criar tabela temporária baseada em

estrutura
aStru := {}
AADD(aStru,{ “MARK” , “C”, 1, 0})
AADD(aStru,{ “AGLUT” , “C”, 10, 0})
AADD(aStru,{ “NUMOP” , “C”, 10, 0})
AADD(aStru,{ “PRODUTO”, “C”, 15, 0})
AADD(aStru,{ “QUANT” , “N”, 16, 4})
AADD(aStru,{ “ENTREGA”, “D”, 8, 0})
AADD(aStru,{ “ENTRAJU”, “D”, 8, 0})

AADD(aStru,{ “ORDEM” , “N”, 4, 0})
AADD(aStru,{ “GERADO” , “C”, 1, 0})
cArqTrab := CriaTrab(aStru, .T.)
USE &cArqTrab ALIAS TRB NEW
DbSelectArea
Esa função permite que você selecione um arquivo .
Sintaxe
DbSelectArea(_cAlias)
Parâmetros
cAlias := Alias a ser selecionado.
Exemplo
DbSelectArea(cAlias)
Este Comando irá selecionar o arquivo que possui o alias (apelido) “SA1” – refere-
se ao arquivo de Cadastro de Clientes do sistema Advanced Protheus.
DbSetOrder
Essa função permite que você selecione um índice pré-definido no arquivo de
índices, o qual se encontra no diretório ..\Sigaadv\SINDEX.DBF; também permite
que você selecione um índice criado especificamente para esta rotina.
Sintaxe
DbSetOrder(nOrdem)
Parâmetros
nOrdem := Order do índice a ser selecionado. Respeita a ordem do alias
corrente.
Exemplo
Local cAlias := “SA1”
dbSelectArea(cAlias)
dbSetOrder(2)
DbSeek
Essa função permite localizar um registro a partir de uma chave (esta chave deve
ser igual ao índice já existente no arquivo SINDEX.DBF ou SIXNNN.DBF, onde
NNN corresponde à empresa corrente).
Sintaxe
DbSeek(_cChave)
Parâmetros
CChave := Chave a ser pesquisada respeitando o índice corrente.
Exemplo
dbSelectArea("SA1")
dbSetOrder(1)
dbSeek(xFilial("SA1")+"000001"+"01")

DbSkip
Essa função permite que você saia do registro corrente e passe para o próximo
registro abaixo dele.
Sintaxe
DbSkip()
Exemplo
dbSelectArea("SA1")
dbSetOrder(1)
While !Eof()
// Processamento da rotina
dbSelectArea("SA1")
dbSkip()
Enddo
RecLock
A função RecLock permite ao usuário travar registro para efetuar inclusão,
alteração ou exclusão de campos ou registros.
Sintaxe
RecLock(cAlias,lAppend)
Parâmetros
cAlias := Alias a ser utilizado.
lAppend := .T. abre um registro em branco, .F. altera o registro corrente.
Exemplo
RecLock("SA1", .F.)
SA1->A1_UF := "SP"
MsUnlock()
MSUnlock
Essa função é usada logo após a função RecLock(), pois tem como objetivo
destravar o registro previamente travado.
Sintaxe
MSUnlock()
Exemplo
RecLock("SA1", .T.)
SA1->A1_CODIGO := "999999"
SA1->A1_NOME := "CURSO DE ADVPL"
MsUnlock()
ExistChav
Verifica se a chave já existe em determinado Alias. Função para uso em validações
de campos-chave, para não permitir a duplicidade de registros.
Sintaxe
ExistChav(cAlias,cChave,nOrdem,cHelp)
Parametros
cAlias – Alias do arquivo no qual a consistência deve ser avaliada

cChave – Chave para a pesquisa. Opcional. Se não for informada, o

conteúdo será automaticamente obtido do GET ativo
nOrdem – Ordem do índice para a pesquisa no Alias. Se não for
especificado, será assumida a primeira ordem
cHelp – Opcional chave de help. Se não for informada, o help será o padrão
do sistema (“JAGRAVADO”)
Retorna
lRet – Retorna Verdadeiro (.T.) se a chave não existir (o que significa que
pode ser usada para incluir um novo registro). Caso contrário, retorna Falso
(.F.) e executa um help do sistema.
Exemplo
ExistChav(“SZ1”,cEsp,1,”ESPEXIST”)
ExistCpo
Verifica se determinada chave existe no Alias especificado. Função utilizada em
processamentos onde o código informado deve existir em determinado cadastro,
na sua validação.
Sintaxe
ExistCpo(cAlias,cChave,nOrdem)
Parâmetros
cAlias – Alias do arquivo para a pesquisa
cChave – Chave a ser pesquisada (opcional). Se não for informada, o conteú-
do é obtido automaticamente do GET em uso
nOrdem – Número da ordem do Índice para Pesquisa (Opcional). Se não for
informado, usa a ordem atual do Alias.
Retorna
lRet – Retorna Verdadeiro (.T.) se a chave existir no Alias especificado, caso
contrário, retorna Falso (.F.) e executa um help padrão do sistema
(“REGNOIS”). A ordem utilizada na pesquisa é a atualmente selecionada. Se
não for informado, usa a ordem atual do álias.
Exemplo
ExistCpo(“SB1”,cProd)
ExistIni
Verifica se o campo possui inicializador padrão.
Sintaxe
ExistIni(cCampo)
Parâmetros
cCampo – Nome do campo para verificação.
Retorna
lEx – Retorna Verdadeiro (.V.) se o campo possui inicializador padrão, caso
contrário, retorna falso (.F.).
Exemplo
If ExistIni(“B1_COD”)
cCod := CriaVar(“B1_COD”)
Endif
IndRegua
Cria índice de trabalho, podendo ser condicional.
Sintaxe
IndRegua(cAlias,cArqtrab,cChave,cPar,cFiltro,cTexto)
Parâmetros
cAlias – Alias do arquivo.
cArqtrab – Nome do arquivo de trabalho retornado pela função CriaTrab
(.F.).
cChave – Expressão utilizada na chave do novo índice.
cPar – Se for igual a ‘D’, cria um indice com a chave inversa, do maior valor
para o menor.
cFiltro – Expressão utilizada para filtro.
cTexto – Texto da régua de processamento ( “Selecionando registros ...”).
Retorno
Nil
Exemplo
DbSelectArea(“SC5”)
cFiltro := “C5_OK<>’X’”
cChave := “Dtos(C5_EMISSAO)+C5_VEND1”
cIndSC51 := CriaTrab(Nil,.F.)
IndRegua(“SC5”, cIndSC51, cChave, , cFiltro, “Selecionando...”)
Posicione
Posiciona o arquivo em um determinado registro.
Sintaxe
Posicione(cAlias, nOrdem, cChave, cCampo)
Parâmetros
nOrdem – Ordem utilizada
cChave – Chave pesquisa
cCampo – Campo a ser retornado
Retorna
Retorna o conteúdo do campo passado com o perímetro.
Exemplo
Posicione(“SA1”,1,xFilial(“SA1”)+001,“A1_NOME”)
RetIndex
Devolve os índices padrões do SIGA.
Sintaxe
RetIndex(cAlias)
Parâmetros
cAlias – Alias do Arquivo
Retorna
Número Índices existentes no SINDEX
Comentários
Baseado no SINDEX, abre todos os índices padrões para o arquivo em
pauta.
Exemplo
nIndex := RetIndex (“SA1”)
Tabela
Devolve o conteúdo da tabela de acordo com a chave. Esta função é usada para a
obtencao do conteúdo de uma determinada tabela, na chave especificada.
Retorna o conteudo, possibilitando inclusive a exibição de um “help” caso a tabela
não exista.
Sintaxe
Tabela(cTab,cChav,lPrint)
Parâmetros
cTab – Número da tabela a pesquisar (deve ser informado como caracter).
cChav – Chave a pesquisar na tabela informada.
lPrint – Indica se deve (.T.) ou não (.F.) exibir o help ou a chave NOTAB
se a tabela não existir.
Retorna
cRet – Conteúdo da tabela na chave especificada. Retorna nulo caso a tabela
não exista ou a chave não seja encontrada.
Exemplo
Tabela(cTabela, cChave)
TamSX3
Retorna o tamanho de um campo no SX3 (dicionário de dados).
Sintaxe
TamSx3(cCampo)
Parâmetros
cCampo – Nome do campo.
Retorna
aTam – Array com o tamanho e decimais do campo.
Índices
A utilização de índices para a pesquisa deve ser bem analisada a fim de evitar
lentidão ou processamentos redundantes nos relatórios.
Os índices ajudam a otimizar as pesquisas em estruturas com looping, por isso não
devem ser utilizados de forma errônea.
Caso a necessidade programa exija uma otimização que não é possível obter com
os índices padrões do sistema é possível criar índices temporários através da
função Indregua tornando assim os relatórios mais ágeis e bem estruturados.

Criando e Deletando Arquivos de Índice (Temporários.)

Quando criamos um arquivo de trabalho ou um índice de trabalho (utilizando a
função Indregua) no final do programa devemos apaga-los.
Exemplo de criação de índice temporário com IndRegua:
Local cArqNtx := CriaTrab(NIL, .F.)

Local cIndCond := “A1_COD == `000001`”
Local cChave := “A1_CGC + A1_INSC”
Local nIdex := SA1->(RetIndex())
IndRegua("SA1", cArqNtx, cChave,, cIndCond, “Aguarde...”)
DbSetOrder(nIndex+1)
Para deletar este índice de trabalho no final do processamento:
SA1->(RetIndex())
fErase( cArqNtx )
Caso o programa que crie um arquivo de trabalho e não o apague no final de seu
processamento, este ficará ocupando espaço em disco no ambiente de trabalho. Isto
poderá gerar problemas futuros para o cliente. Por isto, é fundamental, que após
sua utilização o mesmo seja descartado.
Utilizando Querys no lugar de índices temporários

Podemos utilizar querys no Protheus quando acessamos bancos de dados via
TopConnect.
As querys, quando bem construídas, melhoram sensivelmente a eficiência das

consultas aos dados e reduzem a sobrecarga no servidor de aplicação, TopConnect
e Banco de Dados.
Normalmente uma query é utilizada em substituição a um Loop (While) na base

de dados de programação convencional. Querys mais complexas utilizando joins
poder ser construídas com a mesma função de vários loops.
Cuidados com Posicionamento de Registros

O posicionamento correto de registros é fundamental para a funcionalidade
completa dos programas. Algumas dicas para posicionamento de registros são :
o Evitar DBGOTOP(), usar DBSEEK(XFILIAL()) para os arquivos de dados do

sistema. O comando DBGOTOP() somente será utilizado quando da real
necessidade de se efetuar uma leitura desde o início do arquivo
independente do tratamento de filial.

o Como no mesmo arquivo de dados, poderemos ter registros de várias filiais,

desta forma ficará garantido o posicionamento no primeiro registro da filial
corrente.
o Ao executar um DBSEEK(), verificar se localizou o registro, exemplo:

If ! SB1->(dbSeek(xFilial("SB1")))
// Não achei o registro
Endif
Mesmo que seja óbvio a existência do registro, faça o teste pois o programa deve
prever que a base de dados não é tão confiável como deveria, e um alerta ajuda a
identificar estes casos. Em casos de relatórios, atentar-se para imprimir a
mensagem de forma consciente.
Se for executada a função RECLOCK(cAlias, .F.), para alteração do registro atual,

em um arquivo no estado de EOF() (caso falhe um DBSEEK() ) será abortado o
programa.
O comando SOFTSEEK determina se será usada uma busca relativa durante um

procura em um banco de dados. Se este comando estiver em ON, e for utilizada
uma função DBSEEK(), e nenhuma correspondência for encontrada, o ponteiro de
registro ficará no próximo registro do índice que possua um valor mais alto que a
expressão utilizada nesta função. Este comando deverá ser utilizado com a máxima
atenção, pois caso esteja ligado, poderá localizar um registro errado.
Quanto ao comando DO WHILE não esquecer de incluir a condição referente à

filial, quando esta leitura for de registros de uma filial).
Exemplo :
dbSelectArea("SB1")
dbSeek(xFilial("SB1"))
While ! Eof() .And. B1_FILIAL == xFilial("SB1")

// Processamento
dbSkip()
EndDo
Ao criar uma função que irá desposicionar registros, use a função GETAREA() e
RESTAREA(), para voltar tudo à posição original. Exemplo:
DbSelectArea("SD1")
_aAreaSD1 := Getarea() // Armazena o ambiente do arquivo SD1
dbSetOrder(3)
dbSeek(xFilial("SD1") + DTOS("01/03/01"), .T.)
While !EOF() .And. SD1->D1_FILIAL == xFilial("SD1") .And.;
DTOS(D1_EMISSAO) <= DtoS(mv_par02)
// Processamento
Dbskip()
EndDo
Restarea(_aAreaSD1) //Restaura o ambiente do arquivo SD1
Conceito de Filial e Compartilhamento de Arquivos

O Sistema permite a criação de várias Filiais para uma mesma empresa cadastrada,
de modo que Filiais da mesma empresa compartilhem ou não as mesmas
informações como Cadastro de Produtos, Clientes, etc.
Este tratamento é feito internamente através dos campo XX_FILIAL obedecendo a
seguinte regra:
Arquivos Compartilhados
Quando o arquivo esta configurado para trabalhar no modo compartilhado
(X2_MODO = ‘C’), este campo será gravado com “ “ ( espaços ).
Deste modo o registro ficara disponível para todas as Filiais.
Arquivos Exclusivos
Quando o arquivo esta configurado para trabalhar no modo exclusivo (

X2_MODO= ‘C’ ), esta campo será gravado com o código da Filial Atual.
Deste modo o registro focara disponivel apenas para a Filial que o gravou.
Para que o registro realmente fique disponível ou não para suas respectivas Filiais ,
TODAS as rotinas que manilpulam registros diretamente na base de dados deverá
verificar a Filial através da Função xFilial() , alem disto a maioria dos índices
possuem o campo FILIAL na chave.
xFilial(_cEXPC1) onde, _cExpC1 = Alias do arquivo
A função xFilial() verifica se o arquivo é exclusivo ou compartilhado e ira retornar

“ “ se o arquivo for Compartilhado e o código da Filial se o arquivo for exclusivo .
Por exemplo :
Para executar um dbSeek no arquivo de clientes :
DbSeek(xFilial(“SA1”)+_cCodCli+_cLoja)
Índice do SA1 :
A1_FILIAL+A1_COD+A1_LOJA
Ou um processamento no arquivo :
Do while !EOF() .AND. XX_FILIAL==xFilial(“01”)

Sendo o campo FILIAL parte da chave de Todos os índices do sistema, este

procedimento garante que a utilização dos registros será exclusiva da Filial que
criou os mesmos no caso do arquivo ser Exclusivo, ou disponível para todas as
Filiais quando o mesmo estiver configurado como Compartilhado.
Jamais use um campo filial de uma tabela para executar um dbSeek() em outra
tabela. Pois uma tabela poderá ser compartillhada (campo filial em branco),
enquanto que a outra poderá ser compartilhada (campo filial preenchido).
A variável cFilAnt contém a filial que o usuário está operando, e a variável
cEmpant contém a empresa e a filial
Técnicas para Filtragem

A filtragem dos dados em ambiente Code Base os “DBFs” é feita de maneira geral
pela Função INDREGUA(Params,) , o que de forma geral não impede o uso de
instruções como SET FILTER TO, DBSETFILTER(), DBFILTER() ou qualquer outro
comando de sintaxe xBase. A INDREGUA() é uma função interna que reúne
vários atrativos e facilidades para o seu uso, entre elas a possibilidade de se
indexar e filtrar os registros através dos parâmetros fornecidos, ela também é
preferencialmente usada para que o código fique mais “limpo” e de fácil
interpretação pois dentro de sua estrutura reúne uma série de comandos de
indexação e filtragem que agiliza o processo de criação de índices e filtros em
arquivos de trabalho com menos linhas de código, vejamos o Exemplo :
Chaves Primárias
Sua função é garantir unicidade. Em toda relação, por definição, tem-se uma ou
mais chaves candidatas. Dessas chaves, uma será primária e se houver mais de
uma na relação, essas outras serão definidas como chave alternada.
Chaves Estrangeiras
É um atributo cuja função é permitir relacionamento. Em uma tabela na qual o
atributo é chave externa ou estrangeira, em outra, o atributo deve ser chave
primária, e os valores dos campos são necessários.
Integridade Referencial
Todos os valores da chave estrangeira tem que ter obrigatoriamente valor
correspondente na chave primária que se relaciona; mas nem todos os valores
encontrados na chave primária, precisam ter seus correspondentes na chave
estrangeira que se relaciona. Por exemplo, na tabela de clientes, o campo A1_COD
(código do cliente), vai estar relacionado com outra tabela que indica quais são os
pedidos de venda colocados. Desta forma, nem todos os clientes precisam ter
pedidos de venda colocados; mas, necessariamente, todos os pedidos de venda
precisam de um cliente.
Como o PROTHEUS foi projetado para o ambiente SQL, onde a integridade
referencial das tabelas é definida no próprio banco de dados através de regras
internas, devemos tomar algumas precauções com esse tópico:
Verificar a integridade da coluna em todas as tabelas relacionadas: não se pode

alterar o tamanho do código do cliente em apenas uma tabela, caso esse código seja
alterado deve-se verificar as tabelas de cabecalho e itens das notas fiscais, de titulos
a pagar e receber, etc. O sistema conta com o recurso de grupos de tabelas
relacionadas, que permite alterar o tamanho de diversas colunas de uma vez só ,
garantindo a integridade das colunas
Verificar a integridade dos cadastros com todas as tabelas relacionadas: não pode-
se excluir o código do cliente se existe um pedido de vendas em aberto para esse
cliente, deve-se verificar todas as tabelas relacionadas antes de atualizar a base de
dados.Além disso na inclusão de cadastros devemos utilizar as funções existchav e
existcpo para garantir que as informações de chave não sejam repetidas e que o
acesso a tabelas externas seja validado de maneira consistente.
Verificar a atualização da informação em todas as tabelas relacionadas: a

integridade não se resume a validações de cadastros e tamanho de colunas, deve-se
garantir no ato do desenvolvimento que TODOS os pontos relacionados ao tópico
envolvido sejam analisados e se necessário atualizados. Por exemplo, se será
atualizado o saldo em estoque de determinado produto NÃO DEVE-SE atualizar
somente o arquivo de saldos em estoque, deve-se avaliar se o produto utiliza
rastreabilidade para nesse caso atualizar o arquivo de saldos por lote, deve-se
avaliar se o produto utiliza controle de localização fisica para nesse caso atualizar o
arquivo de saldos por localização, etc. Deve-se fazer um estudo antes de qualquer
alteração em atualização de base de dados.
Funções para Tratamento do Módulo de Contabilidade

CalcSaldo
Calcula o saldo atual de uma determinada conta contábil até um determinado
período. A conta deve estar posicionada no arquivo “SI1” ou “SI7”, de acordo com
a moeda, antes da chamada desta função.
Sintaxe
CalcSaldo(nPer,nMoeda,lSalAnt)
Parâmetros
nPer – Período (1 a 17) que será usado como limite para o cálculo de saldo.
nMoeda – Moeda para o cálculo. Se não informada, é assumida a moeda 1.
lSalAnt – Indica se deve (.T.) ou não (.F.) considerar o saldo inicial da conta.
Se não informado, é assumido verdadeiro (.T.).
Retorna
nSld – Retorna o Saldo atual da conta na moeda desejada.
Exemplos
CalcSaldo(Periodo())

Credito
Devolve o valor a crédito de uma determinada conta.
Sintaxe
Credito(cConta, nMês, nMoeda)
Parâmetros
cConta – Código da Conta
nMês – Mês do movimento desejado
nMoeda – Moeda desejada para obtenção do valor a crédito
Exemplo
Credito(“11103”,03,1)
Ver também
Funções Debito, Saldo e Movimento
Debito
Devolve o valor a débito de uma determinada conta.
Sintaxe
Debito(cConta, nMês, nMoeda)
Parâmetros
nMoeda – Moeda desejada para obtenção do valor a débito
Exemplo
Debito(“11103”,03,1)
Ver também
Funções Credito, Saldo e Movimento
MovimCC
Retorna o movimento de um centro de custo mais conta contábil (extracontábil).
Sintaxe
MovimCC(cCC, cConta, nMês, nMoeda)
Parâmetros
cCC – Código do centro de custo
cConta – Código da conta contábil
nMês – Referente ao mês
nMoeda – Moeda desejada para obtenção do valor
Exemplo
MovimCC(“3001”, “111001”,Month(Ddatabase),1)
Movimento
Devolve o movimento (débito-crédito) de uma determinada conta, ou seja, o saldo
do movimento.
Sintaxe
Movimento(cCódigo,nMês,nMoeda,dData)
Parâmetros
cCódigo – Código da conta

nMoeda – Moeda desejada para obtenção do movimento
dData – Data do exercício desejado
Exemplo
Movimento(“43”,1,1, CTOD ("01/01/95") - retorna o 1º período
Movimento(`43”,1,1,CTOD(“01/01/96”) - retorna o 13º período
Orcado
Retorna o valor orçado de uma conta.
Sintaxe
Orcado(cConta, nPeríodo,nMoeda,dData)
Parâmetros
cConta – Código da conta De
nPerídodo – Referente ao período
dData – Data para conversão (em formato data ou caracter), caso não
informada, será utilizada a DataBase do sistema
Exemplo
Orcado(“11102001”,1,1)
OrcadoCC
Recupera o valor orçado da Conta x Centro de Custo para utilização na planilha.
Sintaxe
OrcadoCC(cConta,cCC,nPeríodo,nMoeda,dData)
Parâmetros
cCC – Código do Centro de Custo
nPeríodo – Período (default mês da database)
nMoeda – Moeda (default 1)
dData – Data para conversão se moeda de 2 a 5 - (default dDataBase)
Exemplo
OrcadoCC( “111001”,“3001”,3,2)
Periodo
Devolve o período contábil de acordo com o exercício atual.
Sintaxe
Periodo(dData,nMoeda)
Parametros
dData – Data a ser considerada. Se não for especificada, é assumida a data
base.
nMoeda – Moeda a ser considerada. Se não for especificada, é assumida a
primeira moeda.
Retorna
nPer – Período contábil retornado.

Saldo
Calcula o saldo de uma determinada conta até o período informado e na moeda
especificada.
Sintaxe
Saldo(cConta,nPer,nMoeda)
Parâmetros
cConta – Código da conta desejada.
nPer – Período contábil até o qual será feito o cálculo.
nMoeda – Moeda desejada.
Retorna
nSld – Retorna o Saldo da conta até o período desejado.
Exemplo
cConta := SA1->A1_CONTA
nSl := Saldo(cConta,Periodo(dDataBase,2),2)
cSl := Transform(nSl,”@E 9,999,999.99")
Alert(“O saldo da conta “+cConta+” na moeda 2 e’: “+cSl)
Return
SaldoCC
Calcula o saldo atual em um determinado centro de custo ou conta (extracontábil).
O arquivo SI3 deve estar posicionado para a obtenção dos valores para o cálculo.
Sintaxe
SaldoCC(cCC,cConta,nPer,nMoeda)
Parâmetros
cCC – Centro de Custo desejado
cConta – Código da conta
nPer – Período até o qual o acúmulo deve ser calculado
nMoeda – Moeda desejada
Retorna
nSld – Saldo atual retorna do.
Exemplo
nSld := SaldoCC(,,12,1)
SaldoCusto
Calcula o saldo dos centro de custos extracontábeis.
Sintaxe
SaldoCusto(cCC1,cCC2,cConta1,cConta2,nMês,nMoeda)
Parâmetros
cCC1 – Centro de Custo Inicial
cCC2 – Centro de Custo Final
cConta1 – Conta Inicial
cConta2 – Conta Final
nMês – Mês (se nula, assume o mês de referência da database)
nMoeda – Moeda (se nula, será assumido 1)
Exemplo
SaldoCusto(“1007”, “1099”, “3”, “4”, “10, 1)
SomaSaldo
Retorna o saldo atual entre um intervalo de contas.
Sintaxe
SomaSaldo(cConta1, cConta2, nPeríodo, nMoeda)
Parâmetros
cConta1 – Código da conta De
cConta2 – Código da conta Até
nPeríodo – Referente ao período
Exemplo
SomaSaldo(“31001”,“31010”,12,1)
SumMovimCC
Retorna o movimento de um intervalo de centro de custos extracontábeis. Poderá
ser parametrizados também um grupo de contas.
Sintaxe
SumMovimCC(cCC1,cCC2,cConta1,cConta2,nMês,nMoeda)
Parâmetros
cCC1 – do Centro de Custo
cCC2 – até Centro de Custo
cConta1 – da Conta
cConta2 – até a Conta
nMês – Mês (default mês da database)
Exemplo
SumMovimCC( “3001”,“3100“,“31001”,“31010”,12,1)
SomaContas
Retorna o saldo acumulado de um grupo de contas, de acordo com a sintaxe
apresentada. Esta função considera somente contas de classe “A” – analítica
Sintaxe
SomaContas(cLista,nMês,nMoeda)
Parâmetros
cLista – Lista de contas, cercada por aspas (“”).
O separador “:” (dois pontos) informa intervalo de contas De-Até.
O separador “ ,” (vírgula) informa separação de contas.
nMês – Mês (default mês da database)
Exemplo
SomaContas(“11101001”,3,1)
//Devolve o saldo da conta em questão no mês 3 na moeda 1.

Funções para Tratamento do Módulo de Estoque/Custos

CalcEst
Devolve a quantidade e saldos do estoque de um produto/almoxarifado em uma
determinada data. Esta função é utilizada para a obtenção dos saldos iniciais em
estoque na data em referência.
Sintaxe
CalcEst(cProduto, cAlmox, dData)
Parâmetros
cProduto – Produto a ser pesquisado
cAlmox – Almoxarifado a pesquisar
dData – Data desejada
Retorna
aArray – Array contendo:
Elemento 1 - Quantidade inicial em estoque na data
Elemento 2 - Custo inicial na data na moeda 1
Elemento 7 - Quantidade inicial na segunda unidade de medida
Exemplos
aSaldos:=CalcEst(SB1->B1_COD,SB1->B1_LOCPAD, dDataBase)
nQuant:=aSaldos[1]
Estrut
Função para obtenção da estrutura de um produto previamente cadastrada no SG1
através dos Módulos “SIGAEST” ou “SIGAPCP”.
Sintaxe
Estrut(cProduto)
Parâmetros
cProduto – Código do produto PAI da estrutura.
Retorna
aStru – Retorna o array com a estrutura do produto na seguinte sintaxe:
{ {Nº , Código , Comp. , Qtd. , TRT }, ... , ... }
Esta função requer que seja declarada a variável chamada “nEstru”
contendo 0, para o seu correto funcionamento.
Exemplo
Local aStru := Estrut(cPrd)
SaldoSB2
Esta função calcula o saldo atual do produto (do Arquivo SB2), descontando os
valores empenhados, reservados, etc. É necessário que o Arquivo SB2 esteja
posicionado no produto desejado.
Sintaxe
SaldoSB2()
Retorna
nSld – Retorna o Saldo do produto calculado.
Exemplo
cSld := Transform(SaldoSb2(),”@E 9,999,999.99")
Funções do Módulo Financeiro

FuncaMoeda
Retorna um array contendo o valor do titulo em até cinco (5) moedas.
Sintaxe
FuncaMoeda(dData,nValor,nMoeda)
Parâmetros
dData – Data utilizada como referência
nValor – Valor utilizado como referência
nMoeda – Moeda em que o valor se encontra
Retorna
aRet – Array contendo o valor informado nas cinco moedas ( {
nVal1,nVal2,nVal3,nVal4,nVal5 } )
Exemplo
nValTit := SE1->E1_SALDO
nMoeda := SE1->E1_MOEDA
aValores := FuncaMoeda(dDataBase,nValTit,nMoeda)
Media
Retorna a taxa média da moeda em um determinado mês/ano.
Sintaxe
Media(nMoeda,nMes,nAno):
Parâmetros
nMoeda := moeda para cálculo da taxa média
nMes := mês para cálculo da taxa média. Se não informado, é
assumido o mês da data base
nAno := ano para cálculo da taxa média. Se não informado, é
assumido o ano da data base
Exemplo
nTaxa := Media(1)
RecMoeda
Rotina para obtenção do valor da moeda desejada em determinada data.
Sintaxe
RecMoeda(dData,nMoeda)
Parâmetros
dData – Data para obtenção do valor da moeda.
nMoeda – Moeda desejada.
Retorna
nVMoeda – Retorna o Valor da moeda na data desejada.

Exemplo
nDolar := RecMoeda(dDataBase,2)
nValDolar := SE1->E1_VALOR * nDolar
SldBco
Retorna o saldo bancário em uma data.
Sintaxe
SldBco(cBanco,cAgência,cConta,dData,nMoeda)
Parâmetros
cBanco – Código do Banco
cAgência – Agência Bancária
cConta – Conta Bancária
dData – Data do Saldo
nMoeda – Moeda do Saldo Bancário
Exemplo
SldBco(“409”,”00198”,”011122”, dDataBase,1)
SldCliente
Retorna o saldo a receber do cliente em uma determinada data.
Sintaxe
SldCliente(cCliente,dData,nMoeda,lSaldo)
Parâmetros
cCliente – Código do Cliente+Loja
dData – Data do Movimento a Receber (padrão é dDataBase)
nMoeda – Moeda
lSaldo – Se .T. considera o saldo do SE5 (padrão é .T.)
Exemplo
SldCliente(“00000101”,dDataBase)
SldFornece
Retorna o saldo a pagar do fornecedor em uma data.
Sintaxe
SldFornece(cFornece,dData,nMoeda,lSaldo)
Parâmetros
cFornece – Código do Fornecedor+Loja
dData – Data do Movimento a Pagar (padrão é dDataBase)
nMoeda – Moeda - (padrão é 1)
lSaldo – Se .T. considera o saldo do SE5 (padrão é .T.)
Exemplo
SldFornece(“00000101")
SldPagar
Retorna o saldo a pagar em uma determinada data.
Sintaxe

SldPagar(dData,nMoeda,lData)
Parâmetros
dData – Data do Movimento a Pagar ( padrão é dDataBase)
nMoeda – Moeda (padrão é 1)
lData – Se .T. Até a Data, .F. Somente Data (padrão é .T.)
Exemplo
SldPagar(dDataBase,1,.T.)
SldReceber
Retorna o saldo a receber em uma data.
Sintaxe
SldReceber(dData,nMoeda,lData)
Parâmetros
dData – Data do Movimento a Receber.
nMoeda – Moeda - default 1
lData – .T. - até a Data; .F. - somente Data (o padrão é .T.)
Exemplo
SldReceber(Data,1,.T.)
XMoeda
Rotina para conversão de valores entre moedas.
Sintaxe
xMoeda(nVMo,nMo,nMd,dData,nDec)
Parâmetros
nVMo – Valor na moeda origem.
nMo – Número da moeda origem.
nMd – Número da moeda destino.
dData – Data para conversão.
nDec – Número de decimais. Se não informado, assume-se 2 casas deci-
mais.
Retorna
nVMoeda – Retorna o Valor na moeda de destino.
Exemplo
nVal := SE1->E1_VALOR // Valor na moeda 1
nVM3 := 0 // Contera o valor na moeda 3
nVM3 := xMoeda(nVal,1,3,dDataBase)
Pontos de Entrada
Dentro dos processos operacionais dos programas é possível criar “aberturas” que
possibilitam a execução de processos distintos a partir de uma rotina do sistema.
Objetivo dos Pontos de Entrada

Deixar o sistema flexivél, pois isso permite uma grande variedade de
desenvolvimento via RDMAKE pelos nossos analistas de suporte de acordo com a
necessidade de cada tipo de cliente/implantação.
Permitir que o sistema seja o mais abrangente possível de acordo com cada tipo de
segmento de negócio.
Quando criar um Ponto de Entrada

O ponto de entrada tem resultado quando permite que um processo possa ser
modificado, desde que ele não seja crítico para o sistema.
Exemplo: Montagem das parcelas de pagamento de um pedido
Ele é útil em processos que podem ser diferentes de acordo com o tipo de negócio
de cada empresa ou estratégia adotada.
Ex: Relatório de Pedido, Cadastro de Clientes
Sintaxe para criar um Ponto de Entrada:
Function TMKA010()
Local _lRetorno := .F.

Local _lTMKMCL := Existblock("TMKMCl")
// O “Existblock” detecta se existe uma função no repositório do AP5 com
esse PE.
If _lTMKMCL
lRetorno := Execblock(“TMKMCI”,.F.,F.,{_aValor})
// aValor é um array que seria recebido pelo usuario em PARAMIXB
Endif
Return( _lRetorno )
Procedimentos para sua criação

Avaliar com critério a criação do Ponto de Entrada, pois é importante localiza-lo
num ponto que seja útil, não redudante e que realmente dê condições de atender
ao solicitante.
O Ponto de entrada não é uma ferramenta de correção de eventuais falha do
sistema e sim para ajudar no desenvolvimento de negócios específicos.
Usando Rotinas Automáticas

A cada dia estamos criando rotinas com interface automática para melhorar a
entrada de dados via outros equipamentos, tais como coletores de dados, interface
de outros softwares, etc. Porém, para nossa própria portabilidade e utilização de
rotinas padronizadas, temos adotado o próprio programa standard, contudo sem
interferencia do usuário (digitador). Para tal, criamos um mecanismo onde todos
os programas que necessitem desta regra devem ser capazes de “inserir” dados de
forma automática. Abaixo mostraremos como proceder :

Tome como exemplo o MATA250.PRX . O vetor aRotAuto é passado para o

programa citado. Se este vetor contiver elementos, significa que será utilizada a
Rotina Automática. Este vetor deve, quando da utilização das rotinas automáticas,
conter os dados mínimos necessários para a atualização dos arquivos.
Veja a estrutura do vetor a ser enviado para a rotina automática.
ARotAuto := { _cCampo, Conteúdo, Validação}
Onde
_cCampo ⇒ é o campo a ser atualizado,
Conteúdo ⇒ é o conteúdo que cCampo vai receber
Validação ⇒ é a validação que cCampo vai receber.
Observação: A Validação pode ser uma função ou um valor ‘NIL’. Se for ‘NIL’, as
validações a serem utilizadas para o respectivo campo serão as existentes no SX3.
Se as validações não forem as do SX3, elas devem ser passadas numa função.
Exemplo,
ARotAuto := { "D3_TM" ,"001" ,NIL } , ;

{
{ "D3_COD" ,padr("10100",15) ,NIL } , ;
{ "D3_UM" ,"UN" ,NIL } , ;
{ "D3_QUANT" ,1 ,NIL } , ;
{ "D3_OP" ,"00000401001" ,NIL } , ;
{ "D3_LOCAL" ,"01" ,NIL } , ;
{ "D3_EMISSAO" ,dDataBase ,NIL } }
Para o processo de inclusão simples, sem getdados, a variável padrão a ser

utilizada nos programas chama-se aRotAuto, e para processo de inclusão com
cabeçalho e itens, as variáveis a serem utilizadas são: aAutoCab para o cabeçalho, e
aAutoItens para os itens da getdados.
Para uma inclusão simples, tomar como exemplo o MATA250.PRX. Para uma
inclusão com cabeçalho e ítem, tomar como exemplo o CONA050.PRX.
Controle de Semáforo
O controle de Semaforo permite que o sistema controle a Numeração Automática
de Documentos On Line. Temos basicamente 3 funções que gerenciam o controle
do mesmo.

GetSX8Num
Fornece um número seqüencial do controle de Semáforo. Esta função retorna o
próximo número, na seqüência e disponível, para o cadastro no Protheus e
mantém esta numeração para o usuário até o momento em que ele confirme ou
abandone a operação. O Arquivo de Semáforo é usado para evitar a duplicidade de
chaves em ambientes multiusuário. Esta função trabalha junta-mente com outras
duas, chamadas CONFIRMSX8 e ROLLBACKSX8. Verifique os exemplos para
maiores detalhes.
Sintaxe
GetSx8Num(cAlias,cCpoSx8)
Parâmetros
cAlias – Alias do Arquivo
cCpoSx8 – Nome do campo para aplicação do semáforo
Exemplo
Para que o Cadastro de Clientes, por exemplo, carregue na inclusão o
próximo número disponível automaticamente, pode-se utilizar a seguinte
sintaxe no inicializador padrão do campo “A1_COD”:
GetSx8Num(“SA1”)
Caso seja um arquivo especifico, utilize a sintaxe a seguir:
GetSx8Num(“SZ1”,”Z1_COD”)
Para uso em RdMakes, as sintaxes descritas acima também são válidas, não
devendo-se esquecer de que a função GETSX8NUM trabalha junto com as
funções CONFIRMSX8 e ROLLBACKSX8, que devem ser chamadas ao final
do processamento (procedimento que é feito automaticamente em um
inicializador padrão conforme a sintaxe explicada acima).
cCodNew := GetSx8Num(“SZ1”,”Z1_COD”)
// Processamento...
// Confirmacao
ConfirmSx8()
// ou Cancelamento
RollBackSx8()
ConfirmSX8
Confirma o número obtido pela função GETSX8NUM no semáforo como utilizado.
Verifique a função GETSX8NUM para maiores detalhes.
Sintaxe
ConfirmBackSx8()
Exemplo
Verifique os exemplos na função GETSX8NUM.
RollBackSX8
Retorna o número obtido pela função GETSX8NUM no semáforo como pendente.
Verifique a função GETSX8NUM para maiores detalhes.
Sintaxe
RollBackSx8()
Exemplo
Verifique os exemplos na função GETSX8NUM.
Programando para Banco de Dados

Controle de Transação (TTS)
Tratando-se de Banco de Dados, toda e qualquer operação de inclusão, alteração
ou exclusão de registro é armazenada primeiramente na área de LOG, garantindo
assim que ao fazer a inclusão de uma linha (registro) seja garantida a inclusão
completa de todas as colunas (campos). Caso não seja possível a inclusão da linha
completa ele executa um procedimento chamado de ROLLBACK, ou seja, ignora
todo o registro.
Quando usar
Quando temos uma operação em Banco de Dados que necessite que várias
inclusões, alterações ou exclusões só sejam efetuadas quando todas as operações
tenham sido realizadas com sucesso, garantindo com isso que não seja atualizada
parcialmente uma tabela ou que atualize uma tabela e não atualize outra tabela
relacionada.
Como usar
Para definir uma transação, deve-se utilizar os comandos BEGIN TRANSACTION
e END TRANSACTION para definir inicio e fim de uma transação
respectivamente. Todas informações à serem gravadas no Banco devem estar
dentro de uma única transação sejam elas provenientes de uma ou várias tabelas.
Deve-ser evitar utilizar laços (WHILE, FOR) dentro de uma transação, pois a área
de LOG do banco é limitada, e se o volume de informações ultrapassarem este
limite, ocasionará o travamento do banco de dados.
Onde não usar

O controle de transação jamais deverá ser utilizado durante processo que
envolvam interface (telas com entrada de dados). O controle deve-se resumir
apenas ao processo de gravação. Entre um início de transação (Begin Transaction)
e um final (End Transaction) Todos os registros a serem gravados ficam “locados”
até o final da transação. Caso tenhamos uma tela após o BEGIN e antes do END
dependeremos do usuário para efetuar a liberação da transação, fato este que
causaria enormes problemas para o usuário.
Outro lugar que não deve-se ter o controle de transação refere-se a rotinas de
reprocessamentos ou recálculos, onde as informações podem ser regerados
durante este processo ou onde possamos ter um grande número de locks.

BEGIN TRANSACTION
cExpN1 :=FuncGrava()
END TRANSACTION
Caso exista uma transação dentro de uma outra a segunda será automaticamente
ignorada, fechando-se a transação principal quando da chamada do comando END
TRANSACTION.
Portabilidade
Acreditamos que muitos já perguntarão por que da existência da coluna

R_E_C_N_O_ no Banco de dados, mesmo os que não conhecem esta coluna tem
como objetivo manter a portabilidade de uma Base DBF e Banco ADS para um
Banco de Dados qualquer e também entre Banco de dados. Se você possui sua
aplicação trabalhando em DBF , você pode porta-la independente de modificações
para uma Base SQL, e se você já esta em uma base SQL do tipo MSSQL SQL Server
e gostaria de porta-la para ORACLE, você pode fazer isto sem nenhum problema.
Se você possui programas específicos desenvolvidos (PERSONALIZAÇÕES), você

precisa que os mesmos estejam desenvolvidos nos padrões de compatibilidade
exigidos pela Microsiga. Você verá mais adiante exemplos de programas e uma
apresentação mais completa deste assunto.
Dicas Importantes – DBF versus SQL

A princípio não existem diferenças na programação na versão SQL, já que pelo
próprio fato de ser uma linguagem interpretada, o sistema é quem se encarrega de
executar os comandos e funções adequadamente no ambiente em que trabalha.
Mas é importante manter algumas informações em mente ao programar para o
ambiente SQL.
Deve-se lembrar que estamos trabalhando com um banco de dados relacional, que
se utiliza de tabelas ao invés de arquivos, e onde o sistema não tem acesso aos
dados de forma nativa e sim através do Top Connect. Essa forma de acesso adiciona
ao sistema algumas das características e vantagens oferecidas pelo SGBD em uso
(por exemplo, o Oracle, MSSQL Server ou o DB2) como por exemplo segurança e
integridade referencial, e as imensas facilidades da linguagem SQL, mas por outro
lado tem-se também as implicações da conversão dos comandos no padrão xBase
para a perfeita compreensão no ambiente SQL.
Imagine a montagem de uma expressão de filtro para um índice condicional. Tome
a seguinte expressão como exemplo: "DTOS(E1_VENCTO) >= DTOS(mv_par01)".
Em um ambiente padrão xBase, como o NTX ou o ADS, pode-se utilizar variáveis
sem qualquer problema em uma expressão de filtro pois a mesma será avaliada
registro a registro durante a montagem do índice. Mas no ambiente SQL, o filtro
nada mais é do que uma tabela temporária, onde estão selecionados apenas os

registros conforme a condição indicada. A seleção de dados em tabelas pelo SQL é

mais rápida, mas em conpensação o SGBD não tem como reconhecer a variável
informada na expressão. Ela existe apenas no sistema ou, mais especificamente, no
seu programa. Por isso, deve-se substituir a expressão anteriormente exemplificada
pela seguinte (que também funcionaria perfeitamente em um ambiente xBase):
"DTOS(E1_VENCTO) >= ‘"+DTOS(mv_par01)+"’". Esta expressão é melhor que
anterior simplesmente porque não se utiliza da variável e sim do conteúdo da
mesma, o que pode ser compreendido em qualquer ambiente. Toda essas
explicações são válidas, da mesma maneira, a filtros criados através do comando
SET FILTER.
Ainda existem outros detalhes a se considerar quando se trabalha com índices em
um ambiente SQL. É que na verdade não existem índices condicionais nesse
ambiente. O filtro é criado independente do índice. Então, você pode criar um
INDREGUA com um filtro e mudar a ordem, mas o filtro permanecerá ativo, em
qualquer ordem. Do mesmo modo, não se pode manter dois índices, com filtros
diferentes, pois um filtro sobrescreveria o outro.
Outro ponto de atenção deve ser a função xBase chamada DBSETINDEX. Podem
ocorrer alguns erros ao tentar-se utilizar essa função para abrir um índice de
trabalho criado. Por esses motivos e pelo fato de tornar o processamento mais lento
deve-se evitar ao máximo o uso de índices de trabalho no ambiente SQL.
Da mesma maneira que a funcão DBSETINDEX, os comandos COPY TO e
APPEND FROM também devem ter uma atenção especial. No ambiente SQL esses
comandos são executados entre uma tabela e um arquivo DBF (e vice-versa) ou
entre dois arquivos DBF. Por exemplo, o comando COPY TO pode ser usado para
copiar os dados da tabela ativa para um DBF local e o comando APPEND FROM
pode ser usado para importar os dados de um arquivo local para a tabela ativa. Os
dois podem ser usados entre dois arquivos, mas nunca pode-se usar, por exemplo,
o comando APPEND FROM para importar os dados de uma tabela para outra.
Função da coluna R_E_C_N_O_
A Coluna R_E_C_N_O_, tem por objetivo principal guardar um número seqüencial

de controle de registro, mais conhecido como ID (identificador). Este identificador
é utilizado pela aplicação na pesquisa e posicionamento de registro.
Esta coluna não possui repetição, ela é sempre preenchida com o valor máximo da
coluna R_E_C_N_O_ + 1 nas próximas inserções. Esta operação é feita pelo
TopConnect , se você utiliza outros produtos que fazem inserção na Base de Dados
do Sigaadvanced / AP5 você deve seguir as orientações do Capítulo Integrações
com outros aplicativos.
Limite de registros
O limite de registros em uma tabela é de 2,147,483,648 , este número normalmente

deve ser levado em consideração para as tabelas que recebem muita inserção de
registro seguidas de muitas exclusões. Lembrando que devido à portabilidade, os

registros nunca são excluídos fisicamente pela aplicação.
Renumeração da coluna RECNO
Quando os registros são deletados pelo sistema, os mesmos são apenas marcados,
para exclusão física acontece em quando executamos a operação que conhecemos
com Pack de registros. Após esta operação a coluna R_E_C_N_O_ não é
renumerada. Não existe a necessidade de fazer a renumeração desta coluna, a não
ser que você esteja perto de estourar o maior número possível nesta coluna. Neste
caso você precisar extrair os dados do Banco de Dados para uma Base DBF e logo
em seguida subir a Base novamente para o Banco de Dados, automaticamente a
coluna R_E_C_N_O_ será ajustada.
Controle dos registros deletados (Coluna D_E_L_E_T_)
Toda exclusão de registro feita no Banco de Dados ou em qualquer plataforma do

SigaAdvanced / AP5, só é feita logicamente, ou seja, o registro é marcado como
excluído (delete), e esta marca é feita utilizando o campo chamado D_E_L_E_T_ , a
mesma é preenchida com (*) Asterisco, caso contrário a coluna permanece com o
conteúdo em branco.
Quando você utiliza o comando Set Delet on/off, o TopConnect estará tratando o
dado para você, mas se você utiliza query’s para recuperação de dados você
deverá tratar este coluna (Mais informações sobre o tratamento da coluna
D_E_L_E_T_ será apresentado em exemplos de query’s em PERSONALIZAÇÕES.
Comandos do TOPCONNECT
TcQuery
Executa uma query (consulta) ao banco de dados, retornando um alias para o
resultado. Semelhante ao comando USE padrão do Clipper, porém executando a
consulta.
Sintaxe
TcQuery <cQuery> [NEW] [ALIAS <cAlias>]
Parâmetros
cQuery – Query a ser executada
NEW – Abre uma nova área de trabalho
ALIAS cAlias – Nome do alias gerado na consulta
Exemplo
cQuery := “Select * from SA1990 for A1_COD > ‘200’”
TQUERY cQuery NEW Alias OTI

TcSQLExec
Esta função executa qualquer syntaxe SQL (não somente consultas como no
comando anterior). Pode ser usada para executar UPDATE, INSERT, DELETE,
etc...
Sintaxe
TcSQLExec(cClause)
Parâmetros
cClause – Clausula a ser executada
Exemplo
cClause := “Create Procedure TSOMA (IN_V1 in number,
OUT_RET ou number) is BEGIN
OUT_RET:=IN_V1+IN_V2”+CHR(59)+”END”+CHR(59)
TCSQLEXEC(cClause)
TcSetField
Esta função serve como apoio ao comando TCQUERY, na recuperação de campos
tipo NUMERIC, DATE e LOGICAL, pois os mesmos são gravados fisicamente no
Banco de Dados como caracteres, e no caso dos numéricos como float.
Sintaxe
TCSetField(<cAlias>, <cField> ,<cType>, [<Prec.Inteira>,<Prec.Decimal>] )
Parâmetros
cAlias – Alias da query a ser ajustada
cField – Campo a ser ajustado
cType – Tipo do campo
Prec.Inteira – Parte inteira
Prec.Decimal – Parte decimal
Exemplo
TCQUERY "SELECT NOME, DATA, MARRIED, VALOR FROM
CUSTOMER" ALIAS QUERY VIA "TOPCONN"
TCSetField("QUERY","DATA","D")
TCSetField("QUERY","VALOR","N",12,2)
TcSPExec
Executa uma Stored Procedure no Banco de Dados.
Devido a uma limitação em alguns dos Bancos de Dados suportados na obtenção
dos tipos de parâmetros (se são de INPUT e/ou OUTPUT) todos as Stored
Procedures a serem executadas através do TOPConnect deverão obedecer o
seguinte padrão de nomenclatura de seus parâmetros :
Parâmetros de INPUT devem começar com IN_... Ex. IN_VALOR.
Parâmetros de OUTPUT devem começar com OUT_... Ex. OUT_CODIGO
Após a execução de uma Stored Procedure o TOPConnect retornará ao ADVPL um
array com 'n' elementos, onde n é o número de parâmetros de OUTPUT da Stored
Procedure.

Onde <aRet> é um array com os parâmetros de retorno da Stored Procedure e

<cSPName> é o nome da Stored Procedure a ser executada e os demais parâmetros
variam conforme a definição da Stored Procedure.
Sintaxe
<aRet> := TCSPExec(<cSPName>,[<xParam1>,<xParam2>...<xParamN>])
Exemplo
If TCSPExist("TESTE")
aRet := TCSPExec("TESTE","JOSE",1000)
EndIf
Performance com SGDB - Otimizando seu código
A linguagem ADVPL tem um enfoque posicional, recuperando os dados

utilizando orientação a registros, enquanto aos Bancos de Dados SQL recuperam
os dados por blocos de dados.
Devido a esta diferença conceitual, vários pontos devem ser levados em
consideração para que se possa obter uma boa performance e utilizar os recursos
de uma aplicação Client/Server.
Leitura Sequencial
Operações de leitura seqüencial de uma tabela podem levar a problemas de

performance.
Vamos analisar o seguinte código:
dbSelectArea("CLIENTES")
nValor := 0
While !Eof()
If ESTADO = "SP"
nValor += SALDO
Endif
DbSkip()
EndDo
O código acima fará com que todas as linhas(registros) da tabela venham para o
Client, o que irá gerar um número de Queries no servidor igual ao número de
linhas da tabela e cada uma delas irá recuperar apenas uma linha, subtilizando a
capacidade de processamento do servidor.
O código acima poderia ser substituído por:

TCQUERY "SELECT SUM(SALDO) ;
FROM CLIENTES ;
WHERE ESTADO = 'SP'" NEW
nValor := COLUMN1
Com a utilização do comando TCQUERY todo a somatória é feita no servidor
retornando assim para a aplicação apenas uma linha com o resultado desejado.

Introdução à Linguagem Orientada a Objetos
A programação orientada à objetos é uma modalidade de desenvolvimento de

software que difere muito da conhecida linguagem procedural que usamos no dia-
a-dia.
Ela apresenta uma estratégia diferenciada de organizar, planejar, escrever,
atualizar e fazer manutenção do software.
As linguagens de alto nível representam uma conexão inteligente entre o
programador e o computador. Sua evolução é paralela às técnicas e métodos do
desenvolvimento do software, sendo inspirada pelo anseio de criar componentes
de softwares robustos e reutilizáveis que reduzem os ciclos e o tempo da produção
do software. Esta diminuição no tempo de produção é ainda mais relevante
quando uma equipe de programadores está trabalhando em um projeto de
software.
A história das linguagens de programação reflete a evolução de linguagens
estruturadas e destas para as orientadas ao objeto. As linguagens estruturadas são
linguagens procedurais, onde um programa é particionado em um conjunto de
procedimentos e funções. A seqüência de rotinas descreve como os dados são
manipulados.
Especificamente, o programador controla a interação entre o código e os dados. O
foco principal das linguagens procedurais é a rotina, enquanto foco secundário são
os dados que estão sendo manipulados.
Conceitos Básicos da OOP

Classe
Uma classe detalha os campos de dados de um objeto e os métodos que atuam
sobre os dados.
A classe é o nível macro do objeto, de onde são herdados suas características e
métodos. Podemos dizer que todo objeto descende de uma classe.
Objeto
Um objeto é um membro de uma classe, tendo em si todas as características da
classe na qual foi herdado. Suas propriedades são protegidas por conceitos de
encapsulamento.
Mensagem
Uma mensagem é uma solicitação enviada a um objeto para chamar um de seus
métodos. Também podem ser acionadas por algum evento.

Método
Um método é o procedimento ou função chamado para atuar num objeto. Um
método define como uma mensagem deve ser executada.
A OOP (Programação Orientada a Objetos) permite uma abordagem mais simples
para a utilização de dados usando objetos que respondem a mensagens. Esta
abordagem demonstra uma noção de que objetos em um programa são similares a
alunos em uma sala de aula – você passa um exercício ou um trabalho para um
aluno ou à um grupo de alunos (o objeto, neste caso) solicitando que lhe seja
apresentado uma solução para um determinado problema. Supondo-se que o
trabalho seja passado ao aluno ou grupo certo, ele responderá usando sua
experiência e recursos. O método pelo qual o trabalho é executado depende do
objeto receptor (aluno). Os detalhes da resposta são transparentes ao professor
(emissor da mensagem). Todo objeto por regra possui um método
CONSTRUCTOR e um método DESTRUCTOR.
Método CONSTRUCTOR
É o responsável por ativar o objeto durante a execução de uma rotina. Esse método aloca o
objeto na memória e o torna disponível para uso. O objeto será carregado com todas suas
propriedades e particularidades. Somente após o método CONSTRUCTOR ser disparado é
que poderemos em seguida acertar suas propriedades e eventos. No ADVPL, o método
CONSTRUCTOR é chamado pela cláusula New(), como veremos nos exercícios a seguir.
Método DESTRUCTOR
Após a sua utilização, cada objeto deve ser removido da memória, para que no decorrer da
aplicação a performance não seja degradada. Para isso, utilizaremos o método
DESTRUCTOR. No ADVPL, os métodos a serem utilizados são End() ou Destroy().
Eventos
Evento nada mais é do que uma ação acontecendo em um determinado momento
no objeto. Na programação OOP, um evento pode disparar outras rotinas e
modificar o processamento. Foi criado para interagir com as ações do usuário
determinando o processamento de forma inteligente. Vamos imaginar uma tela de
entrada de dados. Podemos ter vários eventos relacionados ao usuário que a
estiver operando, como por exemplo, o clique de um mouse, o movimento do
cursor do mouse sobre algum campo, a seleção de uma determinada tecla, entre
outros. Dependendo da ação, determinamos o que será executado e haverá
interação com o usuário.
Herança
Uma outra característica da OOP é a herança, um recurso que produz um grande
efeito, que lhe permite criar subclasses. Cada subclasse recebe as características de
sua classe-mãe (da mesma forma que uma criança traz consigo características
peculiares de seus pais). Uma subclasse acrescenta novos atributos às classes
herdadas e pode também substituir qualquer atributo herdado.

Encapsulamento
Uma das principais características da OOP é o encapsulamento, pois evita que o
programador não precise acessar diretamente os campos de dados de um objeto.
Para isto é necessário criar métodos que serão os responsáveis pelo tratamento de
dados.
Encapsulamento na verdade é unir numa única estrutura, campos de dados e
códigos que agirão sobre eles (métodos). O grande benefício do encapsulamento é
que o programador trabalha voltado única e exclusivamente ao campo de dados
que deseja atingir com seu código. Outra grande vantagem a ser considerada é a
proteção do código interno, fazendo com que rotinas externas não interfiram
diretamente em seu código.

Criação de Janelas padrão OOP
Na programação ADVPL OOP, temos alguns objetos poderosos utilizados na

criação de janelas. Porém antes de nos aprofundarmos nesses objetos, vamos
aprimorar nosso conhecimento no funcionamento das janelas e caixas de diálogo.
Uma janela nada mais é do que um objeto. As características de um objeto de janela
ou caixa de diálogo correspondem numa área retangular na tela, que recebe e
processa mensagens, sempre uma de cada vez, além de interagir com o usuário
através de eventos.
Com o objeto de janelas, temos a liberdade de cria-las visando qualquer finalidade,
onde o limite é a criatividade de cada desenvolvedor.
Durante a criação das janelas, teremos a necessidade de ajustar outros objetos

dentro dela. Dependendo de cada necessidade, poderemos inserir botões, bitmaps,
caixas de texto, rótulos entre outros mais.
Se adicionarmos objetos em nossa área de desenvolvimento, por padrão cada
objeto será independente e ficará separado uns dos outros. Dessa forma, ao criar
um botão após criar a janela, ambos apareceriam separados na tela e não teriam
relação alguma. Então, ao adicionarmos mais objetos em nossos projetos, como
fazer com que eles se tornem integrantes de outro objeto? Simples: os objetos
possuem uma propriedade que identifica quem é o objeto pai. Ao definir essa
propriedade, o objeto filho será sempre criado dentro do objeto pai na qual terá
relação direta, tornando-o independente dos demais objetos que compõem o
projeto.
Essa capacidade de agrupar objetos dentro de outros objetos é chamado de parent.
No ADVPL, a propriedade que define o parent do objeto é o oParent.
A classe que utilizaremos para criação de janelas no ADVPL é a TWINDOW. Essa

classe será responsável pela geração da caixa retangular com todas as
características de uma tela padrão, onde dentro dela deverão ser inseridos novos
objetos de acordo com a necessidade. A classe TWINDOW possui grande
flexibilidade em seu desenvolvimento, permitindo a criação de janelas em
tamanhos definidos, título, botões de maximizar e minimizar, cores de fundo, além
de uma grande funcionalidade para desenvolvedores que utilizam a programação
estruturada, a possibilidade de criar janelas baseadas em pixel na mesma métrica
das janelas em modo texto.
Importante: Para utilizar essa classe, é necessária a utilização de uma include

especial chamada fwmsgs.h, que não está inclusa no pacote original do ADVPL,
mas é facilmente encontrada na internet em sites relacionados ao Clipper.

Sintaxe do método Constructor da classe TWindow:
<oWnd> := TWindow():New(<nTop>,<nLeft>,<nBottom>,<nRight>,<cTitle>,
<nStyle>,<oMenu>,<oBrush>,<oIcon>,<oParent>,[<.vScroll.>],
[<.hScroll.>],<nClrFore>, <nClrBack>, <oCursor>,[Upper(<(border)>)],
!<.NoSysMenu.>,!<.NoCaption.>,!<.NoIconize.>,!<.NoMaximize.>,<.pixel.>)
Propriedades dos objetos da classe TWindow
nTop Linha inicial.

nLeft Coluna inicial.
nBottom Linha final.
nRight Coluna final.
cTitle Título da janela.
nstyle Estilo da janela. Através dessa propriedade podemos personalizar
suas funcionalidades de acordo com a necessidade.
Principais propriedades de estilo de janela

WS_BORDER WS_EX_TRANSPARENT
WS_CAPTION WS_EX_TOOLWINDOW
WS_CHILD WS_EX_TOPMOST
WS_CLIPCHILDREN WS_EX_WINDOWEDGE
WS_CLIPSIBLINGS WS_HSCROLL
WS_DISABLED WS_MAXIMIZE
WS_DLGFRAME WS_MAXIMIZEBOX
WS_EX_ACCEPTFILES WS_MINIMIZE
WS_EX_CLIENTEDGE WS_MINIMIZEBOX
WS_EX_CONTEXTHELP WS_OVERLAPPED
WS_EX_DLGMODALFRAME WS_POPUP
WS_EX_LEFTSCROLLBAR WS_SYSMENU
WS_EX_MDICHILD WS_THICKFRAME
WS_EX_NOPARENTNOTIFY WS_VISIBLE
WS_EX_RIGHT WS_VSCROLL
WS_EX_RTLREADING
oMenu Não utilizado.
oBrush Não utilizado.
oIcon Não utilizado.
oParent Identifica qual é o objeto pai. Se não declarado, assume a
janela principal do sistema.
vScroll Não utilizado.
hScroll Não utilizado.
nClrFore Não utilizado.

nClrBack Seleciona a cor de fundo da janela. Default: branca.
Tabela de cores padrão

Low Intensity colors High Intensity Colors
CLR_BLACK CLR_GRAY
CLR_BLUE CLR_HBLUE
CLR_GREEN CLR_HGREEN
CLR_CYAN CLR_HCYAN
CLR_RED CLR_HRED
CLR_MAGENTA CLR_HMAGENTA
CLR_BROWN CLR_YELLOW
CLR_HGRAY CLR_WHITE
CLR_LIGHTGRAY
CLR_HGRAY
oCursor Não utilizado.
Border Não utilizado.
SysMenu (.T./.F.) .T. exibe botão sysmenu, .F. inibe.
Caption (.T./.F.) .T. exibe titulo da janela, .F. inibe.
Iconize Não utilizado.
Maximize (.T./.F.) .T. exibe botão maximize, .F. inibe.
Pixel (.T./.F.) Define tipo de posicionamento e métrica da janela, .T. em
pixels, .F., modo texto (80/24).

Métodos da classe TWindow
Activate Principal método da classe TWindow, pois, é esse método

que vai ativar a janela na tela. Deve obrigatoriamente ser
chamado sempre que o método construtor de uma janela
for acionado. Este método também possui recursos de
monitoramento de eventos. Quando os eventos forem
declarados dentro deste método, não será mais necessário
declara-los de forma estrutural.
Sintaxe do método Activate
<oWnd>:Activate( [ Upper(<(show)>) ],
<oWnd>:bLClicked [ := \{ |nRow,nCol,nKeyFlags| <uLClick> \} ],
<oWnd>:bRClicked [ := \{ |nRow,nCol,nKeyFlags| <uRClick> \} ],
<oWnd>:bMoved [ := <{uMove}> ],
<oWnd>:bResized [ := <{uResize}> ],
<oWnd>:bPainted [ := \{ | hDC, cPS | <uPaint> \} ],
<oWnd>:bKeyDown [ := \{ | nKey | <uKeyDown> \} ],
<oWnd>:bInit [ := \{ | Self | <uInit> \} ],
[<{uUp}>], [<{uDown}>], [<{uPgUp}>], [<{uPgDn}>],
[<{uLeft}>], [<{uRight}>], [<{uPgLeft}>], [<{uPgRight}>],
[<{uValid}>], [\{|nRow,nCol,aFiles|<uDropFiles>\}],
<oWnd>:bLButtonUp [ := <{uLButtonUp}>
bLClicked Bloco de código disparado quando acionado botão
esquerdo do mouse.
bRClicked Bloco de código disparado quando acionado botão direito
do mouse.
bLDblClick Bloco de código disparado quando acionado duplo clique
do mouse.
bGotFocus Bloco de código disparado quando a janela pega o foco
para si. Equivale à cláusula when.
bLostFocus Bloco de código disparado quando a janela perde o foco.
Equivale à cláusula valid.
bKeyDown Bloco de código disparado quando pressionada uma
tecla. Equivale à cláusula inkey(0).
Ex.: oWnd:bKeyDown := { | nKey,nFlags | MiFuncion (nKey) }
lFocused .T. está com o foco, .F. não está com foco.
End Método de finalização do objeto.
Destroy Método destructor do objeto.
SetFocus Força a obtenção do foco.
Refresh Executa a atualização dos controles da tela.

Exemplo de Código Fonte para Criação de um Objeto de Janela
#include "protheus.ch"
/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ OBJ_JAN ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Exemplo de criação de um objeto de janela simples. º±±
±±º ³ º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºUso ³ APx º±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
User Function OBJ_JAN()
Local oWnd //Objeto de janela

Local _nStyle := WS_CAPTION + WS_SYSMENU + WS_MINIMIZEBOX //Estilo da janela
oWnd := TWindow():New(10,10,20,40,"Exemplo de janela",_nStyle,,,,,.T.,.T.,,,,,;

.T.,.T.,.T.,.T.,.F.)
oWnd:Activate() //Ativa a janela

oWnd:Destroy()
Return
O resultado esperado deverá ser o mesmo que o mostrado na figura abaixo.

Caixas de Diálogo no padrão OOP

As caixas de diálogo são um tipo peculiar de janela que não possuem botões de
maximizar e minimizar. São criadas apenas para estabelecer diálogo entre o
programa e o usuário, oferecendo uma gama de controles (objetos) que tornam a
caixa de diálogo um recurso poderoso para entrada e saída de dados.
Caixas de diálogo podem trabalhar em dois modos, modal e não-modal. As janelas
modais tem objetivo não permitir que o usuário mude para outra janela enquanto
não encerrar a rotina atual. Esse recurso é muito interessante quando se trata de
uma aplicação com diversas caixas de diálogo, pois, podemos fazer com que o
usuário as utilizem na seqüência certa do processamento. Para isso, usamos a
propriedade oParent, fazendo com que dessa forma as caixas de diálogo fiquem
dependentes sempre da anterior, criando um conceito de cascata. A classe utilizada
para a criação da caixa de diálogo é a TDIALOG, derivada da classe TWINDOW,
sendo assim, as propriedades e métodos são bem similares.
Sintaxe do método Constructor da classe TDialog:
<oDlg> = TDialog():New( <nTop>, <nLeft>, <nBottom>, <nRight>,<cTitle>,

<cResName>, <hResources>, <.vbx.>, <nStyle>,<nClrText>, <nClrBack>,
<oBrush>, <oWnd>, <.pixel.>,<oIco>, <oFont>, <nHelpId>, <nWidth>,
<nHeight>)
Propriedades dos objetos da classe TWindow
nTop Linha inicial.

nBottom Linha final.
nRight Coluna final.
cTitle Título da caixa de diálogo.
cResName Não utilizado.
hResources Não utilizado.
Vbx Não utilizado.
NStyle Estilo da janela. Através dessa propriedade podemos personalizar
suas funcionalidades de acordo com a necessidade.
Principais propriedades de estilo de caixas de diálogo
WS_BORDER WS_EX_TRANSPARENT
WS_CAPTION WS_EX_TOOLWINDOW
WS_CHILD WS_EX_TOPMOST
WS_CLIPCHILDREN WS_EX_WINDOWEDGE
WS_CLIPSIBLINGS WS_HSCROLL
WS_DISABLED WS_MAXIMIZE
WS_DLGFRAME WS_MAXIMIZEBOX
WS_EX_ACCEPTFILES WS_MINIMIZE
WS_EX_CLIENTEDGE WS_MINIMIZEBOX

WS_EX_CONTEXTHELP WS_OVERLAPPED
WS_EX_DLGMODALFRAME WS_POPUP
WS_EX_LEFTSCROLLBAR WS_SYSMENU
WS_EX_MDICHILD WS_THICKFRAME
WS_EX_NOPARENTNOTIFY WS_VISIBLE
WS_EX_RIGHT WS_VSCROLL
WS_EX_RTLREADING
nClrText Não utilizado.
nClrBack Seleciona a cor de fundo da janela. Default: branca.
Tabela de cores padrão

Low Intensity colors High Intensity Colors
CLR_BLACK CLR_GRAY
CLR_BLUE CLR_HBLUE
CLR_GREEN CLR_HGREEN
CLR_CYAN CLR_HCYAN
CLR_RED CLR_HRED
CLR_MAGENTA CLR_HMAGENTA
CLR_BROWN CLR_YELLOW
CLR_HGRAY CLR_WHITE
CLR_LIGHTGRAY
CLR_HGRAY
oBrush Não utilizado.
oWnd Parent da caixa de diálogo.
oIco Não utilizado.
oFont Não utilizado.
nHelpID Não utilizado.
nWidth Não utilizado.
nHeight Não utilizado.

Métodos da classe TDialog
Activate Principal método da classe TDialog, pois, é esse método

que vai ativar a caixa na tela. Deve obrigatoriamente ser
chamado sempre que o método construtor de uma janela
for acionado. Este método também possui recursos de
monitoramento de eventos. Quando os eventos forem
declarados dentro deste método, não será mais necessário
declara-los de forma estrutural.
Sintaxe do método Activate
<oDlg>:Activate(<oDlg>:bLClicked[:={|nRow,nCol,nFlags|<uClick>}],
<oDlg>:bMoved [ := <{uMoved}> ],
<oDlg>:bPainted [ := {|hDC,cPS|<uPaint>}],<.center.>,
[{|Self|<uValid>}],[ ! <.NonModal.> ], [{|Self|<uInit>}],
<oDlg>:bRClicked [ := {|nRow,nCol,nFlags|<uRClicked>}],
[{|Self|<uWhen>}] )
bLClicked Bloco de código disparado quando acionado botão
esquerdo do mouse.
bRClicked Bloco de código disparado quando acionado botão direito
do mouse.
bLDblClick Bloco de código disparado quando acionado duplo clique
do mouse.
bValid Bloco de código para validar a saída da janela.
bInit Bloco de código para validar a inicialização da janela.
bWhen Bloco de código para validar a inicialização da janela antes
de ser desenhada na tela.
bGotFocus Bloco de código disparado quando a janela pega o foco
para si. Equivale à cláusula when.
bLostFocus Bloco de código disparado quando a janela perde o foco.
Equivale à cláusula valid.
bKeyDown Bloco de código disparado quando pressionada uma tecla.
Equivale à cláusula inkey(0).
Ex.: oWnd:bKeyDown := { | nKey,nFlags | MiFuncion (nKey) }
lFocused .T. está com o foco, .F. não está com foco.
End Método de finalização do objeto.
Destroy Método destructor do objeto.
SetFocus Força a obtenção do foco.
Refresh Executa a atualização dos controles da tela.

Exemplo de Código Fonte para Criação de Objeto de Janela
/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ OBJ_DLG ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Exemplo de criação de um objeto de diálogo simples. º±±
±±º ³ º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
User Function OBJ_DLG()
Local oDlg //Objeto de Diálogo
oDlg := TDialog():New(10,10,300,500,"Teste de Diálogo",,,,,,,,,.T.,,,,,)

oDlg:lCentered := .T.
oDlg:Activate(,,,,,.F.)
Return
O resultado esperado deverá ser o mesmo que o mostrado na figura abaixo.

Objetos de Controle
A grande finalidade da criação das janelas e caixas de diálogo é a interação com os

usuários durante o processamento de suas rotinas. Para isso devem ser utilizados
objetos de controle como botões, caixas de texto, radio button, chekbox entre
outros. Abaixo estão descritos os objetos necessários para criação de janelas
personalizadas para diversas finalidades. Sempre que utilizarmos os objetos de
controle, não podemos esquecer de informar a propriedade oParent de cada um,
apontando para a janela na qual o objeto irá pertencer.
Botões
Botões são utilizados para dispararem eventos e rotinas dentro de uma janela.
OADVPL possui dois tipos de botões, derivados da classe TBUTTON (Botão
simples) e SBUTTON (botão estilo speed button, com bitmap).
Sintaxe da Classe TBUTTON
[ <oBtn> := ] TButton():New( <nRow>, <nCol>, <cCaption>, <oWnd>,;

<{uAction}>, <nWidth>, <nHeight>, <nHelpId>, <oFont>, <.default.>,;
<.pixel.>, <.design.>, <cMsg>, <.update.>, <{WhenFunc}>,;
<{uValid}>, <.lCancel.> )
nRow Linha inicial.

nCol Coluna inicial.
cCaption Texto do botão.
oWnd Janela parent.
Action Bloco de código com a rotina a ser disparada.
nWidth Tamanho do botão.
nHeight Altura do botão.
oFont Objeto de fonte do botão.
Default Define se virá com o foco quando mostrada a tela.
Design Não utilizado.
cMsg Mensagem estilo Hint com a descrição do botão.
Update Não utilizado.
When Bloco de código que valida a execução da ação do botão,
antes de executar.
Valid Bloco de código que valida a execução da ação do botão,
depois de executar.
Cancel Não utilizado.

Sintaxe da Classe SBUTTON
[ <oBtn> := ] SButton():New( <nTop>,<nLeft>,<nType>,<{ uAction }>,;

<oWnd>,<.mode.>,<cMsg>,<{uWhen}>)
nTop Linha inicial.

nType Texto do botão.
Action Bloco de código com a rotina a ser disparada.
oWnd Janela parent.
Mode Não utilizado.
cMsg Mensagem estilo Hint com a descrição do botão.
When Bloco de código que valida a execução da ação do botão,
antes de executar.

Exemplos de Código Fonte para Criação de um Objetos de botões
Código Fonte exemplo para criação de botões simples.

/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_BTN ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de um objeto de diálogo simples, com botões.º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_BTN()
Local _oDlg //Objeto de Diálogo

Local _oBtn1 //Objeto de Botão
Local _oBtn2 //Objeto de Botão
_oDlg := TDialog():New(10,10,300,500,"Teste de Diálogo",,,,,,,,,.T.,,,,,)

_oDlg:lCentered := .T.
//Exibe botões
_oBtn1 := TButton():New(130,180,"Botão 1",_oDlg,{|| MSGInfo("Teste de
botão","Teste")},30,12,,,.T.,.T.,,"Teste",,,,)
_oBtn2 := TButton():New(130,210,"Fechar",_oDlg,{|| _oDlg:End()},30,12,,,.T.,.T.,,"Fechar",,,,)
_oDlg:Activate()
Return
Exemplo de criação de botões simples.

Código fonte exemplo para criação de botões com bitmap.
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_BTN2 ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de um objeto de diálogo simples, com botões º±±
±±º ³ de bitmap. º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_BTN2()

Local _oBtn1, _oBtn2, _oBtn3, _oBtn4, _oBtn5, _oBtn6,; //Objetos de Botões
_oBtn7, _oBtn8, _oBtn9, _oBtn10, _oBtn11,_oBtn12,;
_oBtn13, _oBtn14, _oBtn15, _oBtn16, _oBtn17, _oBtn18,;
_oBtn19, _oBtn20, _oBtn21, _oBtn22

//Exibe todos tipos válidos de botões

_oBtn1 := SButton():New(020,010,01,{|| MSGInfo("Tipo 1", "Informação")},_oDlg,,"Tipo 1")
_oBtn10 := SButton():New(080,040,10,{|| MSGInfo("Tipo 10","Informação")},_oDlg,,"Tipo 10")
_oDlg:Activate()
Return

Tipos válidos de botões com bitmap

Rótulos de Texto
Rótulos são muito importantes para a definição de campos na tela, bem como
exibição de texto livre. A Classe responsável pela criação de rótulos é a TSAY.
Sintaxe da Classe TSAY
[ <oSay> := ] TSay():New( <nRow>, <nCol>, <{cText}>,[<oWnd>], [<cPict>],;

<oFont>, <.lCenter.>, <.lRight.>, <.lBorder.>, <.lPixel.>, <nClrText>,
<nClrBack>, <nWidth>, <nHeight>)
nRow Linha inicial.

nCol Linha Final.
cText Texto a ser exibido.
oWnd Janela parent.
cPict Picture do texto.
oFont Objeto para selecionar a fonte da janela.
lCenter Centraliza o texto no espaço do objeto.
lRight Alinha à direita (usado para números).
lBorder Não utilizado
nClrText Define a cor do texto.
nClrBack Define cor de fundo na exibição do texto.
nWidth Define o tamanho do objeto.
nHeight Define a altura do objeto.
Seleção de fontes para o objeto de rótulo de texto
Objetos de rótulo de texto podem ter seu fonte padrão alterado para outro
qualquer encontrado no sistema operacional. Para isso, deve ser criado um objeto
derivado da classe TFONT que terá as características do fonte selecionado. Após
carregar o objeto de fonte, basta declara-lo na propriedade oFont do rótulo de
texto.

Sintaxe da classe TFont
<oFont> := TFont():New(<cName>,<nWidth>,<nHeight>,<.from.>,
[<.bold.>],<nEscapement>,,<nWeight>,[<.italic.>])
cName Nome da fonte.

nWidth Comprimento da fonte (normalmente 9).
nHeight Tamanho do fonte.
From Não utilizado.
Bold (.T./.F.) Ativa negrito.
nEscapement Não utilizado.
Reservado
nWeight Não utilizado.
Italic Ativa itálico.
Exemplo de criação de um objeto de fonte
_oFont := TFont():New("Arial",09,12,,.T.,,,,.T.)

Código fonte exemplo para criação de rótulos.

/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_SAY ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de texto livre na janela. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_SAY()

Local _oBtn1, _oBtn2 //Objetos de Botões
Local _oSay //Objeto de rótulo


_oBtn1 := SButton():New(130,180,01,{|| _oDlg:End()},_oDlg,,"Tipo 1")
//Cria objeto de fonte

_oFont := TFont():New("Arial",09,12,,.T.,,,,.T.)
//Exibe o objeto de rótulo

_oSay := TSay():New(020,010,{||"Exemplo de texto livre..."},_oDlg,"@!",_oFont,.T.,,,.T.,,,200,20)
_oDlg:Activate()
Return
Exemplo de apresentação de mensagem de texto em caixas de diálogo

Caixas de Texto
Caixas de texto são objetos importantes para entrada de dados. Através desse
objeto pode-se editar valores de campos para serem processados.
Sintaxe da Classe TGET
[ <oGet> := ] TGet():New( <nRow>, <nCol>, bSETGET(<uVar>),[<oWnd>],;

<nWidth>, <nHeight>, <cPict>, <{ValidFunc}>,<nClrFore>, <nClrBack>,;
<oFont>, <.design.>,<oCursor>, <.pixel.>, <cMsg>, <.update.>, <{uWhen}>,;
<.lCenter.>, <.lRight.>,[\{|nKey, nFlags, Self| <uChange>\}],;
<.readonly.>,<.pass.>)
nRow Linha inicial.

bSetGet Variável de memória do campo.
oWnd Janela parent.
nWidth Tamanho do campo.
nHeight Altura do campo.
cPict Picture do campo.
Valid Bloco de código com função de validação do campo.
nClrBack Define a cor de fundo do objeto.
oFont Objeto que define a fonte utilizada no campo.
cMsg Mensagem tipo Hint do campo.
When Bloco de código para validação na entrada do campo.
lCenter (.T./.F.) Centraliza o texto na caixa de texto.
lRight (.T./.F.) Alinha dados à direita.
nKey Não utilizado.
nFlags Não utilizado.
Change Bloco de código para validar quando alterado o campo.
lReadOnly Deixa o campo somente para leitura.
Pass (.T./.F.) Converte o texto para o formato password (***).

Código fonte exemplo para criação de caixas de texto.

/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_GET ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de caixas de texto e rótulos. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_GET()

Local _oSay1, _oSay2, _oSay3 //Objeto de rótulo
Local _oGet1, _oGet2, _oGet3 //Objeto de caixa de texto
Local _cVar1 := Space(06) //Variável utilizada no Get
Local _cVar2 := Date() //Variável utilizada no Get
Local _cVar3 := 0 //Variável utilizada no Get

//Exibe o objeto de rótulo
_oSay1 := TSay():New(010,010,{||"Caixa de Texto"},_oDlg,,,,,,.T.,,,80,20)
_oSay2 := TSay():New(040,010,{||"Caixa de Data"},_oDlg,,,,,,.T.,,,80,20)
_oSay3 := TSay():New(070,010,{||"Caixa de Número"},_oDlg,,,,,,.T.,,,80,20)
//Exibe as caixas de texto
_oGet1 := TGet():New(020,010,bSetGet(_cVar1),_oDlg,50,12,"@!",,,,,,,.T.)
_oGet2 := TGet():New(050,010,bSetGet(_cVar2),_oDlg,50,12,,,,,,,,.T.)
_oGet3 := TGet():New(080,010,bSetGet(_cVar3),_oDlg,50,12,"@E 999,999.99",,,,,,,.T.)
_oDlg:Activate()
Return

Exemplo de variação de caixas de texto com formatos de dados diferentes
CheckBox
A classe TCHECKBOX criará uma caixa de “marca/desmarca” na janela. Seu

funcionamento consiste em armazenar em uma variável lógica a seleção do
usuário, sendo .T. para marcado e .F. para desmarcado.
Sintaxe da Classe TCheckBox
[ <oCbx> := ] TCheckBox():New( <nRow>, <nCol>, <cCaption>,;

[bSETGET(<lVar>)], <oWnd>, <nWidth>, <nHeight>, <nHelpId>,;
[<{uClick}>], <oFont>, <{ValidFunc}>, <nClrFore>, <nClrBack>,;
<.design.>, <.pixel.>, <cMsg>, <.update.>, <{WhenFunc}> )
nRow Linha inicial.

cCaption Texto do checkbox.
bSetGet Variável lógica que conterá o valor selecionado do
checkbox.
oWnd Janela parent.
nWidth Tamanho do objeto.
nHeight Alturado objeto.
Click Bloco de código disparado com o evento de um clique do
mouse.
oFont Objeto de seleção de fonte para o texto do objeto.
Valid Bloco de código responsável pela validação do objeto.


cMsg Mensagem estilo hint do objeto.
When Bloco de código para validar a entrada no campo.
Código fonte exemplo para criação de CheckBoxes
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_CBX ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de checkbox. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_CBX()

Local _oCbx //Objeto CheckBox
Local _lVar //Variável para armazenar seleção do usuário


//Exibe o objeto checkbox

oCbx := TCheckBox():New(10,10,"Exemplo de Checkbox", bSetGet(_lVar),_oDlg,80,12)
_oDlg:Activate()
Return

Exemplo de criação de diálogo com checkbox.
ComboBox
A classe TCOMBOBOX criará uma caixa de seleção estilo drop-down na janela.

Seu funcionamento consiste em armazenar em uma variável caracter a seleção do
usuário. Os itens são armazenados em um array, que depois é passado como
propriedade do objeto.
Sintaxe da Classe TComboBox
[ <oCbx> := ] TComboBox():New( <nRow>, <nCol>, bSETGET(<cVar>),;

<aItems>, <nWidth>, <nHeight>, <oWnd>, <nHelpId>,;
[{|Self|<uChange>}], <{uValid}>, <nClrText>, <nClrBack>,;
<.pixel.>, <oFont>, <cMsg>, <.update.>, <{uWhen}>)
nRow Linha inicial.

bSetGet Variável que conterá o valor selecionado do objeto.
aItens Array contendo a lista de itens do objeto.
oWnd Janela parent.
Change Bloco de código disparado com o evento alteração no
objeto.
Valid Bloco de código disparado para validar o objeto.

nClrText Define a cor do texto do objeto.

When Bloco de código para validar a entrada no objeto.
Código fonte exemplo para criação de ComboBoxes
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_CBX ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de combobox. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_CBX()

Local _oCbx //Objeto ComboBox
Local _cVar := Space(06) //Variável que armazenará o item selecionado
Local _aVar := {} //Array contendo os itens do ComboBox
AADD(_aVar, "Item 1")



//Exibe o objeto ComboBox

oCbx := TComboBox():New(10,10,bSetGet(_cVar),_aVar,100,12,_oDlg,,,,,,.T.)
_oDlg:Activate()
Return
Exemplo de criação de diálogo com ComboBox.

ListBox
A classe TLISTBOX criará uma caixa de seleção estilo lista na janela. Seu
funcionamento consiste em armazenar em uma variável numérica ou caracter a
seleção do usuário. Os itens são armazenados em um array, que depois é passado
como propriedade do objeto.
Sintaxe da Classe TListBox
[ <oLbx> := ] TListBox():New( <nRow>, <nCol>, bSETGET(<cnVar>),;

<aList>, <nWidth>, <nHeight>, <{uChange}>, <oWnd>, <{uValid}>,;
<nClrFore>, <nClrBack>, <.pixel.>, <.design.>, <{uLDblClick}>,;
<oFont>, <cMsg>, <.update.>, <{uWhen}>)
nRow Linha inicial.

aList Array contendo a lista de itens do objeto.
objeto.
oWnd Janela parent.

DblClick Bloco de código disparado no evento de duplo clique.
Código fonte exemplo para criação de ListBoxes
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_LST ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de listbox. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_LST()

Local _oLbx //Objeto ListBox
Local _cVar := Space(06) //Variável que armazenará o item selecionado
Local _aVar := {} //Array contendo os itens do ListBox



//Exibe o objeto ListBox

oLbx := TListBox():New(10,10,bSetGet(_cVar),_aVar,100,50,,_oDlg,,,,.T.)
_oDlg:Activate()
Return

Exemplo de criação de diálogo com ListBox
Radio Button
A classe TRADMENU criará um campo de seleção de opções na janela estilo Radio

Button. Seu funcionamento consiste em armazenar em uma variável numérica a
seleção do usuário. Os itens são armazenados em um array, que depois é passado
como propriedade do objeto.
Sintaxe da Classe TRadMenu
[ <oRadMenu> := ] TRadMenu():New( <nRow>, <nCol>, {<cItems>},;

[bSETGET(<nVar>)], <oWnd>, [{<nHelpId>}], <{uChange}>,<nClrFore>,;
<nClrBack>, <cMsg>, <.update.>, <{uWhen}>,<nWidth>, <nHeight>,;
<{uValid}>, <.lDesign.>, <.lLook3d.>,<.lPixel.>)
nRow Linha inicial.

aItens Array contendo a lista de itens do objeto.
oWnd Janela parent.
HelpId Não utilizado.
objeto.

Look3D Não utilizado.
Código fonte exemplo para criação de Radio Button
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_RAD ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de Radio Button. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_RAD()

Local _oRad //Objeto Radio Button
Local _nVar := 1 //Variável que armazenará o item selecionado
Local _aVar := {} //Array contendo os itens do Radio Button



//Exibe o objeto Radio Button

oRad := TRadMenu():New(10,10,_aVar,bSetGet(_nVar),_oDlg,,,,,,,,80,20,,,,.T.)
_oDlg:Activate()
Return

Folders
Uma importante classe a ser utilizada nas aplicações é a classe Tfolder. Essa classe
nos permite criar várias instâncias de uma aplicação dividindo-as em várias pastas
diferentes. É muito útil por exemplo quando temos uma tela de entrada de dados
muito grande gerando a necessidade de subdividi-la em várias partes
diferenciando por assunto ou outra forma de divisão a critério do desenvolvedor.
Sintaxe da Classe TFolder
[<oFolder> := ] TFolder():New( <nRow>, <nCol>,[\{<cPrompt>\}],

\{<cDlgName1> [,<cDlgNameN>]\},<oWnd>, <nOption>, <nClrFore>, <nClrBack>,
<.lPixel.>,<.lDesign.>, <nWidth>, <nHeight>, <cMsg> )
nRow Linha inicial.

cPrompt Array contendo os textos de exibição das pastas.
CDlgName1...N Array contendo os nomes dos objetos de pasta.
oWnd Janela parent.
nOption Número da pasta default na inicialização da janela.

Métodos importantes da classe TFolder
oFolder :SetOption(n) Força a seleção da pasta representada por n, onde n é

a sequencia númerica de cada pasta.
oFolder :aDialogs[n] Retorna o objeto individual de cada pasta do Folder
criado. Muito útil para ser usado como parent de
outros objetos, quando houver a necessidade de
armazena-los nas pastas corretas.
Código fonte exemplo para criação de múltiplos Folders com vários objetos dentro
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_FLD ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de Folders. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_FLD()

Local _oFld //Objeto Folder
Local _oSay1, oSay2, oSay3 //Objeto Folder

//Exibe objetos de botões

//Exibe o objeto Folder

_oFld := TFolder():New(05,01,{"Pasta1","Pasta2","Pasta3"},{"Fld1","Fld2","Fld3"},_oDlg,1,,,.T.,,244,120)
//Exibe o objeto Rótulo em seus respectivos objetos Folders

_oSay1 := TSay():New(020,010,{||"Texto do Folder 1..."},_oFld:aDialogs[1],,,.T.,,,.T.,,,200,20)
_oDlg:Activate()
Return

Browse
Browses são ferramentas importantes para a apresentação de dados. O ADVPL

disponibiliza uma classe poderosa para criação de ferramentas de browse, a classe
TWBROWSE. Essa ferramenta será constantemente usada no dia-a-dia do
desenvolvedor ADVPL, devido a sua gama de recursos. Além de apresentar
informações de campos no formato tradicional, essa classe possui recursos de
apresentação de bitmaps em suas colunas. Com isso podemos desenvolver colunas
com marcadores coloridos e marcadores tipo checkbox, comumente conhecidos
como markbrowse.
Sintaxe da Classe TWBrowse
[ <oBrw> := ] TWBrowse():New( <nRow>, <nCol>, <nWidth>, <nHeigth>,;

[\{|| \{<Flds> \} \}], [\{<aHeaders>\}], [\{<aColSizes>\}], ;
<oDlg>, <(cField)>, <uValue1>, <uValue2>,[<{uChange}>],;
[\{|nRow,nCol,nFlags|<uLDblClick>\}],[\{|nRow,nCol,nFlags|<uRClick>\}],;
<oFont>, <oCursor>, <nClrFore>, <nClrBack>, <cMsg>,<.update.>, <cAlias>,;
<.pixel.>, <{uWhen}>,<.design.>, <{uValid}>)
nRow Linha inicial.

nHeight Altura do objeto.
Flds Registros do browse.
aHeaders Array contendo o nome dos campos para exibição.
aColSizes Array contendo o tamanho de cada campo.
oDlg Janela parent.
cField Não utilizado.

Value1 Não utilizado.
Value2 Não utilizado.
Change Bloco de código disparado na alteração do objeto.
bLDblClick Bloco de código disparado no duplo clique do mouse.
bRClick Bloco de código disparado no clique do botão direito.
oFont Define a fonte padrão do objeto.
cMsg Exibe mensagem estilo hint no objeto.
cAlias Não utilizado.
When Bloco de código disparado na entrada do objeto.
Valid Bloco de código disparado na validação do objeto.
Código fonte exemplo para criação de browse completo
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_BRW ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de Browse. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_BRW()

Local _oBrw //Objeto Browse
Local _aFields := {} //Campos do Browse
Local _aHeader := {} //Cabeçalho do Browse
Local _oOk := LoadBitmap(GetResources(),"LBOK")
Local _oNo := LoadBitmap(GetResources(),"LBNO")
Local _oVerde := LoadBitmap(GetResources(),"BR_VERDE")
_aFields := {{.F., _oVerde, "Exemplo de browse"}}

_aHeader := {" ", " ", "Campo 1"}

//Exibe objetos de botões

//Exibe o objeto Browse

_oBrw := TWBrowse():New(10,10,225,115,,_aHeader,,_oDlg,,,,,,,,,,,,.F.,,.T.,,.F.)
_oBrw:SetArray(_aFields)
_oBrw:bLDblClick := {|| _aFields[_oBrw:nAT,1] := !_aFields[_oBrw:nAT,1]}

_oBrw:bLine := {|| {If(_aFields[_oBrw:nAT,1],_oOk,_oNo),_aFields[_oBrw:nAT,2],;

_aFields[_oBrw:nAT,3]}}
_oDlg:Activate()
Return
Exemplo de criação de Browse com recursos de marca e legenda

Criação de janelas mestre-detalhe OOP

Modelo 3
Janelas mestre-detalhe são muito importantes para cadastros envolvendo duas

tabelas relacionadas, normalmente cabeçalhos e itens. O ADVPL nos proporciona
algumas classes de objetos para elaboração de telas complexas envolvendo tabelas
relacionadas. O tutorial a seguir nos mostra como montar uma tela mestre-detalhes
passo-a-passo. As classes envolvidas são MSMGET e MSGETDADOS. A tela
construída no ADVPL possui algumas características peculiares. A tela
normalmente apresentará três seções básicas, a Enchoice, a GetDados e o rodapé
para apresentação de resultados. A imagem abaixo demonstra exatamente o
funcionamento dessa tela.
Enchoice
Bar
Enchoice
GetDados
Rodapé
A janela que traz os itens do cabeçalho é criada pela classe MSMGET e os detalhes
são montados pela classe MSGETDADOS. As informações da GetDados são
provenientes de dois arrays, aHeader e aCols. O aHeader contém informações
sobre os campos, como nome para exibição, tamanho do campo etc. O aCols possui
os dados a serem exibidos. Antes de montar a tela, deve-se criar o aCols e carrega-
lo com as informações da tabela. Um detalhe a ser considerado é que deveremos
criar o aCols com um campo extra no final, pois, ele armazenará um valor lógico
informando se o registro foi deletado ou não. Essa informação será muito útil
durante a gravação dos registros, para que registros descartados não sejam
gravados.

Sintaxe da classe MSMGET
MSMGET():NEW( cAlias, nReg, nOpc, [ uPar1 ], [ uPar2 ], [ uPar3 ], [

aACho ], [ aPos ], [ aCpos ], [ uPar4 ], [ uPar5 ], [ uPar6 ], [ uPar7 ],
[ oWnd ], [ uPar8 ], [ lMemoria ], [ lColuna ], [ uPar9 ], [ lSemPastas ]
)
cAlias Alias dos dados a serem cadastrados.

nReg Número do registro editado.
uPar1 Parâmetro reservado.
aAcho Array com os campos a serem editados.
aPos Vetor com as coordenadas onde a MsMGet será criada no
formato {coord. superior, coord. esquerda, coord. direita,
coord. inferior}.Função executada para validar o contexto
da linha atual do aCols.
aCpos Array com os campos que poderão ser alterados.
uPar4 Parâmetro reservado. Nome dos campos do tipo caracter
que utilizarão incremento automático. Este parâmetro
deve ser no formato “+<nome do primeiro
campo>+<nome do segundo campo>+...”.
oWnd Janela parent.
lMemoria Indica se será usado variáveis de memória ou os campos
da tabela para cadastramento dos dados. Valor padrão
falso.
lColuna Indica se a MsMGet sera apresentada com um objeto por
linha (uma coluna). Valor padrão falso. Parâmetro
reservado.
lSemPastas Indica se não será usado as Pastas de Cadastro na
MsMGet. Função executada para validar a exclusão de
uma linha do aCols.

Construindo um código fonte para criação de um modelo 3
Inicialmente iremos montar um markbrowse para iniciarmos a visualização geral

da tabela principal. Após selecionar o registro a ser trabalhado, será aberta a janela
modelo 3 com todas opções de trabalho para o usuário. No nosso exemplo
estaremos utilizando as tabelas SZ1 (cabeçalho) e SZ2 (Itens). Nas opções do menu
do markbrowse, trocaremos as funções padrão por outra personalizada que irá
disparar o modelo 3 com o registro selecionado.
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_MOD3 ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Exemplo de criação de Modelo3.
º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OBJ_MOD3()
Private cCadastro := "Modelo 3 Exemplo" //Titulo do cadastro

Private aHeader := {} //aHeader original do modelo3
Private aCols := {} //aCols original do modelo3
Private aRotina := {} //Reservado
AADD(aRotina ,{"Pesquisar" , "AxPesqui" , 0, 1})

AADD(aRotina ,{"Visualizar", 'U_MOD3EXEC("SZ1",RecNo(),2)', 0, 2})
AADD(aRotina ,{"Incluir" , 'U_MOD3EXEC("SZ1",RecNo(),3)', 0, 3})
AADD(aRotina ,{"Alterar" , 'U_MOD3EXEC("SZ1",RecNo(),4)', 0, 4})
AADD(aRotina ,{"Excluir" , 'U_MOD3EXEC("SZ1",RecNo(),5)', 0, 5})
dbSelectArea("SZ1")
MBrowse(006, 001, 022, 075, "SZ1")
Return
Após criado o markbrowse, notem que as funções do menu utilizadas foram

trocadas pela U_MOD3EXEC. Nessa função, passaremos como parâmetro a tabela
principal, o registro a ser editado e a ação que o usuário estará fazendo. As ações
são identificadas numericamente. Termos 2-Visualização, 3-Inclusão, 4-Alteração,
5-Exclusão.

Sintaxe da classe MsGetDados
MSGETDADOS():NEW( nSuperior, nEsquerda, nInferior, nDireita, nOpc, [

cLinhaOk ], [ cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter ], [ uPar1
], [ lVazio ], [ nMax ], [ cCampoOk ], [ cSuperApagar ], [ uPar2 ], [
cApagaOk ], [ oWnd ] ) -> objeto
Argumentos Descrição
Distância entre a MsGetDados e o extremidade superior do
nSuperior
objeto que a contém.
Distância entre a MsGetDados e o extremidade esquerda do
nEsquerda
Distância entre a MsGetDados e o extremidade inferior do
nInferior
Distância entre a MsGetDados e o extremidade direita do
nDireita
Posição do elemento do vetor aRotina que a MsGetDados usará
nOpc
como referencia.
Função executada para validar o contexto da linha atual do
cLinhaOk
aCols.
Função executada para validar o contexto geral da
cTudoOk
MsGetDados (todo aCols).
Nome dos campos do tipo caracter que utilizarão incremento
cIniCpos automático. Este parâmetro deve ser no formato “+<nome do
primeiro campo>+<nome do segundo campo>+...”.
lApagar Habilita deletar linhas do aCols. Valor padrão falso.
aAlter Vetor com os campos que poderão ser alterados.
Habilita validação da primeira coluna do aCols para esta não
lVazio
poder estar vazia. Valor padrão falso.
nMax Número máximo de linhas permitidas. Valor padrão 99.
cCampoOk Função executada na validação do campo.
Função executada quando pressionada as teclas
cSuperApagar
<Ctrl>+<Delete>.
Função executada para validar a exclusão de uma linha do
cApagaOk
aCols.
oWnd Objeto no qual a MsGetDados será criada.

/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ OBJ_MOD3 ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Modelo 3 OOP. º±±
±±º ³ º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function MOD3EXEC(_cAlias, _nRecNo, _nOpc)

Private nOpcA //Retorno da Enchoice Bar.
//Seleciona area
dbSelectArea("SZ1") //Cabeçalho
dbSetOrder(1) //Filial + Codigo
//Cria as variaveis de memoria da enchoice

RegToMemory(_cAlias, If(_nOpc==3, .T., .F.))
//Cria as caixa de diálogo principal

_oDlg:bInit := EnchoiceBar(_oDlg, {|| nOpcA:=1, If(U_MOD3TUDOK(), _oDlg:End(),;
nOpcA := 0)}, {|| _oDlg:End()})
//Cria os campos da enchoice.

Zero()
_oEnc := MsMGet():New(_cAlias, _nRecno, _nOpc,,,,,{012,000,070,345},,2,,,, _oDlg)
//Carrega as matrizes aHeader e aCols.

MONTAHEADER(_nOpc)
//Monta a estrutura da getdados.

_oGet1 := MsGetDados():New(70, 001, 210, 345, _nOpc,,,,.T.,,,,,,,,,_oDlg)
_oDlg:Activate()
//Se incluiu ou alterou algum registro, faz a gravação.

If nOpcA == 1 .and. (_nOpc == 3 .or. _nOpc == 4 .or. _nOpc == 5)
BeginTran()
ATUAMOD3(_nOpc)
EndTran()
Else
RollBackSX8()
EndIf
Return

A função MOD3EXEC() cria uma caixa de diálogo e dentro dela monta o modelo3.
Na inicialização da janela, é chamada no método oDlg:bInit a função EnchoiceBar,
que será responsável pela criação dos botões de confirmação e cancelamento, além
de realizar a validação do modelo3 geral. O segundo parâmetro identifica se foi
confirmada a operação do usuário e dispara a rotina U_MOD3TUDOK(), cujo
retorno dever ser .T. ou .F. dependendo da validação. Caso .F., não deixa encerrar a
tela até que o usuário corrija os campos errados ou em branco.
Subseqüentemente é chamada a classe MSMGET, que irá trazer os dados do
arquivo de cabeçalho na tela. Antes de chamar a classe MSGETDADOS, a rotina
MONTAHEADER é executada para carregar os dados dos vetores aHeader e
aCols.
/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³MONTAHEADERº Autor ³ Organon TI º Data ³ 24/07/2003 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Rotina para criar as matrizes aHeader e aCols da GetDados. º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºUso ³ Apx / MPx º±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
Static Function MONTAHEADER(_nOpc)
Local _nUsado := 0
Local _cNum := ""
aHeader := {}
aCols := {}
//Monta o aHeader.
_nUsado := 0
dbSelectArea("SX3")
dbSetOrder(1)
dbSeek("SZ2")
While !EOF() .and. SX3->X3_ARQUIVO == "SZ2"
If X3USO(SX3->X3_USADO) .and.;
cNivel >= SX3->X3_NIVEL .and.;
AllTrim(X3_CAMPO) <> ("Z2_CODIGO")
AADD(aHeader, {Trim(X3TITULO()),;
SX3->X3_CAMPO ,;
SX3->X3_PICTURE ,;
SX3->X3_TAMANHO ,;
SX3->X3_DECIMAL ,;
SX3->X3_VALID ,;
SX3->X3_USADO ,;
SX3->X3_TIPO ,;
SX3->X3_ARQUIVO ,;
SX3->X3_CONTEXT })
_nUsado++
Endif
dbSkip()
EndDo

//Monta o aCols.
//Opcao Inclui.
If _nOpc == 3
For x := 1 to Len("SZ2")
_nUsado := Len(aHeader)
aCols := {Array(_nUsado + 1)}
aCols[1, _nUsado + 1] := .F.
For y := 1 to _nUsado
aCols[1, y] := CriaVar(aHeader[y, 2], .F.)
Next y
Next x
//Monta o aCols.
//Visualiza, Altera e Exclui.
Else
_nUsado := Len(aHeader)
dbSelectArea("SZ2")
dbSeek(xFilial("SZ2") + M->Z1_CODIGO)
If Found()
While SZ2->Z2_CODIGO == M->Z1_CODIGO .and. !EOF()
AADD(aCols, Array(_nUsado + 1))
aCols[Len(aCols), y] := FieldGet(FieldPos(aHeader[y, 2]))
Next
aCols[Len(aCols), _nUsado + 1] := .F.
dbSkip()
EndDo
//Se nao encontrar nenhum reg., abre um aCols em vazio apenas para exibir.
Else
nUsado := Len(aHeader)
aCols := {Array(_nUsado + 1)}
aCols[1, _nUsado + 1] := .F.
aCols[1, y] := CriaVar(aHeader[y, 2], .F.)
Next y
EndIf
EndIf
Return

A função MONTAHEADER irá verificar qual foi a opção selecionada pelo usuário.
Caso tenha escolhido inclusão, abre um aCols com um registro em branco. Nos
demais casos irá varrer a tabela de itens e irá armazenar em sua matriz como se
fosse um filtro. Os dados poderão ser alterados dependendo da operação e
conseqüentemente o processo inverso deverá ser feito para atualizar a tabela. A
rotina responsável por essa ação é a ATUAMOD3.
/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ ATUAMOD3 º Autor ³ Organon TI º Data ³ 24/07/2003 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Rotina para gravar os dados da enchoice e das getdados do º±±
±±º ³ modelo3. º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
Static Function ATUAMOD3(_nOpc)
Local _cVar
Local bCampo := {|nCPO| Field(nCPO)}
//Inicia alterações no cabecalho.

³
dbSelectArea("SZ1")
If _nOpc == 3
RecLock("SZ1", .T.)
Else
RecLock("SZ1", .F.)
EndIf
//Se estiver incluindo ou alterando grava o cabecalho (SZ1).

If _nOpc == 3 .or. _nOpc == 4
For x := 1 to FCount()
If "FILIAL" $ Field(x)
FieldPut(x, xFilial("SZ1"))
Else
FieldPut(x, M->&(EVAL(bCampo, x)))
EndIf
Next x
//Se nao estiver incluindo ou alterando exclui o cabecalho (SZ1).

Else
dbDelete()
EndIf
MsUnlock()
//Se estiver alterando, apaga os detalhes e cria novamente conforme aCols.

//Se for exlusao, apenas apaga.
dbSelectArea("SZ2")

dbSeek(xFilial("SZ2") + SZ1->Z1_CODIGO)
While SZ2->Z2_CODIGO == SZ1->Z1_CODIGO
RecLock("SZ2", .F.)
dbDelete()
MsUnlock()
dbSkip()
EndDo
EndIf
//Se estiver incluindo ou alterando, grava os Itens das GetDados.

For y := 1 to Len(aCols)
If aCols[y][Len(aCols[y])] == .F.
RecLock("SZ2", .T.)
FieldPut(FieldPos("Z2_FILIAL"), xFilial("SZ2"))
FieldPut(FieldPos("Z2_CODIGO"), M->Z1_CODIGO)
For z := 1 to Len(aHeader)
FieldPut(FieldPos(aHeader[z, 2]), aCols[y, z])
Next z
MsUnlock()
EndIf
Next y
EndIf
Return
Por último deve ser desenvolvida a rotina de validação geral do modelo3. Nessa
rotina poderemos validar qualquer informação da janela, sempre observando o
retorno com valor lógico. Se retornar .F., a janela não encerrará até que o usuário
corrija as informações de acordo com a regra da função.
/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ MOD3TUDOK º Autor ³ Organon TI º Data ³ 24/07/2003 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Validação geral do modelo 3. º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
User Function MOD3TUDOK()
//Inclua aqui as validações da tela modelo 3.
Return(.T.)

Sintaxe da Classe MSGETDB

Objeto tipo lista com uma ou mais colunas para cadastramento de dados baseado
em uma tabela temporária.
A tabela temporária utilizada pela MsGetDB deverá ser criada com base no
aHeader mais um último campo tipo lógico que determina se a linha foi excluída.
A MsGetDB cria a variável publica nBrLin que indica qual a linha posicionada do
aCols.
As funções passadas como parâmetro para a MsGetDB (cLinhaOk, cTudoOk, ...)
não poderão ser declaradas como Static Function.
A consulta padrão, validação do usuário e gatilhos estarão habilitados se o campo
estiver cadastrado no Dicionário de Dados (SX3/SX7) e apresentar estas opções
disponíveis.
MSGETDB():NEW( nSuperior, nEsquerda, nInferior, nDireita, nOpc, [

cLinhaOk ], [ cTudoOk ], [ cIniCpos ], [ lApagar ], [ aAlter ], [
nCongelar ], [ lVazio ], [ uPar1 ], cTRB, [ cCampoOk ], [ lCondicional ],
[ lAdicionar ], [ oWnd ], [ lDisparos ], [ uPar2 ], [ cApagarOk ], [
cSuperApagar ] ) -> objeto
Argumentos Descrição
Distancia entre a MsGetDB e o extremidade superior do objeto
nSuperior
que a contém.
Distancia entre a MsGetDB e o extremidade esquerda do objeto
nEsquerda
que a contém.
Distancia entre a MsGetDB e o extremidade inferior do objeto
nInferior
que a contém.
Distancia entre a MsGetDB e o extremidade direita do objeto
nDireita
que a contém.
Posição do elemento do vetor aRotina que a MsGetDB usará
nOpc
como referência.
Função executada para validar o contexto da linha atual do
cLinhaOk
aCols.
Função executada para validar o contexto geral da MsGetDB
cTudoOk
(todo aCols).
Nome dos campos do tipo caracter que utilizarão incremento
cIniCpos automático. Este parâmetro deve ser no formato “+<nome do
primeiro campo>+<nome do segundo campo>+...”.
lApagar Habilita a opção de deletar linhas do aCols. Valor padrão falso.
aAlter Vetor com os campos que poderão ser alterados.
nCongelar Indica qual coluna não ficara congelada na exibição.
Habilita validação da primeira coluna do aCols para esta não
lVazio
poder estar vazia. Valor padrão falso.


cTRB Alias da tabela temporária.
cCampoOk Função executada na validação do campo.
lConditional Reservado
Indica se a MsGetDB ira criar uma linha em branco
lAdacionar
automaticamente quando for inclusão.
oWnd Objeto no qual a MsGetDB será criada.
Indica se será utilizado o Dicionário de Dados para consulta
lDisparos
padrão, inicialização padrão e gatilhos.
Função executada para validar a exclusão de uma linha do
cApagarOk
aCols.
Função executada quando pressionada as teclas
cSuperApagar
<Ctrl>+<Delete>.

Criação de relatórios com qualidade gráfica

Classe TMSPRINTER
A Classe TMSPRINTER inovou a maneira de produzir relatórios com o ADVPL.

Na programação estruturada os relatórios são impressos em formato texto, com
layout simples. Isso pode ser um problema uma vez que podem surgir
necessidades de implementações com qualidade gráfica superior, formulários com
layout avançado, inclusão de imagens etc. Para resolver essa questão, utilizaremos
a classe TMSPRINTER.
Sintaxe da Classe TMSPRINTER
[ <oPrn> := ] TMSPrinter():New()
Principais métodos da classe TMSPRINTER
StartPage Inicia uma nova página.

SetPortrait Ajusta relatório no padrão retrato.
SetLandscape Ajusta relatório no padrão paisagem.
IsPrinterActive Verifica se a impressora está ativa.
Preview Exibe o gerenciador de impressão e o relatório em vídeo.
Print Direciona a impressão direto para a impressora.
Setup Abre a caixa de setup de impressoras.
EndPage Encerra a página.
Principais métodos para impressão de dados
Say
Exibe um texto no relatório.
[ <oPrn> := ] TMSPrinter():Say(nLin, nCol, cTexto, oFont, nTam)
nLin Linha inicial.

cTexto Texto a ser impresso.
oFont Define a fonte do texto impresso.
nTam Tamanho do texto.

SayBitmap
Exibe um bitmap no relatório.
[ <oPrn> := ] TMSPrinter():SayBitmap(nLin, nCol, cBitmap, nWidth, nHeight)
nLin Linha inicial.

cTexto Nome do bitmap a ser impresso.
nWidth Largura do bitmap.
nAlatura Altura do Bitmap.
Box
Imprime uma caixa no relatório.
[ <oPrn> := ] TMSPrinter():Box(nLin, nCol, nWidth, nHeight)
nLin Linha inicial.

nWidth Largura da caixa.
nAlatura Altura da caixa.
Line
Imprime uma linha no relatório.
[ <oPrn> := ] TMSPrinter():Line(nLin, nCol, nWidth, nHeight)
nLin Linha inicial.

nWidth Largura da caixa.
nAlatura Altura da caixa.

Código fonte exemplo para impressão de relatórios com qualidade gráfica

/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ OBJ_PRN º Autor ³Organon TI Consultoriaº Data ³ 16/04/04 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Exemplo de impressão de relatório OOP gráfico. º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
User Function OBJ_PRN()
Local oFont1 := TFont():New("Arial",09,08,,.F.,,,,,.F.)

Local oFont2 := TFont():New("Arial",09,12,,.F.,,,,,.F.)
Local oFont3 := TFont():New("Arial Black",09,16,,.T.,,,,,.F.)
local oFont4 := TFont():New("Arial",09,12,,.T.,,,,,.F.)
Local oFont5 := TFont():New("Courier New",09,18,,.T.,,,,,.F.)
Local oFont6 := TFont():New("Courier New",09,14,,.T.,,,,,.F.)
Local oPrint
//Carrega classe de impressão

oPrint := TMSPrinter():New()
oPrint:StartPage()
oPrint:Box(0040,0040,0660,1400)
oPrint:SayBitmap(0050,0050,"LogoGM.bmp", 0200, 0200)
oPrint:Say(0060,0280,"Teste de impressão de relatório",oFont1,100)
oPrint:EndPage()
oPrint:Preview()
Return

Rotinas de Web
Envio de e-mail pelo sistema (Send Mail) através de SMTP
O ADVPL possui rotinas de envio de e-mail através de SMTP. Esse recurso pode
ser muito útil para envio de informações do sistema pela web. Basicamente o envio
de e-mails é feito por três funções básicas. Durante o envio, temos a opção de
enviar ainda arquivos anexos, com cópia e cópia oculta. Também podemos
selecionar o tipo de corpo de mensagem, HTML ou texto.
Função para conectar-se ao servidor
[<lResult>:=]MailSmtpOn( <cServer>, <cUser>, <cPass>, <nTimeOut> )
cServer Endereço IP do servidor.

cUser Usuário para autenticação.
cPass Senha de autenticação.
nTimeOut Time out.
Função para envio da mensagem
[<lResult>:=]MailSend( <cFrom>, \{ <aTo> \}, \{ <aCc> \}, \{ <aBcc> \},

<cSubject>, <cBody>, \{ <aFiles> \}, <.lText.> ) ; ;
cFrom E-mail do remetente.

aTo Array contendo todos os destinatários.
aCc Array contendo destinatários a copiar.
aBcc Array contendo destinatários a copiar modo oculto.
cSubject Assunto da mensagem.
cBody Corpo da mensagem.
aFiles Array contendo nome dos arquivos anexos.
lText (.T./.F.) Modo do corpo da mensagem, .T. - texto, .F. – HTML.
Função para desconectar-se do servidor
[<lResult>:=]MailSmtpOff()

Código fonte exemplo para envio de e-mails pelo sistema

/*
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ÉÍÍÍÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÑÍÍÍÍÍÍÍÍÍÍÍÍÍ»±±
±±ºPrograma ³ OBJ_EML º Autor ³Organon TI Consultoriaº Data ³ 16/04/04 º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ºDesc. ³ Exemplo de envio de e-mail pelo sistema. º±±
±±ÌÍÍÍÍÍÍÍÍÍÍØÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¹±±
±±ÈÍÍÍÍÍÍÍÍÍÍÏÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ¼±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
*/
User Function OBJ_EML()
Local lResult
Local cBody := '<p><font face="Arial">Teste de envio de e-mail...</font></p>'
//Conecta com o servidor SMTP na conta especificada

lResult := MailSmtpOn("200.157.215.4","organon@organon-ti.com.br","XXXXXX",100)
If !lResult
MsgInfo("Não foi possível conectar-se ao servidor SMTP...","Atenção")
EndIf
//Envia o e-mail
lResult := MailSend("organon@organon-ti.com.br",{"info@organon-ti.com.br"},{""},{""},;
"Teste de envio de email",cBody,,.F.)
If !lResult
MsgInfo("Não foi possível enviar a mensagem para a conta especificada...","Atenção")
EndIf
//Desconecta do servidor SMTP

lResult := MailSmtpOff()
If !lResult
MsgInfo("Erro ao tentar desconectar-se do servidor SMTP...","Atenção")
EndIf
Return

Workflow
Objetivos
O objetivo principal desta ferramenta é automatizar os processos, principalmente

através do envio e resposta de e-mails, que usualmente são realizados
manualmente no dia a dia de uma empresa. Chamamos de Processo toda e
qualquer operação que possa ser realizada dentro do sistema de ERP da
Microsiga e que possa ser automatizado.
O Workflow permite controlar não somente o envio de mensagens, mas
também o retorno/resposta delas, assim como rastrear individualmente cada
processo e atualizar a base de dados do Apx/MPx. Além disto, é possível agendar
tarefas a serem executadas em períodos determinados pelo usuário. Através da
análise minuciosa do processo como um todo, é possível automatizar boa
parte dele através de programação em ADVPL, a linguagem utilizada para
construir funções para o Apx/MPx.
Requisitos
• Para poder construir um processo de Workflow que automatize de

forma correta uma rotina, são necessários basicamente três requisitos
fundamentais:
• Conhecer o sistema de ERP como um todo, inclusive tecnicamente. Isto

corresponde a conhecer todos os recursos de configuração e programação
do Apx/MPx, bem como suas tabelas e respectivos relacionamentos;
• Saber programar em linguagem ADVPL, nível avançado, com conhecimento

em objetos e classes;
• Conhecimento em linguagem HTML, para construção de páginas, além de

saber programar em Java Script, para refinamento e validação das
páginas.
Software Necessário para Instalação
O Workflow, como é uma ferramenta embutida dentro do Server do Apx/MPx,

não necessita de nenhuma instalação própria, apenas configurações. Toda
configuração se dá através do Módulo Configurador do Apx/MPx.

Servidor de E-mail.
O Workflow necessita obter acesso à algum servidor de email. Este servidor pode
estar em um provedor remoto, acessado através de um proxy server ou através de
uma linha discada(totalmente não recomendável), caso queira enviar emails
para fora da sua empresa. Caso a troca de emails seja simplesmente interna,
poderá ser utilizado um Exchange Server, Lotus Domino Server ou outro servidor
de email interno. O único requisito imprescindível é que estes servidores
trabalhem com protocolos SMTP e POP3.
Conta de E-mail
O Workflow necessita que seja criada uma conta de e-mail especificamente para
ele. Isto é, não poderá ser utilizada para mais nenhum fim.
Peça para o seu provedor criar esta nova conta. Sugerimos como nome da conta
Workflow. Exemplo : workflow@seudominio.com.br
Clientes de E-mail
Para recebimento dos emails gerados a partir do Workflow são utilizados os

clientes de emails. Estes clientes de email devem ser aptos a responder os emails
gerados pelo Workflow, gerando arquivos de retorno chamados octetos. Para
saber se o cliente de email é compatível com o Workflow, o mesmo, ao responder
ao email enviado pelo Workflow, não deverá abrir nenhuma tela de reply deste
email, além de enviar a resposta como um simples email.
Os seguintes clientes de email funcionam com o Workflow: OutLook Express

4.01, OutLook Express 5.5x e OutLook 2000. Outros clientes podem não
funcionar. Portanto, garanta que as pessoas que irão receber os emails e
necessitem respondê-los, deverão ter os clientes acima instalados nas suas estações.
Parâmetros de Configuração
Inicialmente será necessário configurar alguns parâmetros dentro do Módulo

Configurador. Os parâmetros a serem configurados são:
MV_WFACC Informe o nome da conta de e-mail do Workflow (ex: workflow).

MV_WFDIR Informe o nome do diretório de trabalho do Workflow. Este
diretório será criado embaixo do diretório raiz do Apx / MPx.
(ex:\workflow).
MV_WFMAIL Informe neste campo o endereço da conta de workflow (ex:
workflow@microsiga.com.br).
MV_WFPASSW Senha da Conta do Workflow : Informe a senha da conta

informada em
MV_WFMAIL.
MV_WFPOP3 Informe o endereço do servidor Pop3 (ex:
pop.microsiga.com.br).
MV_WFSMTP Informe o endereço do servidor SMTP (ex :

smtp.microsiga.com.br).
MV_WFPROT Protocolo de e-mail utilizado para o Workflow. Deve ser 1,
indicando
Pop3. Servirá para futuras implementações de outros protocolos.
MV_WFREMT Nome do remetente do workflow. Informe um nome para
caracterizar mensagens vindas do Workflow (ex: Workflow).
MV_WFREMET Nome do remetente do workflow. Informe um nome para
caracterizar mensagens vindas para o Workflow (ex:
Workflow).
MV_WFATTHT Indica se o HTML do e-mail virá atachado ou no corpo do e-mail
(Vazio).
MV_WFTCONN Indica o tempo(em seg.) de espera para uma nova tentativa de
conexão com os servidores POP/SMTP.
MV_WFENVJA Indica se a mensagem será enviada imediatamente após o
início do Processo ou em Batch, através de agendamento.
MV_WFUSEJS Indica se os HTMLs usam ou não Java Script.
MV_WFAUTUP ndica se os processos que foram paralisados por alguma
razão serão automaticamente reiniciados.
MV_WFTTS Utiliza ou não controle de transação nas funções do usuário.
MV_WFMAILT Informe o email do administrador, que será informado de
eventuais problemas no Workflow.
MV_WFTPCON Indica o tipo de Conexão(Lan ou Dial UP).
Para configurar os parâmetros acima de forma mais rápida, basta entrar no

módulo Configurador, menu Ambiente -> Workflow -> Parâmetros WF.

Nome Informe um nome para o remetente da conta do workflow.

Poderá ser um nome qualquer que identifique que o email vem
do workflow.
Conta Informe o nome da conta criada para o workflow. Não é o
endereço, apenas o nome.
Senha Informe a senha para a conta acima.
Endereço Informe o endereço de email da conta de workflow.
T. Espera(segs) Informe o tempo de espera em segundos que o Workflow
tentará se conectar ao servidor POP e/ou SMTP.
Servidor Pop3 Informe o servidor POP3(nome ou endereço IP)
Porta Pop3 Informe a porta que é usada para o Pop3.
Servidor SMPT Informe o servidor SMTP(nome ou endereço IP)
Porta Smtp Informe a porta que é usada para o Smtp.
Dir. Trabalho Informe o diretório de trabalho do Workflow.
Protocolo Informe o nome do protocolo padrão a ser utilizado.
Html Informe se deseja se o HTML do email irá atachado ao mesmo
ou no corpo.
Envia Mensg Informe se os processos enviarão os emails ou isto será feito em
forma de batch.
Usa j. Script Ativa ou não a execução de código java nas páginas.
Reativar Procs Informe se deseja que o Workflow ative os processos que foram
interrom- pidos automaticamente ou não.
Usa transação ? Informe se as rotinas de retorno serão colocadas em transação
ou não.
Conexão Informe o tipo de conexão .

Mail Administr Informe uma conta de email que será notificada de eventos
acontecidos no Workflow. Por exemplo, erros em tempo de
execução(código errado) serão notificados.
Desenvolvimento
Possuindo todos os requisitos acima, pode-se então partir para a construção de um

processo de Workflow. Mostraremos neste capítulo quais os passos necessários
para a construção de um processo.
Construindo uma página HTML
Caso queira refinar seu e-mail, poderá inserir dentro dele uma página HTML,
criada por você. Isto não é imprescindível, pois você pode enviar um e-mail
contendo apenas texto. Entretanto, neste último caso, você não terá como controlar
a resposta deste, ou seja, seu processo será baseado apenas no envio de e-mail.
Você poderá construir a página HTML no FrontPage Professional,

preferencialmente. A única condição que você deverá seguir é colocar para
cada controle(ou objeto) o valor inicial(propriedade existente em cada objeto)
entre %(porcentagens) ou !(exclamação). Por exemplo para uma caixa onde será
colocado o Código do Pedido, o valor inicial deverá ser %CODIGO%. Outra ponto
é que, caso seja utilizada um objeto tipo TABELA, os valores iniciais de cada
coluna deve ser um índice. Por exemplo : %Produto.Quant%, %Produto.Valor%,
etc. Caso numa tabela seja necessário o input de dados, é necessário usar o caracter
porcentagem em vez da exclamação.
Note que caso você tenha conhecimentos de Java Script, você poderá
adicioná-los à sua página, para programar consistências em inputs de dados. Este
HTML não conterá nenhum dado do Apx / MPx. Será constituído somente do
layout que se deseja para o mesmo. Você poderá refiná-lo com imagens,
AVI’s, etc. Basta somente obedecer as regras citadas acima.
Caso seu HTML tenha um retorno, ele deverá ter na propriedade Action a string
‘mailto:%WFMailTo%’ e a propriedade Method deverá estar setada como POST.
Estas propriedades são do formulário.
Criando seu Ponto de Entrada
Os processos do Workflow podem iniciar através de um modo automático, através

de um agendamento, que será mostrado mais adiante, ou através de um ponto de
entrada dentro do Apx / MPx. Um ponto de entrada é uma função do usuário que
é executada após determinada ação em um processo. Estes pontos de entrada

hoje são fixos no Apx/MPx. Caso seja necessário criar mais de um ponto, será
necessário contactar o setor de desenvolvimento.
A programação do Ponto de Entrada é toda feita em ADVPL. Para se ativar o

Workflow neste ponto de entrada é necessário incluir algumas funções
específicas do mesmo. Estas funções diferem um pouco da tradicional
programação ADVPL, pois passamos a trabalhar com classes e objetos, ao invés de
simples variáveis e funções.
Mostraremos as funções existentes para que se possa fazer uma função para um
processo de Workflow. Note que você deverá ter ótimas noções de
programação ADVPL para entender as funções abaixo.
O principal objeto a ser criado é o objeto do Processo, que chamaremos de

oProcess. Dentro dele existe a propriedade que representa o HTML deste
processo, que chamaremos de ohtml. A seguir, apresentamos uma lista de todos os
métodos do objeto.
Criação do Processo
Sintaxe: TWFProcess():New(Código do processo, Descrição do processo)
Ex: oProcess := TWFProcess():New( “PEDCOM”, “Pedido de Compras” )

Informando o HTML e o código do processo que compõem este Processo. Sintaxe :
oProcess:NewTask(Código Processo, Caminho do HTML). O Arquivo HTML
deverá estar abaixo do Root Path do Apx / MPx.
Ex: oProcess:NewTask(‘Inicio’,”\workflow\WF_450A.htm”)
Definindo o Assunto do E-mail (propriedade cSubject)

Ex: oProcess:cSubject := “Aprovacao de Pedido de Compra” Definindo o(s)
Destinatário(s) do E-mail (propriedade cTo) Ex: oProcess:cTo :=
aprovador1@company.com
Definindo o(s) Destinatário(s) com cópia do E-mail (propriedade cCC)

Ex: oProcess:cCC := aprovador2@company.com
Definindo o(s) Destinatário(s) com cópia oculta do E-mail (propriedade cBCC)

Ex:oProcess:cBCC := aprovador2@company.com;aprovador3@company.com

Definindo o HTML no corpo da mensagem

Ex: oProcess:cBody := “Seu pedido número 120 foi aprovado” Definindo a
Função ADVPL de Retorno (propriedade bReturn). Esta função será executada
quando o Workflow receber o e-mail de resposta de um dos destinatários
informados nas propriedades acima.
Ex: oProcess:bReturn := “U_WFW120P( 1 )”
Definindo a Função de TimeOut (propriedade bTimeOut)

Esta função será executada quando o tempo limite de resposta for alcançado.
No exemplo abaixo, a função U_WFW120P será executada após 2 dias, 5
horas e 50 minutos do e-mail inicial ter sido enviado e o mesmo não ter sido
respondido. Note que a propriedade recebe um array de funções, isto é, você
pode programar várias funções de TimeOut.
Ex: oProcess:bTimeOut := {{“U_WFW120P(2)”,2, 5, 50 }}
Indicando um valor para um controle do HTML, que não esteja em uma tabela da
página HTML. No exemplo abaixo, EMISSAO corresponde à um objeto do HTML
cuja propriedade valor inicial seria %EMISSAO%. Sintaxe: ValByName(Nome
Objeto, valor)
Ex: oProcess:oHtml:ValByName( “EMISSAO”, SC7->C7_EMISSAO ) Indicando o

valor de um controle dentro de uma tabela no HTML. No exemplo abaixo,
produto.item corresponde à um objeto da tabela no HTML cuja propriedade valor
inicial seria %produto.item%. Repare que a tabela é controlada por um array.
Sintaxe: aadd(oProcess:oHtml:ValByName(Nome Objeto), valor)
Ex: aadd((oProcess:oHtml:ValByName( “produto.item” )),C7_ITEM ) Anexando
um arquivo qualquer no e-mail a ser enviado. Repare que o arquivo deve estar
abaixo do Root Path do Apx/MPx.
Ex: oProcess:AttachFile(“\SIGAMAT\SIGACOM.MNU”)
Iniciando o Processo
Ex: oProcess:Start()
Pegando o valor de retorno de um objeto dentro do HTML

Sintaxe: oProc:oHtml:RetByName(Nome do objeto)
Ex: oProc:oHtml:RetByName(“Aprovacao”)
Finalizando o Processo.
Ex: oProcess:Finish()

Após a criação do HTML e do Ponto de entrada, o processo de Workflow estará

criado.
Para mandar e receber os e-mails dos processos, utilize as funções embutidas

dentro do Apx/MPx.
Ativando o Workflow
Como o Workflow é uma ferramenta embutida dentro do Apx/MPx, bastam

algumas configurações no APxSrv.ini / MPxSrv.ini para ativá-lo. Inicialmente,
devemos criar uma função que ative o agendamento de funções(que veremos
mais abaixo). A função deverá ser :
USER FUNCTION INITSCHED()
Local aParams := {‘99’,’01’} //Coloque aqui o código da empresa e filial.

WFScheduler(aParams) Return .T.
Esta função inicia um Job que fica verificando se existem agendamentos a serem
executados. Compile o programa no seu RPO.
Acrescente no APxSrv.Ini / MPxSrv.ini as seguintes linhas :
[ONSTART]
jobs=ScheduleWF
[ScheduleWF] Main=U_INITSCHED
Environment=Environment (Coloque aqui o seu Environment)
As linhas acima indicam que sempre que o servidor do Apx / MPx for iniciado, ele
irá executar as funções contidas em cada job. Você poderá iniciar várias
funções ao mesmo tempo.
Feito isto, basta agendarmos no Agendamento(módulo Configurador ->

Ambiente -> Workflow -> Agendamento) a função WFRETURN(“99”,”01”), onde
os dois parâmetros indicam empresa e filial. Esta função do Workflow faz a leitura
da caixa postal e processa os retornos dos processos, setados na propriedade
bReturn.
Pare e reinicie o serviço do Workflow para as alterações acima terem efeito.

Agendando o Envio de Emails
Caso o parâmetro MV_WFENVJA esteja com False, é necessário agendar uma

função do Workflow para o envio das mensagens em determinado período
desejado. A função a ser agendada será a WFSENDMAIL(empresa, filial).
Rastreabilidade
Uma outra característica do Workflow é a possibilidade de se rastrear os

processos. Isto significa que a qualquer momento o usuário pode saber onde se
encontra, por exemplo, o pedido de compras que foi enviado para aprovação
de um gerente e ele ainda não obteve resposta.
Inicialmente devem ser cadastrados:
Processos: É necessário fazer o cadastro do Processo a ser rastreado. Opção

encontrada no Módulo Configurador - Ambiente->Workflow->Processos.
Informe o Código do Processo e uma descrição para o mesmo. Processos que
podem ser cadastrados, por exemplo: Liberação de Pedido de Compras,
Geração de Cotação para Fornecedores, Liberação de Pagamento, Liberação de
Crédito, etc.
Status: Para cada processo o usuário pode definir Status. Status nada mais é do
que um informativo sobre a situação do processo naquele momento. Opção
encontrada no Módulo Configurador - Ambiente->Workflow->Status. Você
deve cadastrar para cada Status de um Processo, um código cujo valor seja maior
que 1000. Valores abaixo deste número são usados pelo Apx / MPx.
Após serem feitos os cadastros acima, pode-se partir para a consulta de

rastreabilidade. Opção encontrada nos módulos do Apx / MPx em Miscelânea->
Workflow->Rastreabilidade WF. Para cada processo iniciado no Workflow, é
gerado um código que chamamos de ID. Por exemplo para o processo de
aprovação do Pedido de número 1020 é gerado um ID de número, por
exemplo, 03001. Este ID é único e identifica este pedido. Neste exemplo ele deverá
ser gravado no arquivo SC7, em algum campo criado pelo usuário. Esta gravação
deverá ser feita no Ponto de entrada. Mas como saber como pegar este ID? O objeto
oProcess contém uma propriedade chamada fProcessID cujo conteúdo é o ID do
processo iniciado.
Além de gravar este ID na tabela de compras (no exemplo citado acima), é

necessário gravar a rastreabilidade, através da função RastreiaWF(ID do
processo, Código do Processo, Código do Status, Descrição, Usuário), que fará o

Log da rastreabilidade. Portanto, coloque esta função nos trechos do Ponto de

Entrada que deseja rastrear.
Nesta tela de rastreabilidade você deve informar o ID do processo e ele

mostrará todo o andamento do mesmo, inclusive com data e hora do
acontecimento e também o intervalo de tempo entre um status e outro.
Um outro tipo de consulta existente no Apx / MPx para o Workflow é os processos

existentes por usuário. Com isto, o usuário pode ver quais processos estão em
aberto ou não, ou seja, quais e-mails ele necessita responder. Opção encontrada
nos módulos do Apx / MPx em Miscelânea-> Workflow-> Processos do
Usuário. O que estiver em vermelho indica processo pendente, aguardando
resposta. Os processos em verde já foram respondidos.
Outros Exemplos de Uso do Workflow
Além de automatizar vários processos manuais que hoje existem no Apx/MPx, o

uso do Workflow pode se estender nas seguintes aplicações:
• Agendamento de Execução de tarefas (rotinas em batchs, por exemplo). Um

exemplo, é agendar para a noite a execução de um recálculo de estoque, que
poderá demorar horas. Com isto, nenhum usuário precisa monitorar a
execução desta tarefa, que poderá ser executada de tempos em tempos.
Isto pode ser feito através da opção de agendamento de tarefas, existente no

Módulo Configurador -> Ambiente -> Workflow -> Agendamento. Nesta tela
você poderá agendar a execução de funções contidas no RPO do Apx / MPx,
podendo estas execuções serem diárias, semanais (você especi- fica em que dias da
semana será executada a tarefa) e mensais (que dias do mês será executada a
função), tudo dentro de um período de dias e horas pré-estabelecido. Você
deverá informar o ambiente em qual a função será executada.
Informe nesta tela:
Código
Código que identificará o agendamento.
Nome
Identificador do agendamento.
Descrição
Descrição do agendamento.
Tipo
Informe qual o tipo do agendamento:
• Diário: O agendamento será disparado todo dia, no período informado.
• Semanal: O agendamento será disparado durante certos dias da semana

(Segunda, Terça, etc).
• Mensal: O agendamento será disparado em apenas alguns dias do Mês(1,

30, etc).
Data Início
Informe a partir de que data o agendamento será iniciado.
Hora Início
Informe o horário inicial da execução do agendamento.
Data Final
Informe até qual data este agendamento será válido.
Hora Final
Informe o horário final da execução do agendamento.
Intervalo
Informe o intervalo entre o Horário Inicial e Final que será executado o
agendamento.
Se o tipo for Semanal

Informe os dias da semana. Se o tipo for Mensal Informe os dias do mês.
Ação
Informe a função a ser disparada, com seus parâmetros.

Environment
Informe em qual ambiente do Apx / MPx a função está.
Toda e qualquer função disparada de dentro do Agendamento não pode ter

nenhum comando de tela. Além disto, deverá abrir todo o ambiente do Apx /
MPx (dicionários, variáveis, etc). Para isto, sua função deverá ter
na primeira linha o seguinte comando :
Prepare Environment Empresa ‘XX’ Filial ‘YY’ Tables ‘SA1’,‘SD2’
Onde,
XX = Código da Empresa
YY = Código da Filial
Informe após a cláusula Tables os Alias das tabelas a serem abertas,
separados por vírgulas.
Inclua no seu programa a linha #include ‘tbiconn.ch’
Troca de arquivos entre diferentes localizações. Isto é frequente quando matriz e

filiais precisam se comunicar através da troca de arquivos de movimentação
diária. Com isto, o workflow poderá enviar e receber, através de e-mails,
arquivos anexados ao mesmo, salvá-los em uma determinada localização e
executar funções do Apx / MPx que tratem estes arquivos.

Exemplo de Atualização de Preços
Neste exemplo, daremos todos os passos para a construção de um processo

simples de Workflow. O objetivo deste Workflow é fazer que a cada inclusão de
um produto uma pessoa deverá receber um email contendo o código e descrição
deste produto e deverá informar neste email o valor de venda deste produto. Após
a resposta deste usuário, o Apx / MPx atualizará a base de dados do Apx / MPx.
Construindo o HTML
Para este exemplo, faremos um HTML muito simples. O mesmo foi feito no
FrontPage Express. Abaixo segue o código do HTML(Grave-o com o nome de
Curso.HTM, em um diretório abaixo do RootPath chamado Workflow.) :
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Favor atualizar o preco deste produto</title>
</head>
<body>
<form action="mailto:%WFMailTo%" method="POST" name="FrontPage_Form1">
<p>Favor atualizar o preco deste produto</p>
<p>Data: %DATA%</p>
<table border="2">
<tr>
<td width="100">Codigo</td>
<td width="200">Descricao</td>
<td width="120">Preco de venda</td>
</tr>
<tr>
<td>%TB.CODIGO%</td>
<td><input type="text" size="20" name="%TB.DESCRICAO%" value="%TB.DESCRICAO%"></td>
<td><input type="text" size="16" name="%TB.PRECO%" value="%TB.PRECO%"></td>
</tr>
</table>
<p><input type="submit" name="B1" value="Enviar"></p>
</form>
</body>
Repare que no código acima existe o trecho mailto:%WFMailTo%, que teve que ser
incluído na mão.

Em alguns editores de HTML, ao gravar o mesmo poderá ser acrescentado o

número 25 no trecho acima: mailto:%25WFMailTo%25. Basta tirar estes
números.
Neste HTML temos quatro objetos que serão substituídos por dados do Apx /
MPx: DATA, TB.CODIGO, TB.DESCRICAO, TB.PRECO.
Neste exemplo, a tabela somente terá os dados de um só produto, mas poderia ter
mais. O código da página HTML permaneceria o mesmo.
Cadastrando Processos e Status.
Para podermos fazer uma rastreabilidade dos processos doWorkflow, devemos
cadastrar o processo e os Status deste processo.
Vamos cadastrar então o Processo em questão. No módulo Configurador, cadastre

o Processo com o Código PRECOS.
No mesmo módulo, cadastre dois Status para este processo : 10001, colocando a
descrição de ‘Email Enviado’ e o 10002, colocando a descrição de ‘Email
Respondido’.

Criando o Ponto de Entrada com o Processo do Workflow

Vamos então criar o ponto de Entrada que é disparado a cada inclusão de um
produto. O nome do ponto de Entrada é MT010INC. Comentaremos cada linha do
programa.
/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³ MT010INC ºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ Ponto de entrada chamado na confirmação do cadastro de produ- º±±
±±º ³ tos. Usado para disparar a rotina de atualização de precos. º±±
±±º ³ via workflow.
º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function MT010INC()
U_OTICADPRWF(0)
Return
Rotina de Exemplo de Envio e Retorno do workflow

/*
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
±±ºPrograma ³OTICADPRWFºAutor ³ Organon TI Consultoria º Data ³ 13/05/04 º±±
±±ºDesc. ³ tos. Usado para disparar a rotina de atualização de precos via º±±
±±º ³ workflow. º±±
±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±
*/
User Function OTICADPRWF(_nOpcao, oProcess)
If oProcess == Nil
Private oProcess := TWFProcess():New("CADPRO", "Cadastro de Produtos")
EndIf
If _nOpcao == 0
OTISTARTWF(oProcess)
ElseIf _nOpcao == 1
OTIRETWF(oProcess)
ElseIf _nOpcao == 2
OTITOUTWF(oProcess)
EndIf
oProcess:Free()
Return
Static Procedure OTIRETWF(oProcess)
//Obtem a resposta do usuário no HTML e atualiza o cadastro de produtos

dbSelectArea("SB1")
dbSetOrder(1)
dbSeek(xFilial("SB1") + oProcess:oHTML:RetbyName("TB.CODIGO")[1])
RecLock("SB1")
SB1->B1_PRV1 := Val(oProcess:oHTML:RetbyName("TB.PRECO")[1])
MSUnlock()

RastreiaWF(oProcess:fProcessID+'.'+oProcess:fTaskID,oProcess:fProcCode,'10002')
Return
Static Procedure OTISTARTWF(oProcess)
//Cria o novo processo do workflow

oProcess:NewTask("Precos","\Workflow\Curso.html")
oProcess:cSubject := "Atualizacao de Preço de venda"
oProcess:bReturn := "U_OTICADPRWF(1)"
oProcess:bTimeOut := {{"U_OTICADPRWF(2)",0,0,5}}
//Atualiza os campos no HTML a ser enviado no e-mail

oHTML := oProcess:oHTML
oHTML:ValByName("DATA", DDATABASE)
dbSelectArea("SB1")
AADD((oHTML:ValbyName("TB.CODIGO")), SB1->B1_COD)
AADD((oHTML:ValbyName("TB.DESCRICAO")), SB1->B1_DESC)
AADD((oHTML:ValbyName("TB.PRECO")), Transform(SB1->B1_PRV1,'@E 99,999.99'))
oProcess:cTo := "usuario@workflow.com"
oProcess:UserSiga := "000000"
RastreiaWF(oProcess:fProcessID+'.'+oProcess:fTaskID,oProcess:fProcCode,'10001')
RecLock("SB1")
SB1->B1_WFID := oProcess:fProcessID
MSUnlock()
//Inicia o processo
oProcess:Start()
Return(.T.)
Static Procedure OTITOUTWF()
Conout("Time out...")
Return
Configurando o ambiente do Apx / MPx para o Workflow.

Depois de ter criado o processo, devemos configurar o Apx / MPx para que
o agendamento passe a funcionar.
Inicialmente, crie a seguinte função :
User Function InitSched()
Local aParams := {“99”,”01"} //Passe aqui o código da Empresa e Filial

utilizadas
WFSCheduler(aParams) //Esta função inicia a função de Agendamento do

Apx / MPx.
Return .T.

Após criada esta função no repositório, vamos fazer com que ela seja iniciada
sempre que o servidor do Apx / MPx for iniciado. Para isto, basta
alterarmos o AP6Srv.Ini / MPxSrv.ini, incluindo as seguintes linhas:
[ONSTART]
jobs=ScheduleWF
[ScheduleWF] Main=U_INITSCHED
Environment=Environment (Coloque aqui o seu Environment).
Estas linhas fazem com que se execute as funções contidas em cada job. Nos
passos acima simplesmente criamos a função de agendamento e a colocamos
para ser iniciada automaticamente no server. Agora, devemos agendar a
função do Workflow que faz a verificação da caixa de entrada da conta criada para
ele. Esta função ao encontrar um email de um processo respondido, executa a
função de retorno do mesmo.
Entre no Módulo Configurador, na opção de Agendamento e agende a

função WFRETURN(‘xx’,yy’), onde xx é o Código da Empresa e yy o Código
da Filial.
Para estas configurações terem efeitos, pare e reinicie o servidor do Apx / MPx.

Idioma

ADVPL - OOP Organon

Enviado por

Dados do documento

Direitos autorais

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

ADVPL - OOP Organon

Enviado por

Direitos autorais:

Ewerton Alex Vicentin

2005 – Campinas – SP – Brasil

Oficina AdvPl Object Página: 3

Oficina AdvPl Object Página: 4

Quando criar um Ponto de Entrada................................................................................... 72

Principais propriedades de estilo de caixas de diálogo................................................. 89

Oficina AdvPl Object Página: 6

Principais métodos da classe TMSPRINTER ............................................................ 127

Oficina AdvPl Object Página: 7

O Objetivo principal desse material é fornecer subsídios para o programador

Nossa metodologia de trabalho consiste em apresentar de forma clara novas

Para que possamos obter o maior índice de aproveitamento, desenvolvemos

Os conceitos de funcionamento do sistema são importantes para que os

Seja bem vindo ao mundo dos programadores que fazem diferença!!!

O Que é Fazer um Programa com Inteligência

Segundo o dicionário Michaelis, inteligência significa:

Devemos estudar o programa antes de começar a desenvolver. Imagine prestar um

Fazer um levantamento dos programas que sofrerão as conseqüências das

Oficina AdvPl Object Página: 8

Antes de criar uma função, consulte o Guia Eletrônico Organon de AdvPl ou os

Ao criar uma função, certifique-se de que no cabeçalho conste algumas

Imagine se alguém desenvolver uma função inconsistente e esquecer de trocar o

Ao fazer a documentação das alterações realizadas, certifique-se de que as

Pode parecer um pouco trabalhoso passar por estes processos no decorrer do

Programando Simples, mas Certo

Um profissional da área de informática não possui nenhum modelo padrão para

Entender qual o objetivo do processo em questão

Erros que Podem ser Evitados

• Verifique se a variável está declarada antes do uso;

• Ao declarar uma variável, verifique qual a necessidade de ter essa variável e

• Classifiquem as funções e os procedimentos conforme a necessidade, como

• Evite retornar da função antes do seu final, ou seja, crie preferencialmente

• Valide sempre o retorno no caso de um do ponto de entrada;

• Quando for gravar um arquivo que utiliza campos de outros arquivos,

• Utilize de arquivo CH nas strings para localização;

• Quando possível utilize a linguagem SQL, pois minimiza o tempo de

A Importância de Programas Documentados

Oficina AdvPl Object Página: 10

E os cabeçalhos? Quantos programas são “aproveitados” e nem sequer o nome do

No IDE do PROTHEUS existem opções bastante interessantes para nos auxiliar

Existe ainda um tipo de documentação que nem sempre é observada, é aquela

Cabeçalho de Programa / Função

A manutenção/atualização do cabeçalho é de responsabilidade da última pessoa

Oficina AdvPl Object Página: 11

Padrão de Desenvolvimento – ORGANON TI Campinas

O tratamento do índice de usuário para tabelas padrão na rotina, ao invés do

Oficina AdvPl Object Página: 12

Sintaxes para cálculos:

_nCont := _nCont + 1 ou _nCont += 1 ou _nCont++ (incremento)

Oficina AdvPl Object Página: 13

Local _cCod910 := “001”

Oficina AdvPl Object Página: 14

isso, as funções podem não funcionar corretamente, embora funcionassem na

Para tanto, definimos a seguinte padronização :

Criando uma Variável Utilizando a Função CRIAVAR()

Oficina AdvPl Object Página: 15

_uRet ⇒ tipo de retorno de acordo com o dicionário de dados,

Declarando e utilizando vetores e matrizes

Onde: 5 = número de linhas

While !Eof() .and. _lCondicao

Oficina AdvPl Object Página: 16

Utilizando Estruturas de Controle

For _nContador := 1 To _nMaximo

Oficina AdvPl Object Página: 17

Este comando é igual ao item acima, no entanto, é geralmente utilizado em linhas

Agora que conhecemos os operadores lógicos , como devemos definir nossas