使用用户出口扩展 Oracle GoldenGate 功能

用户出口是在提取或复制处理期间在 C 编程代码中编写和调用的自定义例程。用户出口扩展和定制提取和复制流程的功能，同时降低复杂性和风险。用户退出时，您可以在发生数据库事件时响应这些事件，而无需更改生产程序。

注：如果使用 CUSEREXITS，则需要扩展 LD_LIBRARY_PATH 环境变量。缺省情况下，$OGG_HOME/lib 目录是 Oracle GoldenGate 软件主目录的一部分。它通过设计与部署目录分离。如果需要为用户出口函数添加其他共享目标文件，则建议不要使用 $OGG_HOME/lib 目录并选择其他位置。对于 CUSEREXITS，必须将 LD_LIBRARY_PATH 环境变量扩展到其他位置。

何时实施用户出口

您可以使用用户出口替代 Oracle GoldenGate 中提供的列转换函数，也可以将其与之结合使用。用户出口可以更好地替代内置函数，因为用户出口仅处理一次数据（提取数据时），而不是两次（提取数据时和执行转换时）。

下面是一些可以实现用户出口的方法：

在从一个表映射至另一个表时执行算术运算、日期转换或表查找。
离线实施记录归档功能。
以自定义方式响应异常数据库事件，例如发送电子邮件或基于输出值的页面。
累计总计并收集统计信息。
处理记录。
修复无效数据。
计算更新前后的记录净差异。
根据复杂标准接受或拒绝提取或复制的记录。
在转换过程中对数据库进行规范化。

使 Oracle GoldenGate 记录信息可供例程使用

大多数用户出口处理的基础是 EXIT_CALL_PROCESS_RECORD 函数。对于 Extract，此函数仅在记录缓冲区输出到线索之前调用。对于 Replicat，仅在将记录应用于目标之前调用它。如果在参数文件中指定了源 - 目标映射，则 EXIT_CALL_PROCESS_RECORD 事件将在执行映射后发生。

调用 EXIT_CALL_PROCESS_RECORD 时，可通过回调例程向其提供记录缓冲区和其他记录信息。用户出口可以映射、转换、清除或对数据记录执行任何其他操作。完成后，用户出口可以返回状态，指示应由提取或复制处理还是忽略记录。

创建用户出口

以下说明可帮助您创建 Windows 和 UNIX 系统上的用户出口。有关这些说明中介绍的参数和函数的更多信息，请参见 Reference for Oracle GoldenGate for Windows and UNIX 。

注：用户出口对数据库对象名称区分大小写。返回的名称与托管数据库中定义的名称完全相同。对象名称必须完全限定。

创建用户出口

在 C 代码中，创建共享对象（UNIX 系统）或 DLL (Windows) 并创建或导出要从复制调用的例程。此例程是 Oracle GoldenGate 与您的例程之间的通信点。命名您想要的任何例程。例程必须接受以下 Oracle GoldenGate 用户出口参数：
- EXIT_CALL_TYPE：指示在处理期间何时调用例程。
- EXIT_CALL_RESULT：提供对例程的响应。
- EXIT_PARAMS：向例程提供信息。使用此函数，可以使用 TABLE 或 MAP 语句的 EXITPARAM 选项将文本字符串的参数传递给用户出口。这仅在执行退出调用以处理特定记录期间有效。此函数还允许您在退出调用启动时传递使用 CUSEREXIT 参数的 PARAMS 选项指定的参数。
在源代码中，包括 usrdecs.h 文件。usrdecs.h 文件是用户出口 API 的包含文件。它包含类型定义、返回状态值、回调函数代码以及许多其他定义。usrdecs.h 文件安装在 Oracle GoldenGate 目录中。请勿修改此文件。
在用户出口中包括 Oracle GoldenGate 回调例程（如果适用）。回调例程检索记录和应用程序上下文信息，并修改数据记录的内容。要实现回调例程，请在共享对象中使用 ERCALLBACK 函数。根据传递到回调例程的函数代码，用户回调例程的行为有所不同。

ERCALLBACK (*function_code*, *buffer*, *result_code*);

Where:

- *function_code* is the function to be executed by the callback routine.

- *buffer* is a void pointer to a buffer containing a predefined structure associated with the specified function code.

- *result_code* is the status of the function that is executed by the callback routine. The result code that is returned by the callback routine indicates whether or not the callback function was successful.

- On Windows systems, Replicat export the `ERCALLBACK` function that is to be called from the user exit routine. The user exit must explicitly load the callback function at run-time using the appropriate Windows API calls.

在 Replicat 参数文件中包括 CUSEREXIT 参数。此参数接受共享对象或 DLL 的名称以及要从复制中调用的已导出例程的名称。您可以指定共享对象或 DLL 的完整路径，也可以让操作系统的标准搜索策略找到共享对象。

CUSEREXIT {*DLL* | *shared_object*} *routine*
[, INCLUDEUPDATEBEFORES]
[, PARAMS '*startup_string*']

Where:

- *DLL* is a Windows DLL and *shared_object* is a UNIX shared object that contains the user exit function.

- `INCLUDEUPDATEBEFORES` gets before images for `UPDATE` operations.

- `PARAMS `*'startup_string'* supplies a startup string, such as a startup parameter.

示例 9-41 UNIX 基本语法示例

CUSEREXIT eruserexit.so MyUserExit

示例 9-42:Windows 基本语法示例

CUSEREXIT eruserexit.dll MyUserExit

在用户出口中支持字符集转换

为了维护数据完整性，用户出口需要了解其与 Oracle GoldenGate 进程交换的字符类型数据的字符集。Oracle GoldenGate 用户退出逻辑提供以下方面的全球化支持：

基于字符的数据库元数据，例如目录、方案、表和列的名称
字符类型列的值，例如 CHAR、VARCHAR2、CLOB、NCHAR、NVARCHAR2 和 NCLOB，以及基于字符串的数字、日期时间和间隔。

通过在字符集之间正确转换，可以将列数据从一种类型的数据库和字符集正确地进行比较、处理、转换和映射。当调用 EXIT_CALL_PROCESS_RECORD 调用类型并且通过回调例程提供记录缓冲区和其他记录信息时，将执行大部分此处理。

用户出口有自己的会话字符集。这由 GET_SESSION_CHARSET 和 SET_SESSION_CHARSET 回调函数定义。如果用户出口的字符集与进程的托管上下文不同，调用方进程将提供字符集之间的转换。

要在用户出口中启用此支持，需要有 GET_DATABASE_METADATA 回调函数代码。此函数允许用户出口获取数据库元数据，例如它与调用它的进程（提取、数据泵、复制）交换的字符类型数据的区域设置和字符集。它还返回数据库如何处理对象名称的大小写敏感性、如何处理带引号和不带引号的名称以及如何存储对象名称。

有关这些组件的更多信息，请参见 Reference for Oracle GoldenGate for Windows and UNIX 。

使用宏检查名称元数据

用户出口 API 传递的对象名称是用用户出口会话字符集编码的确切名称，并且与从数据库中检索到的名称完全相同。如果用户出口将对象名称与文字字符串进行比较，则用户出口必须检索数据库区域设置，然后对字符串进行规范化，以便以相同的编码将其与对象名称进行比较。

Oracle GoldenGate 提供了以下宏，用户出口可以调用这些宏来检查数据库对象名称的元数据。例如，可以使用宏检查带引号的表名称是否区分大小写，以及它是否作为混合大小写存储在数据库服务器中。这些宏在 usrdecs.h 文件中定义。

表 20 中用于元数据检查的宏

宏	验证内容
`supportsMixedCaseIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的不带引号的混合名称视为区分大小写，并将名称存储为混合大小写。
`supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )`	数据库是否将指定数据类型的混合引号名称视为区分大小写，并将名称存储为混合大小写。
`storesLowerCaseIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的大小写不带引号的混合名称视为不区分大小写，并将名称存储为小写。
`storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的混合引号名称视为不区分大小写，并将名称存储为小写。
`storesMixedCaseIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的混合大小写不带引号的名称视为不区分大小写，并将名称存储为混合大小写。
`storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的混合引号名称视为不区分大小写，并将名称存储为混合大小写。
`storesUpperCaseIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的大小写不带引号的混合名称视为不区分大小写，并将名称存储为大写。
`storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )`	数据库是否将指定数据类型的混合引号名称视为不区分大小写，并将名称存储为大写。

描述字符格式

输入参数 column_value_mode 描述正在处理并在多个函数代码中使用的数据的字符格式。下表说明每个数据类型的 EXIT_FN_RAW_FORMAT、EXIT_FN_CHAR_FORMAT 和 EXIT_FN_CNVTED_SESS_FORMAT 格式代码的含义。

表 21 column_value_mode_matrix 含义

数据类型 EXIT_FN_RAW_FORMAT EXIT_FN_CHAR_FORMAT EXIT_FN_CNVTED_SESS_FORMAT

数据类型	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
`CHAR` `"abc`"	2 字节空指示符 + 2 字节长度信息 + 列的值 0000 0004 61 62 63 20	以 `ASCII` 或 `EBCDIC` 编码的 "abc"。 `NULL` 已终止。尾部空间被修剪。	以用户出口会话字符集编码的 "abc"。 `NOT NULL` 已终止。缺省情况下，除非指定了 `GLOBALS` 参数 `NOTRIMSPACES`，否则尾部空格会被修剪。
`NCHAR` `0061 0062 0063 0020`	2 字节空指示符 + 2 字节长度信息 + 列的值。 0000 0008 00 61 0062 0063 0020	"abc"（在 `UTF8` 中编码）或在第一个字节处被截断，具体取决于 `NCHAR` 是否被视为 UTF-8。 `NULL` 已终止。尾随空格被修剪。	以用户出口会话字符集编码的 "abc"。 `NOT NULL` 已终止。缺省情况下，除非指定了 `GLOBALS` 参数 `NOTRIMSPACES`，否则尾部空格会被修剪。
`VARCHAR2` `"abc"`	2 字节空指示符 + 2 字节长度信息 + 列的值	以 `ASCII` 或 `EBCDIC` 编码的 "abc"。 `NULL` 已终止。没有修剪。	以用户出口会话字符集编码的 "abc"。 `NOT NULL` 已终止。没有修剪。
`NVARCHAR2` `0061 0062 0063 0020`	2 字节空指示符 + 2 字节长度信息 + 列的值	"abc"（在 `UTF8` 中编码）或在第一个字节处被截断，具体取决于 `NVARCHAR2` 是否被视为 `UTF-8`。 `NULL` 已终止。没有修剪。	在用户出口会话字符集中编码 "abc"。 `NOT NULL` 已终止。没有修剪。
`CLOB`	2 字节空指示符 + 2 字节长度信息 + 列的值	类似于 `VARCHAR2`，但输出最多为 4K 字节。 `NULL` 已终止。没有修剪。	与 `VARCHAR2` 类似，但仅输出用户出口会话字符集中请求的输出数据。 `NOT NULL` 已终止。没有修剪。
`NCLOB`	2 字节空指示符 + 2 字节长度信息 + 列的值	与 `NVARCHAR2` 类似，但输出最多为 4K 字节。 `NULL` 已终止。没有修剪。	与 `NVARCHAR2` 类似，但仅输出用户出口会话字符集中请求的输出数据。 `NOT NULL` 已终止。没有修剪。
`NUMBER` `123.89`	2 字节空指示符 + 2 字节长度信息 + 列的值	以 `ASCII` 或 `EBCDIC` 编码的 "123.89"。 `NULL` 已终止。	以用户出口会话字符集编码的 "123.89"。 `NOT NULL` 已终止。
`DATE` `31-May-11`	2 字节空指示符 + 2 字节长度信息 + 列的值	以 `ASCII` 或 `EBCDIC` 编码的 "2011-05-31"。 `NULL` 已终止。	以用户出口会话字符集编码的 "2011-05-31"。 `NOT NULL` 已终止。
`TIMESTAMP` `31-May-11 12.00.00 AM`	2 字节空指示符 + 2 字节长度信息 + 列的值	以 `ASCII` 或 `EBCDIC` 编码的 "2011-05-31 12.00.00 AM"。 `NULL` 已终止。	以用户出口会话字符集编码的 "2011-05-31 12.00.00 AM"。 `NOT NULL` 已终止。
`Interval Year to Month or Interval Day to Second`	2 字节空指示符 + 2 字节长度信息 + 列的值	不适用	不适用
`RAW`	2 字节空指示符 + 2 字节长度信息 + 列的值	2 字节空指示符 + 2 字节长度信息 + 列的值	2 字节空指示符 + 2 字节长度信息 + 列的值

CHAR

"abc"

2 字节空指示符 +

2 字节长度信息

+ 列的值

0000 0004 61 62 63 20

以 ASCII 或 EBCDIC 编码的 "abc"。

NULL 已终止。

尾部空间被修剪。

以用户出口会话字符集编码的 "abc"。

NOT NULL 已终止。

缺省情况下，除非指定了 GLOBALS 参数 NOTRIMSPACES，否则尾部空格会被修剪。

NCHAR

0061 0062 0063 0020

2 字节空指示符 +

2 字节长度信息 +

列的值。

0000 0008 00 61 0062 0063 0020

"abc"（在 UTF8 中编码）或在第一个字节处被截断，具体取决于 NCHAR 是否被视为 UTF-8。

NULL 已终止。

尾随空格被修剪。

以用户出口会话字符集编码的 "abc"。

NOT NULL 已终止。

缺省情况下，除非指定了 GLOBALS 参数 NOTRIMSPACES，否则尾部空格会被修剪。

VARCHAR2

"abc"

2 字节空指示符 +

2 字节长度信息 +

列的值

以 ASCII 或 EBCDIC 编码的 "abc"。

NULL 已终止。

没有修剪。

以用户出口会话字符集编码的 "abc"。

NOT NULL 已终止。

没有修剪。

NVARCHAR2

0061 0062 0063 0020

2 字节空指示符 +

2 字节长度信息 +

列的值

"abc"（在 UTF8 中编码）或在第一个字节处被截断，具体取决于 NVARCHAR2 是否被视为 UTF-8。

NULL 已终止。

没有修剪。

在用户出口会话字符集中编码 "abc"。

NOT NULL 已终止。

没有修剪。

CLOB

2 字节空指示符 +

2 字节长度信息 +

列的值

类似于 VARCHAR2，但输出最多为 4K 字节。

NULL 已终止。

没有修剪。

与 VARCHAR2 类似，但仅输出用户出口会话字符集中请求的输出数据。

NOT NULL 已终止。

没有修剪。

NCLOB

2 字节空指示符 +

2 字节长度信息 +

列的值

与 NVARCHAR2 类似，但输出最多为 4K 字节。

NULL 已终止。

没有修剪。

与 NVARCHAR2 类似，但仅输出用户出口会话字符集中请求的输出数据。

NOT NULL 已终止。

没有修剪。

NUMBER

123.89

2 字节空指示符 +

2 字节长度信息 +

列的值

以 ASCII 或 EBCDIC 编码的 "123.89"。

NULL 已终止。

以用户出口会话字符集编码的 "123.89"。

NOT NULL 已终止。

DATE

31-May-11

2 字节空指示符 +

2 字节长度信息 +

列的值

以 ASCII 或 EBCDIC 编码的 "2011-05-31"。

NULL 已终止。

以用户出口会话字符集编码的 "2011-05-31"。

NOT NULL 已终止。

TIMESTAMP

31-May-11 12.00.00 AM

2 字节空指示符 +

2 字节长度信息 +

列的值

以 ASCII 或 EBCDIC 编码的 "2011-05-31 12.00.00 AM"。

NULL 已终止。

以用户出口会话字符集编码的 "2011-05-31 12.00.00 AM"。

NOT NULL 已终止。

Interval Year to Month or Interval Day to Second

2 字节空指示符 +

2 字节长度信息 +

列的值

不适用

RAW

2 字节空指示符 +

2 字节长度信息 +

列的值

2 字节空指示符 +

2 字节长度信息 +

列的值

2 字节空指示符 +

2 字节长度信息 +

列的值

升级用户出口

usrdecs.h 文件的版本化允许在将增强或升级（例如新功能或结构更改）添加到新的 Oracle GoldenGate 发行版时与现有用户出口向后兼容。在启动 Replicat 或 Extract 时，usrdecs.h 文件的版本将打印在报告文件中。

要使用新的用户出口功能，必须重新编译例程以包括新的 usrdecs 文件。不使用新功能的例程不需要重新编译。

查看如何使用用户出口函数的示例

Oracle GoldenGate 将以下样例用户出口文件安装到 Oracle GoldenGate 安装目录的 UserExitExamples 目录中：

exitdemo.c 显示了如何初始化用户出口、在给定出口点发出回调以及修改数据。还演示了如何检索全限定表名或特定元数据部分，例如目录或容器的名称、方案或仅检索不限定表名。此外，此演示还说明了如何处理 DDL 数据。演示不特定于任何数据库类型。
exitdemo_utf16.c 显示如何在回调结构中使用 UTF16 编码的数据（元数据和列数据）来交换用户出口和调用方进程之间交换的信息。
exitdemo_more_recs.c 显示了如何多次使用同一输入记录来生成多个目标记录的示例。
exitdemo_lob.c 显示了如何获取对 LOB 数据的读取访问权限的示例。
exitdemo_pk_befores.c 显示了如何访问主键更新记录的映像部分之前和之后以及常规更新（非键更新）的映像。它还显示了如何在 Replicat 参数文件中获取目标行值 SQLEXEC 作为冲突检测手段。从目标中提取的结果值在进入用户出口时映射为目标记录。

每个目录都包含 *.c 文件以及 makefile 和 readme.txt 文件。