Consulta padrão (F3): como criar a lupa de um campo

A lupa de um campo é uma consulta padrão. O usuário a abre clicando na lupa ou com a tecla F3; o campo sabe qual consulta abrir pela coluna X3_F3 da SX3; e a consulta em si é um conjunto de linhas na SXB, uma para cada pedaço — tabela, índices, colunas, retorno e filtro.

O C5_CLIENTE do pedido de venda, por exemplo, tem X3_F3 = 'SA1'. É isso que faz a lupa do cliente abrir a consulta SA1.

Neste tutorial, a consulta é a ZA1, sobre o cadastro de motoristas da série, e quem a usa é o C5_XMOTOR, o campo de motorista no pedido de venda.

A SXB não se lê linha a linha: o conjunto de linhas com o mesmo XB_ALIAS forma a consulta, e o XB_TIPO diz o papel de cada linha. O XB_ALIAS é o código da consulta, não a tabela: a tabela é o XB_CONTEM da linha tipo 1. Quase sempre os dois coincidem, mas não precisam. A consulta CLI do padrão, por exemplo, abre a SA1 e devolve só SA1->A1_COD, enquanto a consulta SA1 devolve código e loja. A consulta SA3, de vendedores, é das mais simples do padrão:

Cada tipo aparece num ponto da janela que abre com o F3. Nela, o botão Pesquisa Por escolhe a chave de pesquisa, a grade mostra os registros, e embaixo ficam os botões Cancelar, Incluir, Visualizar e OK:

Lendo por tipo:

A SA3 não tem filtro. A SA1, de clientes, tem, e devolve dois retornos: SA1->A1_COD e SA1->A1_LOJA. A documentação lista ainda o tipo 7 (limite superior e inferior da tabela e alteração da pesquisa), o 8 (consulta analítica) e o 9 (fonte responsável pela manutenção da tabela); uma consulta simples não precisa deles.

O que a documentação acrescenta sobre três dos tipos:

• Tipo 1, marcadores. Depois do alias, A habilita o botão de alteração na consulta; F acrescenta um botão com uma rotina, seguida da descrição do botão e de uma possível alteração do retorno. É o caso da SB1 do padrão: SB1FA093SB1();Config;SBP->BP_BASE.
• Tipo 3, qual rotina o botão chama. Por padrão, a rotina definida para a tabela na SX2 (X2_SYSOBJ e X2_USROBJ); sem ela, o AxInclui, uma tela de inclusão genérica. Com 01#Funcao#Funcao, os # delimitam as funções de inclusão e de visualização; com 01#NO#Funcao, a inclusão fica bloqueada e só a visualização muda. Essa forma com # ainda é muito comum; na versão mais atual da consulta padrão, a rotina chamada na inclusão pode ser definida pelo registro tipo 9.
• Tipo 6, filtro dinâmico. Começado por #, o resto da expressão é macroexecutado — é como a SA1 filtra (#CRMXFilSXB("SA1")). Com @#, a função depois do operador é executada uma vez só, e não uma vez por registro. E a partir da versão 12, uma expressão precedida de @ é tratada como filtro em SQL ANSI. Escreva em SQL ANSI de fato: uma expressão com sintaxe específica de um banco deixa de ser compatível com os demais.

Duas regras da documentação da TOTVS sobre o retorno (tipo 5) que evitam a maior parte dos problemas:

• O campo devolvido precisa estar no primeiro índice do tipo 2. Na SA3, a primeira ordem é a do código, e o retorno é A3_COD.
• Cada retorno preenche um campo da tela, em sequência. Se a consulta devolve código e loja, a tela precisa ter código e loja, um depois do outro. É o caso do C5_CLIENTE com o C5_LOJACLI.

A documentação da TOTVS indica o caminho no Configurador: Base de Dados > Dicionário > Base de Dados, opção de consultas padrão, e incluir. A inclusão pede o tipo de consulta, o código e a descrição; o resto da tela recolhe o que vai para as linhas da SXB. O resultado, para a ZA1, deve ser este:

As decisões por trás de cada linha:

• O nome é o alias da tabela. O padrão faz assim (SA1, SB1, SA3), e como a ZA1 é sua, a consulta ZA1 não disputa nome com a TOTVS. O XB_ALIAS e o X3_F3 têm seis caracteres no dicionário consultado.
• Duas ordens, porque há dois índices. Ordem 1, pelo código; ordem 2, pelo nome — quem procura motorista quase sempre sabe o nome, não o código. Os índices estão em Índices no Protheus.
• Em cada ordem, a coluna da pesquisa vem primeiro. Na ordem 2, o nome abre a grade.
• O retorno é o código, que está no primeiro índice do tipo 2, como a regra pede.
• O filtro esconde motorista bloqueado. ZA1_MSBLQL é o campo reservado de bloqueio, e 1 é bloqueado. O padrão filtra bloqueio desse jeito em várias consultas — por exemplo, G4W->G4W_MSBLQL == '2', que deixa só os desbloqueados. Veja Campos reservados. O filtro vale só dentro da lupa: quem digita o código de um motorista bloqueado direto no campo não passa por ele. Para recusar o bloqueado também na digitação, a regra vai na validação do campo, como mostra o artigo de campos reservados.
• Sem tipo 3. A consulta não inclui motorista. Se a empresa quiser o botão de inclusão, é a linha tipo 3 que o habilita.

Para conferir o que ficou gravado:

SELECT XB_ALIAS, XB_TIPO, XB_SEQ, XB_COLUNA, XB_DESCRI, XB_CONTEM
  FROM SXB010
 WHERE XB_ALIAS = 'ZA1'
   AND D_E_L_E_T_ = ' '
 ORDER BY XB_TIPO, XB_SEQ, XB_COLUNA

O 010 é o sufixo da empresa; no seu ambiente pode ser outro. Troque ZA1 por SA1 ou SB1 para ver como o padrão monta as consultas mais usadas.

Ligando a consulta ao campo

Uma consulta sozinha não aparece em lugar nenhum. Quem a chama é o campo, pela coluna X3_F3. No cadastro do campo C5_XMOTOR, a consulta padrão é ZA1:

A partir daí, o campo ganha a lupa e responde ao F3. O tamanho do campo é o do ZA1_COD, que é o que a consulta devolve.

A mesma coluna existe nas perguntas: o X1_F3 da SX1 põe a lupa numa pergunta. O grupo ZA1REL usa a consulta ZA1 nas perguntas “Motorista de” e “Motorista ate” — veja Perguntas (SX1).

Antes de apagar ou renomear uma consulta, veja quem depende dela:

SELECT 'SX3' AS ORIGEM, X3_CAMPO AS ITEM
  FROM SX3010
 WHERE X3_F3 = 'ZA1'
   AND D_E_L_E_T_ = ' '
UNION ALL
SELECT 'SX1', X1_GRUPO + '/' + X1_ORDEM
  FROM SX1010
 WHERE X1_F3 = 'ZA1'
   AND D_E_L_E_T_ = ' '

A concatenação com + é do SQL Server; em outro banco, use o operador de concatenação dele.

Consulta padrão ou consulta específica

A consulta montada acima lista registros de uma tabela numa grade. Quando a tela de busca precisa ser outra — uma seleção com regra própria, dados de mais de uma tabela —, existe a consulta específica, que chama uma função.

No dicionário padrão, ela aparece com outro formato de linhas. Uma consulta específica real do padrão, a S008:

O tipo 1 traz RE no lugar de DB; o tipo 2 traz a chamada da função que monta a tela; o tipo 5, a expressão de retorno. A função da consulta específica atribui o valor escolhido à variável VAR_IXB, e é essa variável que a linha tipo 5 devolve ao campo. Para o dia a dia de um cadastro como o de motoristas, a consulta padrão resolve.