Parâmetros (SX6): como criar e ler um MV_ customizado

Parâmetro é o valor que o fonte lê em vez de trazer escrito dentro dele. Fica na SX6, uma linha por parâmetro, e se lê assim:

nIdMin := SuperGetMV("MV_XIDMIN", .F., 21)

Nome do parâmetro, um lógico sobre aviso de parâmetro ausente (com o valor padrão informado, ele não muda nada — detalhes em Lendo no fonte), e o valor a usar se o parâmetro não existir. A partir daí, mudar a idade mínima é trabalho de quem administra o Configurador, não de quem recompila.

Antes de criar o seu, saiba de duas coisas que pegam quase todo mundo: nenhum prefixo é exclusivo — o dicionário padrão já tem parâmetros começando com MV_ES e com MV_X, inclusive um MV_X_ —, e numa busca com LIKE 'MV_X%' o _ é curinga de um caractere. Confira o nome com = antes de criar; os detalhes estão na seção sobre o nome, mais abaixo.

O exemplo da série: a transportadora do cadastro de motoristas quer a idade mínima de motorista configurável. O parâmetro é MV_XIDMIN, numérico, com conteúdo 21.

A consulta que confere qualquer parâmetro

Toda vez que um artigo deste site menciona um MV_, ele traz uma consulta como esta. É a forma mais curta de saber se o parâmetro existe no seu ambiente, de que tipo ele é e o que está gravado nele:

SELECT X6_FIL, X6_VAR, X6_TIPO,
       X6_DESCRIC, X6_DESC1, X6_DESC2,
       X6_CONTEUD, X6_CONTSPA, X6_CONTENG,
       X6_PROPRI
  FROM SX6010
 WHERE X6_VAR = 'MV_XIDMIN'
   AND D_E_L_E_T_ = ' '

O 010 do nome da tabela é o sufixo da empresa; no seu ambiente pode ser outro. Troque MV_XIDMIN pelo parâmetro que você quer ver.

Três coisas que essa consulta mostra e que costumam surpreender:

• O conteúdo é sempre texto. O MV_ULMES, data do último fechamento de estoque, é tipo D e guarda 19970101 no dicionário padrão: ano, mês e dia, sem separador. Um numérico guarda 21 como texto. Quem converte para data, número ou lógico é a função de leitura, de acordo com o X6_TIPO — a documentação do GetMV diz que o retorno depende do tipo cadastrado.
• Filial em branco é o normal. No dicionário padrão, todos os parâmetros vêm com X6_FIL em branco.
• A descrição quebra em linhas. O MV_ESTADO começa em X6_DESCRIC (“Sigla do estado da empresa usuaria do Sistema, pa-”) e continua em X6_DESC1 (“ra efeito de calculo de ICMS…”). Quem lê só a primeira coluna lê meia frase.

Para ler a descrição e o conteúdo de um parâmetro padrão sem abrir o banco, o site tem o catálogo de parâmetros — por exemplo, o MV_ULMES e o MV_ESTADO. O catálogo mostra o que a TOTVS entrega; a consulta acima mostra o que está no seu ambiente.

X6_VAR tem dez caracteres, e o maior nome do dicionário padrão também tem dez. Descontando o MV_, sobram sete.

A documentação da TOTVS descreve a nomenclatura como MV seguido de duas letras do módulo e do nome do parâmetro, e registra dois prefixos para quem não é o padrão: FS para a fábrica de software e, em geral, ES nas customizações feitas no cliente.

O problema é que nenhum prefixo é exclusivo. O dicionário padrão já tem parâmetros que começam com MV_ES (o próprio MV_ESTADO é um deles) e parâmetros que começam com MV_X — um deles, inclusive, com MV_X_. O prefixo ajuda quem lê a reconhecer uma customização; não impede colisão.

Recomendação: escolha um prefixo e siga com ele em todos os parâmetros da empresa. Nesta série, é MV_X, a mesma letra que marca o campo customizado em tabela padrão (C5_XMOTOR). Um MV_X_ gasta um dos sete caracteres com o separador; funciona, mas encurta o nome.

O que garante que o nome está livre é conferir antes de criar:

SELECT X6_FIL, X6_VAR, X6_DESCRIC, X6_PROPRI
  FROM SX6010
 WHERE X6_VAR = 'MV_XIDMIN'
   AND D_E_L_E_T_ = ' '

Nenhuma linha: o nome está livre. Use = e não LIKE para essa conferência: no LIKE, o _ é curinga de um caractere, e LIKE 'MV_X%' também traria um nome que tivesse qualquer outro caractere no lugar do sublinhado.

Para ver o que já foi criado fora do padrão, use o proprietário: no dicionário padrão, todo parâmetro tem X6_PROPRI = 'S' (sistema). O que aparecer com outro valor — U, de usuário, ou em branco — não veio do dicionário padrão. Isso não quer dizer que foi a sua empresa que criou: integrações e compatibilizadores da própria TOTVS também gravam parâmetros com U.

SELECT X6_FIL, X6_VAR, X6_TIPO, X6_DESCRIC, X6_CONTEUD, X6_PROPRI
  FROM SX6010
 WHERE X6_PROPRI <> 'S'
   AND D_E_L_E_T_ = ' '
 ORDER BY X6_VAR

Criando o MV_XIDMIN

No Configurador, abra Ambiente > Cadastros > Parâmetros, rotina CFGX017, e clique em Incluir. A inclusão tem duas partes:

1. Em Informações, os dados principais: Filial, Nome da Variável, Tipo (C, N, D ou L) e Conteúdo, o valor inicial. O nome não pode ser alterado depois.
2. Em Descrição, a descrição do parâmetro e as continuações, em português, espanhol e inglês.

Com a Filial em branco, o parâmetro vale para todas as filiais; preenchida, só para aquela filial. Para ter um valor próprio numa filial, a documentação da TOTVS manda cadastrar o parâmetro com o mesmo nome e o mesmo tipo.

Depois de confirmar, a primeira consulta deste artigo deve trazer:

No dicionário padrão, o conteúdo em português, espanhol e inglês é igual na grande maioria dos parâmetros. A documentação da inclusão só fala do Conteúdo; confira na mesma consulta o que ficou em X6_CONTSPA e X6_CONTENG no seu ambiente. As descrições em espanhol e inglês ficam em X6_DSCSPA e X6_DSCENG.

Sobre o tipo:

No lógico, o dicionário padrão tem de tudo: .F., .T., F, T e até conteúdo em branco. Recomendação: grave .T. ou .F., que são as formas mais frequentes, e não conte com o branco.

São três funções, e elas não fazem a mesma coisa:

// 1) Guarda em memória; devolve 21 se o parâmetro não existir
nIdMin := SuperGetMV("MV_XIDMIN", .F., 21)

// 2) Igual ao 1: GetNewPar é o SuperGetMV com lHelp .F.
nIdMin := GetNewPar("MV_XIDMIN", 21)

// 3) Sem memória: lê no banco a cada chamada
nIdMin := GetMV("MV_XIDMIN", .F., 21)

// SuperGetMV lendo o parâmetro de outra filial (quarto argumento)
nIdMin := SuperGetMV("MV_XIDMIN", .F., 21, "02")

As assinaturas, e o que cada uma faz:

• SuperGetMv(cParametro, lHelp, cDefault, cFil) guarda cada parâmetro lido, por filial, numa área de memória; a próxima leitura não vai ao banco. Sem cFil, usa a filial corrente. O lHelp é o ponto em que a documentação se contradiz; veja logo abaixo.
• GetNewPar(cVar, cRet, cFil) é um atalho: o SuperGetMv com lHelp .F.. Usa a mesma memória.
• GetMV(cMv_par, lConsulta, xDefault) não usa essa memória, e o segundo argumento é outro:
  • com lConsulta .T. e sem xDefault, devolve se o parâmetro existe (.T. ou .F.), sem log nem help;
  • com lConsulta .F., sem xDefault e parâmetro inexistente, devolve .F. e gera log (batch) ou help (remote);
  • com xDefault informado e parâmetro inexistente, devolve o xDefault e, nas palavras da documentação, “não gera log ou help” — com .T. ou com .F..

O lHelp do SuperGetMV. As duas páginas da TOTVS não dizem a mesma coisa. A do SUPERGETMV diz que “o valor verdadeiro (.T.) indica que a mensagem de ajuda (Help) será exibida”. Na leitura que vai ao banco, porém, o SuperGetMV chama o GetMV passando o lHelp como o segundo argumento dele, o lConsulta — e, pela página do GetMV, é o .F. que gera help (remote) ou log (batch), e só quando o parâmetro não existe e o valor padrão não foi informado; com .T. e sem valor padrão, a função apenas devolve se o parâmetro existe.

Regra prática: com o valor padrão informado, como em todos os exemplos deste artigo, o segundo argumento não muda nada — sem parâmetro, volta o padrão, sem aviso. Sem valor padrão, conte com o comportamento descrito na página do GetMV: .F. gera help ou log.

A regra prática vem da própria TOTVS: dado que não muda durante a execução, SuperGetMV ou GetNewPar; dado que pode mudar enquanto a rotina roda, GetMV.

Recomendação: passe o valor padrão do mesmo tipo do parâmetro — 21, e não "21", para um numérico. Assim o fonte se comporta igual com o parâmetro criado ou não, e um ambiente em que ele ainda não foi cadastrado não quebra a conta.

O uso completo do MV_XIDMIN — a validação que recusa motorista abaixo da idade mínima — está em Validação de campo.

No dicionário padrão, X6_DEFPOR traz o mesmo valor de X6_CONTEUD em todos os parâmetros. No seu ambiente, comparar as duas colunas mostra o que deixou de bater com esse valor de referência:

SELECT X6_FIL, X6_VAR, X6_TIPO, X6_CONTEUD, X6_DEFPOR
  FROM SX6010
 WHERE RTRIM(X6_CONTEUD) <> RTRIM(X6_DEFPOR)
   AND X6_PROPRI = 'S'
   AND D_E_L_E_T_ = ' '
 ORDER BY X6_VAR

O filtro X6_PROPRI = 'S' está ali porque parâmetro criado fora do padrão pode não ter valor de referência. No exemplo da documentação da FWSX6Util, o MV_DEMO aparece com X6_PROPRI U, X6_CONTEUD FILIAL_01 e X6_DEFPOR vazio. Sem o filtro, parâmetros assim entram na lista mesmo que ninguém os tenha alterado depois de criados.

É pista, não prova: a consulta mostra que o conteúdo difere do valor de referência gravado ali, não quem mudou nem quando. E a diferença nem sempre vem de edição manual. A documentação das regras de atualização da SX6 diz que, nos pacotes gerados pela Gestão de Ambientes, o X6_CONTEUD “atualiza, mesmo que em branco, caso o usuário habilite no momento da alteração”, enquanto o X6_DEFPOR, “conteúdo padrão”, fica em “nunca atualiza”. Um pacote aplicado com essa opção habilitada pode deixar as duas colunas diferentes sem que ninguém tenha editado o parâmetro.

Para o lugar da SX6 entre as outras tabelas do dicionário, veja Dicionário de dados do Protheus.