Semplifica e automatizza il lavoro con le macro Oracle GoldenGate

È possibile utilizzare le macro di Oracle GoldenGate nei file dei parametri per configurare e riutilizzare parametri, comandi e funzioni di conversione. Riducendo la quantità di testo che è necessario immettere per eseguire task comuni. Una macro è uno strumento di automazione integrato che consente di chiamare un set memorizzato di passi di elaborazione dall'interno del file dei parametri di Oracle GoldenGate. Una macro può essere costituita da un semplice set di istruzioni di parametri utilizzate di frequente in una serie complessa di sostituzioni di parametri, calcoli o conversioni. È possibile chiamare altre macro da una macro. È possibile memorizzare le macro più utilizzate in una libreria, quindi chiamare la libreria anziché chiamare le macro singolarmente.

Le macro di Oracle GoldenGate funzionano con i seguenti file di parametri:

Esistono due passaggi per utilizzare le macro:

  1. Definizione di una macro

  2. Chiamare una macro

Definire una macro

Per definire una macro Oracle GoldenGate, utilizzare il parametro MACRO nel file dei parametri. MACRO definisce i parametri di input necessari e definisce il lavoro eseguito dalla macro.

Sintassi

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

Tabella 18 Argomenti definizione macro

Argomento Descrizione 
MACRO
 Obbligatorio Indica l'inizio di una definizione di macro Oracle GoldenGate. 
#macro_name

Il nome della macro. I nomi delle macro e dei parametri devono iniziare con un carattere macro. Il carattere macro predefinito è il cancelletto (#), come in #macro1 e #param1.

Il nome di una macro o di un parametro può essere costituito da lettere e numeri o da entrambi. È possibile utilizzare caratteri speciali, ad esempio il carattere di sottolineatura (_) o il trattino (-. Alcuni esempi di nomi di macro sono: #mymacro, #macro1, #macro_1, #macro-1, #macro$. Alcuni esempi di nomi di parametro sono #sourcecol, #s, #col1 e #col_1.

Per evitare errori di analisi, il carattere macro non può essere utilizzato come primo carattere di un nome di macro. Ad esempio, ##macro non è valido. Se necessario, è possibile modificare il carattere della macro utilizzando il parametro MACROCHAR in Riferimento parametri e funzioni per Oracle GoldenGate.

Per i nomi delle macro e dei parametri non viene fatta distinzione tra maiuscole e minuscole. I nomi delle macro o dei parametri tra virgolette vengono ignorati.

 
PARAMS (#p1, #p2)
 Definizione facoltativa dei parametri di input. Specificare una lista separata da virgole di nomi di parametro e racchiuderla tra parentesi. Ogni parametro deve essere utilizzato come riferimento nel corpo della macro in cui si desidera sostituire i valori di input. È possibile elencare ogni parametro su una linea separata per migliorare la leggibilità (assicurandosi di utilizzare le parentesi aperte e chiuse per racchiudere l'elenco dei parametri). Per ulteriori informazioni, vedere Chiamare una macro che contiene parametri. 
BEGIN
 Inizia il corpo della macro. Deve essere specificato prima del corpo della macro. 
macro_body

Il corpo macro. Il corpo è un'istruzione di sintassi che definisce la funzione che deve essere eseguita dalla macro. Un corpo macro può includere uno qualsiasi dei seguenti tipi di istruzioni.

  • Semplici istruzioni per i parametri, come in:

    COL1 = COL2

  • Istruzioni di parametri complesse con sostituzione dei parametri come in:

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

  • Richiami di altre macro, come in:

    #colmap (COL1, #sourcecol)
 
END;
 Termina la definizione della macro. Per completare la definizione è necessario il punto virgola.

Di seguito è riportato un esempio di definizione di macro che include parametri. In questo caso, la macro semplifica il task del mapping di oggetti e colonne fornendo la sintassi di base dell'istruzione MAP con parametri di input che risolvono i nomi dei proprietari, delle tabelle e delle colonne 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>

Di seguito è riportato un esempio di macro che non definisce i parametri. Esegue un set di parametri utilizzato di frequente.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Chiama una macro

Per chiamare una macro, utilizzare la sintassi seguente in cui si desidera che la macro venga eseguita nel file dei parametri.

Sintassi

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

Tabella 19 Elementi di sintassi per la chiamata di una macro

Argomento Descrizione
destinazione =

Facoltativa. Specifica la destinazione a cui vengono assegnati o mappati i risultati della macro. Ad esempio, è possibile utilizzare target per specificare una colonna di destinazione in un'istruzione COLMAP. Nella chiamata alla macro #make_date seguente, la colonna DATECOL1 è la destinazione e verrà mappata ai risultati della macro. 

DATECOL1 = #make_date (YR1, MO1, DAY1)

Senza una destinazione, la sintassi per chiamare #make_date è la seguente: 

#make_date (YR1, MO1, DAY1)
macro_name Il nome della macro chiamata, ad esempio: #make_date.
( valore[, ...]) Valori di input del parametro. Questo componente è obbligatorio indipendentemente dal fatto che la macro definisca i parametri. Se la macro definisce i parametri, specificare una lista separata da virgole di valori di input, nell'ordine che corrisponde alle definizioni dei parametri nel parametro MACRO, e racchiudere l'elenco tra parentesi. Se la macro non definisce i parametri, specificare le parentesi aperte e chiuse senza alcuna distinzione tra loro ().
( val \| {val, val, ...} )[, ...] Valori di input del parametro. Questo componente è obbligatorio indipendentemente dal fatto che la macro definisca i parametri. Se la macro definisce i parametri, specificare una lista separata da virgole di valori di input, nell'ordine che corrisponde alle definizioni dei parametri nel parametro MACRO, e racchiudere l'elenco tra parentesi. Per passare più valori a un parametro, separarli con virgole e racchiudere l'elenco tra parentesi graffe. Se la macro non definisce i parametri, specificare le parentesi aperte e chiuse senza alcuna distinzione tra loro ().

Per ulteriori informazioni sulla sintassi per la chiamata di una macro, vedere gli argomenti riportati di seguito.

Chiama una macro che contiene parametri

Per chiamare una macro che contiene parametri, l'istruzione di chiamata deve fornire i valori di input che devono essere sostituiti per tali parametri quando viene eseguita la macro.

L'input valido per un parametro macro è uno dei seguenti, preceduto dal carattere macro (l'impostazione predefinita è #):

Oracle GoldenGate sostituisce i valori dei parametri nel corpo della macro in base alle regole riportate di seguito.

  1. Il processore delle macro legge il corpo della macro cercando le istanze dei nomi dei parametri specificati nell'istruzione PARAMS.

  2. Per ogni occorrenza del nome del parametro, viene sostituito il valore del parametro corrispondente specificato durante la chiamata.

  3. Se il nome di un parametro non viene visualizzato nell'istruzione PARAMS, il processore macro valuta se l'elemento è, invece, una chiamata a un'altra macro. Vedere Chiamata di altre macro da una macro. Se la chiamata riesce, viene eseguita la macro nidificata. Se fallisce, l'intera macro fallisce.

Esempio 9-39 Utilizzo dei parametri per popolare un'istruzione MAP

La definizione di macro seguente specifica tre parametri da risolvere. I parametri sostituiscono i nomi del proprietario della tabella (parametro #o), della tabella (parametro #t) e delle colonne KEYCOLS (parametro #k) in un'istruzione MAP.

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

Supponendo che una tabella nell'istruzione MAP richieda una sola colonna KEYCOLS, è possibile utilizzare la sintassi seguente per chiamare #macro1. In questa sintassi, il parametro #k può essere risolto con un solo valore.

#macro1 (SCOTT, DEPT, DEPTNO1)

Per chiamare la macro per una tabella che richiede due colonne KEYCOLS, le parentesi graffe vengono utilizzate come indicato di seguito per racchiudere entrambi i valori richiesti per i nomi delle colonne:

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

I valori DEPTNO1 e DEPTNO2 vengono passati come un argomento per risolvere il parametro #t. Anche le tabelle con tre o più KEYCOLS possono essere gestite in questo modo, utilizzando valori aggiuntivi all'interno delle parentesi graffe.

Esempio 9-40 Utilizzo di una macro per eseguire la conversione

In questo esempio, una macro definisce i parametri #year, #month e #day per convertire un formato data proprietario.

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 viene richiamata nella clausola 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 si espande come indicato di seguito.

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

Chiama una macro senza parametri di input

Per chiamare una macro senza parametri di input, l'istruzione di chiamata deve fornire le parentesi aperte e chiuse, ma senza alcun valore di input: #macro ().

La macro seguente è definita senza parametri di input. Il corpo contiene parametri utilizzati di frequente.

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

Questa macro è denominata come segue:

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

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

La macro si espande come indicato di seguito.

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

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

Chiamare altre macro da una macro

Per chiamare altre macro da una macro, creare una definizione di macro simile alla seguente. In questo esempio, la macro #make_date viene nidificata all'interno della macro #assign_date e viene chiamata quando viene eseguito #assign_date.

La macro nidificata deve definire tutti o un subset degli stessi parametri definiti nella macro di base. In altre parole, i valori di input quando viene chiamata la macro di base devono essere risolti nei parametri di entrambe le macro.

Quanto segue definisce #assign_date:

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

Quanto segue definisce #make_date. Questa macro crea un formato di data che include un anno a quattro cifre, dopo aver determinato prima se la data di input a due cifre deve essere preceduta da un valore di secolo pari a 19 o 20. Si noti che l'istruzione PARAMS di #make_date contiene un subset dei parametri nella 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 sintassi seguente chiama #assign_date:

#assign_date (COL1, YEAR, MONTH, DAY)

La macro si espande ai seguenti valori di input precedenti e alla macro #make_date incorporata:

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

Crea librerie macro

È possibile creare una macro libreria contenente una o più macro. Utilizzando una libreria di macro, è possibile definire una macro una sola volta e quindi utilizzarla in molti file di parametri.

Per creare una libreria macro

  1. Aprire un nuovo file in un editor di testo.

  2. Utilizzare linee commentate per descrivere la libreria, se necessario.

  3. Utilizzare la sintassi seguente per definire ogni macro:

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

*macro_body*
END;

  4. Salvare il file nella sottodirectory dirprm della directory Oracle GoldenGate come indicato di seguito.

    *filename*.mac

    Dove:

    nome_file è il nome del file. L'estensione .mac definisce il file come una macro libreria.

La seguente libreria di esempio denominata datelib contiene due macro: #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;

Per utilizzare una libreria di macro, utilizzare il parametro INCLUDE all'inizio di un file di parametri, come mostrato nel seguente file di parametri di esempio Replicat.

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

Quando si include una lunga libreria di macro in un file di parametri, è possibile utilizzare il parametro NOLIST per eliminare l'elenco di ogni macro nel file di report Extract o Replicat. L'elenco può essere attivato e disattivato posizionando i parametri LIST e NOLIST in qualsiasi punto all'interno del file dei parametri o nel file della libreria delle macro. Nell'esempio seguente, NOLIST elimina l'elenco di ogni macro nella libreria di macro hugelib. Se si specifica LIST dopo l'istruzione INCLUDE, l'elenco viene ripristinato nel file del report.

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

Trace dell'espansione delle macro

È possibile tracciare l'espansione delle macro con il parametro CMDTRACE. Con CMDTRACE abilitato, i passi di espansione delle macro vengono visualizzati nel file di report Extract o Replicat.

Sintassi

CMDTRACE [ON | OFF | DETAIL]

Dove:

Nell'esempio seguente, il trace viene abilitato prima della chiamata di #testmac, quindi disabilitato dopo l'esecuzione della 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>