ADVPL/TLPP Code Generation

Overview

Patterns and templates for generating clean, standardized ADVPL and TLPP code for TOTVS Protheus. Covers User Functions, classes, MVC, REST APIs, Web Services, and entry points (pontos de entrada).

When to Use

• Creating new functions (User Function, Static Function)
• Creating TLPP classes with methods
• Building MVC structures (Model/View/Controller)
• Implementing REST API endpoints
• Writing entry points (pontos de entrada)
• Creating SOAP Web Services
• Any new .prw or .tlpp file creation

Naming Conventions

Type prefixes (Hungarian notation):

Module prefixes:

Mandatory Structure - User Function

Every User Function MUST follow this pattern:

#Include "TOTVS.CH"
#Include "TopConn.ch"

/*/{Protheus.doc} FATA001
Descricao breve da funcao
@type User Function
@author Nome do Autor
@since DD/MM/YYYY
@version 1.0
@param cParam1, Caractere, Descricao do parametro
@return lRet, Logico, Retorno da funcao
@example
    u_FATA001("001")
/*/
User Function FATA001(cParam1)
    Local lRet := .T.
    Local cAlias := "SA1"

    // Salva area de trabalho
    Local aArea := GetArea()

    Begin Sequence

        // Logica principal aqui
        DbSelectArea(cAlias)
        DbSetOrder(1)

        If DbSeek(xFilial(cAlias) + cParam1)
            // Processamento
        Else
            lRet := .F.
            MsgAlert("Registro nao encontrado")
        EndIf

    Recover Using oError
        lRet := .F.
        Conout("Erro em FATA001: " + oError:Description)
    End Sequence

    // Restaura area
    RestArea(aArea)

Return lRet

Variable Scope Rules

Best practice: Always use Local. Pass data via parameters, never via Private/Public.

Error Handling Pattern

Local oError
Local bErrorOld := ErrorBlock({|e| oError := e, Break(e)})

Begin Sequence

    // Codigo que pode falhar

Recover Using oError
    Conout("Erro: " + oError:Description)
    Conout("Linha: " + cValToChar(oError:GenCode))
    // Tratar erro ou re-raise

End Sequence

ErrorBlock(bErrorOld)

Quick Reference - Code Types

Function Keyword Rules (CRITICAL)

Customer code compiled into a customer RPO must use User Function (or Static Function for internal helpers, or class Method for TLPP classes). The bare Function keyword is reserved for the TOTVS core RPO and will fail to compile in customer environments.

TLPP REST with annotations

The official TOTVS pattern (from totvs/tlpp-sample-rest/rest-mod02.tlpp) is user function with annotations. The plugin adds one extra requirement on top of the sample: a mandatory namespace declaration (see "TLPP Namespace Rules" below).

#include "tlpp-core.th"
#include "tlpp-rest.th"

namespace custom.fat.customersapi

@Get("/api/v1/customers")
User Function getCustomers()
    // implementation
return oRest:setResponse(cData)

The class-based variant (rest-mod03.tlpp) is also supported — use class ... from LongClassName with @Get/@Post decorators on methods. Both patterns compile in customer RPOs, both require the namespace declaration. Never use bare Function with TLPP REST annotations.

TLPP Namespace Rules (CRITICAL)

Every generated .tlpp file for customer code must declare a namespace immediately after the includes. This applies to REST endpoints, classes, jobs — any TLPP generation. Missing the namespace breaks consistency with the ADVPL→TLPP migration skill and risks name collisions between customer projects.

Convention: custom.<agrupador>.<servico> — all lowercase, dots as separators, no underscores.

Inference rule:

• --module <agrupador> → <agrupador> (lowercase, no underscores)
• File/service/class name → <servico> (lowercase, no underscores)
• Result: namespace custom.<agrupador>.<servico>

Examples:

Format rules (all must hold):

1. All lowercase — custom.compras.purchase, never Custom.Compras.Purchase
2. Dot separators — never slashes, underscores, or hyphens between segments
3. No underscores inside segments — purchaseorder not purchase_order
4. Only custom.* prefix for customer code (totvs.protheus.* is reserved for TOTVS)
5. Exactly one namespace line per file, after the includes, before the Protheus.doc header

When --module is missing: ask the user during the Planning Phase for the agrupador. Never silently omit the namespace and never invent a default like custom.geral.xxx.

Do NOT use using namespace tlpp.*: tlpp.core, tlpp.rest, tlpp.log, tlpp.data are provided by the .th includes. using namespace is only valid to consume other custom namespaces in consumer files (e.g., using namespace custom.fat.pedidoservice).

Identifier Length Limits (CRITICAL)

ADVPL inherits a 10-character limit on identifiers (functions, methods, variables, fields) from the legacy DBase DBF format — only the first 10 characters are used to identify the symbol. TLPP removes this limit, but only when a namespace is declared. Generating a name that exceeds the limit produces code that either fails to compile or silently collides with another symbol sharing the first 10 characters.

Generation rule (enforced during Planning Phase):

1. If --lang advpl (or default .prw) and the target is User Function: name must be ≤ 8 characters
2. If --lang advpl and the target is Static Function: name must be ≤ 10 characters
3. If --lang tlpp and a namespace is declared: name must be ≤ 255 characters (no practical limit)
4. If the requested name exceeds the ADVPL limit, the generator must not generate the file. Instead, present two options to the user in the plan:
   • (A) Shorten the name — suggest 2-3 abbreviated alternatives (module prefix + mnemonic, e.g., ProcessaValidacaoItens → FATA100, VLDITENS, PRCVALIT)
   • (B) Switch to TLPP with namespace — ask for the agrupador if --module is missing and generate custom.<agrupador>.<servico>

About longnameclass: it is a legacy ADVPL mechanism (magical inheritance) that historically allowed class methods and properties to exceed the 10-char limit. Do not generate new code based on longnameclass — TLPP with namespace is the modern, officially supported replacement. The plugin only recognizes longnameclass as an exception during code review (BP-010) to avoid false positives on legacy code.

References:

• TDN — Tamanho do nome (identificador) de função
• TDN — Suporte a TLPP no Protheus

Common Mistakes