使用使用者結束程式擴充 Oracle GoldenGate 功能

使用者出口是您在 C 程式碼中撰寫的自訂常式，並在 Extract 或 Replicat 處理期間呼叫。使用者退出以最小複雜性和風險來擴充和自訂 Extract 和 Replicat 處理作業的功能。使用使用者退出時，您可以在發生資料庫事件時回應，而不需更改生產程式。

注意：如果您使用 CUSEREXITS，則必須擴充 LD_LIBRARY_PATH 環境變數。依照預設，$OGG_HOME/lib 目錄是 Oracle GoldenGate 軟體本位目錄的一部分。它是依設計與 Deployment 目錄分隔的。如果需要為「使用者結束」函數新增其他共用物件，則建議您不要使用 $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 時，記錄緩衝區和其他記錄資訊可透過回呼常式使用。使用者出口程式可以對應、轉換、清除或執行資料記錄的任何其他作業。完成後，使用者出口程式可傳回狀態，指出擷取或 Replicat 是否應處理或忽略記錄。

建立使用者退出

下列指示可協助您在 Windows 和 UNIX 系統上建立使用者出口。如需有關這些指示中描述之參數和函數的詳細資訊，請參閱Oracle GoldenGate for Windows and UNIX 的參照。

注意：資料庫物件名稱的使用者結束會區分大小寫。名稱的傳回與在代管資料庫中定義的完全相同。物件名稱必須完整。

建立使用者退出

在 C 程式碼中，建立共用物件 (UNIX 系統) 或 DLL (Windows)，並建立或匯出要從 Replicat 呼叫的常式。此常式是 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 的名稱，以及要從 Replicat 呼叫的匯出常式名稱。您可以指定共用物件或 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 回呼函數代碼。此功能可讓使用者退出程式取得資料庫中繼資料，例如與呼叫資料庫中之處理交換的字元類型資料之地區設定與字元集 (擷取、資料汲取、Replicat)。它也會傳回資料庫如何處理物件名稱的區分大小寫、如何處理引號和未引號的名稱，以及如何儲存物件名稱。

如需有關這些元件的詳細資訊，請參閱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 位元組長度資訊 + 欄值	"2011-05-31 12.00.00 AM" 編碼為 `ASCII` 或 `EBCDIC`。 `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 位元組長度資訊 +

欄值

"2011-05-31 12.00.00 AM" 編碼為 ASCII 或 EBCDIC。

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 版本中新增增強功能或升級 (例如新函數或結構變更) 時，允許與現有使用者存在的回溯相容性。usrdecs.h 檔案的版本會在啟動 Replicat 或 Extract 時列印在報表檔案中。

若要使用新的使用者結束功能，您必須重新編譯常式以包含新的 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 檔案、make 檔案以及 readme.txt 檔案。