IdentificadorContrato documentadoObrigatório
Nome exato do ponto de entrada informado pela documentação da rotina.
FUNDAMENTOEm revisão
Pontos de entrada no Protheus
Conceitos, contrato e boas práticasEntenda pontos de entrada convencionais e MVC para estender rotinas padrão do Protheus sem alterar o fonte original.
Visão geral
Um ponto de entrada é uma extensão prevista pela TOTVS em um momento determinado de uma rotina. No modelo convencional, a User Function é chamada no evento documentado. Em MVC, uma única User Function associada ao identificador do modelo pode ser chamada em diversos hooks do ciclo de vida. Em ambos os casos, a finalidade é adaptar um processo de negócio sem modificar o fonte padrão.
Sintaxe
Conceitos, contrato e boas práticasParâmetros
PARAMIXBArray ou contextoOpcional
Disponível somente quando o ponto documentado o fornece; a estrutura varia conforme a rotina e o release.
RetornoContrato documentadoOpcional
Alguns pontos exigem retorno e outros retornam Nil. O tipo e o efeito devem ser confirmados na documentação específica.
Retorno
Uma extensão segura: respeite o contrato de parâmetros e retorno definido para o ponto de entrada escolhido.
Estrutura orientativa de uma extensão
#Include "TOTVS.ch"
/*
Substitua EXEMPLOPE pelo identificador documentado no TDN.
Consulte os parâmetros e o retorno antes de implementar.
*/
User Function EXEMPLOPE()
Local lContinua := .T.
// Aplique somente a regra de negócio prevista para este evento.
Return lContinuaResultado esperado
Modelo didático. O retorno .T. é apenas ilustrativo e não deve ser copiado sem consultar o contrato do ponto real.
Ponto de entrada MVC: seleção de hooks
#Include "TOTVS.ch"
#Include "FWMVCDEF.ch"
/* O nome deve corresponder ao ID documentado do Model. */
User Function MEUMODEL()
Local aParam := PARAMIXB
Local xRet := .T.
Local cIdPonto := ""
If aParam <> Nil
cIdPonto := aParam[2]
Do Case
Case cIdPonto == "MODELPOS"
// Validação global do modelo.
Case cIdPonto == "MODELCOMMITTTS"
// Ação dentro da transação: mantenha-a segura e breve.
EndCase
EndIf
Return xRetResultado esperado
Exemplo didático. Confirme o ID do Model, a estrutura de PARAMIXB, os hooks aceitos e o retorno no TDN da rotina.
- Use pontos de entrada para adequar processos; não altere o fonte padrão e não os trate como mecanismo de correção de defeitos do produto.
- A documentação específica define rotina, evento, fonte, função, parâmetros e retorno. Esse contrato deve ser confirmado no TDN para o release homologado (TOTVS, s.d.).
- Um ponto pode ser alterado, substituído ou descontinuado entre releases. Reavalie customizações a cada atualização relevante do ambiente.
- Mantenha a User Function pequena, rastreável e coberta por teste de cenário de negócio.
- Em MVC, o ponto de entrada é uma única User Function cujo nome corresponde ao ID do Model. O identificador do Model não pode ser igual ao nome do fonte quando este também é uma User Function (TOTVS, 2026).
- O array PARAMIXB de MVC entrega o objeto/contexto e o identificador do hook. Exemplos comuns incluem MODELPOS, FORMPOS, FORMLINEPRE, MODELCOMMITTTS e MODELCOMMITNTTS; trate somente os hooks documentados para a rotina.
- Hooks dentro de TTS exigem cuidado adicional: evite operações externas ou gravações que possam comprometer a transação. Separe validações, pós-processamentos e integrações conforme o momento informado pelo contrato.
- Inventar PARAMIXB, retorno ou momento de execução com base em outro ponto de entrada.
- Gravar dados, abrir transações ou alterar o fluxo padrão sem entender o efeito do retorno.
- Substituir uma correção de produto por customização; defeitos devem ser avaliados com o suporte TOTVS.
- Usar o mesmo nome de User Function para finalidades diferentes ou sem controle de versão.
- No MVC, usar o mesmo nome para o fonte e o ID do Model, contrariando a regra de identificação documentada pela TOTVS.
- Executar integrações externas em hook transacional sem avaliar rollback, tempo de resposta e idempotência.