28112891 boas praticas de programacao advpl

Boas Prticas de Programao Advpl Manual de Regras e Padronizao

Boas Prticas de Programao 1

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


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


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


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


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


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


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:


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.


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.


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:


O cdigo fica mais legvel assim:



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:


Para identar o fonte utilize a tecla 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()


Inteligncia Protheus

Regras e Padronizao para programao do Protheus 14

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

a Array aValores

c Caracter cNomeFornecedor

d Data dDataInicial

l Lgico lContinua

n Numrico nValorConta

o Objeto oMainWindow

x Indefinido xBuffer



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 Utilizar: Entrada de dados / Processamentos A Consulta de dados C Relatrios R Funes genricas do mdulo X

Exemplo:

Cdigo-fonte de incluso de dados do mdulo Gesto de Pessoas -> GPEA010.PRW

GPE famlia de programas do mdulo Gesto de Pessoas A entrada de dados 010 numerao de fonte disponvel .PRW 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 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.



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



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 TRY AS

CATCH THROW

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.



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) //"Sem Contedo lRet := .F. ElseIf cTipoTit = D

Help(" ",1,"CONTINCORR") //"Contedo incorreto lRet := .F. Endif RestArea(aSaveArea) Return lRet



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) ---------- quando vai terminar?? Enddo



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.



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.



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.



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)



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.



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

User

Recipient Policy

Usurio 1

Efetua bloqueio registro 1 da tabela A

Recipient Policy

Tenta bloquear registro 1 da tabela B

User

Recipient Policy

Usurio 2

Efetua bloqueio registro 1 da tabela B

Recipient Policy

Tenta bloquear registro 1 da tabela A

DEAD

LOCK

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.



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 leitura suja a apario de fantasmas, ou seja, a transao T2 l um dado que estava bloqueado por T1. T1, por sua vez, altera o contedo da linha ou at mesmo apaga a linha. Quando T2 for processar alguma informao referente a esta linha ela no existe mais ou seu contedo no mais aquele que foi lido anteriormente.

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



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 ---------- ignorada ExpN1 :=FuncGrava()

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



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 de LOG do banco limitada, e o volume de informaes pode ultrapassar o limite do banco de dados. Por exemplo, devemos controlar a transao de uma nota e no de um conjunto ilimitado de notas para no ultrapassarmos o limite do Log do banco de dados. 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.



Trabalhando com arquivos (Tabelas de Dados)

Conce to de Filial e Compartilhamento de Arquivos i

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.



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



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



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 ndices-padro 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("Selecionando 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 mv_par02 .AND. !SE1->(Eof()) ... dbSetOrder(nIndex+2) dbSeek(M->mv_par02,.T.) While SE1->E1_NUM mv_par02 .AND. !SE1->(Eof()) ...



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. ) //Criando Arquivo ...... dbCloseArea() Ferase(cArqTmp+GetdbExtension()) // Deletando o arquivo Ferase(cArqTmp+OrdBagExt() ) // 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!



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



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 : 'SELECT SE2.E2_PREFIXO,SE2.E2_NUM ' cQuery += 'FROM '+RetSqlTable('SE2')+' SE2,'+RetSqlTable('QEK')+' QEK ' cQuery += 'WHERE SE2.E2_FILIAL= '+xfilial('SE2')+' AND ' cQuery += 'SE2.E2_PREFIXO ''+cPrefixo+'' AND ' cQuery += 'SE2.D_E_L_E_T_ = ' ' ' cQuery += '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



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



Integridade Referencial

Chaves Primrias

Chaves Estrangeiras

Dicas Importantes



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.



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:



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.



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.



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



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.



Processos de Integrao Em construo



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.



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.



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.



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



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



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



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



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)



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



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



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 para o gerenciamento de Apontamentos no PMS

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



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



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



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 de forma que seja mostrada uma mensagem de incio do processo. Aps essa 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().

MsNewProcess()

A funo MsNewProcess() tem a mesma finalidade da MsAguarde(), com a possibilidade de controle de um progresso principal - IncRegua1() - e um sub-progresso - IncRegua2() -. Vide Anexo X Exemplos de programas



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

de produtos e Consuta de ambiente de produo Vide Anexo X Exemplos de programas



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



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 de contas a pagar

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



Desenvolvendo Relatrios

Relatrios Grficos Em construo



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( ), Set( 4 /*_SET_DATEFORMAT*/, ), Set( 5 /*_SET_EPOCH */, )

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!



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 sep

28112891 boas praticas de programacao advpl

Documents