MT140TOK o ponto de entrada que valida os itens da Pré-Nota de Entrada

Para o mecanismo geral, veja Ponto de entrada no Protheus. Para entender por que a Pré-Nota existe separada do documento, veja Pré-nota ou documento de entrada.

Só roda se o padrão já aprovou

A chamada no padrão tem esta forma:

If lRetorno .And. ExistBlock("MT140TOK")
    lRetorno := ExecBlock("MT140TOK", .F., .F., {lRetorno})
EndIf

Duas consequências:

• Seu ponto de entrada nunca vê uma reprovação do padrão. Antes dele, o padrão já conferiu o cabeçalho (fornecedor, emissão, tipo, número), se a nota já existe na base (na inclusão), se o armazém de cada item existe no cadastro e se sobrou alguma linha não deletada, entre outras checagens. Se qualquer uma dessas falha, o MT140TOK nem é chamado. Por isso PARAMIXB[1] chega sempre .T.: ler esse valor não informa nada.
• Retornar .T. não desfaz nenhuma reprovação anterior, ao contrário do que acontece no MT410TOK. O que você devolver substitui lRetorno, mas ele só chegou até aqui por ter sido aprovado.

Depois do ponto de entrada o padrão ainda executa outras validações (nota com empenho e tabela auxiliar de itens, quando ativos). Elas só rodam se você devolver .T.; com .F. a confirmação já está barrada.

O que dá para ler dentro dele

A função é uma validação do grid, então o contexto da tela está visível: as variáveis aHeader e aCols com os itens digitados, e as variáveis do cabeçalho da Pré-Nota, como cNFiscal, cSerie, dDEmissao, cTipo e cA100For, que o próprio padrão usa na mesma função. Nada foi gravado ainda.

Para achar uma coluna, procure pelo nome do campo em aHeader. A última posição de cada linha de aCols diz se ela está deletada, então ignore as deletadas.

Exemplo

A regra do exemplo é fictícia: em Pré-Nota de tipo normal, todo item não deletado precisa vir de pedido de compra.

#Include "Protheus.ch"

/*/{Protheus.doc} MT140TOK
Executado em Ma140TudOk(), ao confirmar a Pré-Nota, depois das
validações do padrão e antes de gravar.
@type user function
@return logical, .F. interrompe a confirmação
/*/
User Function MT140TOK()

    Local lRet     := .T.
    Local nPosPed  := aScan(aHeader, {|x| AllTrim(x[2]) == "D1_PEDIDO"})
    Local nPosItem := aScan(aHeader, {|x| AllTrim(x[2]) == "D1_ITEM"})
    Local nPosDel  := Len(aHeader) + 1   // flag de linha deletada
    Local nX       := 0

    // A regra vale só para nota normal.
    If cTipo <> "N"
        Return .T.
    EndIf

    // Sem a coluna na tela, a regra não se aplica.
    If nPosPed == 0 .Or. nPosItem == 0
        Return .T.
    EndIf

    For nX := 1 To Len(aCols)
        If !aCols[nX][nPosDel] .And. Empty(aCols[nX][nPosPed])
            Help(" ", 1, "MT140TOK",, ;
                "O item " + AllTrim(aCols[nX][nPosItem]) + ;
                " não tem pedido de compra. Informe o pedido ou remova a linha.", 1, 0)
            lRet := .F.
            Exit
        EndIf
    Next nX

Return lRet

Os Return .T. antecipados são os casos em que a regra não se aplica. A mensagem vem antes do .F.: sem ela o botão OK parece não responder e o usuário não sabe qual item corrigir.

Armadilhas

Bloquear sem mensagem. O retorno .F. só devolve o usuário à tela. Sempre Help() ou equivalente, dizendo qual item e o que fazer.

Abrir diálogo na rotina automática. A Pré-Nota também pode ser gravada por MATA140 via ExecAuto, e o padrão chama o mesmo Ma140TudOk() nesse caminho. MsgYesNo ou MsgAlert sem tela trava a execução. Guarde com IsBlind().

Esquecer o Return. O retorno é atribuído a lRetorno e decide a confirmação; sem Return explícito o resultado é Nil.

Pôr aqui regra que só faz sentido na classificação. Este ponto é da Pré-Nota. Quando o documento de entrada é confirmado, a validação equivalente é outra.

MT140TOK ou MT100TOK

Os dois recebem {lRet} e bloqueiam com .F., mas pertencem a telas diferentes. Uma regra no MT140TOK não vale quando alguém lança direto o Documento de Entrada sem passar pela Pré-Nota; se a regra precisa valer nos dois caminhos, ela precisa existir nos dois pontos de entrada.