ユーザー・イグジットを使用したOracle GoldenGate機能の拡張

ユーザー・イグジットは、Cプログラミング・コードで記述してExtractまたはReplicatの処理中にコールするカスタム・ルーチンです。ユーザー・イグジットによって、複雑さとリスクを最小限に抑えながらExtractプロセスとReplicatプロセスの機能を拡張およびカスタマイズできます。ユーザー・イグジットの使用により、本番プログラムを変更することなく、データベース・イベントの発生時にレスポンスすることができます。

ノート:

CUSEREXITSを使用する場合は、LD_LIBRARY_PATH環境変数を拡張する必要があります。デフォルトでは、$OGG_HOME/libディレクトリはOracle GoldenGateソフトウェア・ホーム・ディレクトリの一部です。これは、意図的にデプロイメント・ディレクトリから分離されています。ユーザー・イグジット関数にその他の共有オブジェクトを追加する必要がある場合は、$OGG_HOME/libディレクトリを使用せず、別の場所を選択することをお薦めします。CUSEREXITSの場合は、LD_LIBRARY_PATH環境変数を拡張して別の場所にする必要があります。

ユーザー・イグジットを実装する場合

ユーザー・イグジットは、Oracle GoldenGate内で使用できる列変換関数のかわりとして、またはそれらと組み合せて使用できます。ユーザー・イグジットは、データを2回(データの抽出時に1回と変換の実行時に1回)処理するかわりに、データの抽出時に1回のみ処理するため、組込み関数の代用として適しています。

ユーザー・イグジットは次の用途で実装できます。

ある表から別の表へのマップ時における算術演算、データ変換または表検索の実行。
レコード・アーカイブ関数のオフライン実装。
通常とは異なるデータベース・イベントに対するカスタム形式でのレスポンス(出力値に基づいて電子メール・メッセージまたは通知を送信するなど)。
合計値の蓄積および統計値の収集。
レコードの操作。
無効なデータの修復。
更新前後のレコードにおける正味の差異の計算。
複雑な基準に基づいた抽出またはレプリケーションのためのレコードの受入れまたは拒否。
変換時のデータベースの正規化。

Oracle GoldenGateレコード情報のルーチンへの使用可能化

ほとんどのユーザー・イグジット処理の基本となるのがEXIT_CALL_PROCESS_RECORD関数です。Extractでは、この関数はレコード・バッファが証跡に出力される直前にコールされます。Replicatでは、これはレコードがターゲットに適用される直前にコールされます。パラメータ・ファイルにソースとターゲットのマッピングが指定されている場合、EXIT_CALL_PROCESS_RECORDイベントはマッピングの実行後に発生します。

EXIT_CALL_PROCESS_RECORDがコールされると、コールバック・ルーチンを通じて、レコード・バッファとその他のレコード情報が利用可能になります。ユーザー・イグジットは、マッピング、変換、クリーンアップ、その他すべての操作をデータ・レコードに対して実行できます。操作が完了したら、ユーザー・イグジットは、ExtractまたはReplicatによってレコードを処理するのか、無視するのかを示すステータスを戻すことができます。

ユーザー・イグジットの作成

次の内容は、WindowsおよびUNIXシステムでユーザー・イグジットを作成する場合に役立ちます。それらの説明に記載されているパラメータや関数の詳細は、Oracle GoldenGateリファレンスfor Windows and UNIXを参照してください。

ノート:

ユーザー・イグジットは、データベース・オブジェクト名の大/小文字を区別します。名前は、ホスト・データベースで定義されたとおりに戻されます。オブジェクト名は完全修飾名である必要があります。

ユーザー・イグジットを作成する手順

Cコードで、共有オブジェクト(UNIXシステム)またはDLL(Windows)を作成し、Extractまたは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);
```
説明:
- function_codeは、コールバック・ルーチンによって実行される関数です。
- bufferは、指定した関数コードに関連付けられた事前定義構造を含むバッファへのvoidポインタです。
- result_codeは、コールバック・ルーチンによって実行される関数のステータスです。コールバック・ルーチンによって戻される結果コードは、コールバック関数が成功したかどうかを示します。
- Windowsシステムでは、ExtractおよびReplicatによって、ユーザー・イグジット・ルーチンからコールされるERCALLBACK関数がエクスポートされます。ユーザー・イグジットでは、適切なWindows APIコールを使用して実行時にコールバック関数を明示的にロードする必要があります。
ExtractまたはReplicatのパラメータ・ファイルにCUSEREXITパラメータを含めます。このパラメータでは、共有オブジェクトまたはDLLの名前と、ExtractまたはReplicatからコールされるエクスポート・ルーチンの名前を使用します。共有オブジェクトまたはDLLのフルパスを指定するか、オペレーティング・システムの標準検索機能を使用して共有オブジェクトの場所を特定できます。
```
CUSEREXIT {DLL | shared_object} routine
[, INCLUDEUPDATEBEFORES]
[, PARAMS 'startup_string']
```
説明:
- DLLはWindows DLLで、shared_objectはユーザー・イグジット関数を含むUNIX共有オブジェクトです。
- INCLUDEUPDATEBEFORESは、UPDATE操作のために変更前イメージを取得します。
- PARAMS 'startup_string'は、起動文字列(起動パラメータなど)を指定します。

例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コールバック関数コードがあります。この関数によって、ユーザー・イグジットは、ロケールやコール元プロセス(Extract、データ・ポンプ、Replicat)と交換する文字型データの文字セットなどのデータベース・メタデータを取得できます。データベースでのオブジェクト名の大/小文字の区別、引用符付きおよび引用符なしの名前の処理およびオブジェクト名の格納方法も返されます。

これらのコンポーネントの詳細は、Oracle GoldenGateリファレンスfor Windows and UNIXを参照してください。

名前のメタデータをチェックするマクロの使用

ユーザー・イグジットAPIによって渡されるオブジェクト名は、ユーザー・イグジット・セッション文字セットでエンコードされた正確な名前で、データベースから取得されたものと完全に同じ名前です。ユーザー・イグジットでオブジェクト名をリテラル文字列と比較する場合、ユーザー・イグジットでデータベースのロケールを取得し、文字列を正規化して同じエンコーディングでオブジェクト名と比較できるようにする必要があります。

Oracle GoldenGateには、ユーザー・イグジットでコールし、データベース・オブジェクト名のメタデータをチェックできる次のマクロが用意されています。たとえば、マクロを使用して、引用符で囲まれた名前で大/小文字が区別されるかどうかや、大/小文字混在でデータベース・サーバーに格納されているかどうかをチェックできます。これらのマクロは、usrdecs.hファイルで定義されています。

表9-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形式コードの意味を、データ型ごとに説明します。

表9-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バイトnullインジケータ + 2バイトの長さ情報 + 列値 0000 0004 61 62 63 20	`ASCII`または`EBCDIC`でエンコードされた"abc"。 `NULL`終端。末尾の空白は切り捨てられます。	ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。 `NOT NULL`終端。 `GLOBALS`パラメータの`NOTRIMSPACES`が指定されていない場合、デフォルトで末尾の空白は切り捨てられます。
`NCHAR` `0061 0062 0063 0020`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値。 0000 0008 00 61 0062 0063 0020	`NCHAR`がUTF-8として処理されるかどうかに応じて、"abc" (`UTF8`でエンコード)または最初のバイトで切捨て。 `NULL`終端。末尾の空白は切り捨てられます。	ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。 `NOT NULL`終端。 `GLOBALS`パラメータの`NOTRIMSPACES`が指定されていない場合、デフォルトで末尾の空白は切り捨てられます。
`VARCHAR2` `"abc"`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`ASCII`または`EBCDIC`でエンコードされた"abc"。 `NULL`終端。切捨てなし。	ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。 `NOT NULL`終端。切捨てなし。
`NVARCHAR2` `0061 0062 0063 0020`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`NVARCHAR2`が`UTF-8`として処理されるかどうかに応じて、"abc" (`UTF8`でエンコード)または最初のバイトで切捨て。 `NULL`終端。切捨てなし。	ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。 `NOT NULL`終端。切捨てなし。
`CLOB`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`VARCHAR2`と同様ですが、最大4Kバイトのみの出力。 `NULL`終端。切捨てなし。	`VARCHAR2`と同様ですが、ユーザー・イグジット・セッションの文字セットでリクエストされたデータのみ出力。 `NOT NULL`終端。切捨てなし。
`NCLOB`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`NVARCHAR2`と同様ですが、最大4Kバイトのみの出力。 `NULL`終端。切捨てなし。	`NVARCHAR2`と同様ですが、ユーザー・イグジット・セッションの文字セットでリクエストされたデータのみ出力。 `NOT NULL`終端。切捨てなし。
`NUMBER` `123.89`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`ASCII`または`EBCDIC`でエンコードされた"123.89"。 `NULL`終端。	ユーザー・イグジット・セッションの文字セットでエンコードされた"123.89"。 `NOT NULL`終端。
`DATE` `31-May-11`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	`ASCII`または`EBCDIC`でエンコードされた"2011-05-31"。 `NULL`終端。	ユーザー・イグジット・セッションの文字セットでエンコードされた"2011-05-31"。 `NOT NULL`終端。
`TIMESTAMP` `31-May-11 12.00.00 AM`	2バイトnullインジケータ + 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バイトnullインジケータ + 2バイトの長さ情報 + 列値	NA	NA
`RAW`	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	2バイトnullインジケータ + 2バイトの長さ情報 + 列値	2バイトnullインジケータ + 2バイトの長さ情報 + 列値

CHAR

"abc"

2バイトnullインジケータ +

2バイトの長さ情報

+ 列値

0000 0004 61 62 63 20

ASCIIまたはEBCDICでエンコードされた"abc"。

NULL終端。

末尾の空白は切り捨てられます。

ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。

NOT NULL終端。

GLOBALSパラメータのNOTRIMSPACESが指定されていない場合、デフォルトで末尾の空白は切り捨てられます。

NCHAR

0061 0062 0063 0020

2バイトnullインジケータ +

2バイトの長さ情報 +

列値。

0000 0008 00 61 0062 0063 0020

NCHARがUTF-8として処理されるかどうかに応じて、"abc" (UTF8でエンコード)または最初のバイトで切捨て。

NULL終端。

末尾の空白は切り捨てられます。

ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。

NOT NULL終端。

GLOBALSパラメータのNOTRIMSPACESが指定されていない場合、デフォルトで末尾の空白は切り捨てられます。

VARCHAR2

"abc"

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

ASCIIまたはEBCDICでエンコードされた"abc"。

NULL終端。

切捨てなし。

ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。

NOT NULL終端。

切捨てなし。

NVARCHAR2

0061 0062 0063 0020

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

NVARCHAR2がUTF-8として処理されるかどうかに応じて、"abc" (UTF8でエンコード)または最初のバイトで切捨て。

NULL終端。

切捨てなし。

ユーザー・イグジット・セッションの文字セットでエンコードされた"abc"。

NOT NULL終端。

切捨てなし。

CLOB

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

VARCHAR2と同様ですが、最大4Kバイトのみの出力。

NULL終端。

切捨てなし。

VARCHAR2と同様ですが、ユーザー・イグジット・セッションの文字セットでリクエストされたデータのみ出力。

NOT NULL終端。

切捨てなし。

NCLOB

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

NVARCHAR2と同様ですが、最大4Kバイトのみの出力。

NULL終端。

切捨てなし。

NVARCHAR2と同様ですが、ユーザー・イグジット・セッションの文字セットでリクエストされたデータのみ出力。

NOT NULL終端。

切捨てなし。

NUMBER

123.89

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

ASCIIまたはEBCDICでエンコードされた"123.89"。

NULL終端。

ユーザー・イグジット・セッションの文字セットでエンコードされた"123.89"。

NOT NULL終端。

DATE

31-May-11

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

ASCIIまたはEBCDICでエンコードされた"2011-05-31"。

NULL終端。

ユーザー・イグジット・セッションの文字セットでエンコードされた"2011-05-31"。

NOT NULL終端。

TIMESTAMP

31-May-11 12.00.00 AM

2バイトnullインジケータ +

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バイトnullインジケータ +

2バイトの長さ情報 +

列値

RAW

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

2バイトnullインジケータ +

2バイトの長さ情報 +

列値

2バイトnullインジケータ +

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ファイルに加え、makefileおよびreadme.txtファイルが含まれます。