Simplifica y automatiza el trabajo con macros de Oracle GoldenGate

Puede utilizar macros de Oracle GoldenGate en archivos de parámetros para configurar y reutilizar parámetros, comandos y funciones de conversión. Reduciendo la cantidad de texto que debe introducir para realizar tareas comunes. Una macro es una herramienta de automatización incorporada que permite llamar a un juego almacenado de pasos de procesamiento desde el archivo de parámetros de Oracle GoldenGate. Una macro puede constar de un juego simple de sentencias de parámetros utilizadas con frecuencia para una serie compleja de sustituciones de parámetros, cálculos o conversiones. Puede llamar a otras macros desde una macro. Puede almacenar macros de uso común en una biblioteca y, a continuación, llamar a la biblioteca en lugar de llamar a las macros individualmente.

Las macros de Oracle GoldenGate funcionan con los siguientes archivos de parámetros:

DEFGEN
Extracción
Replicat

Hay dos pasos para utilizar macros:

Definición de una macro
Llamada a una macro

Definición de una macro

Para definir una macro de Oracle GoldenGate, utilice el parámetro MACRO en el archivo de parámetros. MACRO define cualquier parámetro de entrada que sea necesario y define el trabajo que realiza la macro.

Sintaxis

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

Tabla 18 Argumentos de definición de macro

Argumento	Descripción
`MACRO`	Necesario. Indica el inicio de una definición de macro de Oracle GoldenGate.
`#macro_name`	El nombre de la macro. Los nombres de macro y parámetro deben comenzar con un carácter de macro. El carácter de macro por defecto es el carácter de almohadilla (#), como en `#macro1` y `#param1`. Un nombre de macro o parámetro puede ser una palabra que consta de letras y números, o ambos. Se pueden utilizar caracteres especiales, como el carácter de subrayado (`_`) o el guión `(-`. Algunos ejemplos de nombres de macro son: `#mymacro`, `#macro1`, `#macro_1`, `#macro-1`, `#macro$`. Algunos ejemplos de nombres de parámetros son `#sourcecol`, `#s`, `#col1` y `#col_1`. Para evitar errores de análisis, el carácter de macro no se puede utilizar como el primer carácter de un nombre de macro. Por ejemplo, `##macro` no es válido. Si es necesario, puede cambiar el carácter de macro mediante el parámetro `MACROCHAR` en la Referencia de parámetros y funciones para Oracle GoldenGate. Los nombres de macros y parámetros no distinguen entre mayúsculas y minúsculas. Los nombres de macros o parámetros entre comillas se ignoran.
PARAMS (#`p1`, #`p2`)	Definición opcional de parámetros de entrada. Especifique una lista separada por comas de nombres de parámetros y encerrarla entre paréntesis. Se debe hacer referencia a cada parámetro en el cuerpo de la macro donde desea que se sustituyan los valores de entrada. Puede mostrar cada parámetro en una línea separada para mejorar la legibilidad (asegurándose de utilizar los paréntesis de apertura y cierre para delimitar la lista de parámetros). Consulte Llamada a una macro que contiene parámetros para obtener más información.
BEGIN	Inicia el cuerpo de la macro. Se debe especificar antes que el cuerpo de la macro.
`macro_body`	El cuerpo macro. El cuerpo es una sentencia de sintaxis que define la función que va a realizar la macro. Un cuerpo de macro puede incluir cualquiera de los siguientes tipos de sentencias. Sentencias de parámetros simples, como en: COL1 = COL2 Sentencias de parámetros complejas con sustitución de parámetros como en: MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); Invocaciones de otras macros, como en: #colmap (COL1, #sourcecol)
`END;`	Finaliza la definición de macro. El punto y coma es necesario para completar la definición.

A continuación se muestra un ejemplo de una definición de macro que incluye parámetros. En este caso, la macro simplifica la tarea de asignación de objetos y columnas al proporcionar la sintaxis base de la sentencia MAP con parámetros de entrada que se resuelven en los nombres de los propietarios, las tablas y las columnas 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 continuación se muestra un ejemplo de una macro que no define parámetros. Ejecuta un juego de parámetros que se utiliza con frecuencia.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Llamar a una macro

Para llamar a una macro, utilice la siguiente sintaxis donde desee que la macro se ejecute en el archivo de parámetros.

Sintaxis

[*target* =] *macro_name* (*val*[, ...])

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

Tabla 19 Elementos de sintaxis para llamar a una macro

Argumento	Descripción
destino =	Opcional. Especifica el destino al que se asignan o asignan los resultados de la macro. Por ejemplo, `target` se puede utilizar para especificar una columna de destino en una sentencia `COLMAP`. En la siguiente llamada a la macro `#make_date`, la columna `DATECOL1` es el destino y se asignará a los resultados de la macro. `DATECOL1 = #make_date (YR1, MO1, DAY1)` Sin un destino, la sintaxis a la que llamar `#make_date` es: `#make_date (YR1, MO1, DAY1)`
macro_name	Nombre de la macro a la que se está llamando, por ejemplo: `#make_date`.
`(` val`[, ...]`	Los valores de entrada del parámetro. Este componente es obligatorio tanto si la macro define parámetros como si no. Si la macro define parámetros, especifique una lista separada por comas de valores de entrada, en el orden que corresponda a las definiciones de parámetros en el parámetro `MACRO` y encierre la lista entre paréntesis. Si la macro no define parámetros, especifique los paréntesis de apertura y cierre sin nada entre ellos ().
`(` val `\\| {`val`,` val`, ...} )[, ...]`	Los valores de entrada del parámetro. Este componente es obligatorio tanto si la macro define parámetros como si no. Si la macro define parámetros, especifique una lista separada por comas de valores de entrada, en el orden que corresponda a las definiciones de parámetros en el parámetro `MACRO` y encierre la lista entre paréntesis. Para transferir varios valores a un parámetro, sepárelos con comas y delimite la lista entre corchetes. Si la macro no define parámetros, especifique los paréntesis de apertura y cierre sin nada entre ellos ().

Consulte los siguientes temas para obtener más información sobre la sintaxis para llamar a una macro:

Llamada a una macro que contiene parámetros

Para llamar a una macro que contiene parámetros, la sentencia call debe proporcionar los valores de entrada que se van a sustituir para esos parámetros cuando se ejecute la macro.

La entrada válida para un parámetro de macro es cualquiera de las siguientes, precedida por el carácter de macro (el valor por defecto es #):

Un solo valor en texto sin formato o entre comillas, como: #macro (#name, #address, #phone) o #macro (#"name", #"address", #"phone").
Una lista de valores separados por comas entre corchetes, como: #macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2, DEPTNO3}). La capacidad de sustituir un bloque de valores por cualquier parámetro determinado agrega flexibilidad a la definición de macro y a su utilidad en la configuración de Oracle GoldenGate.
Llama a otras macros, como: #macro (#mycalc (col2, 100), #total). En este ejemplo, se llama a la macro #mycalc con los valores de entrada col2 y 100.

Oracle GoldenGate sustituye los valores de parámetros dentro del cuerpo de la macro según las siguientes reglas.

El procesador de macro lee el cuerpo de la macro en busca de instancias de nombres de parámetros especificados en la sentencia PARAMS.
Para cada incidencia del nombre de parámetro, se sustituye el valor de parámetro correspondiente especificado durante la llamada.
Si el nombre de un parámetro no aparece en la sentencia PARAMS, el procesador de macros evalúa si el elemento es, en su lugar, una llamada a otra macro. (Consulte Llamada a otras macros desde una macro). Si la llamada se realiza correctamente, se ejecuta la macro anidada. Si falla, toda la macro falla.

Ejemplo 9-39 Uso de parámetros para rellenar una sentencia MAP

La siguiente definición de macro especifica tres parámetros que se deben resolver. Los parámetros sustituyen los nombres del propietario de la tabla (parámetro #o), la tabla (parámetro #t) y las columnas KEYCOLS (parámetro #k) en una sentencia MAP.

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

Suponiendo que una tabla de la sentencia MAP solo necesita una columna KEYCOLS, la siguiente sintaxis se puede utilizar para llamar a #macro1. En esta sintaxis, el parámetro #k se puede resolver con un solo valor.

#macro1 (SCOTT, DEPT, DEPTNO1)

Para llamar a la macro para una tabla que necesita dos columnas KEYCOLS, los corchetes rizados se utilizan de la siguiente forma para delimitar los dos valores necesarios para los nombres de columna:

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

Los valores DEPTNO1 y DEPTNO2 se transfieren como un argumento para resolver el parámetro #t. Las tablas con tres o más KEYCOLS también se pueden manejar de esta manera, utilizando valores adicionales dentro de los corchetes.

Ejemplo 9-40 Uso de una macro para realizar la conversión

En este ejemplo, una macro define los parámetros #year, #month y #day para convertir un formato de fecha propietario.

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;

La macro se llama en la 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)
);

La macro se expande de la siguiente manera:

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)
);

Llamada a una macro sin parámetros de entrada

Para llamar a una macro sin parámetros de entrada, la sentencia de llamada debe proporcionar los paréntesis de apertura y cierre, pero sin valores de entrada: #macro ().

La siguiente macro se define sin parámetros de entrada. El cuerpo contiene parámetros de uso frecuente.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Esta macro se denomina de la siguiente manera:

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

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

La macro se expande de la siguiente manera:

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

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

Llamada a otras macros desde una macro

Para llamar a otras macros desde una macro, cree una definición de macro similar a la siguiente. En este ejemplo, la macro #make_date está anidada en la macro #assign_date y se llama cuando se ejecuta #assign_date.

La macro anidada debe definir todos los parámetros definidos en la macro base, o un subjuego de ellos. En otras palabras, los valores de entrada cuando se llama a la macro base deben resolverse en los parámetros de ambas macros.

A continuación, se define #assign_date:

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

A continuación, se define #make_date. Esta macro crea un formato de fecha que incluye un año de cuatro dígitos, después de determinar primero si la fecha de entrada de dos dígitos debe tener como prefijo un valor de siglo de 19 o 20. Tenga en cuenta que la sentencia PARAMS de #make_date contiene un subjuego de los parámetros en la 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;

La siguiente sintaxis llama a #assign_date:

#assign_date (COL1, YEAR, MONTH, DAY)

La macro se expande a lo siguiente teniendo en cuenta los valores de entrada anteriores y la macro #make_date embebida:

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

Crear bibliotecas de macros

Puede crear una biblioteca de macros que contenga una o más macros. Mediante el uso de una biblioteca de macros, puede definir una macro una vez y, a continuación, utilizarla en muchos archivos de parámetros.

Para crear una biblioteca de macros

Abra un nuevo archivo en un editor de texto.
Utilice líneas comentadas para describir la biblioteca, si es necesario.

Utilice la siguiente sintaxis para definir cada macro:

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

*macro_body*
END;

Guarde el archivo en el subdirectorio dirprm del directorio de Oracle GoldenGate como:
```
*filename*.mac
```
Dónde:

nombre_archivo es el nombre del archivo. La extensión .mac define el archivo como una biblioteca de macros.

La siguiente biblioteca de ejemplo denominada datelib contiene dos macros, #make_date y #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 utilizar una biblioteca de macros, utilice el parámetro INCLUDE al principio de un archivo de parámetros, como se muestra en el siguiente archivo de parámetros Replicat de ejemplo.

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

Al incluir una biblioteca de macro larga en un archivo de parámetros, puede utilizar el parámetro NOLIST para suprimir la lista de cada macro en el archivo de informe Extract o Replicat. El listado se puede activar y desactivar colocando los parámetros LIST y NOLIST en cualquier lugar dentro del archivo de parámetros o dentro del archivo de biblioteca de macros. En el siguiente ejemplo, NOLIST suprime la lista de cada macro en la biblioteca de macros hugelib. Al especificar LIST después de la sentencia INCLUDE, se restaura la lista normal en el archivo de informe.

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

Rastreo de Expansión de Macro

Puede rastrear la expansión de macros con el parámetro CMDTRACE. Con CMDTRACE activado, los pasos de expansión de macro se muestran en el archivo de informe Extract o Replicat.

Sintaxis

CMDTRACE [ON | OFF | DETAIL]

Dónde:

ON activa el rastreo.
OFF desactiva el rastreo.
DETAIL produce una visualización detallada de la expansión de macros.

En el siguiente ejemplo, el rastreo se activa antes de que se llame a #testmac y, a continuación, se desactiva después de la ejecución de la 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>