Modo de edição (X3_WHEN): quando o campo pode ser editado

A opção simples de edição de um campo é a coluna X3_VISUAL: a documentação da SX3 diz que em branco ou com A o campo é alterável na tela, e com V é apresentado apenas para visualização. Ela resolve o caso fixo — o campo sempre editável ou nunca editável. Quando a resposta é “depende”, a regra vai no modo de edição, a coluna X3_WHEN: uma expressão que devolve .T. para liberar o campo e .F. para travá-lo.

A documentação da SX3 avisa que o X3_WHEN de cada campo é executado a cada mudança de foco — cada vez que o usuário preenche ou troca de campo. Por isso, nada de função pesada ali.

A expressão pode ser qualquer instrução AdvPL que devolva lógico: uma variável, uma comparação com outro campo (M->campo), uma função, ou tudo isso combinado com .And. e .Or..

Pelo Configurador, o caminho que a documentação TOTVS descreve é: Base de Dados > Dicionário > Arquivos, pesquisar a tabela, Editar e Campos, pesquisar o campo, Editar e, na aba Opções, informar a expressão no campo Modo Edição. Gravar o campo não encerra o trabalho: o último passo da mesma orientação é acionar Atualizar Base de Dados e depois Sair. É esse passo que atualiza o banco de dados com a alteração; se a tela continua igual depois de mudar o X3_WHEN, confira se ele foi feito. O que essa rotina faz, e quando ela pede modo exclusivo, está em Tabela customizada no Protheus.

O próprio dicionário usa o X3_WHEN para os três tipos de condição:

E um par que lê parâmetro, com condições opostas:

B1_GARANT  M->B1_TIPO <> SuperGetMV("MV_LJTPGAR", ,"GE")
B1_ADMIN   M->B1_TIPO == SuperGetMV("MV_LJTPGAR", ,"GE")

O B1_GARANT trava quando o produto é do tipo de garantia; o B1_ADMIN só libera nesse tipo.

Três leituras:

• INCLUI e ALTERA são as variáveis que dizem a operação da tela. INCLUI sozinho é o jeito mais curto de “preenche na inclusão, não mexe depois”.
• M->campo lê o que está na tela naquele momento. É assim que um campo trava ou destrava conforme outro.
• O par B1_GARANT/B1_ADMIN mostra um recurso útil: dois campos com condições opostas, lendo o mesmo parâmetro. Mudar o conteúdo do MV_LJTPGAR muda o comportamento dos dois sem tocar no dicionário.

Exemplo: nascimento editável só na inclusão

No cadastro de motoristas do exemplo da série (tabela ZA1), a data de nascimento não deve mudar depois de cadastrada — é dela que sai a idade:

Isso resolve o dia a dia. Sobra a exceção: alguém digitou a data errada, e alguém precisa poder corrigir.

A documentação TOTVS mostra como restringir um campo a usuários específicos pelo modo de edição, usando __cUserId — a variável carregada na entrada do sistema com o código (ID) do usuário logado. O próprio padrão do Protheus usa o mesmo recurso em rotinas suas, com a lista de códigos guardada em parâmetro: __cUserId $ AllTrim(SuperGetMV(...)).

Para o ZA1_NASC, a regra fica “editável na inclusão, ou na alteração por quem está autorizado”:

O parâmetro customizado MV_XUSRNAS (tipo caractere) guarda os códigos dos usuários autorizados — o ID, não o login. A orientação TOTVS separa os códigos por vírgula; aqui usamos barra (000123/000456), por recomendação nossa: qualquer separador serve, desde que seja sempre o mesmo. Sem o parâmetro criado, o valor padrão "" não libera ninguém além da inclusão.

Por que parâmetro e não os códigos direto na expressão:

• trocar quem pode corrigir vira alteração de conteúdo de parâmetro, não de dicionário;
• a mesma lista pode ser lida por outras regras;
• a SQL abaixo mostra a lista inteira de quem tem a exceção.

Quando a regra é “só administradores”, existe função pronta: FWIsAdmin() devolve .T. se o usuário pertence ao grupo de administradores. Sem parâmetro, ela verifica o usuário logado (__cUserId).

Gatilho em campo travado. A documentação TOTVS registra que, em rotinas atualizadas para MVC, o gatilho que preenche um campo com edição desabilitada pelo X3_WHEN passa a mostrar um help e não grava o valor. Se o campo é travado para o usuário mas precisa ser preenchido por gatilho, não use X3_WHEN .F. nele. A diferença entre travar o dado e travar só a tela, no MVC, está em Validar e bloquear campo no MVC.

Regra longa demais para uma linha. Quando a condição junta operação, usuário, parâmetro e outro campo, ela vira uma User Function que devolve lógico — U_ZA1When() no X3_WHEN —, com a mesma disciplina de uma função de validação.

Conferindo no banco

Os campos com modo de edição, e a opção Alterar/Visualizar ao lado. O sufixo 010 é o do exemplo; o seu depende da empresa.

SELECT X3_CAMPO, X3_VISUAL, X3_WHEN
  FROM SX3010
 WHERE X3_ARQUIVO = 'ZA1'
   AND X3_WHEN <> ' '
   AND D_E_L_E_T_ = ' '
 ORDER BY X3_ORDEM

E os dois parâmetros citados — o do padrão e o customizado:

SELECT X6_FIL, X6_VAR, X6_TIPO, X6_DESCRIC, X6_CONTEUD
  FROM SX6010
 WHERE X6_VAR IN ('MV_LJTPGAR', 'MV_XUSRNAS')
   AND D_E_L_E_T_ = ' '

No dicionário padrão, o MV_LJTPGAR é caractere, com a descrição “Define o tipo do produto de garantia estendida” e conteúdo GE. O MV_XUSRNAS só aparece se tiver sido criado; nesse caso, X6_CONTEUD é a lista de quem pode corrigir o nascimento.

Se o seu cadastro precisa de regra de edição por perfil e não sabe por onde começar, fale com a gente.