MsExecAuto: como descobrir por que a rotina falhou

Uma integração que devolve apenas “erro ao incluir” obriga alguém a repetir o processo para descobrir o motivo. Essa repetição pode gerar outro erro, apagar a evidência anterior ou duplicar um documento. Um diagnóstico melhor começa no desenho da captura, antes do primeiro lote.

Existem falhas em etapas diferentes

Uma falha de conexão pode ocorrer antes de qualquer regra de negócio; uma validação funcional pode recusar um dado durante a execução; uma chamada inexistente pode interromper tudo com erro fatal. Os três casos exigem informações diferentes.

lMsErroAuto não é um detector universal de tudo que pode falhar no Protheus: a documentação descreve seu papel só para erros não fatais da rotina automática. Se o processamento interrompe antes da verificação final, olhar somente essa variável não basta.

Por isso, registre início e término do processamento de cada item. Se existe início sem término, essa ausência é uma informação importante para investigar a aplicação, a thread e o contexto da chamada.

O mecanismo por trás dessas variáveis está em AutoGRLog(): ela só alimenta __aErrAuto — o array que GetAutoGRLog() devolve — dentro de um If ( Type('lAutoErrNoFile') == 'L' ) .And. ( lAutoErrNoFile ), seguido de um Return que interrompe a função ali mesmo. Nenhuma outra rotina nativa escreve nesse array. Daí duas consequências que a variável de controle decide sozinha: sem lAutoErrNoFile := .T., GetAutoGRLog() devolve um array vazio sempre — a execução segue para o MSFCreate e grava só o .log padrão; e com a variável ligada, esse .log nunca é gravado, porque o Return acontece antes de a função chegar lá. Os dois caminhos são mutuamente exclusivos — uma execução usa um ou o outro, nunca os dois.

Esses controles precisam existir no escopo esperado pela rotina. Não basta criar nomes parecidos como variáveis locais e presumir que o framework passará a enxergá-los. Configure o contexto conforme o exemplo oficial e a rotina automática concreta que será executada.

Também evite presumir que um lote inteiro compartilha estado sem reinicialização. O erro de um item deve ficar ligado àquele item, não ao próximo — e a limpeza só pode ocorrer depois de preservar a evidência anterior.

GetAutoGRLog() copia o array interno de mensagens, esvazia esse buffer e devolve só a cópia — a chamada se comporta como uma leitura que consome o que lê, não como uma consulta que se repete sem custo.

Assim, duas chamadas consecutivas não são duas consultas independentes ao mesmo histórico. A primeira pode consumir o conteúdo que a segunda esperava encontrar. Capture uma vez e reutilize o resultado:

// Fragmento: executar no contexto de captura configurado para a rotina.
// aLog deve estar declarada no escopo do chamador.
aLog := GetAutoGRLog()

Use aLog para montar a resposta, registrar a evidência e apresentar o diagnóstico. Não chame novamente a função em cada uma dessas etapas.

Existe também uma função irmã que não consome nada: VarAutoLog() devolve __aErrAuto direto — sem AClone, sem zerar. Ela serve exatamente para inspecionar o array sem gastar a única leitura que GetAutoGRLog() permite: quando lAutoErrNoFile está ligada, é VarAutoLog() quem deve responder por essa consulta, não uma segunda chamada a GetAutoGRLog().

Mensagem de negócio e log técnico têm leitores diferentes

Para quem enviou o pedido, uma mensagem útil identifica o item recusado e o dado a conferir. Para quem mantém a integração, também são necessários horário, identificador de correlação, rotina acionada, etapa e mensagens completas.

Uma resposta ilustrativa seria: “O item 2 do envio de demonstração foi recusado. Consulte as mensagens de validação associadas ao identificador TESTE-002.” Isso é melhor que afirmar uma causa que o sistema ainda não confirmou.

Não devolva senha, token, string de conexão ou log irrestrito a um consumidor externo. O registro técnico pode ter acesso controlado; a resposta da integração mostra só o necessário para corrigir o envio.

Quando o erro envolver um lote, comece com um registro de demonstração que passe e outro que reproduza a falha. Compare seus dados com o contrato da rotina automática: nomes, tipos, valores obrigatórios e operação solicitada.

Se a inclusão interativa funciona, isso é uma referência, não prova de equivalência com ExecAuto — defaults da tela, preparação de ambiente e caminhos de pontos de entrada podem divergir. Registre a diferença identificada, em vez de atribuir tudo à automação.

Uma alteração por tentativa facilita o diagnóstico: mudar cadastro, parâmetro, código e payload de uma vez pode fazer o caso funcionar sem explicar qual intervenção resolveu o problema.

Antes de tentar novamente, confirme o estado

Um erro no final do fluxo não prova que nada foi gravado: verifique os documentos produzidos e a estratégia transacional da rotina escolhida. Não envolva toda chamada numa transação genérica só porque o exemplo de outra rotina fazia isso.

Se a integração admite reenvio, desenhe como reconhecer uma solicitação já processada — o número da tentativa precisa ser diferente da identificação de negócio, já que uma tentativa nova pode corresponder à mesma solicitação original.

Esse cuidado vale também para serviços externos acionados por customizações: uma transação de banco não desfaz automaticamente um e-mail enviado ou uma requisição aceita por outra aplicação.

O que guardar ao encerrar o diagnóstico

Guarde a entrada mínima de demonstração, o resultado esperado, a evidência capturada, a correção aplicada e a versão do ambiente. O próximo erro semelhante vira comparação com um caso conhecido, não investigação do zero.