advpl-pontos-entrada

Files (3)

• SKILL.md
• A300STRU.prw · exemplos/
• reference.md

SKILL.md (first lines)

# advpl-pontos-entrada — Customização via PE

**Ponto de Entrada (PE)** é o mecanismo oficial TOTVS para customizar comportamento de rotinas padrão **sem alterar o fonte original**. Toda rotina Protheus principal tem dezenas de PEs cadastrados em pontos estratégicos (antes de validar, antes de gravar, antes de imprimir, etc.).

O cliente implementa uma `User Function` com **nome exato e assinatura esperada** pela rotina TOTVS. Em runtime, o framework chama via reflection se a função existir no RPO.

## Quando usar

- Usuário pede "criar ponto de entrada", "implementar PE", "customizar rotina padrão TOTVS".
- Edit em arquivo cuja função casa com pattern de PE (`^[A-Z]{2,4}\d{2,4}[A-Z_]*$`).
- Investigar comportamento "modificado" de rotina TOTVS — provavelmente há PE ativa.
- Antes de copiar rotina TOTVS inteira para customizar → sempre prefira PE.

## Pattern de naming

Regex que casa a esmagadora maioria dos PEs oficiais:

```
^[A-Z]{2,4}\d{2,4}[A-Z_]*$
```

Exemplos:

- `MT100LOK` — Módulo MT (Faturamento) + 100 (rotina) + LOK (linha OK).
- `M460FIM` — MATA460 — fim do processamento.
- `MA410LOK` — MATA410 — Pedido de venda, line OK.
- `MA410BUT` — MATA410 — botões adicionais.
- `FA080INC` — FINA080 — pós-inclusão.
- `SF2100I` — SF2 + 100 + I (post Insert).

Sufixos comuns:

| Sufixo | Significa                       |
|--------|---------------------------------|
| `LOK`  | Line OK (valida linha em grid)  |
| `TOK`  | TudoOK (validação geral)        |
| `INC`  | Pós-Inclusão                    |
| `ALT`  | Pós-Alteração                   |
| `EXC`  | Pós-Exclusão                    |
| `CAN`  | Cancelamento                    |
| `BUT`  | Botões adicionais               |
| `MNU`  | Menu adicional                  |
| `FIM`  | Final do processamento          |
| `GRV`  | Gravação                        |
| `PRT`  | Impressão                       |
| `VLD`  | Validação                       |

## Assinatura padrão — PARAMIXB

PEs **não recebem parâmetros nomeados**. Recebem uma variável global `PARAMIXB` (array 1-based) preenchida pela rotina chamadora:

```advpl
#include "TOTVS.CH"

/*/{Protheus.doc} MT100LOK
PE Validacao na inclusao de NF de entrada.
Retorna .T. se valido, .F. para bloquear gravacao.
/*/
User Function MT100LOK()
    Local aArea  := GetArea()
    Local lOk    := .T.
    Local cNumNF := SF1->F1_DOC

    // Lógica de validação customizada
    If !MyValida(cNumNF)
        lOk := .F.
        Help(, , "Validacao", , "NF " + cNumNF + " bloqueada por regra interna", 1, 0)
    EndIf

    RestArea(aArea)
Return lOk
```

Quando há parâmetros, eles vêm em `PARAMIXB[N]`:

```advpl
User Function A120GRVC()
    Local aCab := PARAMIXB[1]   // array de cabeçalho do pedido
    Local aItens := PARAMIXB[2] // array de itens

    // Processa
Return Nil
```

## Indexação 1-based

ADVPL usa **arrays 1-based** (não 0-based como C/Python). `PARAMIXB[1]` é o primeiro elemento. **Ler `PARAMIXB[0]` dá erro de runtime.**

`paramixb_count` no lookup `pontos_entrada_padrao` indica quantos parâmetros a PE recebe.

## Retorno via PARAMIXB[última-posição]

Algumas PEs **modificam o último elemento** de `PARAMIXB` para devolver dado ao chamador:

```advpl
User Function MA440PGN()
    // PARAMIXB[1..N-1] são entrada
    // PARAMIXB[N] é o retorno (output)
    Local aSaida := PARAMIXB[Len(PARAMIXB)]

    aSaida[1] := nNovoValor
    PARAMIXB[Len(PARAMIXB)] := aSaida
Return Nil
```

A coluna `retorno_tipo` do lookup indica o tipo esperado: `L` (lógico), `C` (string), `N` (numérico), `A` (array), `O` (objeto), `` (sem retorno).

## Onde a PE é chamada

A rotina TOTVS faz algo como:

```advpl
// Dentro do fonte oficial MATA460
If ExistBlock("M460FIM")
    ExecBlock("M460FIM", .F., .F., {aCabec, aItens})
EndIf
```

`ExistBlock` checa se a User Function existe no RPO; `ExecBlock` invoca passando parâmetros que viram `PARAMIXB`. **Apenas uma User Function com aquele nome pode existir no RPO** — daí a importância de prefixo de cliente em `User Function` regulares (PEs são exceção: o nome é fixo).

From replybr/plugadvpl, MIT.

More from replybr/plugadvpl