Gerar e validar patch do Protheus pela linha de comando antes de aplicar

Um patch é o jeito de levar fontes e recursos de um RPO para outro sem recompilar no destino. O manual do TDS CLI trata a geração e a validação como ações próprias, e essa separação é o que permite conferir o patch antes de tocar no ambiente que importa. Este texto cobre a geração e a validação; a compilação está em Compilar AdvPL e TLPP pela linha de comando.

Gerar: o que entra e onde o arquivo cai

patchGen executa a geração do patch. Com o authentication no início do mesmo arquivo, a seção fica assim (marcadores entre <> são preenchidos só na hora da execução):

[Autenticar]
action=authentication
server=<HOST>
port=<PORTA>
secure=<0_OU_1_CONFORME_O_SERVIDOR>
build=AUTO
environment=<AMBIENTE_DE_ORIGEM>
user=<USUARIO>
psw=<SEGREDO_INJETADO_SO_NA_EXECUCAO>

[GerarPatch]
action=patchGen
fileResourceList=C:/pragiva-lab/entrega.txt
patchType=PTM
patchName=<NOME_DO_PATCH>
saveLocal=C:/pragiva-lab/patches/

Os parâmetros da ação, segundo o manual:

Duas escolhas excludentes: fileResource ou fileResourceList, e saveLocal ou saveRemote. O manual pede um ou outro, nunca os dois. Se a geração precisar do token de compilação, a seção authorization vem antes dela.

A lista de entrada é o escopo da entrega. Leia-a antes de rodar, como no artigo de compilação: o que não está nela não entra no patch.

Validar: uma ação que não aplica

patchValidate “efetua apenas a validação de um patch, sem efetuar sua aplicação”, segundo o manual. Ela também depende do authentication, então vai no mesmo arquivo (ou em outro, com a própria autenticação) apontando para o ambiente de destino:

[Validar]
action=patchValidate
patchFile=C:/pragiva-lab/patches/<NOME_DO_PATCH>.ptm
localPatch=True

localPatch é True para arquivo local e False para arquivo que está em diretório do AppServer. O manual diz que, se a validação acusar algum problema, o retorno da execução do batch será diferente de zero. Guarde esse código logo após o processo, como no artigo de compilação, e guarde também o log.

O exemplo de retorno do manual mostra o caso em que o patch tem recursos mais antigos que o RPO: a mensagem avisa que o patch foi validado com problemas e a saída lista os arquivos com a data no patch e a data no RPO. É um exemplo do manual; não reproduzi a execução.

Inspecionar antes de validar

patchInfo obtém as informações de um patch e grava em um arquivo indicado em output. Serve para conferir o conteúdo do patch contra a lista de entrega antes da validação:

[Conteudo]
action=patchInfo
patchFile=C:/pragiva-lab/patches/<NOME_DO_PATCH>.ptm
localPatch=True
output=C:/pragiva-lab/patches/<NOME_DO_PATCH>.txt

Aplicar é outra decisão

patchApply aplica o patch ao RPO. Ele tem o parâmetro applyOldProgram, que o manual descreve como “True para aplicação de programas com data de compilação mais antigas que as existentes no RPO”. Ou seja: o aviso que a validação deu sobre recurso mais antigo é justamente o que essa opção contorna. Ligar applyOldProgram para o comando passar troca um alerta por uma sobrescrita consciente, e essa escolha é sua, não da ferramenta.

Para o artigo ficar dentro do que foi confirmado, patchApply não é executado aqui. Ele só entra depois da validação lida, do teste funcional planejado e do ponto de retorno anotado.

• Não aprova a funcionalidade. Validar checa o patch contra o RPO; a regra de negócio continua precisando de teste funcional.
• Não é rollback. Nada no manual descreve validação como garantia de desfazer uma aplicação. Tenha a revisão anterior do RPO ou dos fontes identificada antes de aplicar.
• Não substitui olhar a origem. O patch reflete o RPO de onde foi gerado. Registre o ambiente de origem, a lista de entrada e o nome do patch.

Registro mínimo da entrega

Lista de fontes e recursos, tipo e nome do patch, ambiente de origem e de destino, saída do patchInfo, código de saída e log da validação (sem a senha), e o teste funcional previsto. Com isso outra pessoa reconstrói o patch e sabe por que ele foi ou não aplicado.

Quando a geração vira etapa de automação, o repositório de pipeline da TOTVS cita a geração de patch como uma etapa da pipeline, depois de análise, build e testes. O README dele não detalha a validação nem a aplicação, então esses passos continuam sendo decisão sua.