Simplifique e Automatize o Trabalho com Macros do Oracle GoldenGate

Você pode usar macros do Oracle GoldenGate em arquivos de parâmetros para configurar e reutilizar parâmetros, comandos e funções de conversão. Reduzindo a quantidade de texto que você deve informar para executar tarefas comuns. Uma macro é uma ferramenta de automação integrada que permite chamar um conjunto armazenado de etapas de processamento dentro do arquivo de parâmetros do Oracle GoldenGate. Uma macro pode consistir em um conjunto simples de instruções de parâmetro usadas com frequência para uma série complexa de substituições, cálculos ou conversões de parâmetros. Você pode chamar outras macros de uma macro. Você pode armazenar macros comumente usadas em uma biblioteca e, em seguida, chamar a biblioteca em vez de chamar as macros individualmente.

As macros do Oracle GoldenGate funcionam com os seguintes arquivos de parâmetros:

Há duas etapas para usar macros:

  1. Definindo uma Macro

  2. Chamando uma macro

Definir uma macro

Para definir uma macro do Oracle GoldenGate, use o parâmetro MACRO no arquivo de parâmetros. MACRO define todos os parâmetros de entrada necessários e define o trabalho que a macro executa.

Sintaxe

<pre class="copy"><code>MACRO #*macro_name* PARAMS (#*p1*, #*p2* [, ...]) BEGIN *macro_body* END;</code></pre>

Tabela 18 Argumentos de definição de macro

Argumento Descrição 
MACRO
 Obrigatório. Indica o início de uma definição de macro do Oracle GoldenGate. 
#macro_name

O nome da macros. Os nomes de macro e parâmetro devem começar com um caractere de macro. O caractere de macro padrão é o caractere de libra (#), como em #macro1 e #param1.

Um nome de macro ou parâmetro pode ser uma palavra que consiste em letras e números, ou ambos. Caracteres especiais, como o caractere de sublinhado (_) ou o hífen (-), podem ser usados. Alguns exemplos de nomes de macros são: #mymacro, #macro1, #macro_1, #macro-1, #macro$. Alguns exemplos de nomes de parâmetros são #sourcecol, #s, #col1 e #col_1.

Para evitar erros de análise, o caractere de macro não pode ser usado como o primeiro caractere de um nome de macro. Por exemplo, ##macro é inválido. Se necessário, você pode alterar o caractere de macro usando o parâmetro MACROCHAR na Referência de Parâmetros e Funções do Oracle GoldenGate.

Os nomes de macro e parâmetro não fazem distinção entre maiúsculas e minúsculas. Os nomes de macro ou parâmetro entre aspas são ignorados.

 
PARAMS (#p1, #p2)
 Definição opcional de parâmetros de entrada. Especifique uma lista de nomes de parâmetros separados por vírgulas e coloque-a entre parênteses. Cada parâmetro deve ser referenciado no corpo da macro onde você deseja que os valores de entrada sejam substituídos. Você pode listar cada parâmetro em uma linha separada para melhorar a legibilidade (certificando-se de usar os parênteses de abertura e fechamento para delimitar a lista de parâmetros). Consulte Chamar uma Macro que Contém Parâmetros para obter mais informações. 
BEGIN
 Inicia o corpo da macro. Deve ser especificado antes do corpo da macros. 
macro_body

O corpo macro. O corpo é uma instrução de sintaxe que define a função que deve ser executada pela macro. Um corpo de macro pode incluir qualquer um dos seguintes tipos de instruções.

  • Instruções de parâmetro simples, como em:

    COL1 = COL2

  • Instruções de parâmetro complexas com substituição de parâmetro como em:

    MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS);

  • Chamadas de outras macros, como em:

    #colmap (COL1, #sourcecol)
 
END;
 Finaliza a definição da macro. O ponto-e-vírgula é necessário para completar a definição.

Veja a seguir um exemplo de uma definição de macro que inclui parâmetros. Nesse caso, a macro simplifica a tarefa de mapeamento de objetos e colunas fornecendo a sintaxe base da instrução MAP com parâmetros de entrada que resolvem os nomes dos proprietários, as tabelas e as colunas KEYCOLS.

<pre class="copy"><code>MACRO #macro1 PARAMS ( #o, #t, #k ) BEGIN MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); END;</code></pre>

A seguir, um exemplo de macro que não define parâmetros. Ele executa um conjunto de parâmetros usado com frequência.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Chamar uma macro

Para chamar uma macro, use a sintaxe a seguir na qual você deseja que a macro seja executada no arquivo de parâmetros.

Sintaxe

[*target* =] *macro_name* (*val*[, ...])
[*target* =] *macro_name* (*val* | {*val*, *val*, ...}[, ...])

Tabela 19 Elementos de sintaxe para chamar uma macro

Argumento Descrição
destino =

Opcional. Especifica o destino para o qual os resultados da macro são atribuídos ou mapeados. Por exemplo, o target pode ser usado para especificar uma coluna de destino em uma instrução COLMAP. Na chamada a seguir para a macro #make_date, a coluna DATECOL1 é o destino e será mapeada para os resultados da macro. 

DATECOL1 = #make_date (YR1, MO1, DAY1)

Sem um destino, a sintaxe para chamar #make_date é: 

#make_date (YR1, MO1, DAY1)
macro_name O nome da macro que está sendo chamada, por exemplo: #make_date.
( val[, ...]) Os valores de entrada do parâmetro. Este componente é obrigatório se a macro define ou não parâmetros. Se a macro definir parâmetros, especifique uma lista de valores de entrada separados por vírgulas, na ordem que corresponde às definições de parâmetro no parâmetro MACRO e coloque a lista entre parênteses. Se a macro não definir parâmetros, especifique os parênteses de abertura e fechamento sem nada entre eles ().
( val \| {val, val, ...} )[, ...] Os valores de entrada do parâmetro. Este componente é obrigatório se a macro define ou não parâmetros. Se a macro definir parâmetros, especifique uma lista de valores de entrada separados por vírgulas, na ordem que corresponde às definições de parâmetro no parâmetro MACRO e coloque a lista entre parênteses. Para passar vários valores para um parâmetro, separe-os com vírgulas e coloque a lista entre chaves. Se a macro não definir parâmetros, especifique os parênteses de abertura e fechamento sem nada entre eles ().

Consulte os seguintes tópicos para saber mais sobre sintaxe para chamar uma macro:

Chamar uma macro que contém parâmetros

Para chamar uma macro que contém parâmetros, a instrução de chamada deve fornecer os valores de entrada que devem ser substituídos por esses parâmetros quando a macro for executada.

A entrada válida para um parâmetro de macro é qualquer uma das seguintes, precedida pelo caractere de macro (o padrão é #):

O Oracle GoldenGate substitui valores de parâmetro dentro do corpo da macro de acordo com as regras a seguir.

  1. O processador de macro lê o corpo da macro procurando instâncias de nomes de parâmetros especificados na instrução PARAMS.

  2. Para cada ocorrência do nome do parâmetro, o valor do parâmetro correspondente especificado durante a chamada é substituído.

  3. Se um nome de parâmetro não aparecer na instrução PARAMS, o processador de macro avaliará se o item é ou não, em vez disso, uma chamada para outra macro. (Consulte Chamando outras macros de uma macro.) Se a chamada for bem-sucedida, a macro aninhada será executada. Se falhar, toda a macro falha.

Exemplo 9-39 Usando Parâmetros para Preencher uma Instrução MAP

A definição de macro a seguir especifica três parâmetros que devem ser resolvidos. Os parâmetros substituem os nomes do proprietário da tabela (parâmetro #o), da tabela (parâmetro #t) e das colunas KEYCOLS (parâmetro #k) em uma instrução MAP.

MACRO #macro1  PARAMS ( #o, #t, #k )  BEGIN  MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); END;

Supondo que uma tabela na instrução MAP exija apenas uma coluna KEYCOLS, a sintaxe a seguir pode ser usada para chamar #macro1. Nesta sintaxe, o parâmetro #k pode ser resolvido com apenas um valor.

#macro1 (SCOTT, DEPT, DEPTNO1)

Para chamar a macro de uma tabela que requer duas colunas KEYCOLS, as chaves são usadas da seguinte forma para incluir os dois valores necessários para os nomes das colunas:

#macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2})

Os valores DEPTNO1 e DEPTNO2 são passados como um argumento para resolver o parâmetro #t. Tabelas com três ou mais KEYCOLS também podem ser tratadas dessa maneira, usando valores adicionais dentro das chaves.

Exemplo 9-40 Usando uma Macro para Executar a Conversão

Neste exemplo, uma macro define os parâmetros #year, #month e #day para converter um formato de data proprietário.

MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

A macro é chamada na cláusula COLMAP:

MAP sales.acct_tab, TARGET sales.account,
COLMAP
(
targcol1 = sourcecol1,
datecol1 = #make_date(YR1, MO1, DAY1),
datecol2 = #make_date(YR2, MO2, DAY2)
);

A macro se expande da seguinte forma:

MAP sales.acct_tab, TARGET sales.account,
COLMAP
(
targcol1 = sourcecol1,
datecol1 = @DATE ('YYYY-MM-DD', 'CC', @IF (YR1 < 50, 20, 19),'YY', YR1, 'MM', MO1, 'DD', DAY1),
datecol2 = @DATE ('YYYY-MM-DD', 'CC', @IF (YR2 < 50, 20, 19),'YY', YR2, 'MM', MO2, 'DD', DAY2)
);

Chamar uma macro sem parâmetros de entrada

Para chamar uma macro sem parâmetros de entrada, a instrução de chamada deve fornecer os parênteses de abertura e fechamento, mas sem valores de entrada: #macro ().

A macro a seguir é definida sem parâmetros de entrada. O corpo contém parâmetros usados com frequência.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Esta macro é chamada da seguinte forma:

#option_defaults ()
IGNOREUPDATES
MAP owner.srctab, TARGET owner.targtab;

#option_defaults ()
MAP owner.srctab2, TARGET owner.targtab2;

A macro se expande da seguinte forma:

GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
IGNOREUPDATES
MAP owner.srctab, TARGET owner.targtab;

GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
MAP owner.srctab2, TARGET owner.targtab2;

Chamando outras macros de uma macro

Para chamar outras macros de uma macro, crie uma definição de macro semelhante à seguinte. Neste exemplo, a macro #make_date é aninhada na macro #assign_date e é chamada quando a #assign_date é executada.

A macro aninhada deve definir todos, ou um subconjunto de, os mesmos parâmetros definidos na macro base. Em outras palavras, os valores de entrada quando a macro base é chamada devem ser resolvidos para os parâmetros em ambas as macros.

O seguinte define #assign_date:

MACRO #assign_date
PARAMS (#target_col, #year, #month, #day)
BEGIN
#target_col = #make_date (#year, #month, #day)
END;

O seguinte define #make_date. Essa macro cria um formato de data que inclui um ano com quatro dígitos, depois de primeiro determinar se a data de entrada com dois dígitos deve ser prefixada com um valor de século 19 ou 20. Observe que a instrução PARAMS de #make_date contém um subconjunto dos parâmetros na macro #assign_date.

MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

A seguinte sintaxe chama #assign_date:

#assign_date (COL1, YEAR, MONTH, DAY)

A macro se expande para o seguinte, dados os valores de entrada anteriores e a macro #make_date incorporada:

COL1 = @DATE ('YYYY-MM-DD', 'CC', @IF (YEAR < 50, 20, 19),'YY', YEAR, 'MM', MONTH, 'DD', DAY)

Criar Bibliotecas de Macro

Você pode criar uma biblioteca de macros que contenha uma ou mais macros. Ao usar uma biblioteca de macros, você pode definir uma macro uma vez e usá-la em muitos arquivos de parâmetros.

Para criar uma biblioteca de macros

  1. Abra um novo arquivo em um editor de texto.

  2. Use linhas com comentários para descrever a biblioteca, se necessário.

  3. Use a seguinte sintaxe para definir cada macro:

    MACRO #*macro_name*
PARAMS (#*p1*, #*p2* [, ...])
BEGIN

*macro_body*
END;

  4. Salve o arquivo no subdiretório dirprm do diretório do Oracle GoldenGate como:

    *filename*.mac

    Onde:

    filename é o nome do arquivo de dados. A extensão .mac define o arquivo como uma biblioteca de macros.

A seguinte biblioteca de amostra chamada datelib contém duas macros, #make_date e #assign_date.

-- datelib macro library
--
MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

MACRO #assign_date
PARAMS (#target_col, #year, #month, #day)
BEGIN
#target_col = #make_date (#year, #month, #day)
END;

Para usar uma biblioteca de macros, use o parâmetro INCLUDE no início de um arquivo de parâmetros, conforme mostrado no arquivo de parâmetros Replicat de amostra a seguir.

INCLUDE /ggs/dirprm/datelib.mac
REPLICAT rep
ASSUMETARGETDEFS
USERIDALIAS ogg
MAP fin.acct_tab, TARGET fin.account;

Ao incluir uma biblioteca de macro longa em um arquivo de parâmetros, você pode usar o parâmetro NOLIST para suprimir a listagem de cada macro no arquivo de relatório Extract ou Replicat. A listagem pode ser ativada e desativada colocando-se os parâmetros LIST e NOLIST em qualquer lugar dentro do arquivo de parâmetros ou dentro do arquivo de biblioteca de macros. No exemplo a seguir, NOLIST suprime a listagem de cada macro na biblioteca de macros hugelib. Especificar LIST após a instrução INCLUDE restaura a listagem normal para o arquivo de relatório.

NOLIST
INCLUDE /ggs/dirprm/hugelib.mac
LIST
INCLUDE /ggs/dirprm/mdatelib.mac
REPLICAT REP

Rastreando Expansão de Macro

Você pode rastrear a expansão da macro com o parâmetro CMDTRACE. Com a opção CMDTRACE ativada, as etapas de expansão de macro são mostradas no arquivo de relatório Extract ou Replicat.

Sintaxe

CMDTRACE [ON | OFF | DETAIL]

Onde:

No exemplo a seguir, o rastreamento é ativado antes de #testmac ser chamado e, em seguida, desativado após a execução da macro.

<pre class="copy"><code>REPLICAT REP MACRO #testmac BEGIN COL1 = COL2, COL3 = COL4, END; ... CMDTRACE ON MAP test.table1, TARGET test.table2, COLMAP (#testmac); CMDTRACE OFF</code></pre>