Tabela customizada no Protheus: as faixas SZ e Z e o modo de acesso

Tabela sua começa com SZ ou com Z, e o modo de acesso se decide antes de gravar o primeiro registro. As duas escolhas custam caro de consertar depois: um alias do padrão pode ser sobreposto numa atualização de versão, e o campo de filial de cada registro é preenchido na inclusão, conforme o modo de acesso daquele momento.

As faixas SZ e Z

A documentação da rotina de dicionário do Configurador divide os nomes de arquivo em famílias. De SA/A até SY/Y, as famílias são reservadas à TOTVS; SZ e Z são as reservadas a customizações. O texto é direto: os usuários não devem usar as famílias da TOTVS para criar seus arquivos, “pois estes arquivos poderão ser sobrepostos em uma atualização de versão”.

O alias tem três posições. A mesma documentação descreve cada uma: nos nomes que começam com S, a segunda letra é a família e a terceira é a sequência, de 1 a Z; nos que começam pela letra da família, a segunda e a terceira posições são sequência, também de 1 a Z. Aplicado às famílias de customização:

No dicionário padrão, nenhuma tabela começa com SZ nem com Z. A família SZ tem uma posição livre só e se esgota rápido num ambiente com muita customização; a Z tem espaço de sobra.

Antes de escolher o alias, veja o que já está em uso:

SELECT X2_CHAVE, X2_NOME, X2_MODO, X2_MODOUN, X2_MODOEMP
  FROM SX2010
 WHERE (X2_CHAVE LIKE 'SZ%' OR X2_CHAVE LIKE 'Z%')
   AND D_E_L_E_T_ = ' '
 ORDER BY X2_CHAVE

O sufixo 010 é o da empresa; no seu ambiente pode ser outro.

A SX2 guarda o modo de acesso em três colunas, uma para cada nível da estrutura de empresas do Protheus:

Em cada coluna vai C (compartilhado) ou E (exclusivo). Em AdvPL, a função FWModeAccess(cAlias, nLevel) devolve o mesmo dado, com nLevel 1 para empresa, 2 para unidade de negócio e 3 para filial.

O efeito aparece no campo de filial da tabela (ZA1_FILIAL, A1_FILIAL). Pela documentação da rotina de dicionário, esse campo só é gravado em branco quando empresa, unidade de negócio e filial são todas compartilhadas. No uso exclusivo, ele recebe a identificação de empresa, unidade de negócio e filial conforme a configuração do grupo de empresas. Assim, o usuário acessa os dados da sua empresa, unidade e filial.

O documento de conceitos de filial completa: esse valor é gravado quando o registro é inserido, e o leiaute vem do cadastro do grupo de empresas, com no máximo doze caracteres. O exemplo dado ali é EEUUFFFF: dois dígitos de empresa, dois de unidade de negócio, quatro de filial.

Lendo cada nível como uma pergunta:

• Empresa (X2_MODOEMP): as empresas do grupo usam o mesmo registro? C para sim; E para cada empresa ter o seu.
• Unidade de negócio (X2_MODOUN): dentro da empresa, as unidades usam o mesmo registro?
• Filial (X2_MODO): dentro da unidade, as filiais usam o mesmo registro?

No dicionário padrão só aparecem quatro combinações — E,E,E, C,E,E, C,C,C e C,C,E, na ordem filial, unidade, empresa. Repare no desenho: quando um nível é compartilhado, os níveis abaixo dele também são. Não existe tabela padrão exclusiva por filial e compartilhada entre empresas. Recomendação: siga o mesmo desenho nas suas tabelas.

O exemplo da série é uma transportadora com um cadastro de motoristas, a tabela ZA1. Antes de decidir, vale ver como o padrão resolveu cadastros parecidos — e o padrão tem um cadastro de motoristas:

A ZA1 da série fica C nos três níveis, como a SX5: a transportadora mantém um cadastro de motoristas só, que vale para o grupo inteiro. Com isso, ZA1_FILIAL é gravado em branco em todo registro, e o documento de conceitos de filial diz que, com o modo compartilhado, o conteúdo fica visível para qualquer usuário de qualquer filial. xFilial("ZA1") devolve brancos: a documentação da função diz que ela devolve a filial corrente se o arquivo for exclusivo e espaços em branco se ele estiver compartilhado. É esse o valor que os artigos seguintes da série usam nas buscas pela ZA1.

O desenho da DA4, C,E,E, é a alternativa para quem tem a frota separada por unidade de negócio: cada unidade tem os seus motoristas, e as filiais dela os compartilham. Escolhido na ZA1, ele muda o que vai no campo de filial e o que xFilial("ZA1") devolve: entram só a parte de empresa e a de unidade de negócio, e a parte da filial fica em branco. A documentação da xFilial mostra isso com o segundo parâmetro, que informa a filial a considerar. No exemplo dela, com as filiais D MG 01 e D RJ 01:

O modo segue a ordem filial, unidade, empresa. A página usa SA1 e SA6 só para ilustrar essas duas configurações: no dicionário padrão, a SA1 é C,E,E e a SA6 é E,E,E. No mesmo exemplo, xFilial('SA6','D RJ 01') devolve D RJ e três espaços: as filiais de uma unidade enxergam o mesmo cadastro, e as de outra unidade, outro. Numa tabela exclusiva nos três níveis, a regra da função — devolver a filial quando o arquivo é exclusivo — faz D MG 01 voltar inteira. Se a ZA1 estivesse em C,E,E, toda busca pela tabela passaria a depender da filial em que o usuário está e enxergaria só o cadastro da unidade dele.

No Configurador, o caminho documentado é Base de Dados + Dicionário + Arquivos; com o cursor sobre Dicionário de Dados, clique em Incluir e preencha a pasta Nova Tabela de Dados:

A documentação descreve o Modo de Acesso da tela de inclusão como uma escolha só: E - Exclusivo ou C - Compartilhado. Ela não mostra ali um campo para cada nível. O que ficou gravado em cada nível se confere na SX2, nas três colunas X2_MODO, X2_MODOUN e X2_MODOEMP; na ZA1, as três devem trazer C.

Nome é o nome físico: a documentação diz que o arquivo ali especificado é aberto ou criado quando o sistema o carrega. No dicionário padrão ele é o alias seguido de um sufixo de três dígitos que varia por instalação; na série, ZA1010, e é esse o nome que a consulta ao banco procura mais adiante. Confirme com Ok; pela documentação, os campos e as pastas vinculados ao arquivo são informados depois, pelo recurso Editar.

O que foi incluído no dicionário chega ao banco pela rotina Atualizar Base de Dados, e a documentação dela é explícita: alterações que interferem na estrutura da tabela (ela cita inclusão de campos, alteração de título, exclusão de campos) só são gravadas com o processamento em modo exclusivo. O sistema mostra as alterações pendentes; o administrador pode pedir que todos os usuários saiam ou avançar sem gravar. Fora do modo exclusivo aparece uma advertência, e é preciso cancelar e voltar com o sistema em modo exclusivo. Em modo exclusivo, é feito um backup de segurança antes de gravar, e ao final a rotina mostra o que foi gravado.

Depois disso, confira o dicionário:

SELECT X2_CHAVE, X2_ARQUIVO, X2_NOME, X2_NOMESPA, X2_NOMEENG,
       X2_MODO, X2_MODOUN, X2_MODOEMP, X2_UNICO
  FROM SX2010
 WHERE X2_CHAVE IN ('ZA1', 'DA4')
   AND D_E_L_E_T_ = ' '

A coluna X2_UNICO guarda a chave única. A documentação da rotina informa que a inserção da chave única em arquivos customizados (famílias SZ e Z) passou a ser aceita a partir de uma versão recente do Protheus, e que o cliente não pode modificar a chave única das tabelas padrão; ela não diz em que ponto da tela de inclusão a chave é informada. A linha da DA4 mostra o modelo (DA4_FILIAL+DA4_COD); o equivalente na ZA1 seria ZA1_FILIAL+ZA1_COD. Coluna em branco na linha da ZA1 quer dizer que a tabela está sem chave única gravada no dicionário.

E a tabela física:

SELECT TABLE_NAME
  FROM INFORMATION_SCHEMA.TABLES
 WHERE TABLE_NAME = 'ZA1010'

Se ela ainda não aparecer, não é erro: a documentação da rotina diz que o arquivo especificado é aberto ou criado quando o sistema o carrega.

A tabela vai precisar do campo ZA1_FILIAL mesmo compartilhada nos três níveis — é nele que o modo de acesso se materializa, ainda que em branco. Quase toda tabela de dados do padrão tem campo de filial; as exceções são raras, como a SM2 (Moedas do Sistema).

Os próximos passos da série:

1. Os campos reservados de log, bloqueio e imagem: Campos reservados.
2. Os campos comuns e o que cada tipo grava: Os cinco tipos de campo.
3. Os índices, sempre começando pela filial: Índices no Protheus.
4. A primeira tela de cadastro: Testando a tabela criada.

Se a dúvida é se o dado precisa mesmo de uma tabela nova — às vezes uma lista fixa resolve —, veja Tabelas genéricas (SX5).