advpl-jobs-rpc

Files (1)

• SKILL.md

SKILL.md (first lines)

# advpl-jobs-rpc — Execução headless no Protheus

Quando o Protheus precisa executar código **sem usuário humano logado** (cron-like jobs, scheduler, integrações batch, RPC chamado por sistema externo), o entrypoint não é `User Function` — é **`Main Function`** disparada via configuração do `appserver.ini` ou via `StartJob`/`CallProc`/`MsRunInThread`.

Diferenças fundamentais para fluxo de UI:

- **Não há `cFilAnt`/`cEmpAnt` preenchidos** — você abre o ambiente explicitamente com `RpcSetEnv`.
- **Não pode chamar UI** (`MsgInfo`, `Aviso`, `Help`, `FwAlertHelp`, `MsgBox`) — trava o JOB para sempre.
- **Erros precisam ser logados em arquivo/ConOut**, não em diálogo modal.

## Quando usar

- Edit/criação de fonte com `Main Function`.
- Usuário menciona "JOB", "scheduler", "agendamento", "rotina batch", "integração em background", "thread", "RPC".
- Aparece `RpcSetEnv`, `PrepareIn`, `StartJob`, `CallProc`, `MsRunInThread`, `Sleep` em fonte legacy.
- Investigação de "rotina rodou mas não fez nada" (provavelmente travada em `MsgInfo`).

## Estrutura mínima de JOB

```advpl
#include "TOTVS.CH"

/*/{Protheus.doc} XYZJob
JOB de integracao de pedidos diaria.
Disparado por scheduler do appserver.ini.
/*/
Main Function XYZJob(cEmp, cFil)
    Local cEmpDef := If(Empty(cEmp), "01",   AllTrim(cEmp))
    Local cFilDef := If(Empty(cFil), "0101", AllTrim(cFil))

    // Abre ambiente Protheus
    RpcSetType(3)              // 3 = job sem licenca de UI
    RpcSetEnv(cEmpDef, cFilDef, "admin", "totvs", "FAT", "XYZJob",,, .F.)

    ConOut("[" + Time() + "] XYZJob iniciado em " + cEmpDef + "/" + cFilDef)

    Begin Sequence
        // Lógica do job
        ProcessaPedidos()
    Recover Using oErr
        ConOut("[" + Time() + "] XYZJob ERRO: " + oErr:Description)
        ConOut(oErr:ErrorStack)
    End Sequence

    ConOut("[" + Time() + "] XYZJob finalizado")
    RpcClearEnv()
Return Nil

Static Function ProcessaPedidos()
    // ...
Return Nil
```

## `RpcSetEnv` — assinatura completa

```advpl
RpcSetEnv(cEmpresa, cFilial, cUser, cPassword, cAmbiente, cModulo, ;
         aTables, lShowFin, lAbreExclusivo)
```

| Posição | Parâmetro      | Tipo | Default        | O que faz                                  |
|---------|----------------|------|----------------|--------------------------------------------|
| 1       | `cEmpresa`     | C    | obrig          | Código da empresa (2 caracteres)           |
| 2       | `cFilial`      | C    | obrig          | Filial (4 caracteres)                      |
| 3       | `cUser`        | C    | `""`           | Usuário Protheus                           |
| 4       | `cPassword`    | C    | `""`           | Senha (criptografada com `EncryptPwd`)     |
| 5       | `cAmbiente`    | C    | env do appsv   | Ambiente (`PRODUCAO`, etc.)                |
| 6       | `cModulo`      | C    | `""`           | Sigla do módulo (`FAT`, `EST`, `FIN`)      |
| 7       | `aTables`      | A    | `{}`           | Tabelas a abrir (vazio = abre conforme módulo) |
| 8       | `lShowFin`     | L    | `.F.`          | Mostra dialog financeiro                   |
| 9       | `lAbreExclusivo` | L  | `.F.`          | Abre tabelas em modo exclusivo             |

**Sempre chame `RpcClearEnv()` no fim** para liberar conexão.

## `RpcSetType` — tipo de conexão

| Valor | Significado                                                   |
|-------|---------------------------------------------------------------|
| 1     | Default — consome licença "advpl/protheus" (UI-like)          |
| 2     | RPC web service                                               |
| 3     | JOB — **não consome licença de UI** (recomendado p/ batch)    |

**Em JOB sempre use `RpcSetType(3)` antes do `RpcSetEnv`.**

## `PREPARE ENVIRONMENT` / `END ENVIRONMENT` (alternativa)

Sintaxe declarativa equivalente:

```advpl
PREPARE ENVIRONMENT EMPRESA cEmp FILIAL cFil MODULO "FAT" TABLES "SA1","SC5","SF2"
    // código com ambiente aberto
END ENVIRONMENT
```

Cleanup automático no `END ENVIRONMENT`. Útil para escopo curto. Para JOBs longos, prefira `RpcSetEnv`/`RpcClearEnv` por controle explícito.

## Disparando jobs

### Via appserver.ini (scheduler do Protheus)

```ini
[ONSTART]
JOBS=XYZJob_Diario,ABCJob_NF

[XYZJob_Diario]
MAIN=XYZJob
ENVIRONMENT=PRODUCAO
NPARMS=2
PARM1=01
PARM2=0101
DAYS=1,2,3,4,5         ; segunda a sexta
HOUR=02:00             ; 2h da manhã
INSTANCES=1
ONSTART=
```

### Via `StartJob` em código

```advpl

From replybr/plugadvpl, MIT.

More from replybr/plugadvpl