UPDDISTR no Protheus: guia completo

O UPDDISTR é o compatibilizador do TOTVS Protheus: a rotina que lê um dicionário de dados diferencial e aplica no ambiente as mudanças de metadado e de estrutura de banco que ele descreve. É ele que roda em todo upgrade de release do Protheus 12, e também quando a TOTVS expede um dicionário novo dentro da mesma release, por um módulo novo ou por uma exigência legal.

O que o UPDDISTR faz é limitado de propósito: atualiza o dicionário (SX2, SX3, SIX, SX7 e os demais), os helps de campo e a base de dados. Ele não troca o RPO, não aplica patch nem pacote e, fora do upgrade de release, não mexe em menu. Quem confunde essas fronteiras é quem descobre, na janela de produção, que o dicionário subiu e o repositório ficou para trás.

Este guia reúne o que a documentação do TDN e da Central de Atendimento TOTVS espalham em meia dúzia de páginas: quando rodar, os pré-requisitos release a release, os arquivos certos, a limpeza das pastas, o passo a passo com o modo simulação, os erros críticos mais comuns e o que fazer depois.

Vai atualizar de release e não sabe o que vai quebrar? A WeePulse levanta o ambiente, roda CHECKDUPL e UPDDISTR em simulação e trata os erros antes da janela de produção. Falar com um especialista.

UPDDISTR é a rotina do TOTVS Protheus 12 que aplica um dicionário de dados diferencial ao ambiente, atualizando metadados, helps de campo e a estrutura das tabelas no banco de dados. Usa o mesmo núcleo do atualizador de versão, aceita dicionário parcial, roda por grupo de empresas, tem modo de simulação e é obrigatória em todo upgrade de release do Protheus 12.

O que é o UPDDISTR?

O nome vem de “update distribuído”: a mesma lógica do atualizador de versão do Protheus, empacotada para rodar com um dicionário parcial. Segundo a página “Upgrade de Release do Protheus 12” do TDN, o núcleo do UPDDISTR e o do atualizador de versão são iguais, o que garante que as regras de atualização não divergem entre as duas ferramentas. A diferença é que o atualizador de versão exige sempre o dicionário completo, e o UPDDISTR trabalha com o diferencial.

Um dicionário diferencial é um dicionário parcial, com só o que mudou em relação ao que o ambiente já tem. A TOTVS o usa para três coisas: levar o dicionário para uma versão mais nova dentro da mesma release, inserir o dicionário de um produto, módulo ou funcionalidade nova, e fazer ajustes pontuais por requisito legal. A Reforma Tributária é o caso mais frequente de 2026: os campos de IBS e CBS, a tabela cClassTrib e os grupos novos da NF-e chegam ao Protheus por dicionário, e o dicionário chega ao ambiente pelo UPDDISTR.

Na prática, o UPDDISTR lê o arquivo diferencial da pasta SystemLoad, compara com o dicionário em uso, decide o que criar ou alterar (campos novos, tamanhos, índices, tabelas, gatilhos, parâmetros) e aplica a mudança no metadado e no banco. A inteligência de decidir como se comportar em cada situação está documentada na página “Regras para atualização dos dicionários” do TDN.

UPDDISTR, atualizador de versão e UPDBATCH: qual usar

Ferramenta	Para quê	Dicionário	Quando
Atualizador de versão (MP710TO120)	Migrar do Protheus 11 ou anterior para o Protheus 12	Completo	Só na troca de versão. O UPDDISTR não serve para isso
UPDDISTR	Upgrade de release do Protheus 12 e aplicação de dicionário diferencial dentro da release	Diferencial (o completo fica na pasta para uso futuro)	Toda troca de release e toda expedição de dicionário
UPDBATCH	Aplicar vários pacotes SDF de dicionário em lote, com fila	Diferencial, vários	Desde a 12.1.33, para a rotina de Expedição Contínua de muitos módulos

A página “Atualizar o Dicionário de Dados do Protheus 12” do TDN é taxativa: só execute o UPDDISTR se estiver fazendo upgrade de release do Protheus 12, de uma release antiga para uma nova. Na migração de versão anterior para o Protheus 12, o migrador usa o dicionário completo e o UPDDISTR não é necessário.

O UPDBATCH usa o mesmo mecanismo e as mesmas regras do UPDDISTR, mas enfileira a execução de diversos pacotes SDF. A TOTVS o apresentou com a 12.1.33 justamente porque, dependendo de quantos módulos a empresa usa, a quantidade de pacotes de Expedição Contínua é grande. Para uma atualização de release, o caminho é o UPDDISTR; para aplicar o acumulado de dicionários de dez módulos depois dela, o UPDBATCH poupa tempo.

O que o UPDDISTR atualiza, e o que ele não atualiza

Atualiza:

• o dicionário de dados (tabelas SX2, campos SX3, índices SIX, gatilhos SX7, parâmetros SX6, perguntas SX1, grupos de campos SXG e os demais);
• os helps de campo e de pergunta, a partir do arquivo diferencial de helps;
• a estrutura da base de dados decorrente do dicionário novo: tamanho de campo, campo novo, índice novo, tabela nova;
• os menus padrão, só em upgrade de release, com dicionário no banco de dados e Lib 20180820 ou superior, quando o arquivo .xnu do módulo é colocado em systemload/updmenu.

Não atualiza:

• o RPO (repositório de objetos). A troca do RPO e a atualização da Lib são passos à parte;
• patches, updates e pacotes de programa;
• customizações e pontos de entrada, que precisam ser reaplicados e testados;
• o TSS, o DBAccess, o AppServer e o License Server, que têm versões mínimas próprias por release.

Essa separação explica a ordem do procedimento: primeiro os componentes de infraestrutura, depois os arquivos de dicionário, RPO e helps, e só então o UPDDISTR.

Quando rodar o UPDDISTR

Quatro situações, por ordem de frequência em um ambiente em operação:

1. Upgrade de release do Protheus 12. É o caso clássico: sair da 12.1.2410 ou da 12.1.2510 para a 12.1.2610, por exemplo. O UPDDISTR é obrigatório e roda uma vez por grupo de empresas.
2. Dicionário diferencial dentro da mesma release. A TOTVS expede dicionários acumulados por módulo, as Expedições Contínuas, com alterações já feitas para a próxima release e liberadas para as anteriores. Aplicar esses pacotes é rodar o UPDDISTR (ou o UPDBATCH, em lote).
3. Requisito legal. A tabela cClassTrib, o CNPJ alfanumérico e os campos de IBS e CBS da NF-e chegaram ao Protheus por pacote de dicionário. A orientação da TOTVS, em todos esses casos, é atualizar o ambiente e rodar o UPDDISTR antes de importar a tabela ou habilitar a rotina.
4. Módulo ou funcionalidade nova contratada depois da implantação, que traz dicionário próprio.

Quando não rodar: na migração do Protheus 11 para o 12 (é o MP710TO120) e em troca de RPO ou aplicação de patch que não vem acompanhada de dicionário. Rodar o UPDDISTR sem pacote de dicionário na SystemLoad não atualiza nada e, na pior hipótese, confunde o controle de aplicação de pacotes.

Antes de rodar: os pré-requisitos por release

A página de upgrade do TDN, revisada em 18 de setembro de 2026, lista o que precisa estar pronto antes do UPDDISTR. O essencial, release a release:

Release de destino	License Server	DBAccess	AppServer (build)	Lib	Outras exigências
12.1.2210	3.4.3 ou superior				Dicionários, menus e usuários no banco de dados (obrigatório). SX2 e SX3 com chave única: rodar CHECKDUPL antes
12.1.2310	3.6.0 ou superior	23.1.1.0	20.3.2.0	20231009	Configurar o tipo do ambiente ao final
12.1.2410	3.6.2 ou superior	24.1.0.0	24.3.0.0	20241007	Sem chave duplicada em SX5 e SX6 (CHECKDUPL desde a Lib 20240520); dicionário de referência obrigatório; banco de dados e sistema operacional homologados, validados na atualização
12.1.2510	3.7.0 ou superior	24.1.1.0	24.3.1.0	20251006	Oracle Database 21c Standard exige o grant de execução em dbms_crypto, concedido por usuário SYS
12.1.2610	3.7.2 ou superior	26.1.0.0	26.3.0.0	20261005	Repositório de imagens no banco de dados recomendado

Quatro regras valem para qualquer release:

• Cópia fria e consistente. Todos os serviços parados, cópia do banco de dados e das pastas do Protheus. A TOTVS trata isso como recomendação forte e como obrigação em sistema de missão crítica. É o único caminho de volta se o processo precisar ser abortado.
• Homologação primeiro. Qualquer atualização de dicionário e base roda primeiro em ambiente de homologação, com os processos mais importantes da operação validados.
• CHECKDUPL. Em base relacional (DBAccess), a verificação de registros duplicados roda para todas as empresas pelo Configurador, usando o dicionário completo da release de destino descompactado em uma pasta UPGRADE dentro de Protheus_Data e o arquivo SX2.UNQ como referência. Chave duplicada em SX2, SX3, SX5 ou SX6 trava a migração.
• Bloqueio de retrocesso. Se alguma empresa do ambiente já está em release posterior à que está sendo aplicada, a atualização não é permitida. Não existe “voltar de release” pela ferramenta; o caminho de volta é a cópia fria.

Há ainda o TOTVS Diagnóstico de Dicionários, uma ferramenta que verifica divergências do dicionário antes da atualização. Usá-la em homologação, antes do CHECKDUPL, poupa iterações.

Os arquivos certos na pasta certa

O UPDDISTR trabalha a partir da pasta SystemLoad. Antes de rodar, ela precisa receber, baixados do Portal do Cliente na categoria da release de destino:

• Dicionário de dados completo (SXSBRA.TXT para o Brasil). O upgrade usa só o diferencial, mas o completo precisa estar na pasta porque é ele que o sistema usa ao criar empresa ou filial nova.
• Dicionário de dados diferencial (SDFBRA.TXT). Desde a 12.1.2310 a TOTVS expede dois SDFs: um para quem está em release anterior à corrente e outro para quem já está na corrente. Baixar o errado é a causa mais boba de upgrade que “não encontra pacote”.
• Helps de campos e perguntas diferencial, arquivos .txt extraídos na SystemLoad.
• RPO da release de destino, que vai para a pasta APO (não para a SystemLoad): parar o serviço, renomear ou mover o repositório anterior, copiar o novo e renomear mantendo os sete últimos caracteres mais a extensão (TTTM120.RPO no multi-idioma, desde a 12.1.33). Depois do RPO, aplicar a Lib mais recente do Portal.

Dois cuidados de infraestrutura que a TOTVS destaca: em AppServer Linux, transferir o arquivo compactado e descompactar no próprio Linux (descompactar no Windows e copiar o .txt causa erro); e incluir a pasta raiz do Protheus nas exceções do antivírus, porque o UPDDISTR cria e apaga arquivos temporários e o antivírus pode travar a exclusão, com erro do tipo “Ctree Error, Create Index, DelTree 118”.

E a regra que mais economiza chamado: depois de trocar os arquivos, não abra o Protheus. Rode direto o UPDDISTR.

Limpeza das pastas

Antes do UPDDISTR, a documentação manda limpar o que pode interferir:

• SystemLoad: apagar tudo e manter só os dicionários (SXSBRA, SDFBRA) e os helps diferenciais. Os artigos da Central de Atendimento detalham: arquivos .DBF, .DTC e .IDX saem.
• System: apagar os .cdx se o dicionário ainda estiver em arquivo (com dicionário no banco de dados, ignorar), os arquivos TOTVSP*.* e os .LOG.
• AppServer: apagar Console.log, mpupddistri.old e os .tsk.

A exceção que importa: o arquivo MPUPDDISTRI.TSK só deve ser apagado no início do processo ou quando se volta o backup da base e dos dicionários. Se a migração já começou e parou para corrigir um erro crítico, ao retomar o arquivo não deve ser apagado, porque é ele que guarda o ponto em que o processo estava.

O passo a passo do UPDDISTR

1. Abra o client (TOTVS WebApp, ou SmartClient Desktop se ainda estiver na 12.1.2310) e, no Programa Inicial, digite UPDDISTR.
2. Selecione os grupos de empresas a atualizar. Tabelas sem grupo de empresas no nome, como os helps, são compartilhadas por todos os grupos do mesmo StartPath e são atualizadas de qualquer forma.
3. Leia o informativo de requisitos e confirme o termo de aceite, marcando as caixas. Confira a localização (país) selecionada.
4. Faça o login de autorização. Só o usuário Administrador do Protheus ou um usuário do Grupo Administradores com o acesso 194 habilitado (Lib 20210517 ou superior) pode executar. Usuário e senha são validados ao avançar.
5. Decida se é simulação. Nessa mesma tela existe a opção de rodar apenas uma simulação, em que nenhuma alteração é efetivada na base. É o passo que separa uma janela tranquila de uma madrugada ruim.
6. Confira o pacote. A tela seguinte mostra o pacote de atualização encontrado na SystemLoad. Se não é o esperado, pare aqui.
7. Configure a execução. Na tela “Configuração de execução do Update”, a TOTVS indica manter habilitadas só as opções Log de Atualização, Log de Critical Error e Corrigir erros automaticamente, lembrando que a última executa alterações de base pelo próprio sistema. Não marque “Manter o arquivo de log existente”.
8. Confirme grupos e operações. O sistema analisa a base existente contra o dicionário existente (nesse momento o diferencial ainda não é consultado). Se encontrar inconsistências, elas precisam ser corrigidas antes de prosseguir.
9. Aguarde a atualização. Se houver erros, uma janela mostra os logs; corrija na base e reinicie o processo. Ao final, a mensagem “O processo de atualização foi finalizado com sucesso” encerra.
10. Consulte o log e confira a release. O botão Consulta LOG permite ver e enviar o Log de Atualização. No Configurador, Shift+F6 mostra a Release do RPO, que precisa bater com o dicionário aplicado.

Um detalhe de versão: desde a Lib 20211004 (12.1.33), o UPDDISTR tem controle de aplicação de pacotes. Se a migração for interrompida, o Administrador e os usuários do Grupo Administradores veem, ao entrar em qualquer módulo, um aviso de que a base pode não estar íntegra; e, se o UPDDISTR for iniciado com um pacote diferente do inicial, ele avisa e pede para concluir com o pacote original ou abortar e voltar o backup. Vale só para pacotes com marca de migração de release.

Simulação e desempenho: duas chaves que mudam a janela

Modo simulação. A opção aparece na tela de login do UPDDISTR e roda toda a análise sem gravar nada. Em um ambiente com anos de customização, é a única forma barata de descobrir campo de usuário conflitando com campo padrão, índice duplicado ou tamanho divergente antes de parar a operação. O roteiro que a WeePulse aplica é rodar a simulação em uma cópia fria do ambiente, tratar a lista de inconsistências, repetir até zerar e só então marcar a janela de produção.

MAXTHREADUPD. Desde a Lib 20250113, a chave MAXTHREADUPD na seção [GENERAL] do appserver.ini define quantas threads o UPDDISTR abre para atualizar as tabelas, entre 15 e 50. Sem a chave, o padrão é 15. Em base grande, subir o valor encurta a janela; o limite prático é o que o banco de dados e o servidor aguentam sem degradar, e isso se mede na simulação.

[GENERAL]
MAXTHREADUPD=30

Os erros críticos mais comuns, e como corrigir

A página “Erros críticos mais comuns em migrações” do TDN, revisada em 26 de maio de 2026, lista as mensagens que param o UPDDISTR e a correção de cada uma. As que mais aparecem em ambientes em operação:

Mensagem	Onde está o problema	Correção indicada pela TOTVS
O campo da chave de índice não existe no SX3 da empresa	SIX aponta para campo que não existe	Abrir o SIX da empresa, localizar a chave e excluir o índice da tabela com erro
O gatilho está duplicado	SX7 com sequência repetida	Indexar o SX7 por X7_CAMPO, localizar e excluir o registro duplicado
A chave de índice está duplicada	SIX com a mesma chave em ordens diferentes	Conferir se a chave não existe em ordem inferior e excluir o índice duplicado
O arquivo está duplicado no SX2	Tabela cadastrada duas vezes	Indexar o SX2 por X2_CHAVE e excluir o duplicado
O tamanho (ou as casas decimais) do campo é diferente do dicionário	Estrutura física divergente do SX3	Se a tabela está vazia, excluir o arquivo; se tem conteúdo, comparar X3_TAMANHO ou X3_DECIMAL com a estrutura e corrigir um dos lados
O campo não existe no arquivo	SX3 tem o campo, a tabela não	Criar o campo na tabela do banco
A estrutura do arquivo não existe no SX3	SX2 tem a tabela, SX3 não tem os campos	Excluir a tabela do SX2 ou incluir os campos no SX3
O campo está duplicado no SX3	Campo cadastrado duas vezes	Indexar por X3_CAMPO e excluir o registro
O tamanho no SX3 é diferente do SXG (ou inferior ao limite)	Campo fora do tamanho do grupo de campos	Comparar X3_TAMANHO dos campos do mesmo X3_GRPSXG com o SIZE do grupo no SXG e corrigir no SX3 e na tabela
O campo de usuário existe na versão padrão e será substituído	Customização com o mesmo nome de campo padrão	Alterar X3_PROPRI para S no SX3

Duas regras de conduta da própria TOTVS: o APSDU restringe-se ao ajuste de erros críticos durante o UPDDISTR, não é para usar antes de concluir o processo, e, se precisar, com o RPO da release de origem; e inconsistências que exigem restaurar o ambiente ou algum artefato devem ir para o Suporte Framework, pelo Portal do Cliente ou pelo e-mail de upgrade do Protheus.

Depois do UPDDISTR

A conclusão com sucesso não encerra a atualização. O que vem em seguida:

• Aplicar os acumulados mais recentes da release de destino. O RPO do instalador tem as correções até a data de expedição; o que veio depois está nos pacotes de Expedição Contínua, de dicionário e de programa. A TOTVS esclarece que dicionários de módulo com data posterior à da release não geram conflito, porque o UPDDISTR sabe tratar campo novo, tamanho e índice em qualquer ordem. Com muitos módulos, o UPDBATCH enfileira os SDFs.
• Reaplicar e testar customizações. Campos de usuário, pontos de entrada e fontes customizados precisam ser revistos contra o dicionário novo. Na 12.1.2610 isso pesa mais, porque várias rotinas passaram a instalar procedures e descontinuaram trechos em AdvPL.
• Homologar o fiscal de ponta a ponta. NF-e com grupo de IBS e CBS, NFS-e, notas de débito e crédito, apuração. É o que a NT 2025.002 e as expedições seguintes cobram.
• Atualizar o TSS para a versão mínima da release, se a atualização mexeu nele. O guia do TSS cobre a ordem.
• Guardar o log do UPDDISTR com a cópia fria. É a evidência de auditoria da janela.

Para quem roda no Cloud TOTVS, a limpeza de pastas e parte dos passos dependem do time de Cloud, porque o cliente não acessa as pastas do AppServer. O procedimento da Central de Atendimento para esse ambiente é o mesmo, mas a execução passa por chamado.

Como a WeePulse conduz o UPDDISTR

Atualização de release é o serviço mais recorrente da sustentação de Protheus, e o UPDDISTR é o passo em que ela trava quando a base vem com anos de customização. O roteiro da WeePulse em ambientes em operação:

1. Inventário do ambiente: release atual, dicionário em arquivo ou no banco, versões de License Server, DBAccess, AppServer, Lib e TSS, customizações e integrações.
2. Diagnóstico de Dicionários e CHECKDUPL em cópia fria.
3. UPDDISTR em modo simulação, tratamento dos erros críticos, nova simulação até zerar.
4. Homologação funcional e fiscal na release de destino, com o time do cliente.
5. Janela de produção com cópia fria obrigatória, execução, conferência do Shift+F6 e aplicação dos acumulados.
6. Sustentação nas primeiras semanas, quando aparecem os efeitos das procedures e dos pontos de entrada.

A WeePulse atua em consultoria, suporte, parametrização e atualização de TOTVS já em operação. Falar com um especialista e planejar a próxima release com simulação antes da janela.

Perguntas frequentes sobre o UPDDISTR

O que é o UPDDISTR?

É o compatibilizador do TOTVS Protheus 12: a rotina que aplica um dicionário de dados diferencial ao ambiente, atualizando metadados, helps de campo e a estrutura das tabelas no banco. Usa o mesmo núcleo do atualizador de versão, mas aceita dicionário parcial.

Quando devo rodar o UPDDISTR?

Em todo upgrade de release do Protheus 12 e sempre que a TOTVS expedir um dicionário diferencial, por módulo novo, Expedição Contínua ou requisito legal. Não serve para migrar do Protheus 11 para o 12; nesse caso a ferramenta é o MP710TO120.

O UPDDISTR atualiza o RPO?

Não. Ele atualiza dicionário, helps e base de dados. A troca do RPO, a aplicação da Lib, de patches e de pacotes são passos separados, feitos antes do UPDDISTR no caso do RPO e da Lib.

Qual a diferença entre UPDDISTR e UPDBATCH?

O UPDBATCH usa o mesmo mecanismo e as mesmas regras, mas enfileira vários pacotes SDF de dicionário. Existe desde a 12.1.33 e serve para aplicar o acumulado de Expedições Contínuas de muitos módulos de uma vez.

Posso rodar o UPDDISTR sem backup?

A TOTVS recomenda fortemente a cópia fria e consistente do banco e das pastas, e a trata como obrigatória em sistema de missão crítica. O UPDDISTR não tem retrocesso: se o processo for abortado, o único caminho é restaurar o backup.

O que é o modo simulação do UPDDISTR?

Uma opção na tela de login da rotina que executa toda a análise sem efetivar nenhuma alteração na base. Serve para encontrar inconsistências de dicionário e de estrutura antes da janela de produção.

Quem pode executar o UPDDISTR?

O usuário Administrador do Protheus ou um usuário do Grupo Administradores com o acesso 194 habilitado, disponível a partir da Lib 20210517.

O que fazer se o UPDDISTR parar com erro crítico?

Ler o log, corrigir a inconsistência na base conforme a página de erros críticos do TDN, e reiniciar o UPDDISTR com o mesmo pacote, sem apagar o MPUPDDISTRI.TSK. Se o erro não estiver listado ou exigir restaurar artefatos, abrir chamado para o Suporte Framework.

Posso rodar o UPDDISTR no Cloud TOTVS?

O procedimento é o mesmo, mas a limpeza das pastas do AppServer e da SystemLoad depende do time de Cloud, porque o cliente não tem acesso a esses diretórios. A execução passa por chamado.

O que é a chave MAXTHREADUPD?

Uma chave da seção GENERAL do appserver.ini, disponível desde a Lib 20250113, que define quantas threads o UPDDISTR usa na atualização das tabelas, entre 15 e 50. O padrão, sem a chave, é 15.

Fontes oficiais

1. TDN: Upgrade de Release do Protheus 12, revisada em 18 de setembro de 2026 (pré-requisitos por release, arquivos, limpeza de pastas, procedimento do UPDDISTR, simulação, acesso 194, MAXTHREADUPD).
2. TDN: Atualizar o Dicionário de Dados do Protheus 12 (dicionário completo e diferencial; UPDDISTR só em upgrade de release).
3. TDN: Controle de aplicação de pacotes no UPDDISTR (Lib 20211004).
4. TDN: Erros críticos mais comuns em migrações, revisada em 26 de maio de 2026.
5. TDN: Atualizador de dicionário e base de dados - UPDDISTR (página centralizadora).
6. Central de Atendimento TOTVS: Como processar o UPDDISTR para atualização de dicionários.
7. Central de Atendimento TOTVS: Cloud Protheus, execução do UPDDISTR.
8. Central de Atendimento TOTVS: Nota sobre a data dos dicionários completos e diferenciais (Expedição Contínua e UPDBATCH).
9. Central de Atendimento TOTVS: Como atualizar o dicionário de dados (SXSBRA.TXT) do Protheus 12.