O que é um ponto de entrada no Protheus?

A definição

Ponto de entrada (PE) é um lugar que a TOTVS deixou no fonte de uma rotina para o seu código entrar. O padrão não sabe o que você escreveu: ele só pergunta se existe uma User Function com aquele nome e, se existir, chama.

Quem cria o PE é o padrão, que escolhe o nome e o momento. A sua parte é escrever a função com o nome exato.

Um exemplo do tamanho de um botão. O F050ROT é chamado quando o padrão monta o menu do Contas a Pagar e entrega o menu como PARAMIXB. Se a função devolver um array, o padrão passa a usá-lo como menu:

#Include "Protheus.ch"

/*/{Protheus.doc} F050ROT
Acrescenta um botão ao menu do Contas a Pagar.
@type user function
@param PARAMIXB, array, o menu (aRotina) montado pelo padrão
@return array, o menu final; outro tipo de retorno é ignorado
/*/
User Function F050ROT()

    Local aRotina := {}

    // Sem o array esperado, deixa o menu como está.
    If Type("PARAMIXB") <> "A"
        Return Nil
    EndIf

    aRotina := PARAMIXB

    // Título, função (texto), reservado, operação (2 = visualização).
    aAdd(aRotina, {"Minha consulta", "U_MinhaCons", 0, 2})

Return aRotina

Repare no que o exemplo mostra: o nome da função é o nome do PE, sem U_ escrito à mão; o que chega e o que volta dependem deste PE em particular. U_MinhaCons é um nome fictício.

Para que serve, e para que não serve

Serve para o que o padrão previu: validar um campo ou uma confirmação, acrescentar botão ou item de menu, reagir depois de uma gravação, ajustar dados antes de gravar. Cada PE cobre um momento específico, e é isso que decide o que dá para fazer nele.

Duas práticas comuns, que são prática e não regra da TOTVS:

• Quando o que você quer é outro comportamento em um ponto onde não há PE, o caminho não é forçar um PE vizinho. Confira antes se existe um PE para o momento certo.
• Manter o PE pequeno e chamar uma função sua para a regra de negócio deixa a regra testável fora dele.

O padrão pergunta com ExistBlock() e executa com ExecBlock(). O quarto argumento do ExecBlock, quando existe, vira o PARAMIXB dentro da sua função. O passo a passo, com os motivos de um PE “não disparar”, está em Ponto de entrada no Protheus: como o padrão te chama. Leia esse texto em seguida.

O que muda de um PE para outro

Cada rotina decide como chama o seu PE. Três chamadas do fonte padrão, lado a lado:

Por isso não vale supor pelo nome. Um PE de validação pode ou não bloquear, e um PE pode ou não receber dados. Antes de escrever a primeira linha, leia a ficha ou o artigo daquele PE: quando dispara, o que recebe e o que o padrão faz com o retorno. Sobre o conteúdo do PARAMIXB, veja PARAMIXB: o array que às vezes não é seu.

• A documentação oficial da rotina, começando pelo nome da rotina que você quer customizar.
• Os artigos por ponto de entrada deste site, um por PE, no formato da tabela acima. Exemplos: MT410TOK, F050ROT, MT100TOK e FA050INC.
• O fonte da rotina, quando você tem acesso. Na prática, é onde se confirma quando o PE dispara e o que o padrão faz com o retorno.

Cuidados básicos

• Confira o nome exato e não escreva U_ à mão: o compilador já acrescenta.
• Confira o retorno. Devolver .F. só bloqueia se o padrão usar o retorno, como mostra a tabela.
• Prove que executou antes de concluir que a lógica está errada: Meu ponto de entrada executou?.

O próximo passo é o mecanismo completo, em como o padrão te chama.