1. Visão Geral

1.1 O que é MRUpdate

MRUpdate é uma classe ADVPL que padroniza a criação e manutenção de itens do dicionário de dados do Protheus (tabelas, campos, parâmetros, gatilhos, consultas e índices) de forma declarativa e segura.

Em vez de escrever código de manutenção de dicionário do zero a cada projeto, o desenvolvedor instancia MRUpdate, declara o que precisa criar ou alterar por meio dos métodos Add* / Upd*, e chama Execute() para aplicar tudo de uma vez — com confirmação do usuário e barra de progresso.

O compatibilizador é idempotente: campos, índices e parâmetros já existentes são ignorados na criação; os métodos Upd* atualizam apenas a propriedade indicada.

1.2 Pré-requisitos

• Protheus com dicionário em banco relacional (SQL Server, Oracle, PostgreSQL etc.)
• Include protheus.ch no topo do arquivo. O include MRPROJETOS.CH é opcional — necessário apenas se o compatibilizador usar as constantes X3USADO, X3NUSA, X3OBRIG ou X3NOBRI diretamente no código
• Compilação via VSCode com a extensão TOTVS Developer Studio for VSCode, com acesso ao repositório de produção ou homologação
• Execução em modo exclusivo — nenhum outro usuário utilizando o sistema — ou acesso controlado pelo monitor do Protheus

1.3 Fluxo de uso

2. Como Usar

2.1 Exemplo mínimo

Criação de uma tabela com um campo e um índice:

#include "MRPROJETOS.CH"

User Function MEUPROJUPD()
Local oUpd := MRUpdate():New("Deseja aplicar o compatibilizador?")

  oUpd:AddSX2('SZA', 'Minha Tabela')
  oUpd:AddSX3('SZA','ZA_FILIAL ','C',2,0,'Filial','xFilial("SZA")',,,X3NUSA,X3NOBRI,'N','V','R')
  oUpd:AddSX3('SZA','ZA_CODIGO ','C',6,0,'Codigo')
  oUpd:AddSIX('SZA','ZA_FILIAL+ZA_CODIGO','Filial+Codigo')
  oUpd:Execute()

Return(.T.)

2.2 Exemplo completo

O arquivo updmodelo.prw (distribuído junto com mrupdate.prw) contém um exemplo completo de compatibilizador para a tabela SZG — Requisição de Materiais, demonstrando todos os recursos da classe. Abaixo uma versão comentada:

#include "MRPROJETOS.CH"

User Function UPD001()
Local oUpd := MRUpdate():New( ;
    "<b>Atencao</b>" + CRLF + CRLF + ;
    "Este compatibilizador deve ser aplicado em modo exclusivo." + CRLF + ;
    "Deseja efetuar o processamento?")

  // Tabela
  oUpd:AddSX2('SZG', 'Requisicao de Materiais')

  // Campos
  oUpd:AddSX3('SZG','ZG_FILIAL ','C',2,0,'Filial','xFilial("SZG")',,,X3NUSA,X3NOBRI,'N','V','R')
  oUpd:AddSX3('SZG','ZG_NUM    ','C',6,0,'Numero','U_MTA02INI()')
  oUpd:AddSX3('SZG','ZG_EMISSAO','D',8,0,'Emissao','Date()')
  oUpd:AddSX3('SZG','ZG_PRODUTO','C',15,0,'Produto', ;
              ,'SB1 ','ExistCpo("SB1")',,,, 'S','A','R','U','@!')
  oUpd:AddSX3('SZG','ZG_QTDREQ ','N',11,2,'Qt.Requisit.', ;
              ,,,,X3OBRIG,,'A',,'U','@E 99,999,999.99')

  // Índices (ORDEM calculada automaticamente)
  oUpd:AddSIX('SZG','ZG_FILIAL+ZG_NUM+ZG_PRODUTO','Numero+Produto')
  oUpd:AddSIX('SZG','ZG_FILIAL+ZG_CC','Centro Custo')

  // Parâmetros
  oUpd:AddSX6('DL_WFCRDBL','C','Emails bloqueio de credito','')

  // Alteração de propriedade de campo existente
  oUpd:UpdSX3('C5_DIRETO', 'X3_VISUAL', 'V')

  // Gatilho
  oUpd:AddSX7('ZG_PRODUTO','001','SB1->B1_DESC','ZG_DESC','P','S','SB1',1,"xFilial('SB1')+M->ZG_PRODUTO")

  oUpd:Execute()

Return(.T.)

3. Chamada nos Parâmetros Iniciais do Protheus

Compatibilizadores podem ser executados automaticamente na inicialização do Protheus WebApp, sem que o usuário precise localizar a função manualmente. A configuração é feita no campo Programa Inicial nos Parâmetros Iniciais do WebApp.

3.1 Configuração no WebApp — Programa Inicial

No Protheus WebApp, acesse os Parâmetros Iniciais (ícone de configurações na tela de login ou no menu do usuário) e informe o nome da função no campo Programa Inicial. O Protheus executará a função automaticamente após o login, antes de exibir o menu principal.

Informe o nome da User Function no campo Programa Inicial:

Programa Inicial:  U_UPD001

3.2 Boas práticas após a aplicação

1. Após o Execute() concluir, acesse novamente os Parâmetros Iniciais e limpe o campo Programa Inicial.
2. Faça logout e login novamente para confirmar que o sistema inicializa normalmente sem executar o compatibilizador.
3. Verifique no monitor do Protheus (SIGAADM → Miscelânea → Monitor) que não restaram sessões presas.
4. Confira os campos criados no dicionário via Configurações → Dicionário de Dados (CFGX027) para validar que os campos, índices e parâmetros foram criados corretamente.

4. Referência de Métodos

Todos os métodos Add* e Upd* retornam Self, permitindo encadeamento. Parâmetros opcionais não precisam ser informados — basta omiti-los ou passar NIL com o separador ;.

4.1 New — Construtor

Inicializa a classe e define a mensagem de confirmação exibida em Execute().

MRUpdate():New( [ cMsg ] )

Local oUpd := MRUpdate():New( ;
    "<b>Atencao</b>" + CRLF + CRLF + ;
    "Este compatibilizador prepara o modulo de Requisicoes." + CRLF + ;
    "Deseja prosseguir?")

4.2 Execute

Exibe a caixa de confirmação (MsgYesNo) e, se confirmado, processa todos os itens declarados via Add* / Upd* com barra de progresso (MsNewProcess).

oUpd:Execute()

4.3 AddSX2 — Criação de tabela

Registra uma nova tabela no dicionário SX2. Se a tabela já existir, a inclusão é ignorada.

oUpd:AddSX2( cChave, cNome [, cRotina, cModo, cModuUn, cModEmp,
             nDelet, cUnico, cPyme, nModulo, cDisplay,
             cNomeSpa, cNomeEng ] )

oUpd:AddSX2('SZG', 'Requisicao de Materiais')

// Com nome traduzido
oUpd:AddSX2('SZH', 'Itens de Requisicao', , , , , , , , , , ;
             'Articulos de Solicitud', 'Requisition Items')

4.4 AddSX3 — Criação de campo

Registra um novo campo no dicionário SX3. Se o campo já existir (verificado pelo nome do campo), a criação é ignorada — use UpdSX3 para atualizar propriedades. O X3_ORDEM é calculado automaticamente com base no último campo da tabela.

oUpd:AddSX3( cArquivo, cCampo, cTipo, nTamanho, nDecimal, cTitulo
           [, cRelacao, cF3, cValid, lUsado, lObrigat
           ,  cBrowse, cVisual, cContext, cPropri, cPicture
           ,  cVldUser, cCbox, cWhen, cInibrw, cGrpsxg, cFolder
           ,  cTitSpa, cTitEng, cDescric, cDescSpa, cDescEng
           ,  cPictvar, nNivel, cCheck, cTrigger
           ,  cCboxSpa, cCboxEng, cPyme
           ,  cCondsql, cChksql, cIdxsrv, cOrtogra, cIdxfld, cTela ] )

Parâmetros obrigatórios

Parâmetros opcionais — Comportamento e validação

// Campo filial padrão (oculto, virtual, não obrigatório)
oUpd:AddSX3('SZG','ZG_FILIAL ','C',2,0,'Filial','xFilial("SZG")',,,X3NUSA,X3NOBRI,'N','V','R')

// Campo numérico obrigatório com máscara
oUpd:AddSX3('SZG','ZG_QTDREQ ','N',11,2,'Qt.Requisit.', ;
            ,,,,X3OBRIG,,'A',,'U','@E 99,999,999.99')

// Campo com F3, validação e exibição no browse
oUpd:AddSX3('SZG','ZG_PRODUTO','C',15,0,'Produto', ;
            ,'SB1 ','ExistCpo("SB1")',,,, 'S','A','R','U','@!')

// Campo com combo box de opções
oUpd:AddSX3('SZG','ZG_FINALID','C',1,0,'Finalidade', ;
            ,,,,X3OBRIG,,,,,,, ;
            ,,,,,,,,,,,,,,,,,,,,, ;
            '1=Ajust.Eng.;2=Kanban;3=Projeto')

4.5 UpdSX3 — Alteração de campo existente

Altera uma propriedade específica de um campo já existente no SX3, sem recriar o campo inteiro.

oUpd:UpdSX3( cCampo, cPropriedade, uConteudo )

// Tornar campo existente somente visual
oUpd:UpdSX3('C5_DIRETO',   'X3_VISUAL',   'V')

// Adicionar validação de usuário
oUpd:UpdSX3('C5_CLIENTE',  'X3_VLDUSER',  'U_DLAvalCred()')

4.6 AddSX6 — Criação de parâmetro

Registra um novo parâmetro (MV_) no dicionário SX6. Se o parâmetro já existir, a criação é ignorada.

oUpd:AddSX6( cVar, cTipo, cDescric, uConteud
           [, cPropri, cPyme
           ,  cDesc1, cDscSpa1, cDscEng1
           ,  cDesc2, cDscSpa2, cDscEng2
           ,  cContSpa, cContEng, cDscSpa, cDscEng ] )

// Parâmetro de e-mail (caracter)
oUpd:AddSX6('DL_WFCRDBL','C','Emails para bloqueio de credito','')

// Parâmetro numérico com valor padrão
oUpd:AddSX6('MV_LIMREQ','N','Limite de quantidade por requisicao',100)

4.7 UpdSX6 — Alteração de parâmetro existente

Altera uma propriedade específica de um parâmetro já existente no SX6.

oUpd:UpdSX6( cParametro, cPropriedade, uConteudo )

// Redefinir conteúdo de parâmetros de risco
oUpd:UpdSX6('MV_RISCOB','X6_CONTEUD',0)
oUpd:UpdSX6('MV_RISCOC','X6_CONTEUD',0)

4.8 AddSX7 — Gatilhos

Registra um gatilho no dicionário SX7. Gatilhos propagam automaticamente valores de um campo de origem para campos de destino quando o valor do campo origem é alterado.

oUpd:AddSX7( cCampo, cSequenc, cRegra, cCdomin, cTipo, cSeek,
            cAlias, nOrdem, cChave [, cCondic, cPropri ] )

// Quando ZG_PRODUTO muda, busca B1_DESC em SB1 e grava em ZG_DESC
oUpd:AddSX7( ;
  'ZG_PRODUTO',              // campo que dispara
  '001',                     // sequência
  'SB1->B1_DESC',           // valor calculado (regra)
  'ZG_DESC',                 // campo destino
  'P','S',                   // tipo e seek
  'SB1',1,                  // alias e índice
  "xFilial('SB1')+M->ZG_PRODUTO" // chave
)

4.9 AddSXB — Consultas padrão

Registra itens de uma consulta padrão (F3) no dicionário SXB. Uma consulta completa é formada por pelo menos um registro de cabeçalho (tipo 1), itens (tipo 2) e um campo de retorno (tipo 3).

oUpd:AddSXB( cAlias, cTipo, cSeq, cColuna, cDescri, cContem
            [, cWcontem, cDescSpa, cDescEng ] )

// Cabeçalho da consulta (tipo 1)
oUpd:AddSXB('SZG','1','01','ZG_NUM','Numero','ZG_NUM')

// Coluna 2 (tipo 2)
oUpd:AddSXB('SZG','2','01','ZG_NUM','Numero','ZG_NUM')
oUpd:AddSXB('SZG','2','02','ZG_DESC','Descricao','ZG_DESC')

// Retorno (tipo 3)
oUpd:AddSXB('SZG','3','01','ZG_NUM','Numero','SZG->ZG_NUM')

4.10 AddSIX — Índices

Registra um índice no dicionário SIX. A ORDEM é calculada automaticamente: a classe busca o maior valor de ORDEM existente para a tabela e aplica Soma1() — não é necessário informar a ordem manualmente.

oUpd:AddSIX( cIndice, cChave, cDescricao
            [, cPropri, cDescSpa, cDescEng, cF3, cNickname, cShowPesq ] )

// Dois índices para SZG — a ORDEM (1, 2...) é atribuída automaticamente
oUpd:AddSIX('SZG', 'ZG_FILIAL+ZG_NUM+ZG_PRODUTO', 'Numero+Produto')
oUpd:AddSIX('SZG', 'ZG_FILIAL+ZG_CC',             'Centro Custo')

4.11 AddSX1 — Perguntas (SX1)

Registra perguntas do grupo de perguntas (SX1) — usadas nas telas de parâmetros de relatórios e processos batch. Cada pergunta pertence a um grupo e recebe uma ordem.

oUpd:AddSX1( cGrupo, cOrdem, cPergunt, cVariavl, cTipo, nTamanho, nDecimal
            [, cPresel, cGSC, cValid, cF3, cPyme, cGrpsxg, cHelp, cPicture, cIdfil
            ,  cPerspa, cPereng
            ,  cVar01, cDef01, cDefspa1, cDefeng1, cCnt01   <!-- resposta 1 -->
            ,  cVar02, cDef02, cDefspa2, cDefeng2, cCnt02   <!-- resposta 2 -->
            ,  cVar03, cDef03, cDefspa3, cDefeng3, cCnt03   <!-- resposta 3 -->
            ,  cVar04, cDef04, cDefspa4, cDefeng4, cCnt04   <!-- resposta 4 -->
            ,  cVar05, cDef05, cDefspa5, cDefeng5, cCnt05 ] ) <!-- resposta 5 -->

// Pergunta de data inicial para relatório
oUpd:AddSX1('RELMREQ','01','Data Inicial ?','MV_PAR01','D',8,0)
oUpd:AddSX1('RELMREQ','02','Data Final ?',  'MV_PAR02','D',8,0)

// Pergunta com opções de seleção
oUpd:AddSX1('RELMREQ','03','Situacao ?','MV_PAR03','N',1,0, ;
            ,,,,,,,,,, ;
            'MV_PAR03','1','Todos','All','1', ;
            'MV_PAR03','2','Pendentes','Pending','2')

4.12 AddSQL e AddFun — Blocos de execução

Permitem incluir blocos de código ADVPL a serem executados dentro do processo de atualização, para operações que a classe não cobre diretamente (migrações de dados, ajustes específicos etc.).

oUpd:AddSQL( bBloco )   // executa bloco com TCQuery / BeginSql...EndSql
oUpd:AddFun( bBloco )   // executa bloco ADVPL genérico

oUpd:AddFun({||
  Local cQuery := "UPDATE " + RetSQLName("SZG") + ;
                  " SET ZG_STATUS = '1' WHERE ZG_STATUS = '' "
  TCExec(cQuery)
})

5. Dados Técnicos

5.1 Constantes de máscara de campo

As constantes abaixo controlam a visibilidade (X3_USADO) e obrigatoriedade (X3_OBRIGAT) dos campos por módulo do Protheus. Elas são definidas diretamente no topo de mrupdate.prw via #define e também estão disponíveis em MRPROJETOS.CH se este for incluído. Cada posição do string corresponde a um módulo; x=ativo, espaço=inativo.

5.2 Dicionários gerenciados

5.3 Auto-cálculo de X3_ORDEM e ORDEM de índice

Versões anteriores de compatibilizadores exigiam que o desenvolvedor informasse manualmente o valor de X3_ORDEM (SX3) e ORDEM (SIX). A partir da versão 2.0 da classe, esses valores são calculados automaticamente:

• SX3 (X3_ORDEM): antes de criar um campo novo, a engine faz seek no índice 1 do SX3 (X3_ARQUIVO + X3_ORDEM) para localizar o maior valor de ordem da tabela e aplica Soma1(cUltOrdem) para obter o próximo.
• SIX (ORDEM): antes de criar um índice novo, a engine varre o SIX pelo alias da tabela e aplica Soma1(cUltOrdem) ao maior valor encontrado.

5.4 Engine interna

O método Execute() delega o processamento a _UpdProc(), que executa os dicionários na seguinte sequência interna:

1. _UpdAtuSX2() — Tabelas
2. _UpdAtuSX3() — Campos
3. _UpdAtuSIX() — Índices
4. _UpdAtuSX7() — Gatilhos
5. _UpdAtuSX6() — Parâmetros
6. _UpdAtuSX1() — Perguntas
7. _UpdAtuSXB() — Consultas
8. Blocos AddSQL e AddFun

Todos os métodos privados usam RecLock / MsUnLock para controle de concorrência e DbCommit() após cada gravação. A abertura exclusiva da tabela de empresas (SM0) utiliza a API TOTVS OpenSM0Excl() — compatível com ambiente SQL moderno.