Macros

Macros SQL Sankhya (MacroTranslator) — Addon Studio 2.0

Macros SQL traduzidas automaticamente entre Oracle e MSSQL pelo framework Sankhya. Permite escrever queries portáveis sem duplicar sintaxe por banco.

> Onde aparecem: > - ` em metadata XML (datadictionary/) — quando contem SQL > - selectQuery em (lookup customizado) > - @Criteria(clause = "...") em @Repository > - @NativeQuery("...") em @Repository > - Queries externas em model/src/main/resources/queries/.sql ou queries/.xml > > **Nao confundir com BeanShell**: variaveis $col, $ctxusuariologado, $ctxdh_atual sao contexto **BeanShell** em — nao sao macros SQL. Ver data-dictionary` §1.8.

---

1. Por que usar macros

• Sintaxe unificada Oracle/MSSQL — escrita uma vez, traduzida automaticamente
• Centraliza diferencas de banco em um unico ponto
• Reduz risco de query funcionar em um banco e quebrar no outro
• Manutencao em um lugar so (sem ramificacoes por banco)

---

2. Referencia por categoria

2.1 Data e hora

| Macro | Proposito | Exemplo | |:-------------------------------|:---------------------------------------------------|:---------------------------------| | dbDate() | Data/hora atual do banco (SYSDATE/GETDATE()) | WHERE DTMOV = dbDate() | | onlydate() | Apenas a data (sem hora) | onlydate(DATA_VENDA) | | truncDate() | Apenas a data (similar a onlydate) | truncDate(DATA) | | truncWeek() | Inicio da semana | truncWeek(DATA) | | truncMonth() | Inicio do mes | truncMonth(DATA) | | truncQarter() | Inicio do trimestre (nome com typo no SDK: Qarter)| truncQarter(DATA) | | truncYear() | Inicio do ano | truncYear(DATA) | | getDay() | Dia (1-31) | getDay(DATA) | | getMonth() | Mes (1-12) | getMonth(DATA) | | getYear() | Ano (YYYY) | getYear(DATA) | | monYear() | Mes/ano formato MM/YYYY | monYear(DATA) | | yearMonth() | Ano+mes formato YYYYMM (numerico) | yearMonth(DATA) | | addMonths(, ) | Soma N meses a data | addMonths(DATA, 3) | | endOfCurrentMonth() | Ultimo dia do mes atual | endOfCurrentMonth() | | diffdays(, ) | Diferenca em dias (dt1 - dt2) | diffdays(DTFIM, DTINI) | | diffhour(, ) | Diferenca em horas (dt1 - dt2) | diffhour(DTFIM, DTINI) | | convertPtBrDate() | Data como string DD/MM/YYYY | convertPtBrDate(DATA) |

2.2 Texto

| Macro | Proposito | Exemplo | |:-------------------------------------|:------------------------------------------------|:------------------------------------------| | ignorecase() | Compara sem case e sem acentos | ignorecase(NOME) = ignorecase('Jose') | | normalizeText() | Remove acentos + UPPER (busca tolerante) | normalizeText(NOME) LIKE '%SILVA%' | | upperText() | Converte para maiusculas | upperText(NOME) | | trim() | Remove espacos nas pontas | trim(NOME) | | length() | Tamanho da string | length(NOME) | | subString(, , ) | Recorte de string | subString(NOME, 1, 5) | | stringIndex(, ) | Posicao de substring (1-based) | stringIndex(NOME, 'A') | | leftPad(, , ) | Preenche a esquerda ate atingir tamanho | leftPad(CODIGO, '0', 8) | | concatstr(, ) | Concatena duas strings (|| Oracle / + MSSQL)| concatstr(NOME, SOBRENOME) | | quebraLinha() | Quebra de linha (CRLF) | concatstr(NOME, quebraLinha()) |

2.3 Conversao de tipos

| Macro | Proposito | Exemplo | |:---------------------------------|:---------------------------------------|:------------------------------| | convertToNumber() | Converte para NUMERIC/NUMBER | convertToNumber(PRECO) | | convertToFloat() | Converte para FLOAT | convertToFloat(VALOR) | | convertToVarchar() | Converte para VARCHAR | convertToVarchar(CODIGO) | | convertToTimestamp() | Converte para TIMESTAMP/DATETIME | convertToTimestamp(STR_DATA)| | convertToMilliseconds() | Extrai milissegundos | convertToMilliseconds(DATA) |

2.4 Outros

| Macro | Proposito | Exemplo | |:-----------------------------------|:-----------------------------------------------------|:-------------------------------------| | nullValue(, ) | NVL/ISNULL: substitui null por padrao | nullValue(SALARIO, 0) | | maxLines() | Limita linhas (ROWNUM Oracle / TOP MSSQL) | SELECT maxLines(10) * FROM TGFCAB | | ${user.name} | Owner/usuario do banco (prefixo de tabela) | SELECT * FROM ${user.name}TABELA | | sqldatabase. | Qualifica tabela com nome do banco/schema | SELECT * FROM sqldatabase.CLIENTES |

---

3. Uso em `` SQL (datadictionary)

Algumas `` em metadata podem conter SQL (nao BeanShell). Macros SQL valem aqui:

    Data Referencia
    

    Vlr Total (Tratado)
    

> Para ` **BeanShell** (mais comum em campos com $col/$ctx), use as variaveis de contexto BeanShell — **nao** macros SQL. Ver data-dictionary` §1.8.

---

4. Uso em @Criteria / @NativeQuery

// Busca tolerante a acento e case
@Criteria(clause = "ignorecase(this.NOMEPARC) = ignorecase(:nome)")
List findByNome(String nome);

// Filtro por data atual do servidor
@Criteria(clause = "this.DTMOV = dbDate()")
List findHoje();

// Agrupamento por competencia (ano+mes)
@NativeQuery("SELECT yearMonth(DTNEG) AS COMP, SUM(VLRNOTA) AS TOTAL " +
             "FROM TGFCAB GROUP BY yearMonth(DTNEG)")
List agruparPorCompetencia();

// Tratamento de null
@NativeQuery("SELECT nullValue(VLRDESCONTO, 0) FROM TGFCAB WHERE NUNOTA = :nu")
BigDecimal descontoOrZero(BigDecimal nu);

// Limite de linhas portatil
@NativeQuery("SELECT maxLines(10) NUNOTA, VLRNOTA FROM TGFCAB ORDER BY DTNEG DESC")
List ultimas10();

---

5. Uso em queries externas (queries/*.sql)

Macros tambem funcionam em arquivos externos referenciados via fromFile = true:

-- queries/ranking-vendedores.sql
SELECT VEND.CODVEND, VEND.NOMEVEND,
       SUM(nullValue(CAB.VLRNOTA, 0)) AS TOTAL,
       getYear(CAB.DTNEG) AS ANO
FROM TGFCAB CAB
INNER JOIN TGFVEN VEND ON VEND.CODVEND = CAB.CODVEND
WHERE truncMonth(CAB.DTNEG) = truncMonth(dbDate())
  AND ignorecase(VEND.NOMEVEND) LIKE ignorecase(:nome)
GROUP BY VEND.CODVEND, VEND.NOMEVEND, getYear(CAB.DTNEG)

---

6. Anti-Patterns (PROIBIDO)

| Anti-Pattern | Correcao | |:----------------------------------------------------------|:----------------------------------------------------| | Usar SYSDATE/GETDATE() direto | dbDate() | | Usar NVL/ISNULL direto | nullValue(, ) | | Usar ROWNUM/TOP direto | maxLines() | | Concatenacao com || ou + | concatstr(, ) | | UPPER(...) sem tratar acentos em busca textual | normalizeText() ou ignorecase() | | INSTR/CHARINDEX direto | stringIndex(, ) | | TO_NUMBER/CONVERT(NUMERIC, ...) direto | convertToNumber() | | TO_CHAR(...)/CONVERT(VARCHAR, ...) direto | convertToVarchar() ou convertPtBrDate(...)| | LPAD/RIGHT(REPLICATE(...)) direto | leftPad(, , ) | | SUBSTR/SUBSTRING direto | subString(, , ) | | ADD_MONTHS/DATEADD(MONTH, ...) direto | addMonths(, ) | | LAST_DAY(SYSDATE)/EOMONTH(GETDATE()) | endOfCurrentMonth() |

---

7. Quando NAO usar macro

• Operacao muito especifica de um banco sem equivalente no outro (ex.: window function avancada Oracle-only). Nesses casos, separar em queries/.xml com tags ` e . Ver repository` §4.
• **Logica em ` BeanShell** (nao SQL). Use variaveis de contexto BeanShell ($col, $ctx`).
• DDL em dbscripts/ — scripts de banco ja sao split via tags `/`. Macros nao se aplicam ali.

Skills relacionadas

• data-dictionary — macros usadas em campo `` quando contém SQL (não BeanShell)
• repository — macros usadas em @NativeQuery e queries/.xml
• database — dbscripts não usam macros (ver seção 7); portabilidade ali é via split `/`

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snk-devcenter
• Source: snk-devcenter/addon-studio
• License: MIT

Install and usage instructions live in the source repository linked above.