Protheus Entry Point Designer
Overview
Design, implement, and document Protheus Entry Points (Pontos de Entrada). Entry Points are the standard extensibility mechanism in TOTVS Protheus, allowing customization of standard ERP routines without modifying the original source code.
Language Priority — TLPP First
TLPP is the default and mandatory output language for every new Entry Point. Only generate AdvPL (.prw) when the user explicitly requests it (e.g., "em AdvPL", "como .prw", "legacy AdvPL", "sem TLPP").
- Default: generate
.tlpp with #include "tlpp-core.th", type annotations, Try-Catch, and namespaced helpers when applicable
- Opt-in AdvPL: only when the user is explicit. If the request is ambiguous (e.g., the project still has many
.prw files), confirm before falling back to AdvPL
- Migrating an existing
.prw Entry Point: prefer rewriting in TLPP unless the user requires keeping the original extension
When to Use
- Creating a new Entry Point to customize standard Protheus behavior
- Documenting existing Entry Points
- Designing the PARAMIXB interface for custom Entry Points
- Migrating legacy Entry Points to TLPP
How Entry Points Work
- A standard TOTVS routine (e.g., MATA010, FINA010) calls
ExistBlock("PE_NAME") at predefined extension points
- If a
User Function with the matching name exists in the RPO, it is executed
- The standard routine passes parameters via the
PARAMIXB array (Private variable)
- The Entry Point returns a value that influences the standard routine's behavior
MANDATORY Rules
Function Naming — NEVER use the U_ prefix
The compiler resolves U_ automatically at runtime. Adding it manually causes the Entry Point to never be triggered.
| ✅ Correct |
❌ Wrong |
User Function MT410INC() |
User Function U_MT410INC() |
User Function A010TOK() |
User Function U_A010TOK() |
File Naming — match the Entry Point name exactly
File name must be the Entry Point name in uppercase + language extension. No namespaces, no prefixes, no suffixes.
| Entry Point |
AdvPL |
TLPP |
| MT410INC |
MT410INC.prw |
MT410INC.tlpp |
| FA080BUT |
FA080BUT.prw |
FA080BUT.tlpp |
Workflow
Step 1 — Identify the Entry Point
- Confirm the Entry Point name (e.g.,
MT410INC, A010TOK)
- Identify the standard routine and module (e.g., MATA410, SIGAFAT)
- Determine the trigger moment (before validation, after save, grid processing, etc.)
- Consult TDN to confirm PARAMIXB layout and return type
Step 2 — Design the PARAMIXB Interface
Document each parameter using the standard table format in PARAMIXB & Return Types.
Step 3 — Implement the Entry Point
Default: use the TLPP Template.
Only use the AdvPL Template when the user explicitly requested AdvPL.
Key implementation rules:
- Document the Entry Point with a
/*/{Protheus.doc} block (@type user function, @param, @return, @obs)
- Always validate PARAMIXB existence (
Type("PARAMIXB") == "A") and length defensively
- Extract business logic to
Static Function helpers
- Use
Try-Catch for error handling — never ErrorBlock
- Default return value must be fail-safe (must not block the standard routine)
Step 4 — Validate
Apply the Entry Point Design Checklist before delivering.
Quick Reference
1---2name: entry-point-designer3description: Design and document Protheus Entry Points (Pontos de Entrada). Always generates TLPP by default; only generates AdvPL (.prw) when the user explicitly requests AdvPL. Covers User Function signatures, PARAMIXB parameter layouts, return value specifications, and ProtheusDOC documentation. Use when user says 'create entry point', 'ponto de entrada', 'PARAMIXB', 'User Function hook', 'ponto de entrada TLPP', 'ponto de entrada ADVPL'.4license: MIT5---67# Protheus Entry Point Designer89## Overview1011Design, implement, and document Protheus Entry Points (Pontos de Entrada). Entry Points are the standard extensibility mechanism in TOTVS Protheus, allowing customization of standard ERP routines without modifying the original source code.1213## Language Priority — TLPP First1415**TLPP is the default and mandatory output language for every new Entry Point.** Only generate AdvPL (`.prw`) when the user explicitly requests it (e.g., "em AdvPL", "como .prw", "legacy AdvPL", "sem TLPP").1617- Default: generate `.tlpp` with `#include "tlpp-core.th"`, type annotations, `Try-Catch`, and namespaced helpers when applicable18- Opt-in AdvPL: only when the user is explicit. If the request is ambiguous (e.g., the project still has many `.prw` files), confirm before falling back to AdvPL19- Migrating an existing `.prw` Entry Point: prefer rewriting in TLPP unless the user requires keeping the original extension2021## When to Use2223- Creating a new Entry Point to customize standard Protheus behavior24- Documenting existing Entry Points25- Designing the PARAMIXB interface for custom Entry Points26- Migrating legacy Entry Points to TLPP2728---2930## How Entry Points Work31321. A standard TOTVS routine (e.g., MATA010, FINA010) calls `ExistBlock("PE_NAME")` at predefined extension points332. If a `User Function` with the matching name exists in the RPO, it is executed343. The standard routine passes parameters via the `PARAMIXB` array (Private variable)354. The Entry Point returns a value that influences the standard routine's behavior3637---3839## MANDATORY Rules4041### Function Naming — NEVER use the `U_` prefix4243The compiler resolves `U_` automatically at runtime. Adding it manually causes the Entry Point to **never** be triggered.4445| ✅ Correct | ❌ Wrong |46|---|---|47| `User Function MT410INC()` | `User Function U_MT410INC()` |48| `User Function A010TOK()` | `User Function U_A010TOK()` |4950### File Naming — match the Entry Point name exactly5152File name must be the Entry Point name in uppercase + language extension. No namespaces, no prefixes, no suffixes.5354| Entry Point | AdvPL | TLPP |55|---|---|---|56| MT410INC | `MT410INC.prw` | `MT410INC.tlpp` |57| FA080BUT | `FA080BUT.prw` | `FA080BUT.tlpp` |5859---6061## Workflow6263### Step 1 — Identify the Entry Point64651. Confirm the Entry Point name (e.g., `MT410INC`, `A010TOK`)662. Identify the standard routine and module (e.g., MATA410, SIGAFAT)673. Determine the trigger moment (before validation, after save, grid processing, etc.)684. Consult TDN to confirm PARAMIXB layout and return type6970### Step 2 — Design the PARAMIXB Interface7172Document each parameter using the standard table format in [PARAMIXB & Return Types](./references/paramixb-and-returns.md).7374### Step 3 — Implement the Entry Point7576**Default**: use the [TLPP Template](./references/templates.md#tlpp-template).7778Only use the [AdvPL Template](./references/templates.md#advpl-template) when the user explicitly requested AdvPL.7980Key implementation rules:81- Document the Entry Point with a `/*/{Protheus.doc}` block (`@type user function`, `@param`, `@return`, `@obs`)82- Always validate PARAMIXB existence (`Type("PARAMIXB") == "A"`) and length defensively83- Extract business logic to `Static Function` helpers84- Use `Try-Catch` for error handling — **never** `ErrorBlock`85- Default return value must be fail-safe (must not block the standard routine)8687### Step 4 — Validate8889Apply the [Entry Point Design Checklist](./references/design-checklist.md) before delivering.9091---9293## Quick Reference9495| Resource | Contents |96|---|---|97| [Templates](./references/templates.md) | AdvPL and TLPP code templates |98| [PARAMIXB & Return Types](./references/paramixb-and-returns.md) | PARAMIXB layout format, return types, common EP categories |99| [Design Checklist](./references/design-checklist.md) | Interface, defensive programming, code quality, SonarQube compliance |100| [Troubleshooting](./references/troubleshooting.md) | Common issues and fixes |101
tbc-servicos