Simplifier et automatiser le travail avec les macros Oracle GoldenGate

Vous pouvez utiliser les macros Oracle GoldenGate dans les fichiers de paramètres pour configurer et réutiliser les paramètres, les commandes et les fonctions de conversion. Réduisez la quantité de texte que vous devez entrer pour effectuer des tâches courantes. Une macro est un outil d'automatisation intégré qui vous permet d'appeler un ensemble stocké d'étapes de traitement à partir du fichier de paramètres Oracle GoldenGate. Une macro peut être constituée d'un ensemble simple d'instructions de paramètre fréquemment utilisées pour une série complexe de substitutions, de calculs ou de conversions de paramètres. Vous pouvez appeler d'autres macros à partir d'une macro. Vous pouvez stocker les macros couramment utilisées dans une bibliothèque, puis appeler la bibliothèque plutôt que d'appeler les macros individuellement.

Les macros Oracle GoldenGate fonctionnent avec les fichiers de paramètres suivants :

DEFGEN
Extraction
Réplication

L'utilisation des macros se déroule en deux étapes :

Définition d'une macro
Appeler une macro

Définition d'une macro

Pour définir une macro Oracle GoldenGate, utilisez le paramètre MACRO dans le fichier de paramètres. MACRO définit tous les paramètres d'entrée nécessaires et le travail effectué par la macro.

Syntaxe

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

Tableau 18 Arguments de définition de macro

Argument	Description
`MACRO`	Obligatoire. Indique le début d'une définition de macro Oracle GoldenGate.
`#macro_name`	le nom de la macro, Les noms de macro et de paramètre doivent commencer par un caractère de macro. Le caractère de macro par défaut est le caractère dièse (#), comme dans `#macro1` et `#param1`. Un nom de macro ou de paramètre peut être un mot composé de lettres et de chiffres, ou les deux. Des caractères spéciaux, tels que le trait de soulignement (`_`) ou le trait d'union `(-`), peuvent être utilisés. Exemples de noms de macro : `#mymacro`, `#macro1`, `#macro_1`, `#macro-1`, `#macro$`. Voici quelques exemples de noms de paramètre : `#sourcecol`, `#s`, `#col1` et `#col_1`. Pour éviter les erreurs d'analyse, le caractère de macro ne peut pas être utilisé comme premier caractère d'un nom de macro. Par exemple, `##macro` n'est pas valide. Si nécessaire, vous pouvez modifier le caractère de la macro à l'aide du paramètre `MACROCHAR` dans la référence des paramètres et des fonctions pour Oracle GoldenGate. Les noms de macro et de paramètre ne respectent pas la casse. Les noms de macro ou de paramètre entre guillemets sont ignorés.
PARAMS (#`p1`, #`p2`)	Définition facultative des paramètres d'entrée. Indiquez une liste de noms de paramètre séparés par des virgules et placez-la entre parenthèses. Chaque paramètre doit être référencé dans le corps de la macro où vous souhaitez que les valeurs d'entrée soient remplacées. Vous pouvez répertorier chaque paramètre sur une ligne distincte pour améliorer la lisibilité (en vous assurant d'utiliser les parenthèses ouvrante et fermante pour encadrer la liste de paramètres). Pour plus d'informations, reportez-vous à Appel d'une macro contenant des paramètres.
BEGIN	Commence le corps de la macro. Doit être spécifié avant le corps de la macro.
`macro_body`	Le corps macro. Le corps est une instruction de syntaxe qui définit la fonction qui doit être effectuée par la macro. Un corps de macro peut inclure l'un des types d'instruction suivants. Instructions de paramètre simples, comme dans : COL1 = COL2 Instructions de paramètres complexes avec substitution de paramètres comme dans : MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); Appels d'autres macros, comme dans : #colmap (COL1, #sourcecol)
`END;`	Termine la définition de la macro. Le point-virgule est requis pour terminer la définition.

Voici un exemple de définition de macro qui inclut des paramètres. Dans ce cas, la macro simplifie la tâche de mise en correspondance d'objets et de colonnes en fournissant la syntaxe de base de l'instruction MAP avec des paramètres d'entrée qui se résolvent en noms de propriétaires, de tables et de colonnes 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>

Voici un exemple de macro qui ne définit pas de paramètres. Il exécute un ensemble de paramètres fréquemment utilisé.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Appeler une macro

Pour appeler une macro, utilisez la syntaxe suivante pour que la macro s'exécute dans le fichier de paramètres.

Syntaxe

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

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

Tableau 19 Eléments de syntaxe pour appeler une macro

Argument	Description
cible =	Facultatif. Spécifie la cible à laquelle les résultats de la macro sont affectés ou mappés. Par exemple, `target` peut être utilisé pour indiquer une colonne cible dans une instruction `COLMAP`. Dans l'appel suivant de la macro `#make_date`, la colonne `DATECOL1` est la cible et sera mise en correspondance avec les résultats de la macro. `DATECOL1 = #make_date (YR1, MO1, DAY1)` Sans cible, la syntaxe à utiliser pour appeler `#make_date` est la suivante : `#make_date (YR1, MO1, DAY1)`
macro_name	Nom de la macro appelée, par exemple : `#make_date`.
`(` val`[, ...]`)	Valeurs d'entrée du paramètre. Ce composant est obligatoire, que la macro définisse ou non des paramètres. Si la macro définit des paramètres, indiquez une liste de valeurs d'entrée séparées par des virgules, dans l'ordre qui correspond aux définitions de paramètre dans le paramètre `MACRO`, et placez la liste entre parenthèses. Si la macro ne définit pas de paramètres, spécifiez les parenthèses ouvrante et fermante sans rien entre elles ().
`(` val `\\| {`val`,` val`, ...} )[, ...]`	Valeurs d'entrée du paramètre. Ce composant est obligatoire, que la macro définisse ou non des paramètres. Si la macro définit des paramètres, indiquez une liste de valeurs d'entrée séparées par des virgules, dans l'ordre qui correspond aux définitions de paramètre dans le paramètre `MACRO`, et placez la liste entre parenthèses. Pour transmettre plusieurs valeurs à un paramètre, séparez-les par des virgules et placez la liste entre accolades. Si la macro ne définit pas de paramètres, spécifiez les parenthèses ouvrante et fermante sans rien entre elles ().

Pour en savoir plus sur la syntaxe d'appel de macro, reportez-vous aux rubriques suivantes :

Appel d'une macro contenant des paramètres

Pour appeler une macro contenant des paramètres, l'instruction d'appel doit fournir les valeurs d'entrée qui doivent être remplacées par ces paramètres lors de l'exécution de la macro.

L'entrée valide pour un paramètre de macro est l'une des suivantes, précédée du caractère de macro (la valeur par défaut est #) :

Valeur unique en texte brut ou entre guillemets, telle que : #macro (#name, #address, #phone) ou #macro (#"name", #"address", #"phone").
Liste de valeurs séparées par des virgules entre accolades, telle que : #macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2, DEPTNO3}). La possibilité de remplacer un bloc de valeurs par un paramètre donné ajoute de la flexibilité à la définition de la macro et à sa facilité d'utilisation dans la configuration Oracle GoldenGate.
Appels vers d'autres macros, telles que : #macro (#mycalc (col2, 100), #total). Dans cet exemple, la macro #mycalc est appelée avec les valeurs d'entrée col2 et 100.

Oracle GoldenGate remplace les valeurs de paramètre dans le corps de la macro conformément aux règles suivantes.

Le processeur de macro lit le corps de la macro à la recherche d'instances de noms de paramètre spécifiés dans l'instruction PARAMS.
Pour chaque occurrence du nom du paramètre, la valeur de paramètre correspondante spécifiée lors de l'appel est remplacée.
Si un nom de paramètre n'apparaît pas dans l'instruction PARAMS, le processeur de macro évalue si l'élément est, à la place, un appel vers une autre macro. (Voir Appel d'autres macros à partir d'une macro.) Si l'appel réussit, la macro imbriquée est exécutée. Si elle échoue, la macro entière échoue.

Exemple 9-39 Utilisation de paramètres pour remplir une instruction MAP

La définition de macro suivante indique trois paramètres qui doivent être résolus. Les paramètres remplacent les noms du propriétaire de la table (paramètre #o), de la table (paramètre #t) et des colonnes KEYCOLS (paramètre #k) dans une instruction MAP.

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

En supposant qu'une table dans l'instruction MAP ne nécessite qu'une seule colonne KEYCOLS, la syntaxe suivante peut être utilisée pour appeler #macro1. Dans cette syntaxe, le paramètre #k peut être résolu avec une seule valeur.

#macro1 (SCOTT, DEPT, DEPTNO1)

Pour appeler la macro d'une table qui nécessite deux colonnes KEYCOLS, les accolades sont utilisées comme suit pour encadrer les deux valeurs requises pour les noms de colonne :

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

Les valeurs DEPTNO1 et DEPTNO2 sont transmises en tant qu'argument unique pour résoudre le paramètre #t. Les tables contenant au moins trois éléments KEYCOLS peuvent également être gérées de cette manière, en utilisant des valeurs supplémentaires entre accolades.

Exemple 9-40 Utilisation d'une macro pour effectuer une conversion

Dans cet exemple, une macro définit les paramètres #year, #month et #day pour convertir un format de date propriétaire.

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 est appelée dans la clause 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 développe comme suit :

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

Appeler une macro sans paramètres d'entrée

Pour appeler une macro sans paramètre d'entrée, l'instruction d'appel doit fournir les parenthèses ouvrante et fermante, mais sans valeur d'entrée : #macro ().

La macro suivante est définie sans paramètre d'entrée. Le corps contient des paramètres fréquemment utilisés.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Cette macro s'appelle comme suit :

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

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

La macro se développe comme suit :

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

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

Appeler d'autres macros à partir d'une macro

Pour appeler d'autres macros à partir d'une macro, créez une définition de macro similaire à la suivante. Dans cet exemple, la macro #make_date est imbriquée dans la macro #assign_date et elle est appelée lors de l'exécution de #assign_date.

La macro imbriquée doit définir tous les paramètres définis dans la macro de base, ou un sous-ensemble de ces paramètres. En d'autres termes, les valeurs d'entrée lorsque la macro de base est appelée doivent être résolues en paramètres dans les deux macros.

La définition suivante est #assign_date :

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

Les éléments suivants définissent #make_date. Cette macro crée un format de date qui inclut une année à quatre chiffres, après avoir d'abord déterminé si la date d'entrée à deux chiffres doit être précédée d'une valeur de siècle de 19 ou 20. L'instruction PARAMS de #make_date contient un sous-ensemble des paramètres de 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 syntaxe suivante appelle #assign_date :

#assign_date (COL1, YEAR, MONTH, DAY)

La macro se développe comme suit en fonction des valeurs d'entrée précédentes et de la macro #make_date imbriquée :

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

Créer des bibliothèques de macros

Vous pouvez créer une bibliothèque de macros contenant une ou plusieurs macros. En utilisant une bibliothèque de macro, vous pouvez définir une macro une fois, puis l'utiliser dans de nombreux fichiers de paramètres.

Pour créer une bibliothèque de macros

Ouvrez un nouveau fichier dans un éditeur de texte.
Utilisez des lignes commentées pour décrire la bibliothèque, si nécessaire.

Utilisez la syntaxe suivante pour définir chaque macro :

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

*macro_body*
END;

Enregistrez le fichier dans le sous-répertoire dirprm du répertoire Oracle GoldenGate sous :
```
*filename*.mac
```
Où :

filename est le nom du fichier. L'extension .mac définit le fichier comme une bibliothèque de macros.

L'exemple de bibliothèque suivant nommé datelib contient deux macros, #make_date et #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;

Pour utiliser une bibliothèque de macros, utilisez le paramètre INCLUDE au début d'un fichier de paramètres, comme indiqué dans l'exemple de fichier de paramètres Replicat suivant.

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

Lorsque vous incluez une bibliothèque de macro longue dans un fichier de paramètres, vous pouvez utiliser le paramètre NOLIST pour supprimer la liste de chaque macro dans le fichier de rapport Extract ou Replicat. La liste peut être activée et désactivée en plaçant les paramètres LIST et NOLIST n'importe où dans le fichier de paramètres ou dans le fichier de bibliothèque de macros. Dans l'exemple suivant, NOLIST supprime la liste de chaque macro dans la bibliothèque de macros hugelib. Lorsque vous indiquez LIST, l'instruction INCLUDE restaure la liste normale dans le fichier de rapport.

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

Suivi de l'extension de macro

Vous pouvez suivre le développement d'une macro à l'aide du paramètre CMDTRACE. Lorsque l'option CMDTRACE est activée, les étapes d'extension de macro sont affichées dans le fichier de rapport d'extraction ou de réplication.

Syntaxe

CMDTRACE [ON | OFF | DETAIL]

Où :

ON active la fonction de trace.
OFF désactive la fonction de trace.
DETAIL produit un affichage détaillé de l'expansion de la macro.

Dans l'exemple suivant, la fonction de trace est activée avant l'appel de #testmac, puis désactivée après l'exécution 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>