ユーザー・イグジットを使用した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を参照してください。

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

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

1. Cコードで、共有オブジェクト(UNIXシステム)またはDLL(Windows)を作成し、Replicatからコールするルーチンを作成/エクスポートします。このルーチンは、Oracle GoldenGateとユーザー独自のルーチン間の通信ポイントになります。このルーチンに任意の名前を付けます。ルーチンでは、次のOracle GoldenGateユーザー・イグジット・パラメータを受け入れる必要があります。

   • EXIT_CALL_TYPE: 処理中にいつルーチンをコールするかを指定します。

   • EXIT_CALL_RESULT: ルーチンにレスポンスを提供します。

   • EXIT_PARAMS: ルーチンに情報を提供します。この関数を使用すると、TABLE文またはMAP文のEXITPARAMオプションを使用して、リテラル文字列のパラメータをユーザー・イグジットに渡すことができます。これは、特定のレコードを処理するイグジット・コール中にのみ有効です。この関数を使用すると、イグジット・コール起動時にCUSEREXITパラメータのPARAMSオプションで指定されたパラメータを渡すこともできます。

2. ソース・コードで、usrdecs.hファイルをインクルードします。usrdecs.hファイルは、ユーザー・イグジットAPI用のインクルード・ファイルです。型定義、戻りステータス値、コールバック関数コード、および多数の他の定義が含まれます。usrdecs.hファイルは、Oracle GoldenGateディレクトリ内にインストールされます。このファイルは変更しないでください。

3. 必要に応じて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.

1. 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コールバック関数コードがあります。この関数によって、ユーザー・イグジットは、ロケールやコール元プロセス(Extract、データ・ポンプ、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
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バイトの長さ情報 + カラム値

ユーザー・イグジットのアップグレード

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ファイルが含まれます。