FOUNDATIONUnder review

Entry points in Protheus

Concepts, contract and best practices

Learn about conventional and MVC entry points for extending standard Protheus routines without changing the original source code.

Entry pointsCustomizationProtheusPARAMIXBBest practicesUnder reviewMVCFWMVCDEF.ch

01 · OVERVIEW

Overview

An entry point is an extension provided by TOTVS at a specific moment in a routine. In the conventional model, the User Function runs at the documented event. In MVC, one User Function associated with the model identifier can run at several lifecycle hooks. In both cases, the purpose is to adapt a business process without changing the standard source code.

02 · SYNTAX

Syntax

Concepts, contract and best practices

Parameters

Identifier

Documented contractRequired

Exact entry-point name stated in the routine documentation.

PARAMIXB

Array or contextOptional

Available only when the documented entry point provides it; its structure varies by routine and release.

Return value

Documented contractOptional

Some entry points require a return value and others return Nil. Confirm its type and effect in the specific documentation.

Return value

A safe extension: respect the parameter and return-value contract defined for the selected entry point.

03 · PRACTICAL EXAMPLE

Guidance structure for an extension

#Include "TOTVS.ch"

/*
  Replace EXAMPLEEP with the identifier documented in TDN.
  Check parameters and return value before implementing.
*/
User Function EXAMPLEEP()
    Local lContinue := .T.

    // Apply only the business rule intended for this event.

Return lContinue

Expected result

Teaching model. The .T. return is only illustrative and must not be copied without consulting the actual entry-point contract.

04 · PRACTICAL EXAMPLE

MVC entry point: selecting hooks

#Include "TOTVS.ch"
#Include "FWMVCDEF.ch"

/* The name must match the documented Model ID. */
User Function MYMODEL()
    Local aParam   := PARAMIXB
    Local xRet     := .T.
    Local cHookId  := ""

    If aParam <> Nil
        cHookId := aParam[2]

        Do Case
        Case cHookId == "MODELPOS"
            // Global model validation.
        Case cHookId == "MODELCOMMITTTS"
            // In-transaction action: keep it safe and brief.
        EndCase
    EndIf

Return xRet

Expected result

Teaching example. Confirm the Model ID, PARAMIXB structure, accepted hooks and return value in the TDN for the routine.

BEST PRACTICES

Use entry points to adapt processes; do not modify the standard source code or use them as a product-defect fix.
The specific documentation defines the routine, event, source file, function, parameters and return value. Confirm that contract in the TDN for the supported release (TOTVS, n.d.).
An entry point can change, be replaced or be discontinued across releases. Reassess customizations during relevant environment updates.
Keep the User Function small, traceable and covered by business-scenario tests.
In MVC, the entry point is one User Function whose name matches the Model ID. The Model identifier cannot equal the source-file name when that source is also a User Function (TOTVS, 2026).
The MVC PARAMIXB array provides the object/context and the hook identifier. Common examples include MODELPOS, FORMPOS, FORMLINEPRE, MODELCOMMITTTS and MODELCOMMITNTTS; handle only the hooks documented for the routine.
Hooks inside TTS require extra care: avoid external operations or writes that can compromise the transaction. Keep validations, post-processing and integrations aligned with the documented moment.

COMMON PITFALLS

Inventing PARAMIXB, a return value or an execution moment based on another entry point.
Writing data, opening transactions or changing the standard flow without understanding the return value effect.
Replacing a product fix with customization; defects should be assessed with TOTVS support.
Using the same User Function name for different purposes or without version control.
In MVC, using the same name for the source file and the Model ID, against the TOTVS identification rule.
Running external integrations in a transactional hook without evaluating rollback, response time and idempotency.