使用 Oracle GoldenGate 宏简化和自动化工作

您可以使用参数文件中的 Oracle GoldenGate 宏来配置和重用参数、命令和转换函数。减少执行常见任务时必须输入的文本量。宏是内置的自动化工具，可用于从 Oracle GoldenGate 参数文件中调用存储的一组处理步骤。宏可以由一组简单的常用参数语句组成，这些语句用于复杂的一系列参数替换、计算或转换。您可以从宏调用其他宏。您可以将常用宏存储在库中，然后调用库，而不是单独调用宏。

Oracle GoldenGate 宏使用以下参数文件：

DEFGEN
提取
复制

使用宏有两个步骤：

定义宏
调用宏

定义宏

要定义 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` 无效。如果需要，可以使用 Parameters and Functions Reference for Oracle GoldenGate 中的 `MACROCHAR` 参数更改宏字符。宏和参数名称不区分大小写。引号内的宏或参数名称将被忽略。
PARAMS (#`p1`, #`p2`)	输入参数的可选定义。指定参数名称的逗号分隔列表，并将其括在括号中。必须在要替换输入值的宏主体中引用每个参数。您可以将每个参数列在一个单独的行上以提高可读性（确保使用左括号和右括号将参数列表括起来）。有关更多信息，请参见 Call a Macro that Contains Parameters 。
BEGIN	开始宏正文。必须在宏正文之前指定。
`macro_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`。
`(` val`[, ...]`)	参数输入值。无论宏是否定义参数，此组件都是必需的。如果宏定义参数，请按与 `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 语句中未显示参数名称，则宏处理器将评估项是否是另一个宏的调用。（请参见 Calling Other Macros from a Macro 。）如果调用成功，将执行嵌套宏。如果失败，则整个宏将失败。

示例 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 参数，如以下复制参数文件样例中所示。

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

在参数文件中包括长宏库时，可以使用 NOLIST 参数隐藏提取或复制报告文件中的每个宏的列表。可以通过将 LIST 和 NOLIST 参数放置在参数文件或宏库文件中的任意位置来打开和关闭列表。在以下示例中，NOLIST 禁止 hugelib 宏库中每个宏的列表。在 INCLUDE 语句后指定 LIST 将恢复报表文件的正常列表。

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

跟踪宏扩展

可以使用 CMDTRACE 参数跟踪宏扩展。启用 CMDTRACE 后，宏扩展步骤将显示在提取或复制报告文件中。

语法

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>