Criar JOB scheduler no Protheus

Tutorial passo-a-passo: criar JOB que roda agendado (cron-like) no Protheus, configurar em appserver.ini e validar execucao.

JOBs sao rotinas batch executadas em background pelo AppServer, ideais pra processamento agendado: relatorios diarios, integracoes noturnas, limpeza de cache.

1. Criar a User Function

#INCLUDE "PROTHEUS.CH"

User Function GeraRelDiario()
    Local cEmpresa := "99"
    Local cFilial  := "01010001"

    // Prepara ambiente (sem usuario logado)
    RpcSetType(3)                   // 3 = JOB
    RpcSetEnv(cEmpresa, cFilial)

    ConOut("[GeraRelDiario] Iniciou em " + Time())

    // Logica do JOB
    Begin Sequence
        ProcessaRelatorio()
    Recover
        ConOut("[GeraRelDiario] Erro: " + ErrorBlock())
    End Sequence

    RpcClearEnv()
    ConOut("[GeraRelDiario] Concluiu em " + Time())
Return

2. Compilar no RPO

Compile como GeraRelDiario.prw. Confirme que a User Function aparece (use /advpl-compile ou Ctrl+F9 no TDS-VSCode).

3. Configurar no appserver.ini

[ONSTART]
JOBS=GERA_REL_DIARIO
RefreshRate=60

[GERA_REL_DIARIO]
TYPE=Schedule
FUNCTION=U_GeraRelDiario
ENABLED=1
SCHEDULE=060000   ; HHMMSS = 06:00:00 todo dia

4. Formato do SCHEDULE

HHMMSS simples: 060000 = 6h da manha todo dia
HHMMSS;X;Y: 080000;1;0 = 8h, dia da semana 1 (domingo), repete 0
cron-like via tabela SCH: pra agendamentos complexos, use a tabela SCH (no Configurador > Scheduler)

5. Reiniciar AppServer

JOBs sao carregados na inicializacao. Restart do servico AppServer.

6. Validar execucao

console.log do AppServer: deve aparecer "[GeraRelDiario] Iniciou em ..."
Configurador > Scheduler > Monitor: lista jobs em execucao
Tabela SCH: historico de execucoes (se configurado)

Pegadinhas

RpcSetType + RpcSetEnv obrigatorios — sem isso, JOB nao tem ambiente Protheus configurado
Funcao nao pode ter UI: nada de MsgInfo, dbedit. So ConOut e operacoes server-side
Locks: JOB lendo grande volume pode travar usuarios. Use FWSemaphore ou rode em horario sem usuarios
JOB nunca termina: SCHEDULE com tempo curto + funcao demorada pode acumular instancias. Use semaforo pra garantir 1 por vez