Índices no Protheus: filial primeiro e nickname em tabela padrão

Índice é o que permite ao Protheus ir direto a um registro em vez de ler a tabela inteira. Numa tabela sua, ele é quase burocracia: filial, código, pronto. Numa tabela padrão, o índice que você cria disputa espaço com os que a TOTVS entrega — e é aí que o nickname deixa de ser um campo opcional.

O que a SIX guarda

Cada linha da SIX é um índice. As colunas que decidem alguma coisa:

É a mesma estrutura para tabela padrão e customizada. A diferença está no que você faz com ela.

Veja os índices do pedido de venda no dicionário padrão:

Três coisas saltam dessa tabela.

Todas começam por C5_FILIAL. A mesma tabela física guarda os registros de todas as filiais, e a busca parte de “desta filial”. Por isso o DbSeek num índice desses começa com xFilial("SC5"): a chave montada precisa casar com a chave do índice, na mesma ordem de campos. Num índice que começa por outro campo (as exceções logo abaixo), a chave do DbSeek segue aquele índice, não a regra.

No dicionário padrão inteiro, praticamente todos os índices seguem essa regra. As exceções existem e são deliberadas: índices que começam por outro campo de filial (a filial de entrega do pedido de compra, C7_FILENT), índices de busca global por um identificador (E1_IDCNAB, no contas a receber) e alguns em que a filial vem depois do campo buscado. Para uma tabela sua, não há motivo para imitar a exceção: comece pela filial.

Depois do 9 vem o A. A ORDEM tem um caractere só. Passou de nove índices, a numeração segue em letras — no dicionário padrão há tabela chegando à ordem T. Em código, dbSetOrder(10) é a ordem A.

Data entra com DTOS(). O índice é de texto; o campo data é convertido para AAAAMMDD para ordenar certo. Mais sobre o formato em Tipos de dados em AdvPL.

A documentação da SIX define SHOWPESQ assim: preenchido com S, o índice é mostrado no browse do sistema. Com S, ele entra nas ordens que o usuário escolhe ao pesquisar; com N, continua existindo e funcionando para o código (DbSetOrder, DbOrderNickName), só não é oferecido a quem pesquisa. No padrão há os dois casos — na SB1, as ordens A (B1_FILIAL+B1_BASE3), C (B1_FILIAL+B1_CONTA) e D (B1_FILIAL+B1_CC) são N.

A mesma página traz a regra que pega tabela nova: toda tabela precisa de pelo menos um índice com SHOWPESQ = S para poder ser exibida dentro de um browse. Na ZA1, é o índice 1 que cumpre esse papel.

Na ZA1 desta série, os dois índices ficam visíveis:

Onde se cria

Pela documentação da TOTVS, o caminho é o Configurador, em Base de Dados > Dicionário: abra o Dicionário de Dados, localize a tabela, entre em edição, vá em Índices e inclua. No campo da chave, as ações relacionadas oferecem a lista de campos para montar a expressão — filial primeiro. Marque Mostra Pesq se o usuário deve ver o índice e informe o Nickname. Confirme duas vezes, clique em Atualizar Base de Dados e vá avançando até Finalizar — sem esse passo, o índice fica só no que você digitou.

Suponha que a transportadora desta série criou na SC5 o campo C5_XMOTOR, com o código do motorista do pedido, e quer achar os pedidos de um motorista. O índice novo entra depois dos onze do padrão — digamos, na ordem C. O código natural seria:

SC5->(DbSetOrder(12))   // ordem C, hoje

Funciona até a próxima atualização de dicionário. A documentação da TOTVS pede que, antes de rodar um compatibilizador, os índices personalizados estejam identificados pelo nickname: se o compatibilizador precisar criar índices, vai adicioná-los a partir da ordem original instalada pelo Protheus, o que pode sobrescrever índices personalizados sem nickname. A ordem C que era sua passa a ser de um índice do padrão. O DbSetOrder(12) continua compilando e rodando, só que agora num índice com outra chave. O DbSeek não acha o que deveria, ou acha outra coisa, e nenhum erro aparece.

O nickname tira a posição da equação. O índice ganha um nome — ZMOTOR — e o código chama pelo nome:

DBOrderNickname(cApelido) seleciona o índice pelo apelido. Se o apelido não existir, a função mostra erro e devolve .F. — o que é bem melhor que pesquisar em silêncio no índice errado:

#Include "Protheus.ch"

/*/{Protheus.doc} ZPEDMOT
Conta os pedidos de venda de um motorista usando o indice customizado
de nickname ZMOTOR (C5_FILIAL+C5_XMOTOR+C5_NUM), e nao a posicao dele.
@type user function
@param cMotor, character, codigo do motorista (ZA1_COD)
@return numeric, quantidade de pedidos encontrados
/*/
User Function ZPEDMOT(cMotor)

    Local aArea    := GetArea()
    Local aAreaSC5 := {}
    Local cChave   := ""
    Local nQtd     := 0

    DbSelectArea("SC5")
    aAreaSC5 := SC5->(GetArea())

    // A chave precisa ter o tamanho do campo: codigo curto nao casa.
    cChave := xFilial("SC5") + PadR(cMotor, TamSX3("C5_XMOTOR")[1])

    // Pelo nome, nunca pela posicao.
    If SC5->(DbOrderNickName("ZMOTOR"))
        SC5->(DbSeek(cChave))
        While SC5->(!Eof()) .And. SC5->(C5_FILIAL + C5_XMOTOR) == cChave
            nQtd++
            SC5->(DbSkip())
        EndDo
    EndIf

    RestArea(aAreaSC5)
    RestArea(aArea)

Return nQtd

O próprio padrão usa esse desenho — há rotina da TOTVS chamando SB7->(DbOrderNickName("ACDSB701")). O GetArea/RestArea em volta existe porque a função troca a ordem da SC5; quem chamou não pode sentir isso (GetArea e RestArea em AdvPL).

Na tabela customizada (ZA1), não há índice do padrão disputando posição. Ali o nickname é opcional.

Confira no seu ambiente

Os índices de uma tabela, na ordem em que o código os enxerga:

SELECT ORDEM, CHAVE, DESCRICAO, NICKNAME, SHOWPESQ, PROPRI
  FROM SIX010
 WHERE INDICE = 'SC5'
   AND D_E_L_E_T_ = ' '
 ORDER BY ORDEM

O sufixo 010 é o da empresa; troque pelo do seu ambiente.

E a consulta que vale rodar antes de qualquer atualização de dicionário: os índices criados pelo cliente que ainda não têm nickname.

SELECT INDICE, ORDEM, CHAVE, DESCRICAO
  FROM SIX010
 WHERE PROPRI = 'U'
   AND LTRIM(RTRIM(NICKNAME)) = ''
   AND D_E_L_E_T_ = ' '
 ORDER BY INDICE, ORDEM

Cada linha numa tabela padrão é candidata a nickname — e cada fonte que usa aquele índice por DbSetOrder é candidato a revisão.

Se a sua base tem índice customizado sem nickname e uma atualização pela frente, fale com a gente.