Templates e regras de validacao para gerar scripts de configuracao do dicionario SX do TOTVS Protheus - SX2, SX3, SIX, SXG, SXA, SX1, SX5, SXB e SX7

SX Configuration

Templates e regras de validacao para gerar scripts de configuracao do dicionario de dados Protheus. Cobre SX2 (cabecalho de tabela), SX3 (campos), SIX (indices), SXG (grupos de campos), SXA (pastas de cadastro), SX1 (perguntas de relatorio), SX5 (tabelas genericas), SXB (consultas padrao F3) e SX7 (gatilhos).

Quando Usar

Registrar uma nova tabela customizada (cabecalho)
Criar novos campos customizados para uma tabela
Definir indices para tabelas customizadas
Agrupar campos relacionados entre tabelas (grupos de campo)
Organizar campos em pastas/abas em formularios MVC
Configurar perguntas de parametros de relatorio
Criar tabelas genericas de lookup
Configurar consultas padrao F3
Configurar gatilhos de campo

SX2 -- Mapeamento de Tabelas

Define a propria tabela: alias, nome fisico, modo de compartilhamento e modo de acesso. Deve ser criada antes de gerar campos SX3 para uma nova tabela customizada.

Campos Obrigatorios

Campo	Descricao	Exemplo
X2_CHAVE	Alias da tabela (3 chars)	ZA1
X2_PATH	Caminho (geralmente vazio — usa o padrao)
X2_ARQUIVO	Padrao do nome fisico	ZA1990
X2_NOME	Descricao pt-BR	Ordens de Servico
X2_NOMESPA	Descricao es	Ordenes de Servicio
X2_NOMEENG	Descricao en	Service Orders
X2_MODO	Modo de compartilhamento: C/E/M	C
X2_MODOEMP	Modo de compartilhamento por empresa	C
X2_MODOUN	Modo de compartilhamento por filial	C
X2_TTS	Tabela transacional (Sim/Nao)	Sim
X2_PYME	Disponivel na edicao PYME (Sim/Nao)	Sim
X2_USROPER	Auditoria de usuario (Sim/Nao)	Sim

Referencia de Modo de Compartilhamento

X2_MODO	Significado	Caso de Uso
`C`	Compartilhado (entre todas as empresas/filiais)	Tabelas de lookup globais, parametros
`E`	Exclusivo (por filial)	Maioria das tabelas transacionais (SA1, SE1, SF2)
`M`	Misto (depende de X2_MODOEMP/X2_MODOUN)	Casos especiais multi-tenant

Regras

Alias deve ter 3 chars maiusculos; tabelas customizadas usam prefixo Z (ZA1-ZZZ, Z01-Z99).
O nome fisico (X2_ARQUIVO) e o nome base antes do padding de empresa/filial (ex.: ZA1990). Em tempo de execucao, o DBAccess acrescenta o codigo da empresa, produzindo ZA1990010.
Use RetSqlName("ZA1") em tempo de execucao — nunca hardcode o nome fisico.
X2_TTS = Sim habilita controle transacional via BeginTran/EndTran. Obrigatorio para qualquer tabela modificada dentro de blocos RecLock que precisem de rollback.
Para novas tabelas customizadas: registre SX2 primeiro, depois SX3, depois SIX, e por fim SXG/SXA/SXB/SX7 opcionais.

SX3 -- Definicao de Campo

Campos Obrigatorios

Campo	Descricao	Exemplo
X3_ARQUIVO	Alias da tabela	ZA1
X3_ORDEM	Ordem do campo (2 digitos)	01
X3_CAMPO	Nome do campo (ALIAS_FIELD)	ZA1_CODIGO
X3_TIPO	Tipo: C, N, D, L, M	C
X3_TAMANHO	Tamanho	6
X3_DECIMAL	Casas decimais (para N)	0
X3_TITULO	Titulo pt-BR (max 15 chars)	Codigo
X3_TITSPA	Titulo es (max 15 chars)	Codigo
X3_TITENG	Titulo en (max 15 chars)	Code
X3_DESCRIC	Descricao pt-BR	Codigo da OS
X3_DESCSPA	Descricao es	Codigo de la OS
X3_DESCENG	Descricao en	OS Code
X3_PICTURE	Formato de exibicao	@!
X3_VALID	Expressao de validacao	NaoVazio()
X3_USADO	Em uso (Sim/Nao)	Sim
X3_OBRIGAT	Obrigatorio (Sim/Nao)	Sim
X3_BROWSE	Exibir no browse (Sim/Nao)	Sim
X3_VISUAL	Modo de edicao: Alterar/Visualizar	Alterar
X3_CONTEXT	Contexto: Real/Virtual	Real
X3_CBOX	Opcoes de combo (val1=desc1;val2=desc2)
X3_RELACAO	Expressao de valor inicial
X3_F3	Alias de lookup F3	SA1
X3_VLDUSER	Expressao de validacao do usuario
X3_TRIGGER	Tem gatilho (Sim/Nao)	Nao

Regras de Validacao

Regra	Condicao	Acao
Formato do nome do campo	Deve ser ALIAS_XXXXXX (6 chars apos underscore)	Erro se invalido
Tamanho tipo C	1-254 caracteres	Aviso se > 100
Tamanho tipo N	Max 18 digitos incluindo decimal	Erro se > 18
Tamanho tipo D	Sempre 8	Auto-definir para 8
Tamanho tipo L	Sempre 1	Auto-definir para 1
Tamanho tipo M	Sempre 10	Auto-definir para 10
Picture para C	@! (maiuscula), @R (mascara), ou customizado	Sugerir @! para codigos
Picture para N	@E 999,999,999.99 (ajustar ao tamanho)	Auto-gerar a partir de tamanho/decimal
Picture para D	(nao necessario)	Deixar vazio
Obrigatorio + Validacao	Se X3_OBRIGAT = Sim, adicionar NaoVazio() a X3_VALID	Auto-adicionar
Lookup F3	Se X3_F3 definido, validacao deve incluir ExistCpo	Sugerir adicionar
CBOX + Validacao	Se X3_CBOX definido, adicionar Pertence() a X3_VALID	Auto-adicionar
Auto-incremento	Se chave primaria, definir X3_RELACAO = GetSXENum()	Sugerir para primeiro campo
Gatilho	Se F3 definido e campo de exibicao relacionado necessario, gerar SX7	Auto-gerar

Validacoes Comuns

Validacao	Quando usar	Sintaxe
NaoVazio()	Campo obrigatorio	NaoVazio()
ExistCpo(alias, M->field)	Lookup de chave estrangeira	ExistCpo("SA1", M->ZA1_CLIENT)
ExistChav(alias, M->field, order)	Verificacao de chave unica	ExistChav("ZA1", M->ZA1_CODIGO, 1)
Pertence(values)	Validacao de combo	Pertence("1234")
Positivo()	Deve ser > 0	Positivo()
Vazio() .Or. ExistCpo()	Chave estrangeira opcional	Vazio() .Or. ExistCpo("SA1", M->ZA1_CLIENT)

Pictures Comuns

Tipo	Picture	Exemplo de exibicao
Codigo (maiuscula)	@!	ABC123
CNPJ	@R 99.999.999/9999-99	12.345.678/0001-90
CPF	@R 999.999.999-99	123.456.789-00
Telefone	@R (99) 99999-9999	(11) 98765-4321
Moeda	@E 999,999,999.99	1,234.56
Percentual	@E 999.99	15.50

SIX -- Definicao de Indice

Campos Obrigatorios

Campo	Descricao	Exemplo
INDICE	Alias da tabela	ZA1
ORDEM	Numero de ordem do indice	1
CHAVE	Expressao de chave (campos concatenados)	ZA1_FILIAL + ZA1_CODIGO
DESCRICAO	Descricao pt-BR	Codigo
DESCSPA	Descricao es	Codigo
DESCENG	Descricao en	Code
NICKNAME	Apelido do indice	ZA1_CODIGO
SHOWPESQ	Exibir na pesquisa (Sim/Nao)	Sim

Regras

Indice 1 e SEMPRE a chave primaria (FILIAL + campo unico)
FILIAL deve ser o primeiro componente de todo indice
Nickname deve ser unico dentro da tabela
Ordem deve ser sequencial comecando de 1

SXG -- Grupos de Campos

Grupos definem um contrato compartilhado de tamanho/decimais entre campos que devem permanecer alinhados (ex.: um campo de codigo de cliente que aparece em SA1, SE1, SC5 deve sempre ter o mesmo tamanho em todos os lugares). Alterar o grupo propaga a mudanca para todos os campos vinculados via ferramenta de atualizacao do dicionario.

Campos Obrigatorios

Campo	Descricao	Exemplo
XG_GRUPO	Codigo do grupo (3 chars/digitos)	033
XG_DESCRIC	Descricao pt-BR	Codigo do Cliente
XG_DESCSPA	Descricao es	Codigo del Cliente
XG_DESCENG	Descricao en	Customer Code
XG_TAMANHO	Tamanho	6
XG_DECIMAL	Decimais (para N)	0
XG_PICTURE	Formato de exibicao	@!
XG_TIPO	Tipo: C, N, D, L, M	C

Vinculando Campos SX3 a um Grupo

No registro SX3 de cada campo relacionado, preencha X3_GRUPO com o codigo do grupo:

X3_CAMPO   = A1_COD
X3_GRUPO   = 033
X3_TAMANHO = 6     (deve coincidir com XG_TAMANHO)
X3_TIPO    = C     (deve coincidir com XG_TIPO)

Regras

Codigo do grupo: 3 chars (TOTVS usa numerico 001-999; grupos customizados usam prefixo Z, como Z01).
Todos os campos SX3 com o mesmo X3_GRUPO devem concordar em X3_TIPO, X3_TAMANHO, X3_DECIMAL e X3_PICTURE.
Use um grupo sempre que o mesmo campo logico existir em 2 ou mais tabelas (codigos, chaves estrangeiras, totais).
A ferramenta de atualizacao do dicionario (UpdDistr/UPDDISTR) usa SXG para propagar alteracoes de tamanho — sem grupo, cada linha SX3 deve ser editada manualmente.

SXA -- Pastas de Cadastro

Define pastas (abas) usadas para organizar visualmente os campos em formularios MVC (AxCadastro, MVCAxCadastro, FormView). Sem o registro SXA, as views MVC retornam para uma unica aba padrao.

Campos Obrigatorios

Campo	Descricao	Exemplo
XA_ALIAS	Alias da tabela	ZA1
XA_ORDEM	Ordem da pasta (2 digitos)	01
XA_DESCRIC	Nome da pasta pt-BR	Cadastrais
XA_DESCSPA	Nome da pasta es	Generales
XA_DESCENG	Nome da pasta en	General
XA_AGRUPCM	Agrupamento visual (opcional)

Vinculando Campos SX3 a uma Pasta

Em cada linha SX3, defina X3_FOLDER com a ordem da pasta desejada:

X3_CAMPO  = ZA1_CODIGO
X3_FOLDER = 01            -- Vai para a pasta "Cadastrais"

X3_CAMPO  = ZA1_OBSERV
X3_FOLDER = 02            -- Vai para a pasta "Observacoes"

Regras

A ordem das pastas deve ser sequencial (01, 02, 03...) por tabela.
Um campo com X3_FOLDER vazio e alocado na pasta 01.
Os nomes das pastas aparecem traduzidos de acordo com o idioma do usuario (pt-BR / es / en).
Para telas master-detail complexas, combine SXA com a configuracao de view FWFormDetail (o SXA define as pastas; a View anexa as grids a elas).

SX1 -- Perguntas de Relatorio

Campos Obrigatorios

Campo	Descricao	Exemplo
X1_GRUPO	Nome do grupo (corresponde ao alias do relatorio)	ZA1
X1_ORDEM	Ordem da pergunta (2 digitos)	01
X1_PERGUNT	Texto da pergunta pt-BR	Data Abertura De
X1_PERGSPA	Texto da pergunta es	Fecha Apertura De
X1_PERGENG	Texto da pergunta en	Open Date From
X1_TIPO	Tipo: C, N, D	D
X1_TAMANHO	Tamanho do campo	8
X1_GSC	Get/Select/Combo: G, S, C	G
X1_VALID	Expressao de validacao
X1_DEF01	Valor padrao	Space(8)
X1_F3	Lookup F3 (para tipo C)	SA1
X1_HELP	Texto de ajuda	Data inicial

Regras

Perguntas vem em pares para filtros de faixa (De/Ate)
Tipo D sempre tem tamanho 8
Padrao para data "De": Space(8) ou primeiro dia do mes
Padrao para data "Ate": dDataBase ou ultimo dia do mes
Padrao para char "De": Space(tamanho)
Padrao para char "Ate": Replicate("Z", tamanho)
Se combo (C), X1_DEF01 contem o valor da opcao padrao
X1_GSC: G=Get (input de texto), S=Select (incomum), C=Combo

SX5 -- Tabelas Genericas

Campos Obrigatorios

Campo	Descricao	Exemplo
X5_FILIAL	Filial (geralmente vazio para global)
X5_TABELA	Codigo da tabela (2 chars)	ZZ
X5_CHAVE	Valor da chave (2 chars)	01
X5_DESCRI	Descricao pt-BR	Preventiva
X5_DESCSPA	Descricao es	Preventiva
X5_DESCENG	Descricao en	Preventive

Regras

Codigo da tabela: 2 caracteres maiusculos (usar prefixo Z para custom: ZA, ZB, ZZ, etc.)
Chave: 2 caracteres, sequencial (01, 02, 03...)
Para usar no codigo: GetSX5("ZZ", "01") ou X5DESCRI("ZZ", "01")

SXB -- Consultas Padrao (F3)

Define a janela de lookup F3: o dialogo que abre quando o usuario pressiona F3 em um campo com X3_F3 preenchido. Configura colunas de pesquisa, colunas exibidas no resultado e o valor retornado ao campo de origem. Composto por 4 tipos de linha (XB_TIPO): 1 = definicao do lookup, 2 = indice de pesquisa, 3 = colunas de exibicao, 4 = expressao de retorno.

Campos Obrigatorios (cabecalho / tipo 1)

Campo	Descricao	Exemplo
XB_ALIAS	Codigo do lookup (coincide com X3_F3)	SA1
XB_TIPO	Tipo da linha: 1, 2, 3, 4	1
XB_SEQ	Sequencia (2 digitos)	01
XB_COLUNA	Referencia de coluna/ordem	DB
XB_DESCRIC	Descricao pt-BR	Clientes
XB_DESCSPA	Descricao es	Clientes
XB_DESCENG	Descricao en	Customers
XB_CONTEM	Conteudo (expressao de chave / nome de campo)	SA1
XB_WCONTEM	Clausula when (opcional)

Referencia de Tipos de Linha

XB_TIPO	Finalidade	O que vai em XB_CONTEM
`1`	Cabecalho do lookup (um por alias)	Alias da tabela de origem (ex.: `SA1`)
`2`	Indice de pesquisa	Numero de ordem do indice para pesquisa (ex.: `1`, `3`)
`3`	Coluna de exibicao na janela de lookup	Nome do campo (ex.: `A1_COD`, `A1_NOME`)
`4`	Expressao de retorno -- valor devolvido ao campo de origem	Expressao AdvPL (ex.: `SA1->A1_COD`)

Exemplo: Lookup Customizado de SA1 por Nome

-- Tipo 1: Cabecalho
XB_ALIAS    = SACN  (codigo customizado de 4 chars)
XB_TIPO     = 1
XB_SEQ      = 01
XB_DESCRIC  = Clientes por Nome
XB_CONTEM   = SA1

-- Tipo 2: Pesquisa pelo indice 3 (A1_FILIAL + A1_NOMECOM)
XB_TIPO     = 2
XB_SEQ      = 01
XB_CONTEM   = 3

-- Tipo 3: Exibir A1_COD, A1_LOJA, A1_NOME no grid de lookup
XB_TIPO     = 3
XB_SEQ      = 01
XB_CONTEM   = A1_COD
XB_TIPO     = 3
XB_SEQ      = 02
XB_CONTEM   = A1_LOJA
XB_TIPO     = 3
XB_SEQ      = 03
XB_CONTEM   = A1_NOME

-- Tipo 4: Retornar A1_COD ao campo de origem
XB_TIPO     = 4
XB_SEQ      = 01
XB_CONTEM   = SA1->A1_COD

O campo de origem referencia o lookup assim:

X3_F3 = SACN

Regras

XB_ALIAS deve coincidir exatamente com X3_F3 (normalmente o proprio alias da tabela, mas codigos customizados de 4 chars como SACN sao validos para lookups alternativos na mesma tabela).
Sempre fornecer ao menos um registro de cada tipo 1, 2, 3 e 4 -- do contrario a janela de lookup ficara incompleta.
Multiplos registros do tipo 2 permitem ao usuario alternar entre indices de pesquisa (F12 no lookup).
Multiplos registros do tipo 3 definem as colunas exibidas -- a ordem importa.
A expressao do tipo 4 deve retornar um valor compativel com o tipo e tamanho do campo de origem.
A filtragem de D_E_L_E_T_ e feita implicitamente pelo indice subjacente -- o SXB usa Workarea (DbSeek) internamente, nao SQL direto.

SX7 -- Gatilhos

Campos Obrigatorios

Campo	Descricao	Exemplo
X7_CAMPO	Campo de origem	ZA1_CLIENT
X7_SEQUENC	Sequencia (3 digitos)	001
X7_REGRA	Expressao a avaliar	Posicione("SA1", 1, xFilial("SA1") + M->ZA1_CLIENT, "A1_NOME")
X7_CDOMIN	Campo de dominio (destino a preencher)	ZA1_NMCLI
X7_TIPO	Tipo: P=Primario	P
X7_SEEK	Expressao de seek	xFilial("SA1") + M->ZA1_CLIENT
X7_ALIAS	Alias de lookup	SA1
X7_ORDEM	Ordem do indice para seek	1
X7_CHTEFIL	Verificar filial (Sim/Nao)	Sim

Regras

Gatilhos disparam quando o campo de origem muda
Posicione() e a funcao padrao para lookups
Sempre incluir xFilial() na expressao de seek
Sequencia permite multiplos gatilhos no mesmo campo

Formato de Saida

Scripts sao formatados como blocos chave-valor, uma definicao de campo por bloco, separados por tracos. Este formato e legivel e pode ser usado como referencia para configuracao manual no Configurador ou para scripts de importacao.

SX Configuration

Nesta pagina