Stored procedures no Protheus: instalar, conferir e quando usar

Algumas rotinas pesadas do Protheus têm dois caminhos para o mesmo trabalho: um em AdvPL e outro em stored procedure, executado dentro do banco. A rotina verifica se a procedure está instalada; se estiver, usa; se não estiver, segue pelo AdvPL. Instalar as procedures é tarefa do Configurador, na rotina Stored Procedures (CFGX051), no menu Base de Dados | Dicionário | Stored Procedure, e só o administrador consegue abri-la.

Ou seja: sem procedure, a rotina não para. Ela só deixa de usar o caminho que foi escrito para rodar no banco.

Quais rotinas usam

Rotinas de processamento em lote, que varrem um período inteiro de movimentos. Alguns exemplos do padrão que verificam a procedure antes de processar:

O motivo de existirem é o mecanismo: a procedure faz o trabalho dentro do banco, sem trazer registro por registro para o servidor de aplicação e devolver depois. Em rotina que passa por todos os movimentos do mês, é aí que o tempo vai.

O MATA330 é um bom exemplo de como o padrão decide. Antes de processar, ele verifica um conjunto de procedures e só segue pelo caminho do banco se todas estiverem instaladas. Faltando uma, o recálculo vai pelo AdvPL.

É por isso que a instalação é por processo, e não procedure a procedure. Recomendação: instale o processo completo das rotinas que a empresa usa e confira depois (as consultas estão no fim deste artigo).

Dois gerenciadores

A rotina do Configurador mudou. Hoje existem dois modelos, e o menu chama o mesmo CFGX051 para os dois: é a própria rotina que decide para qual interface seguir.

O StartPath é a chave do appserver.ini que indica a pasta de onde o gerenciador antigo lê os arquivos .SPS.

Sobre o gerenciador antigo, o que a rotina faz:

• Pergunta a ação: instalar, desinstalar ou consultar.
• Identifica o banco em uso e escolhe o dialeto das procedures. Se o banco não tem dialeto disponível, avisa e para.
• Instala para cada empresa selecionada: procedure é por empresa.
• Registra cada procedure instalada numa tabela de controle, a TOP_SP.

No novo, tudo fica numa janela só, com todas as empresas do ambiente: você marca as empresas e os processos e instala ou remove de uma vez, sem trocar de empresa.

A ordem do trabalho, do RPO até o log da instalação.

1. Aplicar os dois patches

A documentação do gerenciador novo lista dois pré-requisitos, antes de abrir a rotina:

1. Patch mais recente da Central de Atualizações. Mesmo quem não usa a Central precisa aplicá-lo. Nas palavras da TDN, ele é “imprescindível pois atualizará o RPO com a nova interface e suas funcionalidades”.
2. Patches de Expedição Contínua dos módulos que têm processos de procedures. São eles que trazem para o RPO os pacotes .ZSPS e as rotinas ligadas às procedures. A TDN diz que a aplicação “é obrigatória, caso contrário poderão ocorrer erros durante a instalação/desinstalação de processos”. Os links de cada versão estão na página Stored Procedures - Novo gerenciador de pacotes, na TDN.

2. Abrir a rotina como administrador e migrar

Com um usuário administrador (a rotina recusa os demais), abra Base de Dados | Dicionário | Stored Procedure. A rotina mostra uma tela de migração com quatro botões: Documentação, Manter (segue no modelo antigo, que não recebe mais atualização), Atualizar (faz a migração) e Fechar.

A Central de Atendimento avisa que essa tela depende do primeiro patch: “Esta interface contendo as opções será apresentada somente se o patch da Central de Atualizações […] foi aplicado corretamente no ambiente”. Se a tela não aparece, confira esse patch antes de qualquer outra coisa.

Clique em Atualizar. Ao fim da migração, a nova interface é apresentada, e a tela de migração não aparece mais. A migração cria as tabelas de controle do modelo novo (prefixo TPH_), acrescenta colunas à TOP_SP e não pode ser desfeita. Nas palavras da TDN: “após migrado não será possível voltar ao modelo antigo”. Recomendação: planeje como uma atualização de dicionário — backup antes, janela sem usuários durante, conferência depois.

Na interface principal:

1. Selecione em quais empresas os processos serão instalados.
2. Selecione os processos.
3. Clique no botão de instalar processos.
4. Confirme a janela de avisos. A instalação só ocorre se os processos selecionados não estiverem em uso por outra rotina naquele momento.

De onde vem o pacote depende da integração com a Central de Atualizações. On-line, a instalação usa o pacote homologado mais recente disponível nela, desde que seja mais recente que o do RPO; off-line, usa o .ZSPS que está no RPO. Se o processo não tem .ZSPS no RPO, é preciso aplicar um patch que o contenha. A Central não é obrigatória: sem ela, a rotina funciona normalmente, mas compara o instalado só com o pacote do RPO, o status da rotina AdvPL nos detalhes fica sempre não avaliado e o log de operações não traz o link para baixar o patch indicado.

4. Ler o resumo e as linhas de erro

Ao fim, a rotina mostra um Resumo com o total de operações, Sucessos, Ignoradas e Falhas; o botão Ver detalhes abre o detalhamento. No histórico de operações, cada tarefa tem um tipo: [INFO], [OK], [SKIP] (ignorada) ou [ERRO]. Numa linha [ERRO], o log traz o texto “Duplo clique em Memo para detalhes”: o duplo clique na coluna Detalhes mostra a mensagem completa. Alguns erros, como os de assinatura incompatível, trazem a causa e a solução proposta ali mesmo, e a documentação recomenda sempre verificar as ocorrências do tipo [ERRO]. Ao fechar o resumo, a interface principal é atualizada com o status atual.

O procedimento é o mesmo, com o botão de desinstalar. Também exige que os processos não estejam em uso e ainda precisa de acesso exclusivo a algumas tabelas do banco.

A descrição do parâmetro ocupa três colunas; X6_DESCRIC sozinha traz só o começo da frase:

SELECT X6_FIL, X6_VAR, X6_TIPO, X6_CONTEUD,
       X6_DESCRIC, X6_DESC1, X6_DESC2
  FROM SX6010
 WHERE X6_VAR = 'MV_DROPPE'
   AND D_E_L_E_T_ = ' '

Os status depois da instalação

Cada processo aparece com um status por empresa, entre eles atualizado, desatualizado, não instalado, não avaliado e incompatível.

O status que mais assusta é o que menos exige ação. Desatualizado só quer dizer que existe pacote mais novo; a procedure continua sendo usada normalmente pela rotina, e a documentação diz que a atualização não é obrigatória nem urgente.

Não avaliado quer dizer que o processo instalado não pôde ser comparado nem com o RPO nem com a Central. A documentação aponta duas situações: a conexão com a Central caiu ou não existe, e não há .ZSPS do processo no RPO (nenhum patch com os pacotes foi aplicado, ou o arquivo foi apagado do RPO). A solução é conferir a conexão com a Central, aplicar o patch com o .ZSPS do processo e reabrir a tela para o status ser analisado de novo. Não é preciso reinstalar o processo.

Incompatível é o que impede o uso: as assinaturas do processo e da rotina AdvPL não batem, e a rotina não pode usar as procedures até as assinaturas serem compatibilizadas. Quem executa a rotina recebe uma mensagem de incompatibilidade entre a rotina AdvPL e o processo. Segundo a TDN, essa checagem roda sempre que uma procedure é acionada pelo sistema e não há como evitar a mensagem enquanto houver incompatibilidade. A saída depende de qual lado está atrás:

Se as assinaturas continuarem incompatíveis depois disso, a TDN orienta acionar o suporte.

Existe ainda a opção Forçar utilização de pacotes .ZSPS contidos no RPO, nas configurações adicionais da rotina. Com ela marcada, a instalação usa o pacote do RPO mesmo que não seja o mais recente, o que resolve a incompatibilidade quando o pacote do RPO tem a mesma assinatura da rotina. A TDN pede para “LER COM MUITA ATENÇÃO ANTES DE UTILIZAR ESTA OPÇÃO”: antes, confira nos detalhes do processo se as assinaturas da rotina e do pacote do RPO são compatíveis, porque, com a opção ativa, o processo pode terminar desatualizado ou incompatível, conforme os pacotes presentes no RPO e na Central.

No gerenciador antigo, a tabela de controle TOP_SP é criada e preenchida pela própria instalação, com uma linha por procedure instalada. A migração para o novo mantém a tabela e acrescenta colunas:

SELECT SP_NOME, SP_VERSAO, SP_DATA, SP_HORA, SP_ASSINAT
  FROM TOP_SP
 ORDER BY SP_NOME

Cuidado com SP_DATA e SP_HORA: o instalador grava ali a data e a hora lidas do cabeçalho do próprio script, e não o momento da instalação. Uma procedure instalada hoje a partir de um pacote antigo grava a data do pacote. Servem para saber de que pacote veio cada procedure.

No gerenciador novo, a conferência começa pela própria tela: a legenda de status por processo e empresa. Um duplo clique no processo abre os detalhes, com o identificador do pacote (IDSPS), a data e hora e a assinatura do pacote instalado, do que está no RPO e, on-line, do que está na Central de Atualizações. IDSPS negativo no instalado indica processo legado, instalado antes da migração, e não é erro. O histórico de operações mostra cada instalação e desinstalação, com os erros, e gera o Relatório de Log, que pode sair em planilha para mandar ao suporte. A TOP_SP serve de apoio.

O registro do Protheus diz o que ele instalou; o catálogo do banco diz o que existe de fato. No SQL Server:

SELECT ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE
  FROM INFORMATION_SCHEMA.ROUTINES
 ORDER BY ROUTINE_NAME

Rode com um usuário que só lê — veja Usuário somente leitura no SQL Server. Em outros bancos, o catálogo é outro. Em bancos como Oracle, DB2 e MySQL, algumas das “procedures” são criadas como função: por isso a consulta acima não filtra pelo tipo.

Se o registro do Protheus e o catálogo do banco discordam, o que o Protheus acha que está instalado não é o que existe. Recomendação: reinstale pelo gerenciador, em vez de criar ou apagar procedure direto no banco — é o gerenciador que escolhe o dialeto e mantém o registro em dia.

As outras rotinas do Configurador estão no mapa do começo da série: Configurador do Protheus.