6 ユーザー・イグジット・ファンクション

この章では、Oracle GoldenGateユーザー・イグジット・ファンクションとその構文について説明し、次のトピックを含みます。

6.1項「ユーザー・イグジットのコール」
6.2項「ユーザー・イグジット・ファンクションの概要」
6.3項「EXIT_CALL_TYPEの使用」
6.4項「EXIT_CALL_RESULTの使用」
6.5項「EXIT_PARAMSの使用
6.6項「ERCALLBACKの使用
6.7項「ファンクション・コード」

Oracle GoldenGateの使用の詳細は、Oracle GoldenGateの管理for Windows and UNIXを参照してください。

6.1 ユーザー・イグジットのコール

Cプログラミング・コードでユーザー・イグジットを記述します。CUSEREXITパラメータを使用して、Oracle GoldenGateプロセス内の定義済イグジット・ポイントで、Windows DLLまたはUNIX共有オブジェクトから、ユーザー・イグジットをコールします。ユーザー・イグジット・ルーチンは、ExtractおよびReplicatプロセスから様々なイベントおよび情報を受け入れ、リクエストどおりに情報を処理し、コール元(このルーチンをコールしたOracle GoldenGateプロセス)にレスポンスと情報を返す必要があります。CUSEREXITパラメータの情報および構文は、「CUSEREXIT」を参照してください。

6.2 ユーザー・イグジット・ファンクションの概要

パラメータ	説明
`EXIT_CALL_TYPE`	処理中にいつルーチンをコールするかを指定します。
`EXIT_CALL_RESULT`	ルーチンにレスポンスを提供します。
`EXIT_PARAMS`	ルーチンに情報を提供します。
`ERCALLBACK`	コールバック・ルーチンを実装します。コールバック・ルーチンは、レコードおよびOracle GoldenGateコンテキスト情報を取得して、データ・レコードの内容を変更します。

6.3 EXIT_CALL_TYPEの使用

EXIT_CALL_TYPEでは、処理中にいつExtractまたはReplicatプロセス(コール元)がユーザー・イグジット・ルーチンをコールするかを指定します。プロセスは、次のコールを使用してルーチンをコールできます。

表6-1 ユーザー・イグジット・コール

コール・タイプ	処理ポイント
`EXIT_CALL_ABORT_TRANS`	`RECOVERYOPTIONS`モードが`APPEND` (デフォルト)の場合に有効です。データ・ポンプまたはReplicatがトレイルから`RESTART ABEND`レコードを読み取る際にコールされ、異常終了したライター・プロセスによってそこに配置されます。(ライター・プロセスは、データ・ポンプにより読み取られたローカル・トレイルに書き込むプライマリExtract、またはReplicatにより読み取られたリモート・トレイルに書き込むデータ・ポンプになります。)このコール・タイプによって、ユーザー・イグジットは、ライター・プロセスの停止時に未完了のままのトランザクションを中止または破棄し、以前に完了したトランザクションの開始時の処理をリカバリおよび再開できます。
`EXIT_CALL_BEGIN_TRANS`	次のいずれかの直前にコールされます。データ・ポンプにより読み取られるトランザクションの`BEGIN`レコード Replicatトランザクションの開始
`EXIT_CALL_CHECKPOINT`	ExtractまたはReplicatチェックポイントが書き込まれた直後にコールされます。
`EXIT_CALL_DISCARD_ASCII_RECORD`	Extractの処理中に、ASCII入力レコードが破棄ファイルに書き込まれる前にコールされます。関連するASCIIバッファは、コールバック・ルーチンを使用してユーザー・イグジットによって取得および操作できます。このコール・タイプは、Replicatプロセスでは使用できません。
`EXIT_CALL_DISCARD_RECORD`	Replicatの処理中に、レコードが破棄ファイルに書き込まれる前にコールされます。レコードは、Oracle GoldenGate変更レコードの値がターゲット表の現在のバージョンと異なっているときなど、複数の理由で破棄されます。関連する破棄バッファは、コールバック・ルーチンを使用してユーザー・イグジットによって取得および操作できます。このコール・タイプは、Extractプロセスでは使用できません。
`EXIT_CALL_END_TRANS`	次のいずれかの直後にコールされます。データ・ポンプにより読み取られるトランザクションの`END`レコード Replicatトランザクションの最後のレコード
`EXIT_CALL_FATAL_ERROR`	ExtractまたはReplicatの処理中に致命的なエラーが発生後、Oracle GoldenGateが停止する直前にコールされます。
`EXIT_CALL_PROCESS_MARKER`	Replicatの処理中に、NonStopサーバーのマーカーがトレイルから読み取られ、マーカー履歴ファイルに書き込まれる前にコールされます。
`EXIT_CALL_PROCESS_RECORD`	Extractの場合は、レコード・バッファがトレイルに出力される前にコールされます。 Replicatの場合は、レプリケートされた操作が実行される直前にコールされます。このコールは、ほとんどのユーザー・イグジット処理の基盤です。`EXIT_CALL_PROCESS_RECORD`がコールされると、コールバック・ルーチンを通じて、ユーザー・イグジットでレコード・バッファとその他のレコード情報が利用可能になります。ソースとターゲットのマッピングがパラメータ・ファイルで指定されている場合、マッピングは`EXIT_CALL_PROCESS_RECORD`イベントが発生する前に実行されます。ユーザー・イグジットは、レコード内の他のすべての操作を、マップ、変換、削除、または実行できます。ユーザー・イグジットは、コール元がレコードを処理または無視する必要があるかを示すステータスを返すことができます。ユーザー・イグジットが`PASSTHRU`モードで構成されたデータ・ポンプExtractに使用される場合、ユーザー・イグジットは`EXIT_CALL_PROCESS_RECORD`コールを受け取りません。結果として、ユーザー・イグジットはDDLおよびDML操作にアクセスできません。DDL操作は必ず`PASSTHRU`モードのデータ・ポンプExtractによって処理され、DDLはまったく処理できません。データ・ポンプが`NOPASSTHRU`モードで構成されている場合(DMLのデフォルト)、ユーザー・イグジットはDML操作に対する`EXIT_CALL_PROCESS_RECORD`コールのみ受け取ります。詳細は、「PASSTHRU \| NOPASSTHRU」を参照してください。
`EXIT_CALL_START`	処理開始時にコールされます。ユーザー・イグジットは、ファイルのオープンや変数の初期化などの初期化作業を実行できます。
`EXIT_CALL_STOP`	プロセスが正常に停止または異常終了する前にコールされます。ユーザー・イグジットは、ファイルのクローズや合計の出力などの完了作業を実行できます。
`EXIT_CALL_RESULT`	各イグジット・コールの完了時に、コール元にレスポンス方法を指示するためにユーザー・イグジット・ルーチンによって設定されます。

6.4 EXIT_CALL_RESULTの使用

EXIT_CALL_RESULTでは、ルーチンにレスポンスを提供します。

表6-2 ユーザー・イグジット・レスポンス

コール結果	説明
`EXIT_ABEND_VAL`	コール元に即座に停止するように指示します。
`EXIT_IGNORE_VAL`	レコードのそれ以上の処理を拒否します。`EXIT_IGNORE_VAL`は、ユーザー・イグジットが特定のレコードに必要なすべての処理を実行し、データ・レコードの出力やレプリケートが必要ないときに適切です。
`EXIT_OK_VAL`	ルーチンがイベントに対して何も実行しない場合は、`EXIT_OK_VAL`とみなされます。イグジット・コール・タイプが次のいずれかの場合 `EXIT_CALL_PROCESS_RECORD` `EXIT_CALL_DISCARD_RECORD` `EXIT_CALL_DISCARD_ASCII_RECORD` ... かつ`EXIT_OK_VAL`が返される場合、Oracle GoldenGateはユーザー・イグジットから返されたレコード・バッファを処理します。
`EXIT_PROCESSED_REC_VAL`	ExtractまたはReplicatに、レコードをスキップし、レポート・ファイルに出力される統計の該当する表および操作タイプを更新するように指示します。
`EXIT_STOP_VAL`	コール元に処理を正常に停止するように指示します。`EXIT_STOP_VAL`または`EXIT_ABEND_VAL`は、ユーザー・イグジットでエラー状態が発生したときに適切です。

6.5 EXIT_PARAMSの使用

EXIT_PARAMSでは、ユーザー・イグジット・ルーチンにプログラム名やユーザー定義パラメータなどの情報を提供します。単一のデータ・レコードを複数回処理できます。

表6-3 ユーザー・イグジット入力

イグジット・パラメータ	説明
`PROGRAM_NAME`	コール元プロセスの完全パスおよび名前を指定します(`\ggs\extract`や`\ggs\replicat`など)。このパラメータは、Windows APIを使用してOracle GoldenGateコールバック・ルーチンをロードするときや、ユーザー・イグジットがExtractおよびReplicat両方の処理で使用されているときに、コール元プログラムを特定するために使用します。
`FUNCTION_PARAM`	リテラル文字列のパラメータをユーザー・イグジットに渡すために使用します。パラメータを渡す側である`TABLE`または`MAP`文の`EXITPARAM`オプションでパラメータを指定します。「`EXITPARAM 'parameter'`」を参照してください。これは、特定のレコードを処理するイグジット・コール中にのみ有効です。 `FUNCTION_PARAM`は、`CUSEREXIT`パラメータの`PARAMS`オプションで指定されているパラメータを渡すために、イグジット・コール起動イベントでも使用できます。(「CUSEREXIT」を参照してください。)これは、イグジットの起動時にグローバル・パラメータを提供するためにのみ有効です。
`MORE_RECS_IND`	イグジットからのリターンに対して設定します。データベース・レコードに対して、ExtractまたはReplicatプロセスがレコードをもう一度処理するかどうかを決定します。これにより、EnscribeをSQLに変換する(データ正規化)ときの一般的なファンクションで、ユーザー・イグジットはExtractによって処理される各レコードに対して多くのレコードを出力できます。同一のレコードをもう一度リクエストするには、`MORE_RECS_IND`を`CHAR_NO_VAL`または`CHAR_YES_VAL`に設定します。

6.6 ERCALLBACKの使用

ERCALLBACKでは、コールバック・ルーチンを実行します。ユーザー・コールバック・ルーチンは、ExtractまたはReplicatプロセスからコンテキスト情報を取得し、コール・タイプが次のいずれかのときにレコード自体を含むコンテキスト値を設定します。

EXIT_CALL_PROCESS_RECORD
EXIT_CALL_DISCARD_RECORD
EXIT_CALL_DISCARD_ASCII_RECORD

構文

ERCALLBACK (function_code, buffer, result_code );

function_code: コールバック・ルーチンによって実行されるファンクション。ユーザー・コールバック・ルーチンは、コールバック・ルーチンに渡されるファンクション・コードに基づいて異なる動作をします。一部のファンクションは、ExtractおよびReplicat両方が使用できますが、各プロセスでのファンクションの有効性は、コールバック・ルーチン中にそのファンクションに対して設定される入力パラメータに依存します。使用可能なファンクション・コードの詳細は、6.7項「ファンクション・コード」を参照してください。
buffer: 指定するファンクション・コードに関連付けられている事前定義済構造体を含むバッファへのvoidポインタ。
result_code: コールバック・ルーチンによって実行されるファンクションのステータス。コールバック・ルーチンによって返される結果コードは、コールバック・ファンクションが成功したかどうかを示します。結果コードは、表6-4の値の1つになります。

表6-4 結果コード

コード	説明
`EXIT_FN_RET_BAD_COLUMN_DATA`	列データを取得または設定中に無効なデータを検出しました。
`EXIT_FN_RET_BAD_DATE_TIME`	列`of`の日付、タイムスタンプまたは間隔タイプに、無効な日付または時刻の値が含まれています。
`EXIT_FN_RET_BAD_NUMERIC_VALUE`	列の数値タイプに、無効な数値が含まれています。
`EXIT_FN_RET_COLUMN_NOT_FOUND`	圧縮更新レコードで列が見つかりませんでした(変更された値のみを記録するデータベースによる更新)。
`EXIT_FN_RET_ENV_NOT_FOUND`	指定された環境値がレコードに見つかりませんでした。
`EXIT_FN_RET_EXCEEDED_MAX_LENGTH`	表または列名が割り当てられたバッファに収まらなかったため、メタデータを取得できませんでした。
`EXIT_FN_RET_FETCH_ERROR`	レコードをフェッチできませんでした。エラー・メッセージを表示して理由を確認してください。
`EXIT_FN_RET_INCOMPLETE_DDL_REC`	DDLレコードの処理中に内部エラーが発生しました。レコードが不完全の可能性があります。
`EXIT_FN_RET_INVALID_CALLBACK_FNC_CD`	無効なコールバック・ファンクション・コードがコールバック・ルーチンに渡されました。
`EXIT_FN_RET_INVALID_COLUMN`	ファンクション・コールで、存在しない列が参照されました。
`EXIT_FN_RET_INVALID_COLUMN_TYPE`	ルーチンは、その目的ではOracle GoldenGateにサポートされていないデータ型を操作しようとしています。
`EXIT_FN_RET_INVALID_CONTEXT`	コールバック・ファンクションが不適切なときにコールされました。
`EXIT_FN_RET_INVALID_PARAM`	無効なパラメータがコールバック・ファンクションに渡されました。
`EXIT_FN_RET_NO_SRCDB_INSTANCE`	ソース・データベース・インスタンスが見つかりませんでした。
`EXIT_FN_RET_NO_TGTDB_INSTANCE`	ターゲット・データベース・インスタンスが見つかりませんでした。
`EXIT_FN_RET_NOT_SUPPORTED`	このファンクションは、このプロセスに対してサポートされていません。
`EXIT_FN_RET_OK`	コールバック・ファンクションは成功しました。
`EXIT_FN_RET_SESSION_CS_CNV_ERR`	キャラクタ・セット変換ルーチンに`ULIB_ERR_INVALID_CHAR_FOUND`エラーが返されました。変換は失敗しました。
`EXIT_FN_RET_TABLE_NOT_FOUND`	無効な表名が指定されました。
`EXIT_FN_RET_TOKEN_NOT_FOUND`	指定されたトークンがレコードに見つかりませんでした。

6.7 ファンクション・コード

ファンクション・コードは、コールバック・ルーチンの出力を決定します。コールバック・ルーチンは、データ・バッファの内容が指定されたファンクション・コードの構造体と一致するとみなします。コールバック・ルーチン・ファンクション・コードとそのデータ・バッファは、次の項で説明します。次に、使用可能なファンクションの概要を示します。

表6-5 Oracle GoldenGateファンクション・コードの概要

ファンクション・コード	説明
`COMPRESS_RECORD`	`COMPRESS_RECORD`ファンクションは、マッピングの後にターゲット表の列がすべてでなく一部のみ存在する場合で、個々の列値ではなくレコード全体を操作する必要があるときに使用します。
`DECOMPRESS_RECORD`	`DECOMPRESS_RECORD`ファンクションは、マッピングの後にターゲット表の列がすべてでなく一部のみ存在する場合で、個々の列値ではなくレコード全体を操作する必要があるときに使用します。
`GET_BASE_OBJECT_NAME`	`GET_BASE_OBJECT_NAME`ファンクションでは、レコード内オブジェクトのベース・オブジェクトの完全修飾名を取得します。
`GET_BASE_OBJECT_NAME_ONLY`	`GET_BASE_OBJECT_NAME_ONLY`ファンクションでは、レコード内オブジェクトのベース・オブジェクトの名前のみを取得します。
`GET_BASE_SCHEMA_NAME_ONLY`	`GET_BASE_SCHEMA_NAME_ONLY`ファンクションでは、レコード内オブジェクトのベース・オブジェクトのスキーマの名前のみを取得します。
`GET_BEFORE_AFTER_IND`	`GET_BEFORE_AFTER_IND`ファンクションでは、レコードがデータベース操作のビフォア・イメージかアフター・イメージかを確認します。
`GET_CATALOG_NAME_ONLY`	`GET_CATALOG_NAME_ONLY`ファンクションでは、データベース・カタログの名前を返します。
`GET_COL_METADATA_FROM_INDEX`	`GET_COL_METADATA_FROM_INDEX`ファンクションでは、特定の列索引に関連付けられている列メタデータを確認します。
`GET_COL_METADATA_FROM_NAME`	`GET_COL_METADATA_FROM_NAME`ファンクションでは、特定の列名に関連付けられている列メタデータを確認します。
`GET_COLUMN_INDEX_FROM_NAME`	`GET_COLUMN_INDEX_FROM_NAME`ファンクションでは、特定の列名に関連付けられている列索引を確認します。
`GET_COLUMN_NAME_FROM_INDEX`	`GET_COLUMN_NAME_FROM_INDEX`ファンクションでは、特定の列索引に関連付けられている列名を確認します。
`GET_COLUMN_VALUE_FROM_INDEX`	`GET_COLUMN_VALUE_FROM_INDEX`ファンクションでは、指定する列索引を使用して、データ・レコードから列値を返します。
`GET_COLUMN_VALUE_FROM_NAME`	`GET_COLUMN_VALUE_FROM_NAME`ファンクションでは、特定の列名を使用して、データ・レコードから列値を返します。
`GET_DATABASE_METADATA`	`GET_DATABASE_METADATA`ファンクションでは、データベース・メタデータを返します。
`GET_DDL_RECORD_PROPERTIES`	`GET_DDL_RECORD_PROPERTIES`ファンクションでは、DDL操作に関する情報を返します。
`GET_ENV_VALUE`	`GET_ENV_VALUE`ファンクションでは、Oracle GoldenGate環境に関する情報を返します。
`GET_ERROR_INFO`	`GET_ERROR_INFO`ファンクションでは、破棄レコードに関連付けられているエラー情報を返します。
`GET_GMT_TIMESTAMP`	`GET_GMT_TIMESTAMP`ファンクションでは、操作コミット・タイムスタンプをGMTフォーマットで返します。
`GET_MARKER_INFO`	`GET_MARKER_INFO`ファンクションでは、データを送信するときにマーカー情報を返します。マーカーは、ユーザー・イグジット内でカスタム処理をトリガーするために使用します。
`GET_OBJECT_NAME`	処理中のレコードと関連付けられている表または他のオブジェクトの2つまたは3つの部分からなる完全修飾名を戻します。
`GET_OBJECT_NAME_ONLY`	処理中のレコードと関連付けられている表または他のオブジェクトの修飾されていない名前を戻します。
`GET_OPERATION_TYPE`	`GET_OPERATION_TYPE`ファンクションでは、レコードに関連付けられている操作のタイプを確認します。
`GET_POSITION`	`GET_POSITION`ファンクションでは、Oracle GoldenGateトレイル内のExtractデータ・ポンプまたはReplicatの読取り位置を取得します。
`GET_RECORD_BUFFER`	`GET_RECORD_BUFFER`ファンクションでは、カスタム列変換に関する情報を取得します。
`GET_RECORD_LENGTH`	`GET_RECORD_LENGTH`ファンクションでは、データ・レコードの長さを返します。
`GET_RECORD_TYPE`	`GET_RECORD_TYPE`ファンクションでは、処理されているレコードのタイプを返します。
`GET_SCHEMA_NAME_ONLY`	`GET_SCHEMA_NAME_ONLY`ファンクションでは、表のスキーマ名のみを返します。
`GET_SESSION_CHARSET`	`GET_SESSION_CHARSET`ファンクションでは、ユーザー・イグジット・セッションのキャラクタ・セットを返します。
`GET_STATISTICS`	`GET_STATISTICS`ファンクションでは、ExtractまたはReplicatプロセスの現在の処理統計を返します。
`GET_TABLE_COLUMN_COUNT`	`GET_TABLE_COLUMN_COUNT`ファンクションでは、表内の列の合計数を返します。
`GET_TABLE_METADATA`	`GET_TABLE_METADATA`ファンクションでは、処理中のレコードに関連付けられている表のメタデータを返します。
`GET_TABLE_NAME`	`GET_TABLE_NAME`ファンクションでは、処理中のレコードと関連付けられているソースまたはターゲット表の2つまたは3つの部分からなる完全修飾名を戻します。
`GET_TABLE_NAME_ONLY`	`GET_TABLE_NAME_ONLY`ファンクションでは、処理中のレコードに関連付けられている表の修飾されていない名前のみを返します。
`GET_TIMESTAMP`	`GET_TIMESTAMP`ファンクションでは、ソース・データ・レコードに関連付けられているI/Oタイムスタンプを返します。
`GET_TRANSACTION_IND`	`GET_TRANSACTION_IND`ファンクションでは、データ・レコードがトランザクションの最初、最後、または中間の操作かを確認します。
`GET_USER_TOKEN_VALUE`	`GET_USER_TOKEN_VALUE`ファンクションでは、トレイル・レコードからユーザー・トークン値を取得します。
`OUTPUT_MESSAGE_TO_REPORT`	`OUTPUT_MESSAGE_TO_REPORT`ファンクションでは、レポート・ファイルにメッセージを出力します。
`RESET_USEREXIT_STATS`	`RESET_USEREXIT_STATS`ファンクションでは、Oracle GoldenGateプロセスの統計をリセットします。
`SET_COLUMN_VALUE_BY_INDEX`	`SET_COLUMN_VALUE_BY_INDEX`ファンクションでは、データ・レコード全体を操作せず、単一の列値のみを変更します。
`STRNCMP`	`SET_COLUMN_VALUE_BY_NAME`ファンクションでは、データ・レコード全体を操作せず、単一の列値のみを変更します。
`SET_OPERATION_TYPE`	`SET_OPERATION_TYPE`ファンクションでは、レコードに関連付けられている操作のタイプを変更します。
`SET_RECORD_BUFFER`	`SET_RECORD_BUFFER`ファンクションは、HP NonStopユーザー・イグジットとの互換性の維持、および複雑なデータ・レコード操作のために使用します。
`SET_SESSION_CHARSET`	`SET_SESSION_CHARSET`ファンクションでは、ユーザー・イグジット・セッションのキャラクタ・セットを設定します。
`SET_TABLE_NAME`	`SET_TABLE_NAME`ファンクションでは、レコードに関連付けられている表名を変更します。