使用 Oracle GoldenGate 巨集簡化及自動化工作

您可以在參數檔中使用 Oracle GoldenGate 巨集來設定及重複使用參數、命令以及轉換函數。減少執行一般工作時必須輸入的文字量。巨集是內建的自動化工具，可讓您從 Oracle GoldenGate 參數檔中呼叫一組儲存的處理步驟。巨集可以由一組簡單常用的參數陳述式組成，以替代、計算或轉換一系列複雜的參數。您可以從巨集呼叫其他巨集。您可以將常用的巨集儲存在資源庫中，然後呼叫資源庫，而不是個別呼叫巨集。

Oracle GoldenGate 巨集可以使用下列參數檔：

DEFGEN
擷取
Replicat

使用巨集有兩個步驟：

定義巨集
呼叫巨集

定義巨集

若要定義 Oracle GoldenGate 巨集，請使用參數檔中的 MACRO 參數。MACRO 定義任何需要的輸入參數，並定義巨集執行的工作。

語法

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

表格 18 巨集定義引數

引數	說明
`MACRO`	必要項目。表示 Oracle GoldenGate 巨集定義的開始。
`#macro_name`	巨集的名稱。巨集和參數名稱必須以巨集字元開頭。預設巨集字元為井號 (#) 字元，如 `#macro1` 和 `#param1`。巨集或參數名稱可以是包含字母與數字的一個字，或兩者皆含。可以使用特殊字元，例如底線字元 (`_`) 或連字號 `(-`)。巨集名稱的範例有：`#mymacro`、`#macro1`、`#macro_1`、`#macro-1`、`#macro$`。參數名稱的部分範例包括 `#sourcecol`、`#s`、`#col1` 和 `#col_1`。為了避免剖析錯誤，巨集字元無法用作巨集名稱的第一個字元。例如，`##macro` 無效。如有需要，您可以使用 Oracle GoldenGate 的參數和函數參照中的 `MACROCHAR` 參數來變更巨集字元。巨集和參數名稱不區分大小寫。系統會忽略引號內的巨集或參數名稱。
PARAMS (#`p1`, #`p2`)	輸入參數的選擇性定義。指定以逗號分隔的參數名稱清單，並將其括在括弧內。您必須在巨集主體中參照每個參數，以替代輸入值。您可以在單獨的行列出每個參數，以提高可讀性 (讓確定使用左括號和右括號來括住參數清單)。請參閱呼叫包含參數的巨集瞭解詳細資訊。
BEGIN	開始巨集主體。必須在巨集主體之前指定。
`macro_body`	巨集主體。Body 是定義巨集將執行之函數的語法陳述式。巨集主體可包含下列任一類型的陳述式。簡單參數敘述句，如下所示： COL1 = COL2 含有參數替代的複雜參數敘述句，如下所示： MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); 其他巨集的呼叫，如下所示： #colmap (COL1, #sourcecol)
`END;`	結束巨集定義。需有分號才能完成定義。

以下為包含參數的巨集定義範例。在此情況下，巨集會藉由提供 MAP 敘述句的基本語法 (輸入參數解析為擁有者名稱、表格和 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>

以下是一個未定義參數的巨集範例。它會執行一組常用的參數。

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

呼叫巨集

若要呼叫巨集，請使用下列語法，您希望巨集在參數檔內執行。

語法

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

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

表格 19 呼叫巨集的語法元素

引數	說明
目標 =	選擇性。指定要將巨集結果指派給或對映的目標。例如，您可以使用 `target` 在 `COLMAP` 敘述句中指定目標資料欄。在下列對 `#make_date` 巨集的呼叫中，欄 `DATECOL1` 為目標，並將對映至巨集結果。 `DATECOL1 = #make_date (YR1, MO1, DAY1)` 如果沒有目標，呼叫 `#make_date` 的語法為： `#make_date (YR1, MO1, DAY1)`
macro_name	要呼叫的巨集名稱，例如：`#make_date`。
`(` 值`[, ...]`)	參數輸入值。無論巨集是否定義參數，都需要此元件。如果巨集定義參數，請依照與 `MACRO` 參數中的參數定義對應的順序，指定以逗號分隔的輸入值清單，然後將清單括在括號內。如果巨集未定義參數，請指定左括弧與右括弧，且兩者之間沒有任何項目 ()。
`(` val `\\| {` val`,` val`, ...} )[, ...]`	參數輸入值。無論巨集是否定義參數，都需要此元件。如果巨集定義參數，請依照與 `MACRO` 參數中的參數定義對應的順序，指定以逗號分隔的輸入值清單，然後將清單括在括號內。若要將多個值傳送到一個參數，請以逗號分隔，然後將清單括在大括號中。如果巨集未定義參數，請指定左括弧與右括弧，且兩者之間沒有任何項目 ()。

如需呼叫巨集之語法的詳細資訊，請參閱下列主題：

呼叫包含參數的巨集

若要呼叫包含參數的巨集，呼叫陳述式必須提供輸入值，這些輸入值會在巨集執行時替代這些參數。

巨集參數的有效輸入為下列任何一項，前面加上巨集字元 (預設值為 #)：

以純文字或引號括住的單一值，例如：#macro (#name, #address, #phone) 或 #macro (#"name", #"address", #"phone")。
以逗號分隔的數值清單，以大括弧括住，例如：#macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2, DEPTNO3})。替代任何指定參數之值區塊的功能，可為巨集定義及其在 Oracle GoldenGate 組態中的可用性增加彈性。
呼叫其他巨集，例如：#macro (#mycalc (col2, 100), #total)。在此範例中，使用 col2 和 100 的輸入值呼叫 #mycalc 巨集。

Oracle GoldenGate 會根據下列規則替代巨集主體內的參數值。

巨集處理器會透過巨集主體讀取，以尋找 PARAMS 陳述式中指定的參數名稱實例。
對於每次出現的參數名稱，系統會替換呼叫期間指定的對應參數值。
如果參數名稱未出現在 PARAMS 陳述式中，巨集處理器會評估該項目是否為另一個巨集的呼叫。(請參閱從巨集呼叫其他巨集。) 如果呼叫成功，就會執行巢狀巨集。如果失敗，整個巨集會失敗。

範例 9-39 使用參數植入 MAP 陳述式

下列巨集定義指定三個必須解析的參數。這些參數會取代 MAP 敘述句中表格擁有者 (參數 #o)、表格 (參數 #t) 以及 KEYCOLS 資料欄 (參數 #k) 的名稱。

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

假設 MAP 敘述句中的表格只需要一個 KEYCOLS 資料欄，您可以使用下列語法來呼叫 #macro1。在此語法中，#k 參數只能使用一個值解析。

#macro1 (SCOTT, DEPT, DEPTNO1)

若要針對需要兩個 KEYCOLS 資料欄的表格呼叫巨集，大括號的使用方式如下，以將資料欄名稱的必要值括住：

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

DEPTNO1 和 DEPTNO2 值會以一個引數傳送，以解析 #t 參數。具有三個或更多 KEYCOLS 的表格也可以使用此方式來處理，使用大括號內的其他值。

範例 9-40 使用巨集執行轉換

在此範例中，巨集會定義參數 #year、#month 和 #day，以轉換專屬日期格式。

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;

在 COLMAP 子句中呼叫巨集：

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

此巨集的擴充方式如下：

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

呼叫不含輸入參數的巨集

若要呼叫不含輸入參數的巨集，呼叫陳述式必須提供左右括弧，但不提供任何輸入值：#macro ()。

已定義下列巨集，但無輸入參數。主體包含常用的參數。

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

此巨集的呼叫方式如下：

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

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

此巨集的擴充方式如下：

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

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

從巨集呼叫其他巨集

若要從巨集呼叫其他巨集，請建立類似以下的巨集定義。在此範例中，#make_date 巨集是巢狀於 #assign_date 巨集內，且會在 #assign_date 執行時呼叫。

巢狀巨集必須定義基本巨集中定義的所有參數或相同參數的子集。換句話說，呼叫基本巨集時的輸入值必須解析為兩個巨集中的參數。

以下定義 #assign_date：

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

以下定義 #make_date。此巨集會建立包含四位數年份的日期格式，在第一次決定兩位數輸入日期應以世紀值 19 或 20 為開頭。請注意，#make_date 的 PARAMS 陳述式包含 #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;

下列語法呼叫 #assign_date：

#assign_date (COL1, YEAR, MONTH, DAY)

此巨集會擴充至下列指定之前的輸入值和內嵌的 #make_date 巨集：

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

建立巨集程式庫

您可以建立包含一個或多個巨集的巨集程式庫。透過使用巨集資源庫，您可以定義巨集一次，然後在許多參數檔案中使用巨集。

建立巨集程式庫的步驟

在文字編輯器中開啟新檔案。
如有需要，請使用註釋行來描述資源庫。

請使用以下語法定義每個巨集：

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

*macro_body*
END;

將 Oracle GoldenGate 目錄的 dirprm 子目錄中的檔案另存為：
```
*filename*.mac
```
其中：

filename 是檔案的名稱。.mac 副檔名會將檔案定義為巨集程式庫。

下列名為 datelib 的範例程式庫包含兩個巨集：#make_date 與 #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;

若要使用巨集程式庫，請使用參數檔開頭的 INCLUDE 參數，如下列範例 Replicat 參數檔所示。

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

在參數檔中包含長巨集程式庫時，您可以使用 NOLIST 參數來隱藏 Extract 或 Replicat 報表檔案中每個巨集的清單。只要將 LIST 和 NOLIST 參數放在參數檔或巨集程式庫檔案中的任何位置，即可開啟和關閉清單。在以下範例中，NOLIST 會隱藏 hugelib 巨集程式庫中每個巨集的清單。在 INCLUDE 陳述式將一般清單還原為報表檔案之後指定 LIST。

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

追蹤巨集擴充

您可以使用 CMDTRACE 參數追蹤巨集擴充。啟用 CMDTRACE 時，巨集擴充步驟會顯示在 Extract 或 Replicat 報表檔案中。

語法

CMDTRACE [ON | OFF | DETAIL]

其中：

ON 會啟用追蹤。
OFF 會停用追蹤。
DETAIL 會產生巨集擴充的詳細顯示。

在下列範例中，會在呼叫 #testmac 之前啟用追蹤，然後在巨集執行之後停用追蹤。

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