Entrei na InterSystems há menos de um ano. Mergulhar em ObjectScript e no IRIS foi empolgante, mas também cheio de pequenas surpresas que me pegaram de surpresa no começo. Neste artigo, reúno os erros mais comuns que eu, e muitos colegas novos, cometemos, explico por que eles acontecem e mostro exemplos concretos e correções práticas. Meu objetivo é ajudar outros desenvolvedores iniciantes a economizarem tempo e evitarem os mesmos tropeços no caminho.

1. Se perder entre as classes de sistema e por onde começar

O problema: ObjectScript/IRIS vem com muitas classes e pacotes de sistema (%Library, %SYS, %Persistent, %SQL, etc.). Para um desenvolvedor iniciante, é difícil saber qual classe ou padrão se encaixa melhor em uma tarefa. Lembro de tentar encontrar uma classe persistente adequada e ficar em dúvida entre estender %Persistent ou usar uma classe do tipo registry.

Por que isso importa: Escolher a abordagem errada logo no início torna o código mais difícil de manter e se integra mal com os recursos do IRIS (índices, segurança, SQL).

Dica: Comece pela necessidade concreta (armazenar registros? expor via SQL? compartilhar objetos entre processos?) e então pesquise na Class Reference as capacidades relevantes (persistência, índices, coleções). Use o Studio ou a extensão da InterSystems para VS Code para navegar pelas classes de forma interativa e analisar exemplos.

2. Sobrecarga da documentação: não saber as palavras-chave certas

O problema: A documentação é bastante completa, mas, se você não conhece o nome correto da classe ou o termo adequado, as buscas retornam muitas páginas não relacionadas. No início, eu frequentemente gastava muito tempo porque ainda não conhecia os termos canônicos.

Por que isso importa: Você perde tempo e pode acabar implementando padrões que não são ideais.

Dica:

• Pesquise na comunidade de desenvolvimento por exemplos práticos (busque por “persistent class example”, “ObjectScript transaction TSTART example”, etc.).
• Use a extensão InterSystems para VS Code; ela permite navegar diretamente até as definições das classes.
• Ao pesquisar na documentação, combine nomes de classes e ações, por exemplo: "%Persistent property index example"

3.  Esquecer  .. na chamada de métodos locais

O problema: Chamar um método da mesma classe sem .. resulta em a chamada não ser reconhecida  em tempo de execução.

Errado:

Class MyClass Extends %Persistent { 
   Method DoWork() 
   { 
       Do Hello()  // wrong: this is not a local method invocation
   } 
   Method Hello()
   { 
       Write "Hello", ! 
   } 
}

Correto:

Method DoWork() {
   Do ..Hello()  // correct: local method call 
}

Dica:  Quando você receber o erro “Unknown routine” para os métodos da sua classe, verifique se você está usando .. para chamadas dentro da mesma classe.

4. Confundir globais e variáveis locais

O problema: ObjectScript diferencia globais (persistentes entre sessões, por exemplo ^MyGlobal) e variáveis locais (em memória, com escopo limitado). Desenvolvedores iniciantes frequentemente usam uma quando a intenção era usar a outra.

SET localVar = 10    // exists only during the current process/session
SET ^globalVar = 20  // persists in the database across processes and sessions

Dica: Use classes persistentes para dados que precisam ser armazenados a longo prazo. Limite o uso de globais a necessidades muito específicas de baixo nível ou apenas quando você entender bem as consequências.

5. Utilizar globais diretamente em vez de usar classes persistentes

O problema: Meu instinto inicial foi o “rápido e sujo”: escrever diretamente em ^MyGlobal. Isso funciona, mas ignora os benefícios baseados em classes: esquema, índices, acesso via SQL e segurança.

Melhor abordagem:

Class Person Extends %Persistent 
{ 
    Property Name As %String; 
    Property DOB As %Date; 
}

Dica: Prefira classes %Persistent para os dados da aplicação. Elas oferecem um modelo mais limpo e se integram com SQL e índices.

6. Ignorar transações (TSTART / TCOMMIT)

O problema: Desenvolvedores às vezes realizam várias gravações pensando que são atômicas. Sem o controle explícito de transações, falhas parciais podem deixar os dados inconsistentes.

TSTART 
// multiple updates 
TCOMMIT

Dica: Identifique unidades lógicas de trabalho e envolva-as em transações. Se algo puder falhar no meio do processo, use TSTART / TROLLBACK / TCOMMIT. Lembre-se de que o IRIS suporta transações aninhadas: múltiplas chamadas a TSTART aumentam o nível da transação, e todos os níveis devem ser confirmados (TCOMMIT) ou revertidos (TROLLBACK) antes que as alterações se tornem definitivas.

7. Entender mal as opções de SQL: SQL Embutido vs %SQL.Statement

O problema: SQL embutido (blocos UPDATE, SELECT dentro do ObjectScript) e a API %SQL.Statement estão disponíveis; escolher sem conhecer os prós e contras pode gerar código confuso.

Orientação: Use SQL embutido para consultas fixas/estáticas dentro de rotinas; use %SQL.Statement quando precisar construir e executar SQL de forma dinâmica.

8. Ignorar o tratamento adequado de erros

O problema: Não usar TRY/CATCH ou sinalizar erros corretamente torna a depuração e a confiabilidade do código mais difíceis.

TRY 
{ 
   // code that may fail 
} CATCH ex 
{  
   Write "Error: ", ex.DisplayString(),! 
}

Dica: Envolva operações de risco (I/O, chamadas externas, SQL dinâmico) com manipuladores de erro e registre mensagens informativas.

Notas finais
No início, eu escrevia em globais por conveniência e depois passei um tempo refatorando para classes persistentes. Essa refatoração me ensinou o valor de projetar os modelos de dados desde o início e usar as ferramentas que o IRIS oferece. Meus melhores hábitos agora: pequenos experimentos, buscas frequentes na comunidade e manter transações e tratamento de erros em mente desde o começo.

Se você é iniciante: trate suas primeiras tarefas como experimentos, crie pequenas classes persistentes, teste SQL Embutido simples e use o Management Portal e o navegador do VS Code para inspecionar as classes de sistema. Faça perguntas na comunidade; muitos outros também passaram pelas mesmas “pegadinhas”.

Para mais informações: consulte a documentação oficial do ObjectScript e a comunidade de desenvolvimento para exemplos e padrões.

Este artigo foi revisado e editado com o auxílio de ferramentas de IA para melhorar a clareza e a gramática. As experiências e sugestões descritas são de minha autoria.