Padrões e convenções de codificação em Centura Desenvolvimento Pirâmide ERP

Agenda Introdução Padrões de codificação Tratamento de erros Nomenclaturas Componentes visuais Convenções Tratamento de erros

Introdução Objetivo Documento referência (completo/detalhado) Apresentar os padrões básicos para o desenvolvimento dos sistemas que utilizam o Centura como linguagem. Documento referência (completo/detalhado) DA.07.Codificação em Centura Padrões abordados Pir21 Módulos: Faturamento e Integração Pirâmide Módulos: Comercial, Financeiro, Fiscal, Materiais, Orçamento, Qualidade, ...

Introdução Arquivos Tipo de arquivo Função Libraries (*.apl) Serão denominados a partir de agora de Apls. Nelas são desenvolvidas todas as funcionalidades, telas, classes, etc. Cada Apl deve conter apenas uma funcionalidade, de forma a facilitar a manutenção. Text (*.apt) Serão denominados a partir de agora de Apts. São os arquivos utilizados para geração de executáveis. Cada módulo do sistema tem seu respectivo Apt.

Padrões de codificação

Padrões de codificação Nomenclatura de arquivos Tipo de arquivo Nomenclatura Apls Deve fazer referência ao nome da funcionalidade que ela possui. Exemplos: AjudaContexto.apl Pedido.apl Apts Devem fazer referência ao nome do módulo. Exemplos: Integração.apt Ativo.apt

Padrões de codificação Nomenclatura de variáveis Padrão Sintaxe Pir21 <prefixoDoEscopo>_<prefixoDoTipo>NomeVariavel Piramide <prefixoDoEscopo><prefixoDoTipo>NomeVariavel Escopo Pir21 Piramide Global do Sistema g Global do Form w Local (funções) l Param. Entrada p Param. Saída r Tipo Pir21 Piramide Number n Date/Time dt String s Sql Handle hSql File Handle hFile Long String ls Array a<tipoDado> Window Handle h Objetos o tob Objetos Proxy p

Padrões de codificação Nomenclatura de componentes visuais Componente Pir21 Piramide PushButton pb Scrollbar Horizontal hsb Scrollbar Vertical vsb CheckBox cb RadioButton rb DataField df MultilineText ml Background Text GroupBox gb Table tbl Column col ListBox lb ComboBox cmb ActiveX ax

Padrões de codificação Nomenclatura de constantes Nomenclatura de funções Tipo da Constante Pir21 Piramide Mensagens PFM_NomeMsg PAM_NomeMsg Negócio BOC_NOMECONSTANTE NOMECONSTANTE Sistema PFC_NomeConstante Atributos de Classe BOA_<Função>_NomeAtributo Erros de Sistema PFE_NomeErro Err_NomeErro Erros de Negócio BOE_<Módulo>_NomeErro Mensagens de Erro PFE_Msg_NomeErro Tipo da função Pir21 Piramide Interna PFNomeDaFuncao Gx_NomeDaFunção Externa NomeDaFunção fNomeDaFunção

Padrões de codificação Nomenclatura de classes Tipo da Classe Pir21 Piramide Concretas CNomeClasse Interfaces INomeClasse Proxy NomeClasse Visuais W<TipoClasse(2letrasMinusculas)>NomeClasse Negócio BCNomeClasse tobNomeClasse Básicas de Negócio BCBaseNomeClasse Tipo do atributo Pir21 Piramide Classe c_<prefixodetipo>NomeVariável Instância m_<prefixodetipo>NomeDaVariavel Tipo do método Pir21 Piramide Privado __NomeDoMétodo __fNomeDoMétodo Públicos NomeDoMétodo fNomeDoMétodo Virtuais _NomeDoMétodo _fNomeDoMétodo

Padrões de codificação Componentes visuais (1/3) Componente Pir21 Piramide Piramide (com icone) PushButton pbBasic pbAlterar pbCancelar pbDetalhar pbExcluir pbGravar pbImprimir pbIncluir pbNext pbOk pbPrevious pbProcurar pbSair pbPadrao pbPadraoAlterar pbPadraoCancelar pbPadraoCopia pbPadraoDetalhar pbPadraoEmitir pbPadraoExcluir pbPadraoGravar pbPadraoImprimir pbPadraoIncluir pbPadraoLancar pbPadraoOk pbPadraoSair pbCliente pbConfigurar pbConfigurarNDO pbCopia pbEmitir pbFormula pbFornecedor pbPagar pbParar pbReceber pbTransfere

cmbSubclasseMaterial Padrões de codificação Componentes visuais (2/3) Componente Pir21 Piramide Column colCodeDesc colDate colHelpContext colLong colNumber colPrimaryKey colString colValorAtributo colChavePadraoNew colCodeDescNew colPadraoNew Combo Box cmbBasic cmbClasseMaterial cmbCodeDesc cmbDeposito cmbDescEmpresa cmbDescFilial cmbDescription cmbSubclasseMaterial cmbTipoMaterial cmbUF cmbPadraoNew cmbCodeDescNew cmbDescEmpresaNew cmbDescFilialNew cmbDescriptionNew cmbPadraoUFNew

Padrões de codificação Componentes visuais (3/3) Componente Pir21 Piramide CheckBox cbBasic cbPadraoNew RadioButton rbBasic rbPadrao DataField dfDate dfLong dfNumber dfString dfPadraoNew dfDate2000New MultilineText mlDescription mlLong mlString mlPadraoNew BackgroundText bckBasic bckPadrao GroupBox gbBasic gbPadrao Table tblBasic tblPadraoNew List Box lbBasic lbCodeDesc lbPadrao

Padrões de codificação Convenções  SQL Recomendações O nome de campos e tabelas devem estar sempre em caixa alta. As palavras reservadas do SQL devem ser escritas com letra inicial maiúscula. Utilizar os binds (:NomeVariável) nas cláusulas Where que utilizam variáveis como critério. Exemplo: Select CLIENTE From CLIENTES Where CLIENTE = :sCodCliente

Padrões de codificação Convenções  Formulários (Forms) Existem algumas operações básicas que devem ser feitas sempre que um formulário é aberto e fechado: Piramide As operações básicas deverão ser inseridas nas funções fInitializeWindow() e fCloseWindow(). Essas funções serão chamadas respectivamente pelas mensagens SAM_Create e SAM_Close. Pir21 As operações básicas já são implementadas diretamente no SAM_Create e SAM_Close da classe frmBasic (classe a partir da qual são criadas todas as telas deste padrão). As funções InitializeWindow() e CloseWindow() também são chamadas nas mensagens citadas, sendo definidas em métodos virtuais _InitializeWindow() e _CloseWindow(), sendo possível a redefinição destes métodos nas instâncias para algum fim específico.

Padrões de codificação Convenções  Formulários (Forms) Formulários de manutenção simples Os formulários "frmMnt" (padrão Pirâmide) e "frmBasicMnt" (padrão Pir21) devem ser utilizados para cadastros simples, que não envolvam mais de quatro atributos. Para utilizá-los, basta criar as colunas de acordo com a funcionalidade e redefinir os métodos virtuais de seleção, inserção, update e deleção dos dados da tabela.

Padrões de codificação Convenções  Formulários (Forms) Formulário de manutenção simples (padrão Pirâmide)

Padrões de codificação Convenções  Formulários (Forms) Formulário de manutenção simples (padrão Pir21)

Padrões de codificação Convenções  Formulários (Forms) Browser e formulários de manutenção Trata-se de uma tela de navegação a partir da qual podem ser realizadas operações referentes a cadastros ou movimentações); Se o cadastro possuir mais de quatro atributos e não for complexo, oferecendo poucas funcionalidades alem da manutenção (inclusão, alteração, exclusão e detalhamento), uma tela de browser deve ser criada; Outras operações como cancelamentos, impressão, autorizações, entre outras, poderão ser chamadas a partir de botões do browser. (Caso o browser esteja com excesso de objetos visuais ou a operação necessite de filtros específicos, pode-se criar uma tela específica para a operação a ser realizada).

Padrões de codificação Convenções  Formulários (Forms) Browser e formulário de manutenção (padrão Pirâmide)

Padrões de codificação Convenções  Formulários (Forms) Browser e formulário de manutenção (padrão Pir21)

Padrões de codificação Convenções  Classes de sistema Existe uma classe genérica previamente instanciada que pode ser utilizada em qualquer trecho do código. Essa classe genérica agrupa diversas funcionalidades. Convenções  Empresa Existem funções pré-definidas que devem ser utilizadas para recuperar a empresa selecionada no MDIPrincipal. Piramide Pir21 Nome da classe tobPiramide PGlobal Nome da instância tobPir Global Dado Piramide Pir21 Código tobPir.tGetS(“EMPRESA”) Global.GetEmpresa() Nome tobPir.tGetS(“EMPRESA_NOME”) Global.GetEmpresaNome()

Padrões de codificação Convenções  Funções de conexão Principais operações a serem executadas na base dados e as respectivas funções que devem ser usadas: Funcionalidade Piramide Pir21 Abertura de conexão Set hSql = oConexao.fGH() Global.db.GetHandle(w_hSql) Fechamento de conexão oConexao.fFH(hSql) Global.db.FreeHandle(w_hSql) Abertura de transação tobPir.tBeginTransaction() Global.db.BeginTransaction() Commit de transação tobPir.tEndTransaction() Global.db.EndTransaction() Rollback de transação tobPir.tCancelTransaction() Global.db.CancelTransaction() SQL Handle comum hSqlComum Global.db.GetBasicHandle()

Padrões de codificação Convenções  Recuperação de parâmetros Padrão Piramide Padrão Pir21 Os parâmetros globais devem ser recuperados através da PGlobal: Global.param.GetParam(“NOME_PARAMETRO”) Para recuperar os parâmetros por empresa, deve-se utilizar um objeto da classe CParametroEmpresa. Uma vez o objeto declarado, deve-se fazer uma carga dos parâmetros, utilizando o serviço LoadParam do objeto. Sintaxe: oParam.LoadParam(sEmpresa, “NOMEPARAM1, NOMEPARAM2, ...”, sOrigem) onde “NOMEPARAM1, NOMEPARAM2, ...”  Lista dos parâmetros que se deseja carregar o valor. Se nulo, carrega todos. sOrigem  Origem à qual pertence o parâmetro. Também é opcional. Feita a carga dos parâmetros, para recuperar seu valor deve-se utilizar o método GetParam() do objeto: Set sValorParametro = oParam.GetParam(“NOME_PARAMETRO”) Tipo do Parâmetro Modo de Recuperação Global fBuscaParam (“NOME_PARAM”, sValorParam) Empresa fEmpresaParam (“NOME_PARAM”, sValorParam) Filial fEmpresaParamP (sEmpresa, “NOME_PARAM”, sValorParam)

Tratamentos de erros

Tratamento de erros O tratamento de erros deve ser feito através do empilhamento da mensagem de erro no momento em que o mesmo acontece e sua posterior exibição na interface. A exibição de mensagens de erro (ou outros tipos de mensagens) nunca deverá ser feita dentro de um objeto de negócio ou dentro de uma transação. As mensagens de erro ficam armazenadas no banco de dados, na tabela PIR_ERROS. No padrão Pir21, a utilização da tabela PIR_ERROS é obrigatória, não sendo permitido a transcrição de mensagens de erro diretamente no código fonte. Para empilhar o erro devem ser utilizadas constantes de erros que indicam o código do mesmo no banco de dados. As mensagens podem receber parâmetros que facilitem o entendimento ou identificação da causa do erro. Isso deve ser feito utilizando o símbolo % precedido de um índice para o parâmetro, conforme exemplo: “Não foi possível gravar o pedido ‘%1’ da filial ‘%2’.” Os parâmetros das mensagens serão passados para funções de empilhamento de erro. Devem formar uma única String, sendo os parâmetros separados por um #. No exemplo acima, caso o erro tenha acontecido para o pedido ‘000123’ da filial ‘001’, a string de parâmetros deverá ser ‘000123#001’.

Tratamento de erros Padrão Pirâmide Padrão Pir21 O empilhamento e exibição dos erros são feitos através do objeto tobPir. As funções deverão sempre retornar TRUE ou FALSE, de forma que a interface identifique a existência ou não de erros e decida se irá exibir ou não a mensagem. If Not fGravarPedido() If Not fGravarPedido() Return FALSE Mostra mensagem de erro. Padrão Pir21 O empilhamento e exibição dos erros são feitos através do objeto Global. As funções deverão sempre retornar constantes de erro, ou a constante PFC_Ok, que indica que a função foi executada com sucesso. O retorno de uma função sempre deve ser testado utilizando-se a função PFFailed(nReturn) ou PFSucced(nReturn), onde nReturn é a constante de erro retornada pela função. Set nReturn = GravarPedido() Set nReturn = GravarPedido() If PFFailed(nReturn) If PFFailed(nReturn) Return nReturn Mostra mensagem de erro.

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método tError do tobPiramide Pode ser utilizada tanto para empilhar quanto para exibir erros, mas não suporta as mensagens de erro gravadas em PIR_ERROS. Quando o erro detectado for erro de banco, o parâmetro pnError deve receber a constante Err_SQL e o handle SQL deve ser enviado para o parâmetro phSqlErro. Ex.: Call tobPir.tError( 0, Err_SQL, '',hSqlComum) Quando o erro detectado for erro de negócio, o parâmetro pnError deve receber a constante de erro correspondente. Estas constantes deverão estar declaradas em Constant.apl. O handle SQL a ser enviado para o parâmetro phSqlErro deve ser hWndNULL. Ex.: Call tobPir.tError(0, Err_ClienteInvalido, '', hWndNULL)   Para exibir erros empilhados: Call tobPir.tError(1,1, 'Erro ao gravar', hWndNULL)

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método tErrorApp do tobPiramide Pode ser utilizada tanto para empilhar quanto para exibir erros, e suporta as mensagens de erro gravadas em PIR_ERROS. Exemplo: Call tobPir.tErrorApp(0, Err_PedidoVenda,'Erro inserindo pedido', ‘000123#001’, ‘fInserPedido’, hWndNULL)

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método __PushPckErro do tobPiramide Deve ser utilizado para empilhar mensagens de erro retornadas por processamento em packages. A exibição da mensagem é feita através da tobPir.tErrorApp. O parâmeto “p_nCode” é o código de erro retornado pela package e o prâmetro “p_sPackage” é o nome da package que retornou o erro. Exemplo: tobPir.__PushPckError(nReturn ,PCK_PIR_TITULO_RECEBER’)

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método Global.PushDBError Utilizado para empilhar erros de banco de dados, normalmente após uma instrução SqlPrepareAndExecute(). Exemplo: Call Global.PushDBError( Global.db.GetBasicHandle())

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método Global.PushAppError Utilizada para empilhar erros, suporta as mensagens de erro gravadas em PIR_ERROS. Exemplo: Call Global.PushAppError( BOE_VEN_PedidoVenda, ‘000123#001’, ‘GravaPedido()’, hWndNULL)

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Método Global.PushPckError Deve ser utilizado para empilhar mensagens de erro retornadas por processamento em packages. Exemplo: Call Global.PushPckError(nReturn , 'PCK_PIR_FATURAMENTO', Global.db.GetBasicHandle())

Tratamento de erros Formas de empilhamento e exibição das mensagens de erro Métodos Global.err.Show() e Global.ShowValidacao() Estes métodos devem ser utilizados para exibição de mensagens de erro no padrão Pir21. O Global.ShowVailidacao() deve ser utilizado no SAM_Validate de objetos, pois já exibe a tela padrão para tratamento de erros de validação.