Você está na página 1de 67

Boas Prticas de Programao Advpl

Manual de Regras e Padronizao

Boas Prticas de Programao

Boas Prticas de Programao...........................................................................................................1


Para que padronizar?..........................................................................................................................6
Legibilidade de Cdigo........................................................................................................................7
Estrutura de um programa ........................................................................................................................ 7
rea de cabealho ....................................................................................................................................... 8
rea de Identificao .................................................................................................................................. 8
rea de Ajustes Iniciais .............................................................................................................................. 9
Corpo do Programa .................................................................................................................................... 9
rea de Encerramento................................................................................................................................ 9
Linhas de Comentrio............................................................................................................................... 10
Tamanho da Linha.................................................................................................................................... 11
Utilizao de Espaos em Branco ............................................................................................................ 11
No abreviar comandos ............................................................................................................................ 12
Utilizao de Identao............................................................................................................................. 12
Capitulao de Palavras-Chave ............................................................................................................... 13
Palavras em maisculo ............................................................................................................................. 14
Utilizao da Notao Hngara ............................................................................................................... 14
Nomeando um Cdigo Fonte.................................................................................................................... 15

Regras Bsicas de Programao ......................................................................................................16


Variveis .................................................................................................................................................... 16
Declarao.................................................................................................................................................. 16
Visibilidade ................................................................................................................................................ 16
Inicializao ............................................................................................................................................... 16
Funes....................................................................................................................................................... 17
Declarao.................................................................................................................................................. 17
Visibilidade ................................................................................................................................................ 17
Nomeando .................................................................................................................................................. 17
Palavras Reservadas ................................................................................................................................. 18
Gravando variveis ambientais ............................................................................................................... 19
Retorno de funes.................................................................................................................................... 19
Utilizando loops ......................................................................................................................................... 20
Loops Infinitos........................................................................................................................................... 20

Trabalhando com Dados...................................................................................................................21


Trabalhando com Registros ..................................................................................................................... 21
Como referenciar um campo.................................................................................................................... 21
Cuidados com Posicionamentos de Registros ......................................................................................... 21
dbSeek() ................................................................................................................................................................. 21

Boas Prticas de Programao

SoftSeek.................................................................................................................................................................. 21

Funes de Posicionamento Restritas...................................................................................................... 22


Funes de Procura................................................................................................................................... 22
Posicione() .............................................................................................................................................................. 22
ExistCpo() .............................................................................................................................................................. 22

Travamentos / Bloqueios / Locks ............................................................................................................. 23


RecLock(cAlias, lAppend) .................................................................................................................................... 23
MSUnlock(cAlias) ................................................................................................................................................. 23

Funes de Travamento Restritas ........................................................................................................... 24


DBRLock( [ recno ] )............................................................................................................................................. 24
DBRUnlock( [ recno ] ) ......................................................................................................................................... 24
MSRLock( [ recno ] ) ............................................................................................................................................ 24
MSRUnlock............................................................................................................................................................ 24
DBUnlock............................................................................................................................................................... 24
DBUnlockAll.......................................................................................................................................................... 24
MultLock( Alias, aChaves, nOrd )....................................................................................................................... 24
SoftLock ................................................................................................................................................................. 25
MSUnlockAll ......................................................................................................................................................... 25
MSUnlockSoft........................................................................................................................................................ 25

DeadLock ................................................................................................................................................... 26
Como evitar ............................................................................................................................................... 26
Leitura Suja ............................................................................................................................................... 27
Cuidados .................................................................................................................................................... 27
Controle de Transao (TTS) .................................................................................................................. 28
O que ........................................................................................................................................................ 28
Quando usar .............................................................................................................................................. 28
Como usar .................................................................................................................................................. 28
BEGIN TRANSACTION...END TRANSACTION............................................................................................ 28
FKCommit() .......................................................................................................................................................... 29

Onde no usar............................................................................................................................................ 29
Trabalhando com arquivos (Tabelas de Dados)..................................................................................... 30
Conceito de Filial e Compartilhamento de Arquivos............................................................................. 30
xFilial() ....................................................................................................................................................... 31
cFilAnt e cEmpAnt.................................................................................................................................... 32
Arquivos e ndices Temporrios.............................................................................................................. 33
CriaTrab ................................................................................................................................................................ 33
IndRegua................................................................................................................................................................ 33

Criando e Deletando Arquivos temporrios .......................................................................................... 34


Usando Filtros ........................................................................................................................................... 35
Querys Embedded SQL......................................................................................................................... 36
Dicas de Tunning....................................................................................................................................... 37
Integridade Referencial ............................................................................................................................ 38
Chaves Primrias .................................................................................................................................................. 38
Chaves Estrangeiras.............................................................................................................................................. 38

Dicas Importantes ..................................................................................................................................... 38

Sistema Internacionalizado ..............................................................................................................39


Boas Prticas de Programao

Diferena entre Localizar e Traduzir...................................................................................................... 39


Localizar .................................................................................................................................................... 39
Traduzir ..................................................................................................................................................... 39
Como produzir um programa traduzido? .............................................................................................. 40
Arquivos header (CH) anexados ao cdigo-fonte............................................................................... 40
Dicionrio de Dados .................................................................................................................................. 41
Como Produzir um programa Localizado .............................................................................................. 42

Processamento Automtico...............................................................................................................43
Rotinas Automticas ................................................................................................................................. 43
O que so?.................................................................................................................................................. 43
Como fazer?............................................................................................................................................... 43
Schedule ..................................................................................................................................................... 44

Processos de Integrao....................................................................................................................45
Customizaes ...................................................................................................................................46
Pontos de Entrada ..................................................................................................................................... 46
O que so?.................................................................................................................................................. 46
Quando criar? ........................................................................................................................................... 46
Utilizao.................................................................................................................................................... 46
Semforo .................................................................................................................................................... 47

Desenvolvendo Telas.........................................................................................................................48
Interfaces do Protheus .............................................................................................................................. 48
Browses ...................................................................................................................................................... 49
mBrowse() .................................................................................................................................................. 49
MarkBrow() ............................................................................................................................................... 50
TWBrowse()............................................................................................................................................... 51
Perguntas ................................................................................................................................................... 52
Pergunte() .................................................................................................................................................. 52
Entrada de Dados...................................................................................................................................... 53
Enchoice() .................................................................................................................................................. 53
MSGetDados() ........................................................................................................................................... 55
Componentes Individuais ......................................................................................................................... 56
TSay() ......................................................................................................................................................... 56
TGet()...................................................................................................................................................... 56
TComboBox() e TListBox()...................................................................................................................... 56
TCheckBox().............................................................................................................................................. 56
TButton() e SButton() ............................................................................................................................... 57
TPanel()...................................................................................................................................................... 57
Mensagens.................................................................................................................................................. 58
Boas Prticas de Programao

Aviso() ........................................................................................................................................................ 58
Help().......................................................................................................................................................... 58
MsgNoYes(), MsgStop(), MsgInfo() e MsgAlert() .................................................................................. 59
MSAguarde() ............................................................................................................................................. 59
MsNewProcess() ........................................................................................................................................ 59
Outros Modelos ......................................................................................................................................... 60
dbTree()...................................................................................................................................................... 60
APWizard()................................................................................................................................................ 61
cones e Legendas...................................................................................................................................... 62
Legendas .................................................................................................................................................... 62
cones.......................................................................................................................................................... 62

Desenvolvendo Relatrios.................................................................................................................63
Relatrios Grficos.................................................................................................................................... 63

Pecados da Programao..................................................................................................................64
Excesso de Refresh .................................................................................................................................... 64
SET CENTURY / DATE FORMAT e Loops ......................................................................................... 64
Begin...End Sequence / Break .................................................................................................................. 64
Interface durante transao ..................................................................................................................... 65
Transaes muito longas........................................................................................................................... 65
Alto acopalhamento com Interface.......................................................................................................... 65
dbGoTop .................................................................................................................................................... 65
Fontes com economia de IF .................................................................................................................. 65
* em querys........................................................................................................................................... 66
Objetos visuais........................................................................................................................................... 66
Objetos visuais em loops........................................................................................................................... 66
Objetos visuais e o End() .......................................................................................................................... 66
Objetos visuais em Jobs ............................................................................................................................ 67
MSAdvSize() e dimenses de janela ........................................................................................................ 67
Codeblocks em componentes visuais ....................................................................................................... 67
DEFINE DIALOG e ACTIVATE............................................................................................................ 67
Funes em ON INIT ................................................................................................................................ 67
DBTree ....................................................................................................................................................... 67

Boas Prticas de Programao

Para que padronizar?


O ser humano convive com a padronizao h milhares de anos e depende dela para a
sua sobrevivncia, mesmo que no tenha conscincia disto.
Imagine como seriam as relaes comerciais entre as naes se no existisse o
Sistema Mtrico para estabelecer uma linguagem comum? Ou ento, como seria
possvel manter a ordem pblica sem os sinais de trnsito?

A padronizao deve ser vista dentro das organizaes da mesma forma, ou seja,
como algo que trar benefcio para todos: diretores, gerentes, executantes,
fornecedores e clientes.
Hoje, com a complexidade dos processos produtivos e gerenciais, mais do que nunca
necessrio registrar de forma organizada (em meio fsico ou eletrnico) a maneira
de se trabalhar e introduzir formalmente o treinamento no trabalho (On the Job
Training - OJT).
Podemos, ento, definir PADRO como sendo:
"Compromisso documentado, utilizado em comum e repetidas vezes pelas
pessoas relacionadas com um determinado trabalho."
As principais vantagens de se padronizar o desenvolvimento de sistemas numa
organizao so:
Disciplina nos mtodos de trabalho;
Facilidade de controles e conseqente gerenciamento;
Diminuio dos problemas de manuteno.

Padronizar Servir de Modelo

Boas Prticas de Programao

Legibilidade de Cdigo
Entende-se por legibilidade de cdigo, a facilidade de ler e entender o que foi escrito
pelo programador. Usando as regras de legibilidade de cdigo, fica fcil para outro
programador entender os fontes e facilitar futuras alteraes feitas por qualquer
programador.

Estrutura de um programa
Um programa em Advpl pode ser dividido em 5 partes bsicas:
A) rea de cabealho
B) rea de identificao
C) rea de declarao de variveis e ajustes iniciais
D) Corpo do programa
E) rea de encerramento

Boas Prticas de Programao

rea de cabealho
Se um arquivo de cdigo criado se referencia a comandos para interpretao e
tratamento de arquivos XML, este deve se incluir o arquivo de cabealho prprio para
tais comandos (XMLXFUN.CH no exemplo). Porm no deve-se incluir arquivos de
cabealho apenas por segurana. Se no se est referenciando nenhuma das
constantes ou utilizando nenhum dos comandos contidos em um destes arquivos, a
incluso apenas tornar a compilao mais demorada.
Nesta rea tambm devem declaradas as variveis estticas, as constantes e os
arquivos .CH.

rea de Identificao
Esta uma rea dedicada a documentao do programa / funo. Contm
comentrios explicando a sua finalidade, data de criao, parmetros, retornos e
alteraes efetuados.
Existem dois tipos de cabealho, conforme mostrado a seguir:
Cabealho de fonte:

Boas Prticas de Programao

Cabealho de Funo:

rea de Ajustes Iniciais


Nesta rea devem ser feitos os ajustes iniciais, importantes para o correto
funcionamento do programa. Entre esses ajustes iniciais se encontram declaraes de
variveis, inicializaes, abertura de arquivos etc.

Corpo do Programa
nesta rea que se encontram as linhas de cdigo do programa. onde se realiza a
tarefa necessria atravs da organizao lgica destas linhas de comando. Espera-se
que as linhas de comando estejam organizadas de tal modo que no final desta rea o
resultado esperado seja obtido, seja ele armazenado em um arquivo ou em variveis
de memria, pronto para ser exibido ao usurio atravs de um relatrio ou na tela.

rea de Encerramento
nesta rea onde as finalizaes so efetuadas. onde os arquivos abertos so
fechados, e o resultado da execuo do programa utilizado. Pode-se exibir o
resultado armazenado em uma varivel ou em um arquivo ou simplesmente finalizar,
caso a tarefa j tenha sido toda completada no corpo do programa. nesta rea que
se encontra o encerramento do programa. Todo programa em AdvPl deve sempre
terminar com a palavra chave Return.

Boas Prticas de Programao

Linhas de Comentrio
A formatao permitida para comentrios a seguinte:

Dicas sobre comentrios:


Comente apenas o necessrio! Comentrios demais poluem o fonte, e no
trazem ganho significativo legibilidade do cdigo.
Passagens complicadas no fonte so fortes candidatos a terem um comentrio.
Clculos complicados devem ser explicados.
Pontos de entrada devem ter comentrios sobre o seu uso.

Boas Prticas de Programao

10

Tamanho da Linha
O tamanho mximo ideal de uma linha para visualizao na ferrramenta IDE de 130
caracteres. Se a linha digitada ultrapassar esse limite utilize o ponto-e-virgula (;) para
dividi-la.
Pode-se tambm dividir linhas menores que 130 caracteres em mais linhas para
tornar o cdigo mais legvel. Veja os exemplos abaixo:

If !Empty(cNome) .And. !Empty(cEnd) .And. !Empty(cTel) .And. !Empty(cFax).And. nValor !=0


GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif

O cdigo acima pode ser reescrito:

If

!Empty(cNome) .And. !Empty(cEnd) .And. !Empty(cTel) .And.;


!Empty(cFax) .And. nValor != 0
GravaDados(cNome,cEnd,cTel,cFax,cEmail)

Endif

Utilizao de Espaos em Branco


Espaos em branco extras tornam o cdigo mais fcil para a leitura. No so
necessrias imensas reas em branco, mas agrupar pedaos de cdigo atravs da
utilizao de espaos em branco funciona muito bem. Costuma-se tambm separar
parmetros com espaos em branco. Veja os exemplos abaixo:
If !Empty(cNome) .And. !Empty(cEnd) .And. !Empty(cTel) .And.;
!Empty(cFax) .And. nValor != 0
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif

O cdigo fica mais legvel assim:


If !Empty(cNome) .And. !Empty(cEnd) .And. !Empty(cTel) .And.;
!Empty(cFax) .And. nValor != 0
GravaDados(cNome,cEnd,cTel,cFax,cEmail)
Endif
Boas Prticas de Programao

11

No abreviar comandos
Embora o AdvPl suporte a abreviao de comandos para quatro letras (Replace pode
ser escrito como Repl) expressamente proibida a utilizao dessa funcionalidade.
Isto apenas torna o cdigo mais difcil de ser lido e no torna a compilao mais
rpida ou simples.

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

A utilizao da identao seguindo as estruturas de controle de fluxo (while, if, caso


etc) torna a compreenso do cdigo muito mais fcil:

Boas Prticas de Programao

12

Para identar o fonte utilize a tecla <TAB> e na ferramenta IDE, configure em


Preferncias o espaamento da identao:

Capitulao de Palavras-Chave
Uma conveno amplamente utilizada a de capitular as palavras chaves, funes,
variveis e campos utilizando uma combinao de caracteres em maisculo e
minsculo, visando facilitar a leitura do cdigo fonte. O cdigo a seguir:
local ncnt
while ( ncnt++ < 10 )
ntotal += ncnt * 2
enddo
Ficaria melhor com as palavras chaves e variveis capituladas:
Local nCnt
While ( nCnt++ < 10 )
nTotal += nCnt * 2
EndDo

Obs:
Para funes de manipulao de dados que comecem por db, a capitulao s ser
efetuada aps o db.
dbSeek()
dbSelectArea()

Boas Prticas de Programao

13

Inteligncia Protheus

Palavras em maisculo
A regra utilizar caracteres em maisculo para:
Constantes:
#define NUMLINES 60
#define NUMPAGES 1000
Variveis de memria:
M-> CT2_CRCONV
M->CT2_MCONVER := CriaVar("CT2_CONVER")
Campos:
SC6->C6_NUMPED
Querys:
SELECT * FROM...

Utilizao da Notao Hngara


A notao hngara consiste em colocar-se prefixos nos nomes de variveis, de modo
a facilmente se identificar seu tipo. Isto facilita na criao de cdigos-fonte extensos,
pois usando a Notao Hngara, voc no precisa ficar o tempo todo voltando
definio de uma varivel para se lembrar qual o tipo de dados que deve ser
colocado nela. Variveis devem ter um prefixo de Notao Hngara em minsculas,
seguido de um nome que identifique a funo da varivel, sendo que a inicial de cada
palavra deve ser maiscula.
obrigatria a utilizao desta notao para nomear variveis.
Notao

Tipo de
dado

Exemplo

Array

aValores

Caracter

cNomeFornecedor

Data

dDataInicial

Lgico

lContinua

Numrico

nValorConta

Objeto

oMainWindow

Indefinido

xBuffer

Regras e Padronizao para programao do Protheus

14

Inteligncia Protheus

Nomeando um Cdigo Fonte


O nome do cdigo-fonte deve ser montado da seguinte forma:
Famlias de Programas + Tipo de Operao + Identificador Numrico.prw
O Tipo de operao indicado na tabela abaixo:
Tipo de Operao
Entrada de dados / Processamentos
Consulta de dados
Relatrios
Funes genricas do mdulo

Utilizar:
A
C
R
X

Exemplo:
Cdigo-fonte de incluso de dados do mdulo Gesto de Pessoas -> GPEA010.PRW
GPE
A
010
.PRW

famlia de programas do mdulo Gesto de Pessoas


entrada de dados
numerao de fonte disponvel
extenso indicadora de que o arquivo um cdigo-fonte

Importante!
Novos fontes devem ter a extenso .prw.
Fontes migrados da verso DOS sero mantidos como .prx at que sejam
desativados ou reescritos.
Nova incluso de famlia deve ser solicitada para rea Engenharia de Software.

Veja Anexo 1 com a Famlia de programas disponveis.

Regras e Padronizao para programao do Protheus

15

Inteligncia Protheus

Regras Bsicas de Programao


Variveis
Ao se utilizarem variveis deve-se estar atento para sua:
Declarao
Visibilidade
Inicializao

Declarao
obrigatria a declarao da varivel no inicio da rotina. Deve-se utilizar a notao
hngara para nomear as variveis.
Function a910VerCod()
Local cCod910 := 001

Visibilidade
O seu uso est determinado conforme indicado a seguir:
Proibidas: Public
Restritas: Private (os casos devero ser avaliados)
Liberadas: Local e Static

Inicializao
Todas as variveis devero ser inicializadas no momento de sua declarao. Inicialize
com um valor discreto, ou utilize a funo CriaVar()*.

*CriaVar(): Esta funo cria uma varivel, retornando o valor do campo, de acordo com o

dicionrio de dados. Avalia o inicializador padro e retorna o contedo de acordo com o tipo de
dado definido no dicionrio.

Regras e Padronizao para programao do Protheus

16

Inteligncia Protheus

Funes
Ao se criarem novas funes deve-se estar atento :
Declarao
Visibilidade
Nomeando
Passagem de parmetros
Recebimento de parmetros
Entrada da funo
Sada da funo

Declarao
As funes no necessitam nenhuma declarao se forem executadas a partir do
menu da aplicao. Caso sejam executadas a partir do Remote, devem ser declaradas
como Main ou User Function.

Visibilidade
Funes que so utilizadas somente dentro de um mesmo cdigo-fonte devem ser
obrigatoriamente declaradas como STATIC. Esse tipo de funo visvel somente no
cdigo-fonte em que foi chamada.
Demais tipos de funes so visveis em todo o sistema e devem ser usadas com
critrio, pois carregam a pilha de memria.

Nomeando
As funes pertencentes a um cdigo-fonte podem ser nomeadas de acordo com a
sua aplicabilidade. Utiliza-se como regra geral a seguinte forma:
1. Letra do nome do cdigo fonte
Tipo de Operao indicado no cdigo fonte
Identificador do cdigo-fonte
abreviao descritiva do que a funo faz
Exemplo:
Funo de incluso de dados presente FINA050 -> FA050Inclu
F
1. Letra do nome do cdigo fonte
A
Tipo de operao (manipulao de dados)
050
Identificador do cdigo fonte
Inclu
Abreviao do que a funo faz -> incluso de dados
Para funes genricas utilizadas em um determinado mdulo, nomeia-se a funo
diretamente de acordo com a sua aplicabilidade.
Exemplo:
SaldoTit() -> calculo saldo de ttulos
CalcAbat() -> calculo do abatimento do ttulo
Regras e Padronizao para programao do Protheus

17

Inteligncia Protheus

Palavras Reservadas
As palavras reservadas do ADVPL so:
AADD

DTOS

INKEY

REPLICATE

VAL

ABS

ELSE

INT

RLOCK

VALTYPE

ASC

ELSEIF

LASTREC

ROUND

WHILE

AT

EMPTY

LEN

ROW

WORD

BOF

ENDCASE

LOCK

RTRIM

YEAR

BREAK

ENDDO

LOG

SECONDS

CDOW

ENDIF

LOWER

SELECT

CHR

EOF

LTRIM

SETPOS

CMONTH

EXP

MAX

SPACE

COL

FCOUNT

MIN

SQRT

CTOD

FIELDNAME

MONTH

STR

DATE

FILE

PCOL

SUBSTR

DAY

FLOCK

PCOUNT

TIME

DELETED

FOUND

PROCEDURE

TRANSFORM

DEVPOS

FUNCTION

PROW

TRIM

DOW

IF

RECCOUNT

TYPE

DTOC

IIF

RECNO

UPPER

CATCH

THROW

TRY

AS

Notas:
Palavras reservadas no podem ser utilizadas para variveis, procedimentos ou
funes.
Funes reservadas so pertencentes ao compilador e no podem ser redefinidas
por uma aplicao.
Todos os identificadores que comearem com um ou mais caracteres de sublinhado
(_) so utilizados como identificadores internos e so tambm reservados.

Regras e Padronizao para programao do Protheus

18

Inteligncia Protheus

Gravando variveis ambientais


Para garantir a integridade do sistema obrigatria a gravao e restaurao do
ambiente a partir das funes:
GetArea() -> utilizar no incio da funo
RestArea() -> utilizar antes da sada da funo
Exemplo:
Function Calculox(nValor)
Local lRet := .T.
Local aSaveArea := GetArea()
...
...
...
RestArea(aSaveArea)
Return lRet

Retorno de funes
As funes e cdigos-fonte devem preferencialmente ter apenas 1 ponto de abandono
(retorno). Se existirem vrios pontos de abandono, utilize variveis lgicas para
compor a estrutura como mostrado no exemplo abaixo:
Function ValidCont(cConteudo)
Local aSaveArea := GetArea()
Local lRet := .T.
If Empty(cConteudo)
Help(" ",1,"NOCONTEUDO)
lRet := .F.
ElseIf cTipoTit = D
Help(" ",1,"CONTINCORR")
lRet := .F.
Endif

//"Sem Contedo
//"Contedo incorreto

RestArea(aSaveArea)
Return lRet

Regras e Padronizao para programao do Protheus

19

Inteligncia Protheus

Utilizando loops
Ao utilizar o comando While no esquecer de incluir a condio referente filial
(quando esta leitura for de registros de uma filial) e de final de arquivo (Eof()).
Exemplo :
dbSelectArea("SB1")
dbSeek(xFilial("SB1")+cVar)
Do While ! Eof() .And. SB1->B1_FILIAL == xFilial("SB1")
// Processamento
dbSkip()
Enddo
Importante!
A falta do Eof() pode acarretar em um Loop Infinito (vide a seguir).
A falta da leitura da filial pode acarretar em leitura incorreta de dados (filial
errada).

Loops Infinitos
Muito cuidado ao utilizar laos em funes para que o programa no trave por falta de
uma sada desse lao. Vide exemplos abaixo:
dbSeek(xFilial(SE1)+DTOS(dDtIni))
Do While SE1->(!Eof())

---------- Falta um dbSkip()


Enddo

aCampos := {}
Do while .T.
Aadd(aCampos, Teste)
Enddo

Regras e Padronizao para programao do Protheus

---------- quando vai terminar??

20

Inteligncia Protheus

Trabalhando com Dados


Trabalhando com Registros
Como referenciar um campo
Todos os campos devero ser referenciados com o seu Alias e em letras maisculas:
SB1->B1_FILIAL
SB1->B1_CODPROD

Cuidados com Posicionamentos de Registros


dbSeek()
Ao executar um dbSeeK() SEMPRE verifique se localizou o registro, exemplo:
Exemplo:
If !SB1->(dbSeek(xFilial("SB1")+cVar))
// No achei o registro
Endif
Mesmo que seja bvio a existncia do registro, faa o teste para evitar qualquer
interrupo indesejada do programa.
SoftSeek
A funo dbSeek() possui a opo de SoftSeek, isto , determina se ser usada uma
busca relativa durante um procura em um banco de dados. Se nenhuma
correspondncia for encontrada, o ponteiro de registro ficar no prximo registro do
ndice que possua um valor mais alto que a expresso utilizada nesta funo. Esta
opo dever ser utilizada com a mxima ateno, pois caso esteja ligado, poder
localizar um registro errado.

Regras e Padronizao para programao do Protheus

21

Inteligncia Protheus

Funes de Posicionamento Restritas


RESTRITA a utilizao das seguintes funes:
dbGoTop()
dbSeek(xFilial())
Importante!
A utilizao dessas duas funes s justificvel quando se est utilizando algum
filtro de leitura ou um arquivo temporrio.
O dbSeek com a passagem somente de xFilial() deve ser evitado. Se a chave de
procura, incluir outros que no somente a Filial, o uso de dbSeek liberado.

Funes de Procura
recomendado o uso das funes de procura a seguir:
Posicione()
Podemos tambm buscar uma informao em determinado campo usando a funo
Posicione.
Exemplo:
cDesc:= Posicione("SB1", 1, xFilial("SB1") + cCodigo, "B1_DESC")
Desta forma, ser efetuada uma busca no SB1, na ordem 1, chave da busca
xFilial("SB1") + cCodigo e ser retornado o contedo do campo "B1_DESC". Note que
esta funo, no restaura a posio original do arquivo alvo (no caso SB1).
necessrio passar a filial do arquivo na chave passada como parmetro, caso ela
exista na chave do ndice.
ExistCpo()
Retorna se determinada chave existe ou no no arquivo.
Exemplo :
ExistCpo("SE1", M->EF_PREFIXO+M->EF_TITULO+M->EF_PARCELA,1)
Desta forma, ser efetuada uma busca no SE1, na ordem 1, chave:
M->EF_PREFIXO+M->EF_TITULO+M->EF_PARCELA. E ser retornado se a chave foi
encontrada ou no (.T. ou .F.).
No necessrio passar a filial. Ela ser inserida automaticamente na chave de
pesquisa pela prpria funo.

Regras e Padronizao para programao do Protheus

22

Inteligncia Protheus
Travamentos / Bloqueios / Locks
Quando estamos trabalhando em um ambiente multi-usurio, se faz necessrio um
controle de bloqueio desta informao para quando a mesma for atualizada ou
excluda. Esse bloqueio serializa as operaes, possibilitanto que vrios usurios
faam alteraes no mesmo registro, porm no ao mesmo tempo.
RecLock(cAlias, lAppend)
Tem a funo de criar um registro em branco para insero ou bloquear o registro
atual para edio, neste caso a funo executa um refresh do dado, buscando a
informao mais atual no banco. Durante o perodo que o registro estiver bloqueado
os demais usurios podem acess-lo apenas para consulta (vide adiante DeadLock
- leitura suja).
Caso no seja possvel o bloqueio do registro a funo ir interagir com o usurio,
questionando se deve permanecer tentando o bloqueio ou desistir da operao.
Exemplo:
Verifica se o registro existe na tabela SA1:
If !dbSeek(xFilial(SA1)+000001)
// Se no existir, insere um registro em branco e o bloqueia
Reclock(SA1, .T. )
Else
// Bloqueia o registro encontrado
Reclock(SA1, .F. )
Endif
MSUnlock(cAlias)
Libera o registro criado ou bloqueado pela RecLock.
Exemplo:
Verifica se o registro existe na tabela SA1:
If !dbSeek(xFilial(SA1)+000001
//Se no existir, insere um registro em branco e o bloqueia
Reclock(SA1, .T. )
Else
//Bloqueia o registro encontrado
Reclock(SA1, .F. )
EndIf
SA1->A1_SALDO := nNovoSaldo
MSUnLock(SA1)

A recomendao que sejam utilizadas somente as funes RecLock e MsUnLock.


Demais funes de travamento disponveis s podero ser utilizadas com aprovao
da Engenharia de Software.

Regras e Padronizao para programao do Protheus

23

Inteligncia Protheus
Funes de Travamento Restritas
DBRLock( [ recno ] )
Realiza o bloqueio do registro indicado pelo parmetro. Caso este seja omitido ir
bloquear o registro corrente, desbloqueando demais bloqueados.
DBRUnlock( [ recno ] )
Desbloqueia o registro indicado pelo parmetro. Caso este seja omitido ir
desbloquear o registro corrente.
MSRLock( [ recno ] )
Esta funo uma variao da DBRLock. Seu comportamento difere somente no caso
do argumento ser omitido, pois ela ir bloquear o registro corrente sem desbloquear
os demais bloqueados.
MSRUnlock
Esta funo um encapsulamento da DBRUnLock()
DBUnlock
Desbloqueia todos os registros bloqueados para a tabela corrente.
DBUnlockAll
Desbloqueia todos os registros bloqueados de todas as tabelas abertas pelo sistema.
MultLock( Alias, aChaves, nOrd )
Esta funo reserva atravs de semforo apropriado as chaves definidas no array
aChaves evitando assim a ocorrncia de deadlock.
Deve ser utilizada toda vez que houver a necessidade de alterar mais de uma linha de
uma mesma tabela dentro da mesma transao.
Um exemplo prtico a alterao de saldos de estoque na incluso de vrias
movimentaes (na mesma transao).
No caso do TopConnect este semforo feito atravs de locks virtuais (em
memria), no sendo feito lock no banco. Para outras bases o semforo feito
atravs de lock de registro.
nPosPrd:=aScan(aHeader,{|x| AllTrim(x[2]) == "C6_PRODUTO"})
nPosLoc:=aScan(aHeader,{|x| AllTrim(x[2]) == "C6_LOCAL"})
For ni := 1 to Len(aCols)
AADD(aTrava, C6_PRODUTO+C6_LOCAL )
Next
lTrava := MultLock("SB2",aTrava,1) .And.;
MultLock("SA2",{M->C5_CLIENTE+M->C5_LOJACLI},1) .And.;
MultLock("SA2",{M->C5_CLIENTE+M->C5_LOJAENT},1)
Regras e Padronizao para programao do Protheus

24

Inteligncia Protheus
SoftLock
A funo SoftLock tem por objetivo efetuar um bloqueio no registro quando a
operao de alterao ou excluso for executada pela Mbrowse ou pela MarkBrowse.
Essa funo no deve ser utilizada nos programas, visto que se trata de uma funo
interna, utilizada nas bibliotecas do ADVPL.
MSUnlockAll
Esta funo desbloqueia todos os registros bloqueados pelas funes Multlock,
SoftLock e RecLock.
MSUnlockSoft
Tem por funo desbloquear os registros bloqueados pela SoftLock.

Regras e Padronizao para programao do Protheus

25

Inteligncia Protheus

DeadLock
Um sistema est em estado de deadlock quando existe uma operao (A) fazendo um
bloqueio em um registro (R1) e tentando bloquear outro registro (R2). Neste mesmo
momento existe outra operao (B) bloqueando o registro (R2) e tentando bloquear o
registro (R1).
Nesta situao no existe como o banco resolver as solicitaes, ento ele elege,
aleatoriamente, uma das conexes e a encerra.
Exemplo

Deadlock Explicao Rpida


Usurio 1

Usurio 2

User

Tenta bloquear
registro 1 da
tabela B

D
EA
D

Efetua bloqueio
registro 1 da
tabela A

LO

User

Recipient Policy

Recipient Policy

Efetua bloqueio
registro 1 da
tabela B

Tenta bloquear
registro 1 da
tabela A

Recipient Policy

Recipient Policy

Como evitar
Dentro do sistema Protheus existem duas formas de evitarmos o deadlock. A primeira
delas utilizando a funo Multlock (descrita anteriormente) para bloquear todos os
registros que sero manipulados, antes de iniciar a gravao.
A segunda forma, e mais indicada, seria a insero dos dados sempre na mesma
orderm, por exemplo, ao inserir um pedido de venda, o programa deve ordenar os
itens pelo cdigo do produto, evitando assim a possibilidade de um deadlock nas
tabelas relacionadas ao produto.
Lembre-se sempre de seguir a ordem de dependncia da informao, incluindo
primeiro as informaes pai para em seguida incluir as informaes filho.
Ex. Pedido de venda incluir cabealho depois itens.

Regras e Padronizao para programao do Protheus

26

Inteligncia Protheus
Leitura Suja
Permite que outros usurios faam a leitura dos dados que esto bloqueados por
outra(s) sesso(es) e que ainda no foram confirmados. Trata-se do nvel mais baixo
de consistncia de leitura.
Porque utilizar leitura suja
Para permitir que outros usurios tenham acesso aos dados que esto sendo
alterados, caso contrrio o sistema funcionaria de forma serializada, inviabilizando
vrios processos.
Impacto da utilizao
O grande impacto que pode haver na utilizao da
fantasmas, ou seja, a transao T2 l um dado que
por sua vez, altera o contedo da linha ou at mesmo
processar alguma informao referente a esta linha
contedo no mais aquele que foi lido anteriormente.

leitura suja a apario de


estava bloqueado por T1. T1,
apaga a linha. Quando T2 for
ela no existe mais ou seu

Cuidados
A situao descrita neste exemplo est incorreta:
SA1->MSSeek( 01 + 12345601 )
nVal := SA1->A1_SALDO
Reclock( SA1, .F. )
nVal += nValAcumulado
SA1->A1_SALDO := nVal
MSUnlock()
Existe um erro de lgica, pois a varivel nVal recebeu o contedo de A1_SALDO sem
que o registro estivesse bloqueado. Neste caso o contedo de A1_SALDO pode ter
sofrido alterao e o contedo de nVal est diferente.
A forma correta de escrita do exemplo anterior seria:
If SA1->MSSeek( 01 + 12345601 )
Reclock( SA1, .F. )
nVal := SA1->A1_SALDO
nVal += nValAcumulado
SA1->A1_SALDO := nVal
MSUnlock()
Endif

Regras e Padronizao para programao do Protheus

27

Inteligncia Protheus

Controle de Transao (TTS)


O que
A seqncia de um ou mais comandos de manipulao de dados constitui uma
transao. Por conceito, uma transao necessita de confirmao (COMMIT) ou
cancelamento (ROLLBACK) para confirmar ou no as alteraes.
O exemplo mais fcil para entendermos o que uma transao partindo para uma
transferncia bancria entre contas. A transao s confirmada quando a operao
for realizada nas duas contas (crdito e dbito). Caso uma das duas partes falhe a
transao cancelada.

Quando usar
Quando temos uma operao que necessite que vrias incluses, alteraes ou
excluses s sejam efetuadas quando todas as operaes tenham sido realizadas com
sucesso, garantindo com isso que no sejam atualizadas parcialmente as tabelas
envolvidas.

Como usar
BEGIN TRANSACTION...END TRANSACTION
Para definir uma transao, deve-se utilizar os comandos BEGIN TRANSACTION e END
TRANSACTION para definir incio e fim de uma transao respectivamente. Todas
informaes serem gravadas no Banco devem estar dentro de uma nica transao
sejam elas provenientes de uma ou vrias tabelas.
BEGIN TRANSACTION
ExpN1 :=FuncGrava()
END TRANSACTION

Caso exista uma transao dentro de outra, a segunda ser automaticamente


ignorada, fechando-se a transao principal quando da chamada do comando END
TRANSACTION.
BEGIN TRANSACTION
FuncGrava1()
BEGIN TRANSACTION
ExpN1 :=FuncGrava()
END TRANSACTION
END TRANSACTION

---------- ignorada
---------- ignorada

Importante!
Dentro de uma transao proibida a utilizao de Exit que interrompa o fluxo de
gravaes, deixe pendente a transao aberta.

Regras e Padronizao para programao do Protheus

28

Inteligncia Protheus
FKCommit()
Executa os comandos de gravao dos dados pendentes no banco (flush) para a
tabela corrente, se a integridade referencial estiver ativa. Deve ser utilizada aps a
insero de dados em uma tabela pai, em que na mesma transao sero inseridos os
filhos.
Exemplo:
BEGIN TRANSACTION
RecLock(SC5,.T.)
SC5->C5_NUM := cNumPed
FKCommit()
For nContador := 1 To Len (aItens)
RecLock(SC6,.T.)
SC6->C6_NUM := cNumPed
SC6->C6_ITEM := cItemPed
SC6->C6_COD := cProduto
FKCommit()
Next nContador
SC5->(MsUnlock())
END TRANSACTION
A execuo do comando de gravao no banco de dados pode no ocorrer no mesmo
momento em que executado um MsUnlock(). Por questes de desempenho, o
Protheus faz um cach desses comandos e de tempos em tempos os aplica no banco.
Esta execuo pode ser antecipada pelas seguintes aes:
Desposicionamento do ponteiro de registro da tabela que teve a insero.
Execuo de: FKCommit(), Recno() ou TCQuery().

Onde no usar
proibida a utilizao de laos (WHILE, FOR) dentro de uma transao, pois a rea
LOG do banco limitada, e o volume de informaes pode ultrapassar o limite
banco de dados. Por exemplo, devemos controlar a transao de uma nota e no
um conjunto ilimitado de notas para no ultrapassarmos o limite do Log do banco
dados.

de
do
de
de

O controle de transao jamais dever ser utilizado durante processos que envolvam
interfaces de entrada de dados. O controle deve se resumir apenas ao processo de
gravao. Entre um incio de transao (Begin Transaction) e um final (End
Transaction) todos os registros a serem gravados ficam bloqueados at o final da
transao. Caso exista uma tela entre o BEGIN e o END, a aplicao fica dependente
do usurio para efetuar a liberao da transao, fato que poderia causar muitos
transtornos aos usurios.
Rotinas de reprocessamentos ou reclculos, onde as informaes podem ser
regeradas durante sua execuo no devem ter controle de transao, pois a
quantidade de registros processados pode ultrapassar o limite do log de transao.

Regras e Padronizao para programao do Protheus

29

Inteligncia Protheus

Trabalhando com arquivos (Tabelas de Dados)


Conceito de Filial e Compartilhamento de Arquivos
O compartilhamento de arquivos baseado no conceito de filiais. Cada empresa
cadastrada pode ter n filiais onde os dados inseridos por cada filial - como cadastro de
produtos, clientes, etc. podem ou no ser compartilhados com as demais filiais. Este
recurso somente possvel devido existncia do campo XX_FILIAL (XX
representa o nome do arquivo) em todos os arquivos do sistema.
O modo de operao de cada arquivo compartilhado ou exclusivo est definido no
arquivo SX2 do dicionrio de dados.
Caso o modo de acesso seja compartilhado, quando um novo registro for inserido, o
campo XX_FILIAL receber o valor (dois caracteres brancos) e o seu contedo
ser visvel por qualquer usurio de qualquer filial.
Caso o modo de acesso seja exclusivo, quando um novo registro for inserido, o campo
receber o cdigo alfanumrico da filial (no exemplo abaixo, 01 ou 02) e ser
visvel apenas para os usurios da filial que inseriu o mesmo.
Exemplo:
O arquivo XX est com o modo de acesso definido como exclusivo no SX2, portanto
seus registros sero visveis somente para a filial que os inseriu. Vide exemplo abaixo:

Os usurios da Filial 01 tero acesso somente aos dados cujo registro possua o
contedo 01 no campo XX_FILIAL. J os usurios da Filial 02, acessaro os dados
dos registros com o valor 02 no campo XX_FILIAL.
Regras e Padronizao para programao do Protheus

30

Inteligncia Protheus

xFilial()
Para que o registro realmente fique disponvel ou no para suas respectivas Filiais,
TODAS as rotinas que manipulam registros diretamente na base de dados devero
verificar a Filial atravs da Funo xFilial().
A funo xFilial() verifica se o arquivo exclusivo ou compartilhado e ir retornar
se o arquivo for Compartilhado ou o cdigo da Filial se o arquivo for exclusivo .

Exemplo :
Para executar um dbSeek no arquivo de clientes :
dbSelectArea(SA1)
dbSeek(xFilial(SA1)+cCodCli+cLoja)
Para efetuar um processamento em um arquivo :
While !Eof() .And. CT1_FILIAL==xFilial(01)
Importante!!
O campo XX_FILIAL faz parte da chave de todos os ndices do sistema
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).

Regras e Padronizao para programao do Protheus

31

Inteligncia Protheus

cFilAnt e cEmpAnt
Estas variveis de ambiente contm respectivamente a Filial e a Empresa que o
usurio est operando no momento.
Se a rotina for manipular a filial e/ou empresa correntes, deve-se inicialmente gravar
a filial e a empresa corrente, para que ao trmino da rotina, tudo seja restaurado
sua posio inicial.
Exemplo:
cSvEmpAnt := cEmpAnt
cSvFilAnt := cFilAnt
..... (processamento de cdigo que altera o valor da filial e/ou empresa corrente)
cEmpAnt := cSvEmpAnt
cFilAnt := cSvFilAnt

Regras e Padronizao para programao do Protheus

32

Inteligncia Protheus

Arquivos e ndices Temporrios


Arquivos e ndices temporrios devem ser utilizados com cuidado, pois podem
gerar um tempo de resposta longo enquanto esto sendo construdos.
No caso de ndices temporrios, o processamento da rotina bem mais rpido (aps a
sua gerao), mas de qualquer forma, sempre d preferncia utilizao dos ndicespadro do sistema ou de querys.
Utilize as funes:
CriaTrab
Criatrab(cAlias,.F.) -> Cria somente um arquivo de ndice temporrio
Criatrab(cAlias,.T.) -> Cria um arquivo de dados e um arquivo de ndice temporrio (a
criao do ndice temporrio no obrigatria.
IndRegua
Cria efetivamente o ndice, a partir do arquivo j criado com a CriaTrab.
Exemplo:
Para criar dois ndices temporrios, utilize o cdigo abaixo:
dbSelectArea("SE1")
cIndex
:= CriaTrab(nil,.f.)
cIndex2
:= CriaTrab(nil,.f.)
cChave
:= IndexKey()
IndRegua("SE1",cIndex,"E1_FATURA+E1_NUM+E1_SERIE",,,OemToAnsi("Selecionan
do Registros..."))
IndRegua("SE1",cIndex2,"E1_NUM",,,OemToAnsi("Selecionando Registros..."))
nIndex := RetIndex("SE1")
dbSelectArea("SE1")
#IFNDEF TOP
dbSetIndex(cIndex+OrdBagExt())
dbSetIndex(cIndex2+OrdBagExt())
#ENDIF
dbSetOrder(nIndex+1)
dbSetOrder(nIndex+2)
...
dbSetOrder(nIndex+1)
dbSeek(M->mv_par01,.T.)
While SE1->E1_FATURA <= M->mv_par02 .AND. !SE1->(Eof())
...
dbSetOrder(nIndex+2)
dbSeek(M->mv_par02,.T.)
While SE1->E1_NUM <= M->mv_par02 .AND. !SE1->(Eof())
...
Regras e Padronizao para programao do Protheus

33

Inteligncia Protheus
Criando e Deletando Arquivos temporrios
Quando criamos um arquivo de trabalho ou um ndice de trabalho (utilizando a funo
Indregua) obrigatrio que sejam apagados ao final do programa.
Exemplo:
Para criao de um ndice de Trabalho (Temporrio) com Indregua:

cArqTmp
......

:= CriaTrab( NIL, .T. )

dbCloseArea()
Ferase(cArqTmp+GetdbExtension())
Ferase(cArqTmp+OrdBagExt() )

//Criando Arquivo

// Deletando o arquivo
// Deletando ndice

Importante!!
Utilize a funo GetdbExtension() para retornar a extenso do arquivo de trabalho.
No utilize .dbf, .dbt etc como mostrado abaixo:
Ferase(cArqTmp+.dbf) ---------- Incorreto!
Ferase(cArqTmp+GetdbExtension())
---------- Correto!

Regras e Padronizao para programao do Protheus

34

Inteligncia Protheus

Usando Filtros
A utilizao de filtros poder ser feita de duas maneiros:
Set Filter to
dbSelectArea("CV3")
cFilCV3 := xFilial("CV3")
Set Filter to CV3->CV3_FILIAL == cFilCV3 .AND. CV3->CV3_DTSEQ == dDtCV3 .AND.;
CV3->CV3_SEQUEN == cSequenc
..
dbSelectArea("CV3")
Set Filter to
EndIf
IndRegua()
cIndex
:= CriaTrab(nil,.f.)
cChave
:= IndexKey()
cFiltro := 'E1_FILIAL=="'
+cFilial + '".And.'
cFiltro += 'E1_FATURA=="'
+cFatura + '".And.'
cFiltro += 'E1_TIPOFAT=="'
+cTipo
+ '"'
IndRegua("SE1",cIndex,cChave,,cFiltro,OemToAnsi(STR0048))
nIndex := RetIndex("SE1")
dbSelectArea("SE1")
#IFNDEF TOP
dbSetIndex(cIndex+OrdBagExt())
#ENDIF
dbSetOrder(nIndex+1)
dbGoTop()

Ao trmino do uso do filtro o mesmo dever ser desabilitado, utilizando-se uma das
seguintes funes / comandos:
dbSetFilter()
Set Filter to
dbClearFilter()

Regras e Padronizao para programao do Protheus

35

Inteligncia Protheus

Querys Embedded SQL


O objetivo do Embedded SQL facilitar a escrita e leitura de query's. Foi definida uma
sintaxe para que se possa escrever a query diretamente no cdigo ADVPL, sem a
necessidade de ficar concatenando pedaos de string para compor a string final.
Recomenda-se que novas querys sejam desenvolvidas utilizando-se este novo
recurso.
Exemplo:
Query padro:

cQuery
cQuery
QEK '
cQuery
cQuery
cQuery
cQuery

: 'SELECT SE2.E2_PREFIXO,SE2.E2_NUM '


+= 'FROM '+RetSqlTable('SE2')+' SE2,'+RetSqlTable('QEK')+'
+=
+=
+=
+=

'WHERE SE2.E2_FILIAL= '+xfilial('SE2')+' AND '


'SE2.E2_PREFIXO<> ''+cPrefixo+'' AND '
'SE2.D_E_L_E_T_ = ' ' '
'ORDER BY '+RetSqlOrder('SE2')

dbUseArea(.T.,'TOPCONN',TcGenQry(,,cQuery),'E2TEMP',.T.,.T.)
TCSetField('E2TEMP','E2_EMISSAO','D',8,0)

Embedded SQL:

BeginSql alias 'E2TEMP'


column E2_EMISSAO as Date
%noparser%
SELECT SE2.E2_PREFIXO,SE2.E2_NUM
FROM %table:SE2% SE2,%table:QEK% QEK
WHERE SE2.E2_FILIAL= %xfilial:SE2% AND
SE2.E2_PREFIXO<> %exp:cPrefixo% AND
SE2.%notDel%
ORDER BY %Order:SE2%
EndSql

Regras e Padronizao para programao do Protheus

36

Inteligncia Protheus
Outro Exemplo:
BeginSql alias 'E2TEMP'
column E2_EMISSAO as Date, E2_VALOR as Numeric(tam_cp,2)
column QEK_SKLDOC As Logical
%noparser%
SELECT SE2.E2_PREFIXO,SE2.E2_NUM, SE2.E2_FORNECE, SE2.E2_LOJA,
SE2.E2_VALOR, SE2.D_E_L_E_T_ DEL1, QEK.D_E_L_E_T_ DEL2 ,
QEK.QEK_SKLDOC, SE2.R_E_C_N_O_ SE2RECNO
FROM %table:SE2% SE2,%table:qeK% QEK
WHERE SE2.E2_FILIAL= %xfilial:SE2% AND
qek.%notDel% and
SE2.E2_PREFIXO<> %exp:cPrefixo% AND
SE2.E2_NUM<> %exp:(cAlias)->M0_CODIGO% AND
SE2.E2_NUM<>45
AND
SE2.E2_FORNECE=%exp:Space(Len(SE2->E2_FORNECE))% AND
SE2.E2_EMISSAO<>%exp:MV_PAR06% AND
SE2.E2_LOJA<>%exp:MV_PAR05% AND
SE2.E2_VALOR<>%exp:MV_PAR04% AND
qek.QEK_SKLDOC<>%exp:MV_PAR03%
And
SE2.%notDel%
ORDER BY %Order:SE2,1%
EndSql

Dicas de Tunning

Regras e Padronizao para programao do Protheus

37

Inteligncia Protheus

Integridade Referencial
Chaves Primrias
Chaves Estrangeiras

Dicas Importantes

Regras e Padronizao para programao do Protheus

38

Inteligncia Protheus

Sistema Internacionalizado
A TOTVS atua hoje em diversos pases e isto faz com que os seus sistemas precisem
estar adaptados s realidades fiscais e comerciais de cada um desses pases. Para que
isso seja aplicvel, o sistema precisa ser traduzido e localizado.

Diferena entre Localizar e Traduzir


Localizar
De maneira geral, localizao de software a adaptao de um sistema j
desenvolvido para um determinado pas ou regio que precisa de adequaes legais e
de regras de negcios para um outro pas ou regio. Sob esse ponto de vista, tambm
podemos afirmar que qualquer regra de negcio que atenda exclusivamente ao Brasil,
pode ser considerada como uma localizao Brasil.
A localizao de um sistema independe da lngua na qual ele ser executado. Dessa
forma possvel termos um sistema localizado para a Argentina que ser executado
em ingls.
Veja abaixo as principais dvidas sobre o processo de localizar:

O clculo de um determinado imposto de um pas, assim como todas as necessidades


legais que esse imposto estabelece (consultas e relatrios) uma localizao.
O parmetro MV_PAISLOC configura a localizao que foi instalada. Esse parmetro
carrega a varivel pblica cPaisLoc, que pode ser usada nos programas, com a sigla
do pas.
Uma regra de negcio no presente no ERP padro Brasil, mas praticada em outro
pas (de forma genrica por todas as empresas) uma localizao.
Um programa que valide o RUT no Chile (equivalente ao CNPJ/CPF no Brasil) uma
localizao.
Se um cliente na Argentina quiser usar o sistema em portugus, ter todos seus
impostos locais calculados corretamente, uma vez que a localizao independente
da lngua na qual o sistema est sendo usado.
Nem todo mdulo implantado em outro pas deve ser localizado.

Traduzir
A traduo de software verte as mensagens exibidas pelo sistema para outra
lngua. Atualmente o Protheus comercializado em 3 lnguas: Portugus, Espanhol e
Ingls.
O fato do sistema ser executado numa determinada lngua, no significa que o mesmo
possui alguma localizao.

Regras e Padronizao para programao do Protheus

39

Inteligncia Protheus

Como produzir um programa traduzido?


Todas as mensagens que permitam interao com o usurio devero estar traduzidas
para as 3 lnguas na qual o sistema opera. Isto possvel a partir de duas
ferramentas bsicas:

Arquivos header (CH) anexados ao cdigo-fonte


Veja o exemplo abaixo:

Regras e Padronizao para programao do Protheus

40

Inteligncia Protheus
Arquivo PrgExem.ch:

Para criar um fonte traduzido so necessrios:


#Include PrgExem.ch
a chamada do arquivo que contm as tradues das mensagens (strings)
mostradas ao usurio. As constantes (STRs) presentes neste arquivo sero
anexadas aplicao durante a compilao do cdigo-fonte.
STR0001 / STR0002
Constante que ser trocada em tempo de compilao pelo contedo presente no
arquivo PrgExem.Ch. No exemplo mostrado, ao executar a aplicao em Ingls, a
constante STR0001 ser exibida como Value Input.
Importante!!
Observe que no cdigo-fonte existe o comentrio: //Entrada de Valor. Este
apenas um indicativo do que ser mostrado para o usurio. Comentrios deste tipo
so obrigatrios para facilitar a leitura do cdigo-fonte.
Utilize sempre a funo OemToAnsi(STRxxxx) para exibir as mensagens.
A criao dos arquivos CH de tradues feita a partir da ferramenta ATUSX. No
crie diretamente arquivos CH, pois os mesmos no sero traduzidos! A rea de
desenvolvimento pode apenas cadastrar STRs em portugus, as demais sero
traduzidas pela equipe de Tradues atravs da prpria ferramenta ATUSX.

Dicionrio de Dados
Todo o dicionrio de dados do sistema traduzido. Observar os seguintes pontos:
Quando criado um campo novo, ou modificado o contedo de um j existente, os
campos que devem refletir esta alterao nos demais idiomas devem ser deixados
em branco, assim como o pessoal de tradues identifica os campos que devem
ser traduzidos. Isto valido para todos os arquivos do dicionrio de dados.
Quando criado ou alterado um novo HELP (de campo ou de programa) deve ser
informado de imediato para tradues para proceder a traduo para os outros
idiomas.
Regras e Padronizao para programao do Protheus

41

Inteligncia Protheus
Para atualizar um parmetro deve ser sempre usada a funo PUTMV, NUNCA
DEVE SER PREENCHIDO NEM POSICIONADO POR FORA. Esta funo atualiza nos
trs idiomas.
Os novos campos tipo COMBO, devem ser criados com numerao e no com
siglas (1 para sim e 2 para no, ao invs de S para sim e N para no).
Quando for criado um novo parmetro, ou modificado o contedo default de um j
existente, esta modificao deve ser aplicada nas 3 lnguas.
Quando houve a possibilidade de pegar um STR do dicionrio (funo RETTITLE()
), este deve ser pego, o que evita ter que criar vrios STR e tratarmos com a
varivel cPaisLoc dentro do programa. Exemplo CGC, NOTA FISCAL, CEP, etc.
No deve ser usada a acentuao

Como Produzir um programa Localizado


Necessidade de localizar
Quando criado um campo novo de uso exclusivo de Brasil (E1_INSS por exemplo)
deve ser informada a equipe de localizaes para configurar este campo (uso,
browse, etc.) de acordo com os demais paises.
Quando for modificada a caracterstica de um campo do sistema e este estiver
replicado para o resto dos pases, as alteraes devem ser replicadas em todos os
paises. Na dvida da aplicabilidade da alterao nos outros paises, deve ser
informada a equipe de localizaes.

Regras e Padronizao para programao do Protheus

42

Inteligncia Protheus

Processamento Automtico
Rotinas Automticas
O que so?
A cada dia estamos criando rotinas com interface automtica para melhorar a entrada
de dados via outros equipamentos, tais como coletores de dados, interface de outros
softwares, etc. Porm, para nossa prpria portabilidade e utilizao de rotinas
padronizadas, temos adotado o prprio programa standard, contudo sem interferencia
do usurio (digitador). Para tal, criamos um mecanismo onde todos os programas que
necessitem desta regra devem ser capazes de inserir dados de forma automtica.
Abaixo mostraremos como proceder :

Como fazer?
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
Automtica. Este vetor deve, quando da utilizao das rotinas automticas, conter os
dados mnimos necessrios para a atualizao dos arquivos.
Veja a estrutura do vetor a ser enviado para a rotina automtica.
ARotAuto := { cCampo, Contedo, Validao}
Onde
CCampo -> o campo a ser atualizado,
Contedo -> o contedo que cCampo vai receber
Validao -> a validao que cCampo vai receber.
Observao: A Validao pode ser uma funo ou um valor NIL. Se for NIL,
as validaes a serem utilizadas para o respectivo campo sero as existentes
no SX3. Se as validaes no forem as do SX3, elas devem ser passadas
numa funo.
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 } }

Regras e Padronizao para programao do Protheus

43

Inteligncia Protheus
Para o processo de incluso simples, sem getdados, a varivel padro a ser utilizada
nos programas chama-se aRotAuto, e para processo de incluso com cabealho e
itens, as variveis a serem utilizadas so: aAutoCab para o cabealho, e aAutoItens
para os itens da getdados.
Para uma incluso simples, tomar como exemplo o MATA250.PRX. Para uma incluso
com cabealho e tem, tomar como exemplo o CONA050.PRX.

Schedule
Recomendao: Processos longos, que no dependem de interferncia de usurio, recomendamos que
sejam executados como JOB (Reprocessamentos, acertos, etc). Motivo: Se durante o processamento a
conexo entre Protheus Remote e Protheus Server cair, ocorrer perda do resultado do processamento, ou
gerar inconsistncias na base de dados.

Regras e Padronizao para programao do Protheus

44

Inteligncia Protheus

Processos de Integrao
Em construo

Regras e Padronizao para programao do Protheus

45

Inteligncia Protheus

Customizaes
Pontos de Entrada
O que so?
Os pontos de entrada tem por objetivo deixar o sistema flexivl, permitindo uma
grande variedade de desenvolvimento pelos nossos analistas de suporte de acordo
com a necessidade de cada tipo de cliente/implantao.

Quando criar?
Avaliar com critrio a criao do Ponto de Entrada, pois importante inseri-lo num
ponto que seja til, no redundante e que realmente d condies de atender ao
solicitante.
O Ponto de entrada no pode ser usado como uma ferramenta de correo de
eventuais falhas do sistema.
Em processos crticos do sistema NO devem ser criados pontos de entrada, pois
poder tornar os resultados do sistema totalmente imprevisveis.
Todo novo ponto de entrada deve ser documento no DEM.

Utilizao
Duas funes so primordiais e obrigatrias para o funcionamento de um ponto de
entrada:
ExistBlock(): Verifica a existncia ou no do ponto de entrada no repositrio. Sua
utilizao obrigatria, e deve condicionar a execuo do ponto de entrada. O seu
retorno poder ser .T. no caso do ponto de entrada existir ou .F. caso contrrio.
ExecBlock(): Executa o ponto de entrada. O ideal efetuar o teste da existncia
do mesmo pela funo Execblock(), antes de tentar a sua execuo.
Function TMKA010()
Local lRet := .F.
Local lPE := Existblock("TMKMCl")
If lPE
lRet := Execblock(TMKMCI,.F.,F.,{aValor})
Endif
Return(lRet)
Importante!
Efetuar o teste da existncia apenas uma vez no cdigo-fonte, para no sobrecarregar
o processamento.

Regras e Padronizao para programao do Protheus

46

Inteligncia Protheus

Semforo
O controle de Semaforo permite que o sistema controle a Numerao Automtica de
Documentos On Line. Temos basicamente 3 funes que gerenciam o controle do mesmo. So
elas :

GETSXENUM( EXPC1) -> Obtem o nmero sequencial do alias especificado no parmetro.


ROLLBACKSXE -> Descarta o nmero pendente do semforo. usado quando o usurio
cancela a operao (o numero no aproveitado).
CONFIRMSXE -> Confirma o nmero sugerido. Esta funo deve ser chamada quando da
confirmao da gravao do registro.
MAYIUSE -> Checa fisicamente se um determinado arquivo existe. O arquivo poder conter
o nmero sequencial.

Obs : A funo GETX8NUM executa a prpria GETSXENUM.

Regras e Padronizao para programao do Protheus

47

Inteligncia Protheus

Desenvolvendo Telas
A padronizao de telas de fundamental importncia na linha de aprendizagem de
utilizao do sistema, pois se voc aprender a utilizar um cadastro, saber utilizar
todos os outros.

Interfaces do Protheus
No decorrer das verses e releases do produto Microsiga, as interfaces sofreram
modificaes para receber melhorias e visuais diferenciados. Exemplo da evoluo:
Abaixo temos, respectivamente, a mesma tela de cadastro de Bancos nas Interface
Classic (AP6), Ocean (AP7) e Flat (MP8).

Independente da evoluo de interface, o produto mantem seus facilitadores de


padronizao, ou seja, componentes de cdigo que se adaptam tecnologia e
prpria mudana de interface. Alguns exemplos deles so: mBrowse(), Enchoice(),
MsGetDados() etc.

Regras e Padronizao para programao do Protheus

48

Inteligncia Protheus

Browses
mBrowse()

A mBrowse() um dos modelos mais comuns e , praticamente, utilizado por todos


os cadastros no sistema. Ela oferece alguns recursos como:
o Cores para classificao dos registros e montagem da legenda
o Pesquisa por qualquer indice da tabela em uso
o Organizao por qualquer campo chave (indicado pela seta ao lado do
campo nas colunas), bastando clicar na coluna para mudar a ordem
o Filtro de usurio (mostrado no rodap do browse)
o Configurao (seleo de colunas para exibio, restaurao do browse
original e opo para no exibio do browse)
Exemplo: Cadastro de bancos.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

49

Inteligncia Protheus
MarkBrow()

A MarkBrow() utilizada para browses onde necessrio fazer uma seleo de


elementos para posterior processamento. Geralmente precedida por um grupo de
perguntas onde sero filtrados os dados a serem exibidos.
Exemplo: Gerao das cotaes de compra.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

50

Inteligncia Protheus
TWBrowse()

A TWBrowse() permite construir um objeto browse similar ao MarkBrow() apresentado


anteriormente, porm com a possibilidade de junt-lo a uma tela com outros
componentes de exibio e entrada de dados.
Exemplo: Reconciliao Bancria.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

51

Inteligncia Protheus

Perguntas
Pergunte()

A Pergunte() o facilitador para criao de perguntas. Seja para obter um filtro de


browse ou para determinar parmetros de um relatrio ou processamento, ela se
baseia no grupo informado e previamente cadastro na tabela SX1. As propriedades
desse componente so:
o Gerar gets conforme o tipo de campo: data, numero, caracter e combo
box (lista de opes).
o Armazenar a ultima resposta informada (SX1). A partir da verso 8.11
essa informao por usurio (profile).
o Permitir exibir help por pergunta (rodap)
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

52

Inteligncia Protheus

Entrada de Dados
Enchoice()

A Enchoice() o modelo mais utilizado para realizar a manuteno de cadastros do


sistema. Seja na incluso, alterao, consulta ou excluso, este componente pode ser
usado para manipular os campos de uma tabela de dados definida no dicionrio
(SX3). Algumas das propriedades so:
o Disposio e alinhamento automtico dos campos em duas colunas
seguindo a ordem definida no dicionrio de dados SX3.
o Destaque de campos de preenchimento obrigatrio e bloqueio para
campos somente de leitura.
o Agrupamento de campos por painis, definidos no arquivo SXA e
associados em cada campo do dicionrio.
o Considera os tipos de campos e suas propriedades (calculadora para
nmeros, calendrios para datas, listas de opes, F3-pesquisa em
outras tabelas etc)
o Aplicao das propriedades dos campos de dicionrio (x3_relacao,
x3_usado, x3_valid, x3_cbox, x3_f3 etc) e permite o uso de gatilhos
(SX7)
Regras e Padronizao para programao do Protheus

53

Inteligncia Protheus
Exemplo: Manuteno do cadastro de Produtos
Para cadastros simples, pode ser utilizado o facilitador AxCadastro(), o qual j monta
um browse (mBrowse citado anteriormente) considerando as opes de incluso
(AxInclui), alterao (AxAltera), consulta (AxVisual) e excluso (AxDeleta). O
componente Enchoice() utilizado por todas essas opes para a montagem da tela.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

54

Inteligncia Protheus

MSGetDados()

A MSGetDados() o componente mais utilizado para a construo de grids de


digitao/exibio. Algumas das propriedades so:
o Incluso, alterao e excluso de linhas
o Incluso de nmero sequencial automtico (identificador de item)
o Considera os tipos de campos e suas propriedades (calculadora para
nmeros, calendrios para datas, listas de opes, F3-pesquisa em
outras tabelas etc)
o Validao por linha e validao aps todo o preenchimento
o Aplicao das propriedades dos campos de dicionrio (x3_valid, x3_cbox,
x3_f3 etc) e permite o uso de gatilhos (SX7)
Exemplo: Itens do Pedido de Compras
Ao compor uma tela, alm da rea de linhas ou itens -MSGetDados()-, comum
definir-se um cabealho ou rodap. Para esses casos existem dois facilitadores: a
Modelo2() e a Modelo3(). Ambas esto definidas no programa matxatu.prx e podem
ser usadas como referncia.
A Modelo2() capaz de criar uma tela com cabealho fixo (campos passados atravs
de um array), um grid de itens MSGetDados() - e um rodap (campos tambm
passados atravs de um array)
A Modelo3() difere da Modelo2() na construo do cabealho, pois permite um
cabealho obedecendo as regras de uma Enchoice() referente alguma tabela do
dicionrio de dados.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

55

Inteligncia Protheus

Componentes Individuais
TSay()
Componente que permite a exibio de algum texto
na tela, podendo ser definida a posio, tamanho,
picture, cor, estilo de fonte a ser usado, entre
outros.
Exemplo: Consulta Histrico do Produto

TGet()
Permite a construo de um elemento de entrada de
dados, podendo-se definir: posio de tela especfica,
estilo de fonte, cor, picture de entrada, validao, entre
outros.
Exemplo: Tela de Filtro
Apontamentos no PMS

para

gerenciamento

de

TComboBox() e TListBox()
O TComboBox() e o TListBox()
permitem a construo de um
elemento de entrada de dados com
uma lista de opes pr-definida. A
diferena entre eles que o
TComboBox() ocupa menos espao na tela, sendo que a sempre
h uma opo da lista pr-selecionada, por default. J no
TListBox() pode-se definir o espao de forma a visualizar parte
ou todas as opes disponveis.
Exemplos: Compensao entre Carteiras e Cadastro de perguntas customizadas por
usurio

TCheckBox()
Permite a construo de um elemento de entrada de dados com
uma lista de opes, onde pode ser selecionado uma, mais de
uma ou nenhuma opo atravs de uma marca.
Exemplo: Opes do Fluxo de Caixa

Regras e Padronizao para programao do Protheus

56

Inteligncia Protheus
TButton() e SButton()

Permite a construo de botes na tela. Pode ser definida: posio, tamanho, texto e
estilo de fonte para o TButton() ou tipo pr-definido para o SButton(), ao, entre
outros.
Exemplos: Botes da Consulta Histrico de Produtos e Botes da Manuteno de
Estrutura de produtos.

TPanel()
Componente que permite a construo de um
painel para separar, agrupar, organizar grupos
de textos, browses, entrada de dados,
perguntas etc.
Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

57

Inteligncia Protheus

Mensagens
Aviso()
A funo Aviso() gera uma mensagem onde podem ser definidos:
o O ttulo
o O corpo da mensagem
o Os botes de resposta
Os botes a serem exibidos so
definidos em um array. A funo
retornar o ndice do array conforme a
escolha feita. No exemplo, retornar 1
caso seja escolhida a opo Confirma
e 2 caso seja escolhida a opo
Abandona.

Help()
A funo Help() utilizada, geralmente, para mensagens de alertas ou erros, onde
pode ser definida uma soluo para um determinado problema. Ela tambm usada
como default dos helps de campo presentes no
sistema. As descries dos problemas e sulues para
todos os helps so carregados na instalao ou
atualizao de verso. Tambm possvel, via
programa, criar novos helps utilizando a funo
PutHelp().
A funo Help() permite que se defina:
Qual help ser utilizado (para trazer a descrio do
problema e soluo para a tela)
Complemento da mensagem
Linha e coluna onde ser exibido o complemento da
mensagem

Regras e Padronizao para programao do Protheus

58

Inteligncia Protheus

MsgNoYes(), MsgStop(), MsgInfo() e MsgAlert()

Este grupo de mensagens exibem, atravs de smbolos, o alerta respectivo para cada
tipo:
MsgNoYes() - Tipo escolha/pergunta (opes Sim ou No retorno boleano)
MsgStop() - Tipo parada/erro (opo Ok)
MsgInfo() - Tipo informao (opo Ok)
MsgAlert() - Tipo ateno/alerta (opo Ok)

MSAguarde()
A funo MsAguarde() utilizada,
geralmente, na execuo de processos
forma
que
seja
mostrada
uma
mensagem de incio do processo. Aps
exibio inicial pode-se controlar o
progresso
do
processamento.
Tal
progresso pode ser exibido na tela
atravs do uso de outras funes como
IndRegua(), SetRegua(), IncProc() e
ProcRegua().

de
essa

MsNewProcess()
A funo MsNewProcess() tem a mesma finalidade da MsAguarde(), com a
possibilidade de controle de um progresso principal - IncRegua1() - e um subprogresso - IncRegua2() -.
Vide Anexo X Exemplos de programas
Regras e Padronizao para programao do Protheus

59

Inteligncia Protheus

Outros Modelos
dbTree()
A funo dbTree() utilizada na visualizao de elementos em forma de rvore. um
facilitador para a exibio de estruturas em nveis, permitindo o uso de imagens para
identificao dos itens e definindo aes no momento do posicionamento em algum
item.
Esta funo utilizada geralmente para conceitos de estrutura de produtos, contas
contbeis, rastreabilidade de processos etc...

Alguns
exemplo
s:
Consulta
de produtos e Consuta de
ambiente de produo

Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

60

Inteligncia Protheus

APWizard()
A APWizard() usada para a elaborao de telas passo-a-passo no sentido de garantir
que determinados procedimentos no sejam esquecidos ou ignorados. Nas telas
passo-a-passo podem ser utilizados quaisquer objetos e habilitar o avano ou
retrocesso dependendo do preenchimento.

Exemplo: Integrao WMS atualizao dos dados de produtos


Vide Anexo X Exemplos de programas

Regras e Padronizao para programao do Protheus

61

Inteligncia Protheus

cones e Legendas
Legendas
As legendas auxiliam na compreenso dos smbolos, cores ou objetos mostrados na
tela sem sua descrio explcita. Alguns exemplos de legendas no sistema:

Exemplo: Legenda na Consulta de ambiente de


produo

Exemplo: Legenda da Carteira


contas a pagar

de

Exemplo: Tela de Legenda/Fase na gerencia de apontamento no PMS

cones
ICONES DA APLICAO
O Protheus possui cones que sempre so os mesmos no importa em que tela se est...
Vide lista de cones no anexo Y
Regras e Padronizao para programao do Protheus

62

Inteligncia Protheus

Desenvolvendo Relatrios
Relatrios Grficos
Em construo

Regras e Padronizao para programao do Protheus

63

Inteligncia Protheus

Pecados da Programao
Excesso de Refresh
Excesso de Refresh nos componentes, principalmente em processamento. Insto inclui
mensagens que ficam metralhando o canal de comunicao , principalmente em
processament.
Exemplo:
Atualizao das mensagens de STATUS com muita freqncia, para informar sobre o
atual status de processamento.
Nada impede que isto seja feito, porm cabe ao programador usar de bom senso para
no fazer notificaes desnecessrias. Para casos de necessidade desta informao na
interface, uma boa sada criar uma varivel local, numrica, e ir incrementando a
varivel, e apenas fazer a notificao da interface quando uma poro significativa de
dados, que justifique a atualizao da interface, tenha sido processada.

SET CENTURY / DATE FORMAT e Loops


Os comandos SET CENTURY ON e SET DATE FORMAT modificam a maneira de
exibio de campos data no cdigo ADVPL e tambm no Protheus Remote. Evitar
chamar os comandos em loops. Motivos: Geram trfego de rede excessivo entre
Protheus Server e Protheus Remote. O mesmo vale para as chamadas __SetCentury(
<x> ), Set( 4 /*_SET_DATEFORMAT*/, <c> ), Set( 5 /*_SET_EPOCH */, <year> )

Begin...End Sequence / Break


Embora no influencie em performance, programar com Begin Sequence / End
Sequence / Break horrvel, e pode trazer efeitos colaterais srios ! As instrues
Begin / End Sequence foram criadas para proteger determinados blocos de cdigo
Advpl, para funes especiais que requerem um tratamento de erro especfico. Deve
ser usado apenas em casos especiais, e SEMPRE que utilizado, DEVE ser escrito com
um tratamento de erro apropriado, que salve e restaure o codeBlock de tratamento
padro em uso!
Programar controlando o desvio de execuo do programa por BREAK no se faz. Os
tratamentos de erro do FrameWork Advpl foram montados partindo da premissa que
um BREAK executado pelo tratamento de erro da LIB, vai cair num RECOVER ou END
SEQUENCE da LIB, e no cai, o que pode acabar engolindo erros de programao,
dependendo do ambiente envolvido.
Exemplo:
Fazer um begin sequence / end sequence, dentro de um bloco transacionado (begin /
end transaction) : Caso ocorra um erro dentro do begin sequence, o BREAK executado
vai cair no End Sequence, e no no End Transaction!

Regras e Padronizao para programao do Protheus

64

Inteligncia Protheus

Interface durante transao


No se deve colocar parada de Interface entre o Begin Transaction e o End
Transaction, como por exemplo, perguntar alguma informao ou deciso ao usurio.
As pr-validaes e entradas de dados para um determinado processamento em
transao devem ser realizadas antes da transao, para que o bloco transacionado
no "pense" ou "valide", apenas "faa", para que seja mnimo o tempo que um ou
mais registros sejam retidos dentro de uma transao.

Transaes muito longas


Uma transao longa no cdigo-fonte, problema na certa. Pense sempre na
possibilidade de transaes mais curtas, a exemplo: Pedido de Venda que era por
bloco e passou a ser por linha. Refora o princpio que zela para que seja mnimo o
tempo que um ou mais registros sejam retidos dentro de uma transao.

Alto acopalhamento com Interface.


Programar entre a criao do objeto do dialogo e o activate dificulta a transformao
da funcionalidade em Web Service. Num conceito mais amplo, vamos enfatizar a
separao entre processamento e interface.

dbGoTop
Fazer DbGoTop() aps abrir uma query totalmente desnecessrio ! Ao ser aberto um
alias de uma query, ele j est posicionado no primeiro registro. Fazer um DbGoTop()
em um alias de Query fora o re-envio da query ao banco, dobrando o processamento
desnecessariamente.

Fontes com economia de IF


Se uma funo retorna um status de sucesso ou falha, isto deve ser tratado. Existem
funes que no abortam a aplicao em caso de insucesso, e retornam um status
justamente para o programador fazer o tratamento adequado. No verificar este
retorno um pecado que, geralmente, apresenta problema em ambientes grandes,
sob concorrncia ou condies adversas. Por exemplo, no verificar o handle de um
arquivo aps usar fopen() / fcreate(), no verificar se um DbSeek() realmente
posicionou no registro procurado, etc ...

Regras e Padronizao para programao do Protheus

65

Inteligncia Protheus

* em querys
Evitar o uso de * em querys. Usar somente em casos extremos e de real necessidade,
pois eles oneram a performance da instruo, trazendo campos que nem sempre so
necessrios, gerando um trafego de rede maior. E, existe um limite de numero
mximo de campos retornados em uma query ( aqui verificar ). Se voc precisa de
mais campos do que isso, mais eficiente a sua query retornar apenas os
R_E_C_N_O_ (s) dos registros selecionados, e os dados serem lidos diretamente do
alias correspondente, sendo realizado o posicionamento atravs da instruo
DbGoto()

Objetos visuais
Objetos visuais em loops
O uso de propriedades ou mtodos visuais em loops gera trfego de dados
desnecessrio entre Protheus Server e Protheus Remote. Exemplo:
While SD2->( !Eof( ) )
nVal:= nVal+SD2->D2_VAL
oSay:VarPut( nVal ) << EVITAR
SD2->( dbSkip() )
End
...
While SD2->( !Eof( ) )
nVal:= nVal+SD2->D2_VAL
SD2->( dbSkip() )
End
oSay:VarPut(nVal) << MELHOR

Objetos visuais e o End()


No utilizar propriedades ou mtodos de objetos visuais de uma janela aps a
chamada do mtodo End( ) da janela, pois aps a chamada do mtodo End( ) de uma
janela, todos os componentes visuais internos contidos na janelas ficam invlidos (so
destrudos). Exemplo:
// No utilizar
@ 10,10 BUTTON oBtn "Fechar" ACTION ( oDlg:End(), nVal:= Len( oLbx:aItems ) )
// MELHOR
@ 10,10 BUTTON oBtn "Fechar" ACTION ( nVal:= Len( oLbx:aItems ), oDlg:End() )

No chamar o mtodo End( ) de uma janela no comando ON VALID da mesma janela,


pois o programa entrar em Loop e causar erro STACK OVERFLOW.
Regras e Padronizao para programao do Protheus

66

Inteligncia Protheus
Objetos visuais em Jobs
Nunca utilizar codificar componente visuais em rotinas que sero executadas em
JOBs. Motivo: Ir gerar um erro de execuo do programa. Solues:
Retirar toda construo de janela ou chamada a funes que criam janelas ou
chamam Alert( ), MsgBox( ) das rotinas que sero executadas em JOBs.
Testar a execuo de rotinas em JOBS com a funo GetRemoteType( ), se a funo
retornar -1 a rotina est dentro de um JOB.

MSAdvSize() e dimenses de janela


Evitar o uso da funo MSAdvSize( ) para obter as dimenses de uma janela. Motivo:
A funo no funciona bem em ambiente MDI e ActiveX. Soluo: Organizar a
disposio dos controles visuais com o uso de painis ( TPanel ) e propriedade de
alinhamento de controles nAlign.

Codeblocks em componentes visuais


No incluir codeblocks extensos nos componentes visuais. Motivo: Codeblocks
extensos so muito difceis de debugar. Soluo: Criar uma funo auxiliar que
contenha o contedo do codeblock.

DEFINE DIALOG e ACTIVATE


A definio de uma janela (DEFINE MSDIALOG... ) DEVE ficar dentro da mesma
funo que a chamada de ACTIVATE. Motivo: No pode haver DEFINES de janela em
sequncia, isso gera erro de execuo que extremamente dficil de debugar em
ADVPL.

Funes em ON INIT
No incluir chamadas de funo para rotinas de longa durao no mtodo ON INIT
das janelas. Motivo: Pode dar uma falsa impresso de que a janela travou. Soluo:
Mova a rotina para antes do incio da construo da janela e use a funo ProcRegua()
e IncProc() para exibir uma janela com uma rgua de execuo.

DBTree
Nos programas com DBTREE, NO MANIPULEM o arquivo de trabalho do
componente. Motivo: O DBTREE pode apresentar comportamentos no definidos e que
so extremamente dficeis de debugar.

Regras e Padronizao para programao do Protheus

67