| Oracle® Call Interfaceプログラマーズ・ガイド 12c リリース1 (12.1) B72465-07 |
|
 前 |
 次 |
この項および表26-2では、OCI XStream関数について説明します。
表26-2 OCI XStream関数
| 関数 | 用途 |
|---|---|
LCR関数 |
LCRの1つ以上の値を取得および設定します。注意: これらのコールにはサーバーのラウンドトリップは必要ありません。 |
LCRから既存の追加属性を戻します。 |
|
行またはDDL LCRに追加属性を設定します。 |
|
LCRを解放します。 |
|
行またはDDL LCRの共通のヘッダー・フィールドを戻します。 |
|
行またはDDL LCRの共通のヘッダー・フィールドを初期化します。 |
|
DDL LCRの特定のフィールドを取り出します。 |
|
DDL LCRの特定のフィールドを移入します。 |
|
ピース単位のLOB LCRのLOB情報を戻します。 |
|
ピース単位のLOB LCRのLOB情報を設定します。 |
|
指定した期間で、特定した型(ROWまたはDDL)の新しいLCRオブジェクトを作成します。 |
|
行LCRの列フィールドを戻します。 |
|
行LCRの列フィールドを移入します。 |
|
行LCRに生成されたSQL文を値とともに戻します。 |
|
列値のバインド変数を使用する、生成されたSQL文を戻します。 |
|
位置値からSCNおよびコミットSCNを取得します。 |
|
SCNを位置に変換します。 |
|
指定した行LCRの |
|
指定した行LCRの |
|
XStream In関数 |
LCRストリームをXStreamインバウンド・サーバーに送信します。 |
インバウンド・サーバーに連結します。 |
|
インバウンド・サーバーにチャンク・データを送信します。 |
|
指定したトランザクションをコミットします。 |
|
インバウンド・サーバーから連結解除します。 |
|
連結コール後、インバウンド・サーバーで最初に発生したエラーを戻します。 |
|
XStreamインバウンド・サーバーへの連結中、ネットワークをフラッシュします。 |
|
コールバックを使用して連結されたインバウンド・サーバーにLCRストリームを送信します。 |
|
コールバックを使用して連結されたインバウンド・サーバーにLCRストリームを送信します。 |
|
ローカルの処理済最低位置を取得します。 |
|
XStream In関数のセッション属性を設定します。 |
|
XStream Out関数 |
XStreamアウトバウンド・サーバーからのLCRストリームを受信します。 |
アウトバウンド・サーバーに連結します。 |
|
各LOBまたは |
|
アウトバウンド・サーバーから連結解除します。 |
|
コールバックを使用してアウトバインド・サーバーからLCRストリームを取得します。 |
|
コールバックを使用せずにアウトバインド・サーバーからLCRストリームを受信します。 |
|
処理済最低水位標のローカル・コピーを更新します。 |
|
XStream Out関数のセッション属性を設定します。 |
用途
(ROWまたはDDL) LCRの追加属性の情報を取得します。さらに、エディション名など、OCILCRHeaderGet()、OCILCRDDLInfoGet()またはOCILCRProcedureInfoGet()によって移入されない、最初のもの以外の追加のクラス属性を取得します。
構文
sword OCILCRAttributesGet ( OCISvcCtx *svchp,
OCIError *errhp,
ub2 *num_attrs,
oratext **attr_names,
ub2 *attr_namesl,
ub2 *attr_dtyp,
void **attr_valuesp,
OCIInd *attr_indp,
ub2 *attr_alensp,
void *lcrp,
ub2 array_size,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
追加属性の数です。
追加属性名のポインタの配列です。
追加属性名の長さの配列です。
追加属性のデータ型の配列です。有効なデータ型は「コメント」を参照してください。
追加属性のデータ値ポインタの配列です。
インジケータ配列です。戻される各要素は、OCIInd値(OCI_IND_NULLまたはOCI_IND_NOTNULL)です。
実際の追加属性のデータ長の配列です。alensp内の各要素はバイト長です。
行またはDDL LCRへのポインタです。
他のパラメータの配列引数のサイズです。array_sizeが、要求された属性リストの属性数に十分な大きさでない場合、OCI_ERRORが戻されます。パラメータnum_attrsにより指定のサイズが戻されます。
OCI_DEFAULTを指定します。
コメント
attr_dtypに有効なデータ型は次のとおりです。
SQLT_CHR SQLT_INT SQLT_RDD
用途
行またはDDL LCRの追加属性の情報を移入します。さらに、エディション名など、OCILCRHeaderSet()、OCILCRDDLInfoSet()またはOCILCRRowColumnInfoSet()によって設定できない、最初のもの以外の追加のクラス属性を取得します。
構文
sword OCILCRAttributesSet ( OCISvcCtx *svchp,
OCIError *errhp,
ub2 num_attrs,
oratext **attr_names,
ub2 *attr_names_lens,
ub2 *attr_dtyp,
void **attr_valuesp,
OCIInd *attr_indp,
ub2 *attr_alensp,
void *lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
追加属性の数です。
追加属性名の配列へのポインタです。属性名は正規化されている必要があります。
追加属性名の長さの配列へのポインタです。
追加属性のデータ型の配列へのポインタです。有効なデータ型は、「OCILCRRowColumnInfoSet()」の「コメント」を参照してください。
追加属性のデータ値の配列のアドレスです。
インジケータ配列へのポインタです。すべてのデータ型について、これはOCIInd値(OCI_IND_NULLまたはOCI_IND_NOTNULL)の配列へのポインタです。
実際の追加属性のデータ長の配列へのポインタです。attr_lensp内の各要素はバイト長です。
行またはDDL LCRへのポインタです。
OCI_DEFAULTを指定します。
コメント
次の属性が有効です。
#define OCI_LCR_ATTR_THREAD_NO "THREAD#" #define OCI_LCR_ATTR_ROW_ID "ROW_ID" #define OCI_LCR_ATTR_SESSION_NO "SESSION#" #define OCI_LCR_ATTR_SERIAL_NO "SERIAL#" #define OCI_LCR_ATTR_USERNAME "USERNAME" #define OCI_LCR_ATTR_TX_NAME "TX_NAME" #define OCI_LCR_ATTR_EDITION_NAME "EDITION_NAME" #define OCI_LCR_ATTR_MESSAGE_TRACKING_LABEL "MESSAGE_TRACKING_LABEL" #define OCI_LCR_ATTR_CURRENT_USER "CURRENT_USER" #define OCI_LCR_ATTR_ROOT_NAME "ROOT_NAME"
用途
DDL LCRの特定のフィールドを取り出します。
構文
sword OCILCRDDLInfoGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext **object_type,
ub2 *object_type_len,
oratext **ddl_text,
ub4 *ddl_text_len,
oratext **logon_user,
ub2 *logon_user_len,
oratext **current_schema,
ub2 *current_schema_len,
oratext **base_table_owner,
ub2 *base_table_owner_len,
oratext **base_table_name,
ub2 *base_table_name_len,
oraub8 *flag,
void *ddl_lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
DDL文が実行されたオブジェクトの型です。(OCILCRDDLInfoSet()に関する説明を参照してください。)オプションです。NULLでない場合、object_typeとobject_type_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないobject_type文字列の長さです。
DDL文のテキストです。オプションです。NULLでない場合、ddl_textとddl_text_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないDDLテキストのバイト長です。
DDL文を実行したセッションの正規化された(ルールまたはプロシージャに準拠)ユーザー名です。オプションです。NULLでない場合、logon_userとlogon_user_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないlogon_user文字列の長さです。
ddl_textの変更済データベース・オブジェクトに対していずれのスキーマも明示的に指定されていない場合に使用される正規化されたスキーマ名です。オプションです。NULLでない場合、current_schemaとcurrent_schema_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないcurrent_schema文字列の長さです。
DDL文が表関連のDDLである場合(CREATE TABLE、ALTER TABLEなど)、またはDDL文に表が関連する場合(表でトリガーを作成するなど)、base_table_ownerで、関連する表の正規化された所有者が指定されます。それ以外の場合は、base_table_ownerはNULLです。オプションです。NULLでない場合、base_table_ownerとbase_table_owner_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないbase_table_owner文字列の長さです。
DDL文が表関連のDDLである場合(CREATE TABLE、ALTER TABLEなど)、またはDDL文に表が関連する場合(表でトリガーを作成するなど)、base_table_nameで、関連する表の正規化名が指定されます。それ以外の場合は、base_table_nameはNULLです。オプションです。NULLでない場合、base_table_nameとbase_table_name_lenの引数は両方ともNULL以外である必要があります。
NULL終端文字を含めないbase_table_name文字列の長さです。
DDL LCRフラグです。オプションです。引数がNULLの場合、データは戻されません。現在、今後の拡張要素は使用されていません。
DDL LCRです。NULL以外にしてください。
OCI_DEFAULTを指定します。
用途
行またはDDL、あるいはプロシージャLCRの共通のヘッダー・フィールドを戻します。戻されるポインタはすべて、対応するLCRフィールドを直接指し示します。
構文
sword OCILCRHeaderGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext **src_db_name,
ub2 *src_db_name_len,
oratext **cmd_type,
ub2 *cmd_type_len,
oratext **owner,
ub2 *owner_len,
oratext **oname,
ub2 *oname_len,
ub1 **tag,
ub2 *tag_len,
oratext **txid,
ub2 *txid_len,
OCIDate *src_time,
ub2 *old_columns,
ub2 *new_columns,
ub1 **position,
ub2 *position_len,
oraub8 *flag,
void *lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
正規化されたソース・データベースの名前です。NULL以外にしてください。
NULL終端文字を含めないsrc_db_name文字列のバイト長です。
行LCRの場合、次のいずれかの値です。
注意:
#define OCI_LCR_ROW_CMD_ROLLBACKと#define OCI_LCR_ROW_CMD_START_TXの値は、Oracle Database 11g リリース2 (11.2.0.2)より使用可能な機能です。
#define OCI_LCR_ROW_CMD_INSERT #define OCI_LCR_ROW_CMD_DELETE #define OCI_LCR_ROW_CMD_UPDATE #define OCI_LCR_ROW_CMD_COMMIT #define OCI_LCR_ROW_CMD_ROLLBACK #define OCI_LCR_ROW_CMD_START_TX #define OCI_LCR_ROW_CMD_LOB_WRITE #define OCI_LCR_ROW_CMD_LOB_TRIM #define OCI_LCR_ROW_CMD_LOB_ERASE
DDL LCRの場合、『Oracle Call Interfaceプログラマーズ・ガイド』に記載されているいずれかのコマンド型です。
NULL終端文字を含めないcmd_type文字列のバイト長です。
正規化された表の所有者名です。NULL以外にしてください。
NULL終端文字を含めないowner文字列のバイト長です。
正規化された表の名前です。NULL以外にしてください。
NULL終端文字を含めないoname文字列のバイト長です。
LCRの追跡を可能にするバイナリ・タグです。たとえば、適用転送が使用されている場合、このタグを使用してDML文の元のソース・データベースを判別できます。
タグ内のバイト数です。
トランザクションIDです。NULL以外にしてください
NULL終端文字を含めない文字列のバイト長です。
変更がソース・データベースのREDOログ・ファイルで生成された時間です。
OLD列リスト内の列数です。入力LCRがDDL LCRである場合0 (ゼロ)を戻します。オプションです。
NEW列リスト内の列数です。入力LCRがDDL LCRである場合0 (ゼロ)を戻します。オプションです。
LCRの位置です。
positionの長さです。
LCRフラグです。可能なフラグのリストは「コメント」を参照してください。
lcrpはNULL以外にしてください。
OCILCR_NEW_ONLY_MODEモードを指定した場合、戻されるnew_columnsは、NEW列リストのみの列数です。それ以外の場合は、戻されるnew_columnsは、指定した行LCRのNEWまたはOLD列リストのいずれかに含まれる列の数です。
コメント
LCRフラグです。
#define OCI_ROWLCR_HAS_ID_KEY_ONLY /* only has ID key cols */ #define OCI_ROWLCR_SEQ_LCR /* sequence lcr */
用途
行LCRに生成されたSQL文を値とともに戻します。sql_stmtにメモリーを事前に割り当てる必要があり、渡される際の割当てバッファのサイズになるように*sql_stmt_lenを設定する必要があります。*sql_stmt_lenが生成されるSQL文を保持するのに十分な大きさでない場合、エラーが発生します。
構文
sword OCILCRRowStmtGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *row_stmt,
ub4 *row_stmt_len,
void *row_lcrp,
ub4 mode );
用途
列値のバインド変数を使用する、生成されたSQL文を戻します。バインド変数の値が個別の配列で戻されます。sql_stmtにメモリーを事前に割り当て、配列*sql_stmt_lenを割り当てられたバッファのサイズに設定し、さらにarray_sizeを配列の長さにする必要があります。bind_var_valuesp内の実際の列値はLCR内の値を指し示すため、これは簡単なコピーです。array_sizeがすべての変数を保持するのに十分な大きさでない、または*sql_stmt_lenが生成されるSQL文を保持するのに十分な大きさでない場合、エラーが発生します。
構文
sword OCILCRRowStmtWithBindVarGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *row_stmt,
ub4 *row_stmt_len,
ub2 *num_bind_var,
ub2 *bind_var_dtyp,
void **bind_var_valuesp,
OCIInd *bind_var_indp,
ub2 *bind_var_alensp,
ub1 *bind_var_csetidp,
ub1 *bind_var_csetfp,
void *row_lcrp,
oratext **chunk_column_names,
ub2 *chunk_column_namesl,
oraub8 *chunk_column_flags,
ub2 array_size,
oratext *bind_var_syntax,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
行LCRに生成されるSQL文です。
渡される際のrow_stmtに割り当てられたバッファのサイズになるように設定します。row_stmtの長さを戻します。
バインド変数の数です。
バインド変数のデータ型の配列です。
バインド変数の値の配列です。
バインド変数のNULLインジケータの配列です。
バインド変数値の長さの配列です。
バインド変数のキャラクタ・セットのIDの配列です。
バインド変数のキャラクタ・セット・フォームの配列です。
行LCRへのポインタです。
LCR内のLOB列名の配列です。
LOB列名の長さの配列です。
LOB列のフラグの配列です。可能なフラグのリストは「コメント」を参照してください。
各パラメータの配列のサイズです。
(:) (バインドはフォーム:1、:2などのもの)または(?)(バインドはフォーム(?)のもの)のいずれかです。
OCI_DEFAULTを指定します。
コメント
次のLCR列フラグは、ビット単位のOR演算子を使用して結合可能です。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains LOB data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty LOB */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of current column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */ #define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff data */ #define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */ #define OCI_LCR_COLUMN_UPDATED /* col is updated */ /* OCI_LCR_COLUMN_UPDATED is set only for the modified columns in the NEW * column list of an update LCR. */
用途
指定した期間で、特定した型(ROWまたはDDL)の新しいStreams LCRオブジェクトを作成します。
構文
sword OCILCRNew ( OCISvcCtx *svchp,
OCIError *errhp,
OCIDuration duration,
ub1 lcrtype,
void **lcrp,
ub4 mode );
パラメータ
コメント
注意:
作成後は、LCR (ROWまたはDDL)の型またはメモリー割当ての期間を変更することはできません。
行またはDDL LCRの共通ヘッダー・フィールドを移入するにはOCILCRHeaderSet()を使用します。
LCRヘッダーの初期化後、OCILCRRowColumnInfoSet()またはOCILCRDDLInfoSet()を使用して操作に特定の要素を移入します。追加属性の情報を移入するにはOCILCRExtraAttributesSet()を使用します。
この関数で作成されたLCRを解放するにはOCILCRFree()を使用します。
行LCRの列フィールドを戻します。
用途
行LCRの列フィールドを戻します。
構文
sword OCILCRRowColumnInfoGet ( OCISvcCtx *svchp,
OCIError *errhp,
ub2 column_value_type,
ub2 *num_columns,
oratext **column_names,
ub2 *column_name_lens,
ub2 *column_dtyp,
void **column_valuesp,
OCIInd *column_indp,
ub2 *column_alensp,
ub1 *column_csetfp,
oraub8 *column_flags,
ub2 *column_csid,
void *row_lcrp,
ub2 array_size,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ROW LCR列値の型です。次のいずれかです。
#define OCI_LCR_ROW_COLVAL_OLD #define OCI_LCR_ROW_COLVAL_NEW
指定した列配列内の列数です。
列名のポインタの配列です。
列名の長さの配列です。
列のデータ型の配列です。オプションです。column_dtypがNULLの場合、データは戻されません。
列データのポインタの配列です。
インジケータの配列です。
列の長さの配列です。戻される各要素はバイト長です。
列のキャラクタ・セット・フォームの配列です。オプションです。引数がNULLの場合、データは戻されません。
列のフラグの配列です。オプションです。引数がNULLの場合、データは戻されません。値は「コメント」を参照してください。
列のキャラクタ・セットIDの配列です。
row_lcrpはNULL以外にしてください。
各パラメータの配列のサイズです。array_sizeが、要求された列リスト内の列数よりも少ない場合、エラーが戻されます。要求された列リストの実際のサイズは、num_columnsパラメータによって戻されます。
OCILCR_NEW_ONLY_MODEモードを指定した場合、戻されるnew_columnsは、NEW列リストのみの列数です。それ以外の場合は、戻されるnew_columnsは、指定した行LCRのNEWまたはOLD列リストのいずれかに含まれる列の数です。
コメント
INSERTの場合、この関数はNEW列の値を取得するためにのみコールする必要があります。
DELETEの場合、この関数はOLD列の値を取得するためにのみコールする必要があります。
UPDATEの場合、この関数は、NEW列の値を取得するためと、OLD列の値を取得するための、2回コールできます。
この関数は、COMMIT演算子の場合はコールしないでください。
次のLCR列フラグは、ビット単位のOR演算子を使用して結合可能です。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains LOB data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty LOB */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of current column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */
#define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff data */
#define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */ #define OCI_LCR_COLUMN_UPDATED /* col is updated */ /* OCI_LCR_COLUMN_UPDATED is set only for the modified columns in the NEW * column list of an update LCR. */
表26-3は、現在サポートされている表の列のデータ型を示しています。データ型ごとに、対応するLCR列のデータ型、LCR列の値をキャストするCプログラム変数型、およびOCILCRRowColumnInfoGet()から戻される列の値の操作が可能なOCI関数を示しています。
表26-3 表の列のデータ型
| 表の列のデータ型 | LCR列のデータ型 | プログラム変数 | 変換関数 |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
構造に直接アクセスして、日付および時刻フィールドを取得できます。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
脚注 1
列データを取得するにはOCIXStreamOutChunkReceive()をコールします。
用途
行LCRの列フィールドを移入します。
構文
sword OCILCRRowColumnInfoSet ( OCISvcCtx *svchp,
OCIError *errhp,
ub2 column_value_type,
ub2 num_columns,
oratext **column_names,
ub2 *column_name_lens,
ub2 *column_dtyp,
void **column_valuesp,
OCIInd *column_indp,
ub2 *column_alensp,
ub1 *column_csetfp,
oraub8 *column_flags,
ub2 *column_csid,
void *row_lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ROW LCR列の値の型です。
#define OCI_LCR_ROW_COLVAL_OLD #define OCI_LCR_ROW_COLVAL_NEW
各配列パラメータ内の列数です。
列名の配列へのポインタです。列名は正規化されている必要があります。列名は、Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
列名の長さの配列へのポインタです。
列のデータ型の配列へのポインタです。有効なデータ型は「コメント」を参照してください。
列データのポインタの配列へのポインタです。
インジケータ配列へのポインタです。すべてのデータ型について、これはOCIInd値(OCI_IND_NULLまたはOCI_IND_NOTNULL)の配列へのポインタです。
実際の列のバイト長の配列へのポインタです。
列のキャラクタ・セット・フォームの配列へのポインタです。デフォルトのフォームはSQLCS_IMPLICITです。この属性を設定することにより、データベースまたは各国語キャラクタ・セットがクライアント側で使用されるようになります。この属性は、各国語キャラクタ・セットの場合はSQLCS_NCHARに設定し、データベース・キャラクタ・セットの場合はSQLCS_IMPLICITに設定します。文字以外の列の場合は0 (ゼロ)を渡します。
列フラグの配列へのポインタです。(有効なLCR列フラグのリストは、「コメント」を参照してください。)
列のキャラクタ・セットIDの配列へのポインタです。
row_lcrpはNULL以外にしてください。
OCI_DEFAULTを指定します。
コメント
注意:
INSERTの場合、この関数はNEW列の値を指定するためにのみコールする必要があります。
DELETEの場合、この関数はOLD列の値を指定するためにのみコールする必要があります。
UPDATEの場合、この関数は、NEW列の値を指定するためと、OLD列の値を指定するための、2回コールできます。
この関数は、COMMIT演算子の場合はコールしないでください。
次のLCR列フラグは、ビット単位のOR演算子を使用して結合可能です。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains LOB data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty LOB */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of current column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */
#define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff data */
#define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */ #define OCI_LCR_COLUMN_UPDATED /* col is updated */ /* OCI_LCR_COLUMN_UPDATED is set only for the modified columns in the NEW * column list of an update LCR. */
次のデータ型が有効です。
SQLT_AFC SQLT_TIMESTAMP SQLT_DAT SQLT_TIMESTAMP_TZ SQLT_BFLOAT SQLT_TIMESTAMP_LTZ SQLT_BDOUBLE SQLT_INTERVAL_YM SQLT_NUM SQLT_INTERVAL_DS SQLT_VCS SQLT_ODT SQLT_INT SQLT_BIN SQLT_CHR SQLT_RDD SQLT_VST SQLT_INT SQLT_FLT
用途
DDL LCRの特定のフィールドを移入します。
構文
sword OCILCRDDLInfoSet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *object_type,
ub2 object_type_len,
oratext *ddl_text,
ub4 ddl_text_len,
oratext *logon_user,
ub2 logon_user_len,
oratext *current_schema,
ub2 current_schema_len,
oratext *base_table_owner,
ub2 base_table_owner_len,
oratext *base_table_name,
ub2 base_table_name_len,
oraub8 flag,
void *ddl_lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
DDL文が実行されたオブジェクトの型です。有効なオブジェクト型は「コメント」を参照してください。
NULL終端文字を含めないobject_type文字列の長さです。
DDL文のテキストです。このパラメータはNULL以外の値に設定する必要があります。DDLテキストはOracle Database DDL形式である必要があります。
NULL終端文字を含めないDDLテキストのバイト長です。
DDL文を実行したセッションのユーザーの正規化された名前です。
NULL終端文字を含めないlogon_user文字列の長さです。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
ddl_textの変更済データベース・オブジェクトに対していずれのスキーマも明示的に指定されていない場合に使用される正規化されたスキーマ名です。current_schemaと異なるスキーマがcurrent_schemaに指定されている場合、このファンクションはcurrent_schemaに指定されているスキーマを使用します。
このパラメータはNULL以外の値に設定する必要があります。
NULL終端文字を含めないcurrent_schema文字列の長さです。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
DDL文が表関連のDDLである場合(CREATE TABLE、ALTER TABLEなど)、またはDDL文に表が関連する場合(表でトリガーを作成するなど)、base_table_ownerで、関連する表の正規化された所有者が指定されます。それ以外の場合は、base_table_ownerはNULLです。
NULL終端文字を含めないbase_table_owner文字列の長さです。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
DDL文が表関連のDDLである場合(CREATE TABLE、ALTER TABLEなど)、またはDDL文に表が関連する場合(表でトリガーを作成するなど)、base_table_nameで、関連する表の正規化名が指定されます。それ以外の場合は、base_table_nameはNULLです。
NULL終端文字を含めないbase_table_nameの長さです。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
DDL LCRフラグです。(現在は使用されていません。今後の拡張で使用されます)。OCI_DEFAULTを指定します。
ddl_lcrpはNULL以外にしてください。
OCI_DEFAULTを指定します。
コメント
次に示すオブジェクト型が有効です。
CLUSTER FUNCTION INDEX OUTLINE PACKAGE PACKAGE BODY PROCEDURE SEQUENCE SYNONYM TABLE TRIGGER TYPE USER VIEW
NULLも有効なオブジェクト型です。リストに含まれていないオブジェクト型の場合、すべてNULLを指定します。
用途
行またはDDL LCRの共通のヘッダー・フィールドを初期化します。
構文
sword OCILCRHeaderSet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *src_db_name,
ub2 src_db_name_len,
oratext *cmd_type,
ub2 cmd_type_len,
oratext *owner,
ub2 owner_len,
oratext *oname,
ub2 oname_len,
ub1 *tag,
ub2 tag_len,
oratext *txid,
ub2 txid_len,
OCIDate *src_time,
ub1 *position,
ub2 position_len,
oraub8 flag,
void *lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
正規化されたソース・データベースの名前です。NULL以外にしてください。
NULL終端文字を含めないsrc_db_name文字列のバイト長です。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
行LCRの場合、次のいずれかの値です。
注意:
#define OCI_LCR_ROW_CMD_ROLLBACKと#define OCI_LCR_ROW_CMD_START_TXの値は、Oracle Database 11g リリース2 (11.2.0.2)より使用可能です。
#define OCI_LCR_ROW_CMD_INSERT #define OCI_LCR_ROW_CMD_DELETE #define OCI_LCR_ROW_CMD_UPDATE #define OCI_LCR_ROW_CMD_COMMIT #define OCI_LCR_ROW_CMD_ROLLBACK #define OCI_LCR_ROW_CMD_START_TX #define OCI_LCR_ROW_CMD_LOB_WRITE #define OCI_LCR_ROW_CMD_LOB_TRIM #define OCI_LCR_ROW_CMD_LOB_ERASE
DDL LCRの場合、OCI_ATTR_SQLFNCODEのいずれかのコマンド型です。
cmd_typeの長さです。
正規化された表の所有者名です。所有者はCOMMIT LCRには必要ありません。
NULL終端文字を含めないowner文字列のバイト長です。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
正規化された表の名前です。所有者はCOMMIT LCRには必要ありません。
NULL終端文字を含めないoname文字列のバイト長です。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
LCRの追跡を可能にするバイナリ・タグです。たとえば、適用転送が使用されている場合、このタグを使用してDML文の元のソース・データベースを判別できます。
タグ内のバイト数です。2000バイトを超えないようにします。
トランザクションIDです。NULL以外にしてください。
NULL終端文字を含めないtxid文字列のバイト長です。Oracle Databaseのネーミング規則およびサイズの制限に従う必要があります。
変更がソース・データベースのオンラインREDOログ・ファイルで生成された時間です。
LCRの位置です。NULL以外で、バイト互換性になるようにしてください。
位置の長さです。0 (ゼロ)より大きくなるようにしてください。
LCRフラグです。可能なフラグのリストは「コメント」を参照してください。
lcrpはNULL以外にしてください。
OCI_DEFAULTを指定します。
コメント
注意:
この関数は、追加属性を含め、LCRのすべての内部フィールドをNULLに設定します。
この関数は、渡された値はディープ・コピーしません。LCRの間、データが有効であることを確認する必要があります。
COMMIT LCRの場合、ownerおよびoname情報は必要ありません。src_db_name、cmd_type、tag、txidおよびpositionに有効な値を指定します。
行LCRの場合、OCILCRRowColumnInfoSet()を使用して行LCRに特定の列の情報を移入します。
DDL LCRの場合は、OCILCRDDLInfoSet()を使用してDDL操作に特定の情報を移入します。
行またはDDL LCRの場合は、OCILCRAttributesSet()を使用して追加属性の情報を移入します。
次にLCRフラグを示します。
#define OCI_ROWLCR_HAS_ID_KEY_ONLY /* only has ID key cols */ #define OCI_ROWLCR_SEQ_LCR /* sequence lcr */
用途
DBMS_LOBまたはOCILobプロシージャから生成されたピース単位のLOB LCRのLOB情報を戻します。
構文
sword OCILCRLobInfoGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext **column_name,
ub2 *column_name_len,
ub2 *column_dty,
oraub8 *column_flag,
ub4 *offset,
ub4 *size,
void *row_lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
LOB列の名前です。
LOB列の名前の長さです。
列のデータ型(SQLT_CHRまたはSQLT_BINのいずれか)です。
列フラグです。「OCILCRRowColumnInfoSet()」の「コメント」を参照してください。
コード・ポイントのLOB操作のオフセットです。LOB WRITEおよびLOB TRIM操作の場合にのみ戻します。これは、OCILobErase()のoffsetパラメータまたはOCILobWrite()のoffsetパラメータと同じです。
コード・ポイントのLOB操作のサイズです。LOB TRIMおよびLOB ERASE操作の場合にのみ戻します。これは、OCILobTrim()のnew_lengthパラメータまたはOCILobErase()のamtpパラメータと同じです。
行LCRへのポインタです。
OCI_DEFAULTを指定します。
コメント
OCI_SUCCESSまたはOCI_ERRORを戻します。
用途
ピース単位のLOB LCRのLOB情報を設定します。このコールは、入力LCRがLOB_WRITE、LOB_ERASEまたはLOB_TRIMである場合に有効です。それ以外の場合はエラーが戻されます。
構文
sword OCILCRLobInfoSet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *column_name,
ub2 column_name_len,
ub2 column_dty,
oraub8 column_flag,
ub4 offset,
ub4 size,
void *row_lcrp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
LOB列の名前です。
LOB列の名前の長さです。
列のデータ型(SQLT_CHRまたはSQLT_BINのいずれか)です。
列フラグです。「OCILCRRowColumnInfoSet()」の「コメント」を参照してください。
コード・ポイントのLOB操作のオフセットです。LOB WRITEおよびLOB TRIM操作の場合にのみ必要です。これは、OCILobErase()のsoffsetパラメータまたはOCILobWrite()のoffsetパラメータと同じです。
コード・ポイントのLOB操作のサイズです。LOB TRIMおよびLOB ERASE操作の場合にのみ必要です。これは、OCILobTrim()のnew_lengthパラメータまたはOCILobErase()のamtpパラメータと同じです。
行LCRへのポインタです。
OCI_DEFAULTを指定します。
コメント
OCI_SUCCESSまたはOCI_ERRORを戻します。
用途
位置値からSCNおよびコミットSCNを戻します。入力位置は、XStreamアウトバウンド・サーバーから取得されたものである必要があります。入力位置が指定の形式に準拠していない場合、エラーが戻されます。
構文
sword OCILCRSCNsFromPosition ( OCISvcCtx *svchp,
OCIError *errhp,
ub1 *position,
ub2 position_len,
OCINumber *scn,
OCINumber *commit_scn,
ub4 mode );
用途
SCNを位置に変換します。生成された位置をlast_positionとしてOCIXStreamOutAttach()に渡し、指定したSCNを下回るコミットSCN、および指定したSCNを下回るLCRのSCNのあるLCRをフィルタできます。したがって、アウトバウンド・サーバーで送信される最初のLCRは次のいずれかになります。
指定したSCNのコミットLCRです。
指定したSCN以上のコミットSCNがある後続のトランザクションの最初のLCRです。
構文
sword OCILCRSCNToPosition ( OCISvcCtx *svchp,
OCIError *errhp,
ub1 *position,
ub2 *position_len,
OCINumber *scn,
ub4 mode );
パラメータ
コメント
変換が成功した場合はOCI_SUCCESSを戻し、それ以外の場合はOCI_ERRORを戻します。
用途
指定した行LCRのWHERE句文を取得します。
構文
sword OCILCRWhereClauseGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *wc_stmt,
ub4 *wc_stmt_len,
void *row_lcrp,
ub4 mode );
パラメータ
コメント
INSERT LCRに生成されたWHERE句には、挿入されるすべての列が含まれます。このWHERE句は、たとえば「ROWIDを戻す」など、挿入された行を識別するために使用できます。
INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10
UPDATEに生成されたWHERE句には、古い列リストのすべての列が含まれます。ただし、UPDATEの新しい列リストに存在する場合は列の値は新しい値のものになります。その列に新しい値が含まれない場合、古い値が使用されます。
UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10 UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20
DELETEのWHERE句では、古い列リストの列および値が使用されます。
LOBのピース単位の操作では、WHERE句の生成に新しい列および値が使用されます。
戻り値
OCI_SUCCESSまたはOCI_ERROR。
用途
指定した行LCRのWHERE句文をバインド変数とともに取得します。
構文
sword OCILCRWhereClauseWithBindVarGet ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *wc_stmt,
ub4 *wc_stmt_len,
ub2 *num_bind_var,
ub2 *bind_var_dtyp,
void **bind_var_valuesp,
OCIInd *bind_var_indp,
ub2 *bind_var_alensp,
ub2 *bind_var_csetidp,
ub1 *bind_var_csetfp,
void *row_lcrp,
ub2 array_size,
oratext *bind_var_syntax,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
LCRと等価のSQL文です。
wc_stmtバッファの長さです。
バインド変数の数です。
バインド変数のデータ型の配列です。
バインド変数の値の配列です。
バインド変数のNULLインジケータの配列です。
バインド値の長さの配列です。
バインドのキャラクタ・セットIDの配列です。
バインドのキャラクタ・セット・フォームの配列です。
SQLに変換される行LCRです。
バインド値の配列のサイズです。
バインドに使用されるネイティブ構文です。
今後の拡張で使用されるモード・フラグです。OCI_DEFAULTを指定します。
コメント
array_sizeが、要求された列リストの列数に十分な大きさでない場合、OCI_ERRORが戻されます。指定したarray_sizeはnum_bind_varパラメータによって戻されます。
Oracle Databaseのbind_var_syntaxには(:)が含まれている必要があります。これにより、:1、:2、:3などの位置バインドが生成されます。Oracle以外のデータベースの場合、バインドに使用する必要がある文字列が入力されます。
INSERT LCRに生成されたWHERE句には、挿入されるすべての列が含まれます。このWHERE句により、たとえば「ROWIDを戻す」など、挿入された行を識別できます。
INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10
UPDATEに生成されたWHERE句には、古い列リストのすべての列が含まれます。ただし、UPDATEの新しい列値に存在する場合は、列の値は新しい列値のものになります。列が古い列にのみ存在する場合は、その古い列の値が使用されます。
UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10 UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20
DELETEのWHERE句では、古い列リストの列および値が使用されます。
LOBのピース単位の操作では、WHERE句の生成に新しい列および値が使用されます。
戻り値
OCI_SUCCESSまたはOCI_ERROR。
用途
インバウンド・サーバーに連結します。クライアント・アプリケーションは、専用の接続を使用してデータベースに接続する必要があります。
構文
sword OCIXStreamInAttach ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *server_name,
ub2 server_name_len,
oratext *source_name,
ub2 source_name_len,
ub1 *last_position,
ub2 *last_position_len,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
XStreamインバウンド・サーバーの名前です。
XStreamインバウンド・サーバー名の長さです。
データ・ソースを識別するためのソース名です。
ソース名の長さです。
インバウンド・サーバーで受信された最後の位置です。オプションです。指定する場合、戻り値にOCI_LCR_MAX_POSITION_LENバイトを事前に割り当てる必要があります。
last_positionの長さです。last_positionがNULL以外の値の場合、NULL以外の値である必要があります。
OCIXSTREAM_IN_ATTACH_RESTART_INBOUNDモードを指定する場合、この関数は、無効または異常終了状態に関係なく、インバウンド・サーバーを再起動するようにサーバーに通知できます。このモードを渡さず、またこのコールが実行されたときにインバウンド・サーバーが異常終了状態である場合、この関数はエラーを戻します。
コメント
1つのOracleインスタンスで複数のインバウンド・サーバーを構成できるため、インバウンド・サーバーの名前を指定する必要があります。この関数は、インバウンド・サーバーへの連結中にエラーが発生した場合、OCI_ERRORを戻します。XStreamインバウンド・サーバーには一度に1つのクライアントのみを連結できます。複数のクライアントを同じインバウンド・サーバーに連結しようとする、または同じクライアントを複数のインバウンド・サーバーに同時に連結しようとするとエラーが発生します。
この関数は、インバウンド・サーバーで受信された最後の位置を戻します。サーバーに正常に連結された場合、インバウンド・サーバーでlast_position以下の位置にあるすべてのLCRが破棄されるため、クライアントではこのlast_positionより上の位置にあるLCRの送信が再開されます。
OCI_SUCCESSまたはOCI_ERRORのいずれかを戻します。
用途
インバウンド・サーバーから連結解除します。
構文
sword OCIXStreamInDetach ( OCISvcCtx *svchp,
OCIError *errhp,
ub1 *processed_low_position,
ub2 *processed_low_position_len,
ub4 mode );
パラメータ
コメント
位置引数の事前割当て済バッファで渡す必要があります。このバッファの最大長はOCI_LCR_MAX_POSITION_LENです。この位置はDBA_XSTREAM_INBOUND_PROGRESSビューで表示されます。
このコールはサーバーの処理済最低位置を戻します。OCIXStreamInLCRSend()コールの実行中にこの関数が呼び出された場合、インバウンド・サーバーから連結解除する前にすぐにそのコールを終了します。
OCI_SUCCESSまたはOCI_ERRORのいずれかを戻します。
クライアントから連結されたインバウンド・サーバーへLCRストリームを送信します。
用途
OCIXStreamInLCRSend()コールごとのネットワークのラウンドトリップを回避するため、接続がこのコールに連結され、サーバーへのLCRストリームの開始以降、ACK間隔後にこのコールを終了します。
構文
sword OCIXStreamInLCRSend ( OCISvcCtx *svchp,
OCIError *errhp,
void *lcrp,
ub1 lcrtype,
oraub8 flag,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
送信する新規LCRへのポインタです。これはNULLにはできません。
LCRの型です。次のいずれかです。
#define OCI_LCR_XROW #define OCI_LCR_XDDL
ビットOCI_XSTREAM_MORE_ROW_DATA (0x01)を設定した場合、LCRに追加のチャンク・データが含まれるようになります。OCIXStreamInLCRSend()を再度コールする前に、OCIXStreamInChunkSend()をコールする必要があります。
OCI_DEFAULTを指定します。
コメント
リターン・コードは次のとおりです。
OCI_STILL_EXECUTINGは、現在のコールがまだ実行中であることを意味します。指定したサービス・ハンドルに関連付けられている接続は、サーバーへのLCRのストリームのためにこのコールにまだ連結されています。同じ接続を使用して、OCIStmtExecute()、OCIStmtFetch()、OCILobRead()など、データベースのラウンドトリップを必要とするOCIコールを実行しようとすると、エラーが戻されます。OCILCR*コールはローカル・コールであるため、このコールの実行中は有効になります。
OCI_SUCCESSは現在のコールが完了したことを意味します。同じサービス・コンテキストからOCIStmt*、OCILob*などを実行できます。
OCI_ERRORはこのコールでエラーがいくつか発生したことを意味します。エラーに関する情報を取得するにはOCIErrorGet()を使用します。
関連項目:
連結されたインバウンド・サーバーにLCRストリームを送信します。
用途
ストリームされる各LCRを作成するには、コールバックを指定する必要があります。一部のLCRにチャンク・データが含まれている場合は、各チャンク・データを作成するために2番目のコールバックを指定する必要があります。
構文
sword OCIXStreamInLCRCallbackSend (
OCISvcCtx *svchp,
OCIError *errhp,
OCICallbackXStreamInLCRCreate createlcr_cb,
OCICallbackXStreamInChunkCreate createchunk_cb,
void *usrctxp,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ストリームされるLCRを生成するために呼び出されるクライアント側コールバック・プロシージャです。NULL以外にしてください。
各チャンクを作成するために呼び出されるクライアント側コールバック・プロシージャです。LOB、LONGまたはXMLType列を含んだLCRを送信する必要がない場合は、NULLにできます。この引数がNULLで、追加のチャンク・データとともにLCRを送信しようとした場合、OCI_ERRORが戻されます。
両方のコールバック関数に渡されるユーザー・コンテキストです。
現行では、OCI_DEFAULTを指定します。
コメント
リターン・コードはOCI_ERRORまたはOCI_SUCCESSです。
createlcr_cb引数はOCICallbackXStreamInLCRCreate型にしてください。
typedef sb4 (*OCICallbackXStreamInLCRCreate)
void *usrctxp, void **lcrp, ub1 *lcrtyp, oraub8 *flag);
OCICallbackXStreamInLCRCreate()のパラメータは次のとおりです。
ユーザー・コンテキストへのポインタです。
送信されるLCRへのポインタです。
LCR型(OCI_LCR_XROWまたはOCI_LCR_XDDL)です。
OCI_XSTREAM_MORE_ROW_DATAを設定した場合、現在のLCRに追加のチャンク・データが含まれるようになります。
このコールバックへの入力パラメータはユーザー・コンテキストです。出力パラメータは新しいLCR、その型およびフラグです。生成されたLCRに追加のチャンク・データが含まれている場合、このフラグにはOCI_XSTREAM_MORE_ROW_DATA (0x01)ビット・セットが必要です。OCICallbackXStreamInLCRCreate()コールバック関数からの有効なリターン・コードはOCI_CONTINUEまたはOCI_SUCCESSです。OCIXStreamInLCRCallbackSend()コールの処理を続行するには、このコールバック関数でOCI_CONTINUEが戻されるようにする必要があります。OCI_CONTINUE以外のリターン・コードは、クライアントがOCIXStreamInLCRCallbackSend()コールの即時終了を求めていることを示します。さらに、OCICallbackXStreamInLCRCreate()コールバック関数からNULL LCRが戻された場合、クライアントが現在のコールの終了を求めていることを示します。
createchunk_cb引数はOCICallbackXStreamInChunkCreate型にしてください。
typedef sb4 (*OCICallbackXStreamInChunkCreate) void *usrctxp, oratext **column_name, ub2 *column_name_len, ub2 *column_dty, oraub8 *column_flag, ub2 *column_csid, ub4 *chunk_bytes, ub1 **chunk_data, oraub8 *flag);
createchunk_cb()プロシージャの入力パラメータは、ユーザー・コンテキストおよびチャンクに関する情報です。
OCICallbackXStreamInChunkCreate()のパラメータは次のとおりです。
ユーザー・コンテキストへのポインタです。
現在のチャンクの列名です。
列名の長さです。
チャンク・データの型(SQLT_CHRまたはSQLT_BINのいずれか)です。
「OCIXStreamInChunkSend()」の「コメント」を参照してください。
列のキャラクタ・セットIDです。列がXMLType列である(つまり、column_flagにOCI_LCR_COLUMN_XML_DATAビット・セットが含まれている)場合にのみ適用します。
チャンク・データのバイト長です。
チャンク・データのポインタです。
OCI_XSTREAM_MORE_ROW_DATAを設定した場合、現在のLCRに追加のチャンク・データが含まれるようになります。
OCIXStreamInLCRCallbackSend()関数はcreatelcr_cb()プロシージャを呼び出し、サーバーに送信する各LCRを取得します。createlcr_cb()プロシージャからの戻りフラグのOCI_XSTREAM_MORE_ROW_DATAビットがセットされている場合は、createchunk_cb()プロシージャを呼び出して各チャンクを取得します。また、このコールバックから戻されたフラグのOCI_XSTREAM_MORE_ROW_DATAビットがセットされている間、createchunk_cb()プロシージャを繰り返しコールします。このビットがセットされていない場合は、createlcr_cb()プロシージャを繰り返し呼び出して、次のLCRを取得します。このサイクルは、createlcr_cb()プロシージャがNULL LCRを戻すまで、またはコールの開始時からACK時間隔が経過した後のトランザクション境界まで繰り返されます。
OCICallbackXStreamInChunkCreate()コールバック関数からの有効なリターン・コードはOCI_CONTINUEまたはOCI_SUCCESSです。OCIXStreamInLCRCallbackSend()コールの処理を続行するには、このコールバック関数でOCI_CONTINUEが戻されるようにする必要があります。OCI_CONTINUE以外のリターン・コードは、クライアントがOCIXStreamInLCRCallbackSend()コールの即時終了を求めていることを示します。
現在のコールを終了すると、ネットワークはフラッシュされ、次のコールで別のネットワークのラウンドリップが発生するため、送信するLCRがない場合はすぐにNULL LCRが戻されるのを回避する必要があります。これにより、ネットワークのスループットが大幅に削減し、パフォーマンスが低下することがあります。短期間のアイドル中、NULL LCRをすぐに戻してネットワークのフラッシュを頻繁に回避するかわりに、コールバック・プロシージャに遅延をいくらか追加できます。
図26-1は、OCIXStreamInLCRCallbackSend()関数の実行フローを示しています。
* OCI_XSTREAM_MORE_ROW_DATAが設定されている場合です。
次は図26-1の説明です。
1で、ユーザーが2つのコールバックを提供するOCIXStreamInLCRCallbackSend()を呼び出します。この関数により、サーバーへのLCRインバウンド・ストリームが開始されます。
2で、この関数はcreatelcr_cb()プロシージャを呼び出し、コールバックからサーバーに送信するLCRを取得します。リターンLCRがNULLの場合、この関数は終了します。
2からのフラグが、現在のLCRに追加のデータが存在する(つまり、OCI_XSTREAM_MORE_ROW_DATAビットが設定されている)ことを示す場合、この関数は3に進みます。それ以外の場合は、2にループし、次のLCRを取得します。
3で、この関数はcreatechunk_cb()を呼び出し、サーバーに送信するチャンク・データを取得します。このコールバックからのフラグのOCI_XSTREAM_MORE_ROW_DATAビットがセットされている場合は、3を繰り返します。セットされていない場合は、2に戻り、ユーザーからの次のLCRを取得します。コールバック関数がOCI_CONTINUE以外の値を戻した場合は、OCIXStreamInLCRCallbackSend()コールが終了します。
サンプルのコールバック・モードのクライアント側擬似コードのスニペットを次に示します(簡単にするために、エラー・チェックは含まれていません)。
main
{
/* Attach to inbound server */
OCIXStreamInAttach();
/* Get the server's processed low position to determine
* the position of the first LCR to generate.
*/
OCIXStreamInProcessedLWMGet(&lwm);
while (TRUE)
{
/* Initiate LCR inbound stream */
OCIXStreamInLCRCallbackSend(createlcr_cb, createchunk_cb);
OCIXStreamInProcessedLWMGet(&lwm);
if (some terminating condition)
break;
}
OCIXStreamInDetach(&lwm);
}
createlcr_cb (IN usrctx, OUT lcr, OUT flag)
{
if (have more LCRs to send)
{
/* construct lcr */
OCILCRHeaderSet(lcr);
OCILCRRowColumnInfoSet(lcr);
if (lcr has LOB | LONG | XMLType columns)
Set OCI_XSTREAM_MORE_ROW_DATA flag;
if (lcr is LOB_ERASE | LOB_TRIM | LOB_WRITE)
OCILCRLobInfoSet(lcr);
}
else if (idle timeout expires)
{
lcr = null;
}
}
createchunk_cb (IN usrctx, OUT chunk, OUT flag)
{
/* set col_name, col_flag, chunk data, and so on */
construct_chunk;
if (last chunk of current column)
{
set col_flag |= OCI_LCR_COLUMN_LAST_CHUNK;
if (last column)
clear OCI_XSTREAM_MORE_ROW_DATA flag;
}
}
用途
クライアント側でキャッシュされるローカルの処理済最低位置を取得します。この関数は、クライアントがXStreamインバウンド・サーバーに連結されている間いつでもコールできます。クライアント側では、サーバーへのLCRのストリームのためのコールバック・モードを使用して(「OCIXStreamInLCRCallbackSend()」を参照)、コールバック・プロシージャ中この関数を呼び出すことができます。
構文
sword OCIXStreamInProcessedLWMGet ( OCISvcCtx *svchp,
OCIError *errhp,
ub1 *processed_low_position,
ub2 *processed_low_position_len,
ub4 mode );
パラメータ
コメント
XStreamインバウンド・サーバーへの連結後、サーバーの処理済最低位置のローカル・コピー(「OCIXStreamOutProcessedLWMSet()」を参照)はクライアントでキャッシュされます。このローカル・コピーは、次のコールでOCI_SUCCESSが戻されるごとに、サーバーの最低位置でリフレッシュされます。
OCIXStreamInAttach()
OCIXStreamInLCRSend()
OCIXStreamInLCRCallbackSend()
OCIXStreamInFlush()
リターン・コードはOCI_ERRORまたはOCI_SUCCESSです。
位置引数の事前割当て済バッファで渡す必要があります。このバッファの最大長はOCI_LCR_MAX_POSITION_LENです。この位置はDBA_XSTREAM_INBOUND_PROGRESSビューで表示されます。
クライアントでは、この位置を使用して、この位置以下でLCRを生成するために使用されたログが定期的に削除されるようにすることができます。
用途
OCIXStreamInAttach()コール後、インバウンド・サーバーで最初に発生したエラーを戻します。
構文
sword OCIXStreamInErrorGet ( OCISvcCtx *svchp,
OCIError *errhp,
sb4 *errcodep,
oratext *msgbuf,
ub2 msg_bufsize,
ub2 *msg_len,
oratext *txn_id,
ub2 txn_id_bufsize,
ub2 *txn_id_len );
パラメータ
OCIサービス・ハンドルです。
エラー・ハンドルです。
エラー・コードを戻します。
事前割当て済メッセージ・バッファです。
メッセージ・バッファのサイズです。
戻されるエラー・メッセージの長さです。
事前割当て済トランザクションIDバッファです。
トランザクションIDバッファのサイズです。
戻されるトランザクションIDの長さです。
コメント
戻されるトランザクションIDの最大サイズはOCI_LCR_MAX_TXID_LENです。txn_idに割り当てられたバッファが小さすぎる場合、このルーチンでORA-29258が戻されます。戻されるエラー・メッセージの最大サイズはOCI_ERROR_MAXMSG_SIZEです。msgbufに割り当てられたサイズが小さすぎる場合、戻されるメッセージは切り捨てられます。
用途
XStreamインバウンド・サーバーへのアタッチ中、ネットワークをフラッシュします。また、指定したサービス・コンテキストに関連付けられている、進行中のOCIXStreamInLCRSend()コールを終了します。
構文
sword OCIXStreamInFlush ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 mode );
パラメータ
コメント
リターン・コードはOCI_ERRORまたはOCI_SUCCESSです。
各コールでデータベース・ラウンドトリップが発生し、サーバーの処理済最低位置を取得します。この位置は、OCIXStreamInProcessedLWMGet()を使用して後でも取得できます。この関数は、サーバーに送信するLCRが存在せず、アタッチしたインバウンド・サーバーの進行状況をクライアントが認識しておく必要がある場合にのみコールします。
このコールは、OCIXStreamInLCRCallbackSend()のコールバック関数から呼び出される場合、OCI_ERRORを戻します。
用途
インバウンド・サーバーにチャンクを送信します。この関数は、OCIXStreamInLCRSend()コールの実行中は有効になります。
構文
sword OCIXStreamInChunkSend ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *column_name,
ub2 column_name_len,
ub2 column_dty,
oraub8 column_flag,
ub2 column_csid,
ub4 chunk_bytes,
ub1 *chunk_data,
oraub8 flag,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
指定したデータに関連付けられている列名です。列名は正規化し、Oracle Databaseのネーミング規則に従う必要があります。
列名の長さです。
LCRチャンク・データの型です(SQLT_CHRまたはSQLT_BINのいずれかである必要があります)。表26-5を参照してください。
列フラグです。(有効な列フラグは、「コメント」を参照してください。)各LOB、LONGまたはXMLType列の最後のチャンクにはOCI_LCR_COLUMN_LAST_CHUNKを指定する必要があります。
列のキャラクタ・セットIDです。これは、column_flagに OCI_LCR_COLUMN_XML_DATAビット・セットが含まれる場合にのみ必要です。
チャンク・データのバイト長です。
列データ・チャンクへのポインタです。列がNCLOBまたは可変幅CLOBの場合、入力チャンク・データはAL16UTF16形式である必要があります。チャンク・データは、表26-5で定義されているキャラクタ・セットである必要があります。
OCI_XSTREAM_MORE_ROW_DATA (0x01)を設定した場合、現在の列変更に追加のデータが含まれるようになります。現在のLCRの最後のチャンクを送信する際は、このビットを消去する必要があります。
OCI_DEFAULTを指定します。
コメント
次のLCR列フラグは、ビット単位のOR演算子を使用して結合可能です。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains LOB data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty LOB */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of current column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */
#define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff data */
#define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */ #define OCI_LCR_COLUMN_UPDATED /* col is updated */
#define OCI_LCR_COLUMN_32K_DATA /* col contains 32K data */
#define OCI_LCR_COLUMN_OBJECT_DATA /* col contains object data in xml format */
Streamsでは、LOB、LONGまたはXMLType列データは、複数のチャンクに分割されます。これらのデータ型の列が含まれる行変更の場合、関連付けられているLCRには、他の列型のデータのみが含まれます。すべてのLOB、LONGまたはXMLType列は、表26-4で定義されているように、LCRでNULLとして表現されるか、またはLCRには含まれません。
OCILCRRowColumnInfoSet()は、LCRでスカラー列のリストを生成するために提供されています。LOB、LONGまたはXMLType列の場合、OCIXStreamInChunkSend()は列内の各チャンクの値を設定するために提供されています。大きな列の場合、この関数は小さなチャンク・データずつ複数回連続して呼び出すことができます。XStreamインバウンド・サーバーでは、これらのチャンクをアセンブルし、指定する列に蓄積して変更を適用できます。
行変更のLCRには、適用サイトで行を固有に識別できるようにすべてのスカラー列が含まれている必要があります。表26-4は、DML操作ごとの各LCRで必要な列リストを示しています。
表26-4 最初のLCRで必要な列のリスト
| 行変更の最初のLCRのコマンド型 | 最初のLCRで必要な列 |
|---|---|
|
|
|
|
|
|
|
|
各LCRを作成した後、OCIXStreamInLCRSend()をコールしてそのLCRを送信できます。その後、OCIXStreamInChunkSend()を繰り返しコールし、そのLCR内の各LOB、LONGまたはXMLType列にチャンク・データを送信できます。異なる列へのチャンク値の送信はインターリーブできません。列に複数のチャンクが含まれる場合、新しい列に進む前に同じ列名を使用してこの関数を連続してコールする必要があります。列の順序は関連付けられていません。
この関数を呼び出す際、現在のLCRに追加のデータが存在する場合、OCI_XSTREAM_MORE_ROW_DATAをフラグ引数として渡す必要があります。現在のLCRの最後のチャンクを送信する際は、このフラグを消去して、現在のLCRの最後であることを示す必要があります。
この関数は、INSERT、UPDATEおよびLOB_WRITE操作にのみ有効です。INSERTおよびUPDATEには、複数のLOB、LONGまたはXMLType列を指定できますが、LOB_WRITE操作には1つのLOB列のみを指定できます。
サンプルの非コールバック・モードのクライアント側擬似コードのスニペットを次に示します(簡単にするために、エラー・チェックは含まれていません)。
main
{
/* Attach to inbound server */
OCIXStreamInAttach();
/* Get the server's processed low position to determine
* the position of the first LCR to generate.
*/
OCIXStreamInProcessedLWMGet(&lwm);
while (TRUE)
{
flag = 0;
/* construct lcr */
OCILCRHeaderSet(lcr);
OCILCRRowColumnInfoSet(lcr);
if (lcr has LOB | LONG | XMLType columns)
set OCI_XSTREAM_MORE_ROW_DATA flag;
status = OCIXStreamInLCRSend(lcr, flag);
if (status == OCI_STILL_EXECUTING &&
(OCI_XSTREAM_MORE_ROW_DATA flag set))
{
for each LOB/LONG/XMLType column in row change
{
for each chunk in column
{
/* set col_name, col_flag, chunk data */
construct chunk;
if (last chunk of current column)
col_flag |= OCI_LCR_COLUMN_LAST_CHUNK;
if (last chunk of last column)
clear OCI_XSTREAM_MORE_ROW_DATA flag;
OCIXStreamInChunkSend(chunk, col_flag, flag);
}
}
}
else if (status == OCI_SUCCESS)
{
/* get lwm when SendLCR call ends successfully. */
OCIXStreamInProcessedLWMGet(&lwm);
}
if (some terminating_condition)
break;
}
OCIXStreamInDetach();
}
用途
指定したトランザクションをコミットします。この関数は、クライアントからインバウンド・サーバーに、サーバー側ではなくクライアント側で実行されたトランザクションについて通知されるようにします。これにより、再起動の適用中、同じトランザクションが再送信されてもインバウンド・サーバーで無視されます。トランザクションIDおよびコミットの位置を抽出するには、インバウンド・サーバーにコミットLCRを指定する必要があります。
構文
sword OCIXStreamInCommit ( OCISvcCtx *svchp,
OCIError *errhp,
void *lcrp,
ub4 mode );
パラメータ
コメント
入力LCRの位置は、DBA_XSTREAM_INBOUND_PROGRESS.APPLIED_HIGH_POSITIONよりも上で、LCRのソース・データベースは連結されているインバウンド・サーバーのDBA_APPLY_PROGRESS.SOURCE_DATABASEと一致している必要があります。
定義済プリコミット・ハンドラが存在する場合、このコミットLCRが実行される際に実行されます。
インバウンド・サーバーで特定のデータ型がサポートされていないが、クライアント側で直接操作できるとします。クライアント側で、データベースへのトランザクション変更が直接実行され、OCIXStreamInCommit()を呼び出し、インバウンド・サーバーによってこのトランザクションがコミットされます。クライアント側でトランザクション自体を直接コミットすることはできません。かわりに、トランザクション変更は、このコマンド(OCIXStreamInCommit())でコミットされるため、トランザクションはアトミックになります。このため、クライアントのトランザクション中にインバウンド・サーバーが無効になる場合、トランザクション全体が正常にロールバックします。
用途
XStream In関数のセッション属性を設定します。
構文
sword OCIXStreamInSessionSet(OCISvcCtx *svchp,
OCIError *errhp,
oratext *attribute_name,
ub2 attribute_name_len,
void *attribute_value,
ub2 attribute_value_len,
ub2 attribute_dty,
ub4 mode);
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
属性名です。
attribute_nameの有効な値は次のとおりです。
#define OCIXSTREAM_ATTR_ATTACH_TIMEOUT "ATTACH_TIMEOUT_SECS" #define OCIXSTREAM_ATTR_MAX_ATTACH_RETRIES "MAX_ATTACH_RETRIES"
属性名の長さです。
属性値です。
属性値の長さです。
attribute_value_lenの最大値は128です。
属性のデータ型の配列へのポインタです。attribute_dtyの有効な値はDTYUB2のみです。ATTACH_TIMEOUT_SECSおよびMAX_ATTACH_RETRIESにDTYUB2以外のデータ型を指定するとエラーが戻されます。
OCI_DEFAULTを指定します。
コメント
OCIXStreamInAttach()をコールする前に、OCIXStreamInSessionSet()を呼び出す必要があります。
戻り値
成功した場合はOCI_SUCCESS、それ以外の場合はOCI_ERROR。
用途
XStreamアウトバウンド・サーバーに連結します。クライアント・アプリケーションは、専用の接続を使用してデータベースに接続する必要があります。
構文
sword OCIXStreamOutAttach ( OCISvcCtx *svchp,
OCIError *errhp,
oratext *server_name,
ub2 server_name_len,
ub1 *last_position,
ub2 last_position_len,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
XStreamアウトバウンド・サーバーの名前です。
XStreamアウトバウンド・サーバー名の長さです。
最後に受信したLCRの位置です。NULLにできます。
last_positionの長さです。
OCIXSTREAM_OUT_ATTACH_APP_FREE_LCRモードを指定した場合、アプリケーションで、アウトバウンド・サーバーからのLCRの解放が行われます。
コメント
OCIEnv環境ハンドルをOCI_OBJECTモードで作成し、サービス・コンテキストを接続済状態にして、この関数を発行する必要があります。この関数は、非ブロック化モードはサポートしていません。OCI_SUCCESSまたはOCI_ERRORのいずれかのステータス・コードを戻します。
1つのOracle Databaseインスタンスで複数のアウトバウンド・サーバーを構成できるため、アウトバウンド・サーバーの名前を指定する必要があります。この関数は、アウトバウンド・サーバーへの連結中にエラーが発生した場合、OCI_ERRORを戻します。XStreamアウトバウンド・サーバーには一度に1つのクライアントのみを連結できます。複数のクライアントを同じアウトバウンド・サーバーに連結しようとする、または同じサービス・ハンドルを使用して同じクライアントを複数のアウトバウンド・サーバーに連結しようとするとエラーが発生します。
last_positionパラメータは、ストリームの開始位置を確立するために使用します。このコールは、指定した位置がNULL以外で、サーバーの処理済最低位置より下の場合にOCI_ERRORを戻します(「OCIXStreamOutProcessedLWMSet()」を参照)。それ以外の場合は、指定したlast_positionより上の位置のLCRをユーザーに送信します。
last_positionがNULLである場合、ストリームはサーバーでメンテナンスされている処理済最低位置から開始されます。
用途
アウトバウンド・サーバーから連結解除します。
構文
sword OCIXStreamOutDetach ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 mode );
パラメータ
コメント
この関数は、アウトバウンド・サーバーからの連結解除前に現在のローカルの処理済最低位置をサーバーに送信します。アウトバウンド・サーバーは、このコール後、自動的に再起動されます。この関数は、OCIXStreamOutReceive()コールが実行中に呼び出された場合、OCI_ERRORを戻します。
用途
アウトバウンド・ストリームからLCRを取り出します。LCRが使用可能な場合、この関数はすぐにそのLCRを戻します。各LCRの期間は2つの連続するOCIXStreamOutLCRReceive()コール間の間隔に制限されます。ストリーム内にLCRが存在しない場合、このコールはタイムアウト後にNULL LCRを戻します。
構文
sword OCIXStreamOutLCRReceive ( OCISvcCtx *svchp,
OCIError *errhp,
void **lcrp,
ub1 *lcrtype,
oraub8 *flag,
ub1 *fetch_low_position,
ub2 *fetch_low_position_len,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ストリームから受信されるLCRへのポインタです。使用可能なLCRが存在する場合、状態コードOCI_STILL_EXECUTINGでこのLCRが戻されます。コールが終了すると、状態コードOCI_SUCCESSでNULL LCRが戻されます。
この値は、lcrpがNULLでない場合にのみ有効です。
リターン・フラグです。ビットOCI_XSTREAM_MORE_ROW_DATA (0x01)を設定した場合、このLCRには追加のデータが含まれるようになります。残りのデータを取得するには、OCIXStreamOutReceiveChunk()関数を使用する必要があります。
XStreamアウトバウンド・サーバーのフェッチ最低位置です。この値は、リターン・コードがOCI_SUCCESSである場合のみ戻されます。オプションです。NULL以外の場合、戻り値にOCI_LCR_MAX_POSITION_LENバイトを事前に割り当てる必要があります。
fetch_low_positionの長さです。
OCI_DEFAULTを指定します。
コメント
OCIXStreamOutLCRReceive()コールごとのネットワークのラウンドトリップを回避するため、接続はこのコールに連結され、サーバー側でネットワーク・バッファがLCRで満たされるようになり、後続のコールでネットワークからのLCRを迅速に受信できるようになります。サーバー側で、コール開始以降、ACK間隔が経過した後、各コールがトランザクション境界で終了されます。ストリーム内にLCRが存在しない場合、アイドルのタイムアウト経過後、サーバーでコールが終了されます。
リターン・コード:
OCI_STILL_EXECUTINGは、現在のコールがまだ実行中であることを意味します。指定したサービス・ハンドルに関連付けられている接続は、サーバーからのLCRのストリームのためにこのコールにまだ連結されています。同じ接続を使用して、OCIStmtExecute()、OCIStmtFetch()、OCILobRead()など、データベースのラウンドトリップを必要とするOCIコールを実行しようとすると、エラーが戻されます。OCILCR*コールにはラウンドトリップは必要ないため、このコールの実行中は有効になります。
OCI_SUCCESSは現在のコールが完了したことを意味します。同じサービス・コンテキストからOCIStmt*、OCILob*などを実行できます。
OCI_ERRORは現在のコールでエラーがいくつか発生したことを意味します。エラーに関する情報を取得するにはOCIErrorGet()を使用します。
このコールは、リターン・コードがOCI_SUCCESSである場合、常にNULL LCRを戻します。さらに、この値以下のコミット位置でアウトバウンド・サーバーがすべてのトランザクションを受信したことを示すフェッチ最低位置を戻します。
用途
コールバックを使用してアウトバインド・サーバーからLCRストリームを取得するために使用します。受信されたLCRごとに呼び出されるコールバック・プロシージャを指定する必要があります。ストリーム内の一部のLCRに、LOB、LONGまたはXMLType列が含まれる場合、各チャンクを処理するために2番目のコールバックを指定する必要があります(「OCIXStreamOutChunkReceive()」を参照)。
構文
sword OCIXStreamOutLCRCallbackReceive (
OCISvcCtx *svchp,
OCIError *errhp,
OCICallbackXStreamOutLCRProcess processlcr_cb,
OCICallbackXStreamOutChunkProcess processchunk_cb,
void *usrctxp,
ub1 *fetch_low_position,
ub2 *fetch_low_position_len,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
クライアントで受信される各LCRを処理するためのコールバック関数です。NULL以外にしてください。
受信されたLCR内の各チャンクを処理するためのコールバック関数です。追加のチャンク・データを含んだLCRを受信するとみなされない場合は、NULLにできます。
両方のコールバック・プロシージャに渡されるユーザー・コンテキストです。
XStreamアウトバウンド・サーバーのフェッチ最低位置です(「OCIXStreamOutLCRReceive()」を参照)。オプションです。
fetch_low_positionの長さです。
OCI_DEFAULTを指定します。
コメント
リターン・コードはOCI_SUCCESSまたはOCI_ERRORです。
processlcr_cb引数はOCICallbackXStreamOutLCRProcess型にしてください。
typedef sb4 (*OCICallbackXStreamOutLCRProcess)
(void *usrctxp, void *lcrp, ub1 lcrtyp, oraub8 flag);
OCICallbackXStreamOutLCRProcess()のパラメータは次のとおりです。
ユーザー・コンテキストへのポインタです。
たった今受信されたLCRへのポインタです。
LCR型(OCI_LCR_XROWまたはOCI_LCR_XDDL)です。
OCI_XSTREAM_MORE_ROW_DATAを設定した場合、現在のLCRに追加のチャンク・データが含まれるようになります。
processlcr_cb()プロシージャの入力パラメータは、ユーザー・コンテキスト、たった今受信されたLCR、その型、およびLCRに追加のデータが含まれているかどうかを示すフラグです。使用可能なLCRが存在する場合、このコールバックはすぐに呼び出されます。ストリーム内にLCRが存在しない場合は、アイドルのタイムアウト後、OCI_SUCCESSリターン・コードでこのコールは終了します。OCICallbackXStreamOutLCRProcess()コールバック関数からの有効なリターン・コードはOCI_CONTINUEまたはOCI_SUCCESSです。OCIXStreamOutLCRCallbackReceive()コールの処理を続行するには、このコールバック関数でOCI_CONTINUEが戻されるようにする必要があります。OCI_CONTINUE以外のリターン・コードは、クライアントがOCIXStreamOutLCRCallbackReceive()の即時終了を求めていることを示します。
関連項目:
processchunk_cb引数はOCICallbackXStreamOutChunkProcess型にしてください。
typedef sb4 (*OCICallbackXStreamOutChunkProcess) (void *usrctxp, oratext *column_name, ub2 column_name_len, ub2 column_dty, oraub8 column_flag, ub2 column_csid, ub4 chunk_bytes, ub1 *chunk_data, oraub8 flag );
OCICallbackXStreamOutChunkProcess()のパラメータは次のとおりです。
ユーザー・コンテキストへのポインタです。
現在のチャンクの列名です。
列名の長さです。
チャンク・データの型(SQLT_CHRまたはSQLT_BINのいずれか)です。
「OCIXStreamInChunkSend()」の「コメント」を参照してください。
列のキャラクタ・セットIDです。列がXMLType列である(つまり、column_flagにOCI_LCR_COLUMN_XML_DATAビット・セットが含まれている)場合にのみ適用します。
チャンク・データのバイト長です。
チャンク・データのポインタです。
OCI_XSTREAM_MORE_ROW_DATAを設定した場合、現在のLCRに追加のチャンク・データが含まれるようになります。
processchunk_cb()プロシージャの入力パラメータは、ユーザー・コンテキスト、チャンクに関する情報およびフラグです。flag引数にOCI_XSTREAM_MORE_ROW_DATA (0x01)ビット・セットが含まれる場合、現在のLCRには追加のデータが存在します。
OCICallbackXStreamOutChunkProcess()コールバック関数からの有効なリターン・コードはOCI_CONTINUEまたはOCI_SUCCESSです。OCIXStreamOutLCRCallbackReceive()コールの処理を続行するには、このコールバック関数でOCI_CONTINUEが戻されるようにする必要があります。OCI_CONTINUE以外のリターン・コードは、クライアントがOCIXStreamOutLCRCallbackReceive()の即時終了を求めていることを示します。
OCIコールは、LCR内の各フィールドにアクセスするために提供されています。LCRにスカラー列のみが含まれる場合、そのLCRの期間はprocesslcr_cb()プロシージャのみに制限されます。LCRにチャンク・データがいくらか含まれる場合、そのLCRの期間は、すべてのチャンクが処理されるまで拡張されます。後でLCRデータにアクセスする場合、解放前にそのLCRのコピーを作成しておく必要があります。
OCIXStreamOutLCRReceive()の場合、サーバー側で、コールの開始以降、各ACK間隔の経過後または各アイドル・タイムアウト後に、各コールがトランザクション境界で終了されます。デフォルトのACK間隔は30秒で、デフォルトのアイドル・タイムアウトは1秒です。これらの値を調整するには、「サーバー・ハンドル属性」を参照してください。この関数は、コールが終了した際、フェッチ最低位置も戻します。
図26-2は、OCIXStreamOutLCRCallbackReceive()関数の実行フローを示しています。
* OCI_XSTREAM_MORE_ROW_DATAが設定されている場合です。
次は図26-2の説明です。
1で、クライアント側で2つのコールバックを提供するOCIXStreamOutLCRCallbackReceive()が呼び出されます。この関数により、サーバーからのLCRアウトバウンド・ストリームが開始されます。
2で、この関数はストリームからLCRを受信して、受信したこのLCRでprocesslcr_cb()プロシージャを呼び出します。また、現在のLCRに追加のデータがある場合は、OCI_XSTREAM_MORE_ROW_DATAフラグをprocesslcr_cb()に渡します。
現在のLCRに追加のチャンクが含まれていない場合、この関数はストリーム内の次のLCRに対して2を繰り返します。
3で、現在のLCRに追加のチャンク・データが含まれる場合、この関数はOCI_XSTREAM_MORE_ROW_DATAフラグを使用して、受信されたチャンクごとにprocesschunk_cb()を呼び出します。このフラグは、現在のLCRの最後のチャンクでコールバックが呼び出されると消去されます。
ストリーム内に追加のLCRが存在する場合は、2にループします。この処理は、現在のコールの最後までか、1秒間にストリーム内にLCRが存在しない場合、またはコールバック関数でOCI_CONTINUE以外の値が戻される場合に続行されます。
コールバック・モードのサンプルの擬似コードを次に示します。
main
{
/* Attach to outbound server specifying last position */
OCIXStreamOutAttach(last_pos);
/* Update the local processed low position */
OCIXStreamOutProcessedLWMSet(lwm);
while (TRUE)
{
OCIXStreamOutLCRCallbackReceive(processlcr_cb,
processchunk_cb, fwm);
/* Use fetch low position(fwm)
* to update processed lwm if applied.
*/
/* Update the local lwm so it is sent to
* server during next call.
*/
OCIXStreamOutProcessedLWMSet(lwm);
if (some terminating_condition)
break;
}
OCIXStreamOutDetach();
}
processlcr_cb (IN lcr, IN flag)
{
/* Process the LCR just received */
OCILCRHeaderGet(lcr);
OCILCRRowColumnInfoGet(lcr);
if (lcr is LOB_WRITE | LOB_TRIM | LOB_ERASE)
OCILCRLobInfoGet(lcr);
if (OCI_XSTREAM_MORE_ROW_DATA flag set)
prepare_for_chunk_data;
else
process_end_of_row;
}
processchunk_cb (IN chunk, IN flag)
{
process_chunk;
if (OCI_XSTREAM_MORE_ROW_DATA flag not set)
process_end_of_row;
}
用途
処理済最低位置のローカル・コピーを更新します。この関数は、OCIXStreamOutAttach()コールとOCIXStreamOutDetach()コールの間、いつでもコールできます。クライアント側では、サーバーからのLCRのストリームのためのコールバック・メカニズムを使用して(「OCIXStreamOutLCRCallbackReceive()」を参照)、コールバック・プロシージャ中この関数を呼び出すことができます。
構文
sword OCIXStreamOutProcessedLWMSet ( OCISvcCtx *svchp,
OCIError *errhp,
ub1 *processed_low_position,
ub2 processed_low_position_len,
ub4 mode );
パラメータ
コメント
処理済最低位置は、処理されたLCRとそれ以降のすべてのLCRを示します。XStreamアウトバウンド・サーバーへの連結に成功した後は、処理済最低位置のローカル・コピーはクライアント側でメンテナンスされます。すでに処理済のトランザクションが含まれているアーカイブ済REDOログ・ファイルを消去できるように、この位置はサーバー側に定期的に送信されます。
リターン・コードはOCI_SUCCESSまたはOCI_ERRORです。
XStreamOut関数を使用するクライアントは、処理済の内容に基づいて処理済最低位置を追跡し、その位置が変更されるたびにこの関数をコールする必要があります。これを実行することにより、次の更新時に現在の値がサーバーに送信されます。この処理は、OCIXStreamOutLCRCallbackReceive()およびOCIXStreamDetach()コールの先頭で行われます。OCIXStreamOutLCRReceive()コールでは、アウトバウンド・ストリームを開始するリクエストが開始されたときに、処理済最低位置がサーバーに送信されます。ストリームの進行中には送信されません。
DBA_XSTREAM_OUTBOUND_PROGRESSビューを問い合せて、処理済最低位置がサーバー側で保存されたことを確認できます。
用途
クライアント側で、各LOB、LONGまたはXMLType列のデータを一度に1つのチャンクずつ取り出すことができます。
構文
sword OCIXStreamOutChunkReceive ( OCISvcCtx *svchp,
OCIError *errhp,
oratext **column_name,
ub2 *column_name_len,
ub2 *column_dty,
oraub8 *column_flag,
ub2 *column_csid,
ub4 *chunk_bytes,
ub1 **chunk_data,
oraub8 *flag,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
データが含まれている列の名前です。
列名の長さです。
列のチャンク・データ型(SQLT_CHRまたはSQLT_BINのいずれか)です。
列フラグです。有効なフラグは、「コメント」を参照してください。
列のキャラクタ・セットIDです。これは、XMLType列の場合、つまり、column_flagにOCI_LCR_COLUMN_XML_DATAビット・セットが含まれている場合にのみ戻されます。
戻されるチャンク内のバイト数です。
LCR内のチャンク・データへのポインタです。LCRおよびその内容はこの関数でメンテナンスされるため、クライアント側でこのバッファを事前に割り当てないでください。
OCI_XSTREAM_MORE_ROW_DATAを設定した場合、現在のLCRに受信される追加のチャンクが含まれるようになります。
OCI_DEFAULTを指定します。
コメント
Streamsでは、LOB、LONGまたはXMLType列データは、オンラインREDOログ・ファイル内に格納されている形式に基づき、複数のLCRに分割されます。したがって、これらの列が含まれている行変更の場合、複数のLCRが作成されることがあります。行変更の最初のLCRには、すべてのスカラー列の列データが含まれます。これらのデータは、その行変更の際に後続のLCRで送信されるため、最初のLCR内のLOB、LONGまたはXMLTypeはすべて、NULLに設定されます。表26-5に示すように、これらの列データは、RAW (SQLT_BIN)またはVARCHAR2 (SQLT_CHR)チャンクのいずれかとしてLCR内に格納されます。
表26-5 LCRでのLOBまたはLONGデータの格納
| ソース列のデータ型 | Streams LCRデータ型 | Streams LCRキャラクタ・セット |
|---|---|---|
|
|
該当なし |
固定幅 |
|
クライアント側キャラクタ・セット |
可変幅 |
|
AL16UTF16 |
|
|
AL16UTF16 |
|
|
チャンクから取得された列 |
Streamsでは、LOB、LONGまたはXMLType列データは、オンラインREDOログ・ファイル内に格納されている形式に基づき、複数のチャンクに分割されます。これらのデータ型の列が含まれる行変更の場合、関連付けられているLCRには、他のスカラー列のデータのみが含まれます。すべてのLOB、LONGまたはXMLType列は、LCRでNULLとして表現されるか、またはLCRには含まれません。表26-5に示すように、これらの列の実際のデータは、RAW (SQLT_BIN)またはVARCHAR2 (SQLT_CHR)チャンクのいずれかとして各LCRに続き送信されます。
次のLCR列フラグは、ビット単位のOR演算子を使用して結合可能です。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains LOB data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty LOB */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of current column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */
#define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff data */
#define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */ #define OCI_LCR_COLUMN_UPDATED /* col is updated */
#define OCI_LCR_COLUMN_32K_DATA /* col contains 32K data */
#define OCI_LCR_COLUMN_OBJECT_DATA /* col contains object data in xml format */
リターン・コードはOCI_ERRORまたはOCI_SUCCESSです。
このコールは、現在のLCRにLOB、LONGまたはXMLType列が含まれていない場合に呼び出されると、NULL列名およびNULLチャンク・データを戻します。この関数は、OCIXStreamOutLCRReceive()コールが実行中である場合にのみ有効です。それ以外の場合は、呼び出されるとエラーが戻されます。
OCIXStreamOutLCRReceive()からのリターン・フラグにOCI_XSTREAM_MORE_ROW_DATAビット・セットが含まれている場合、OCIXStreamOutChunkReceive()を反復的にコールし、次の行変更の前に(つまり、次のOCIXStreamOutLCRReceive()コールを実行する前)、現在の行変更に属するすべてのチャンクを取り出す必要があります。それ以外の場合は、エラーが戻されます。
非コールバック・モードのサンプルの擬似コードを次に示します。
main
{
/* Attach to outbound server specifying last position */
OCIXStreamOutAttach(last_pos);
/* Update the local processed low position */
OCIXStreamOutProcessedLWMSet(lwm);
while (TRUE)
{
status = OCIXStreamOutLCRReceive(lcr, flag, fwm);
if (status == OCI_STILL_EXECUTING)
{
/* Process LCR just received */
OCILCRHeaderGet(lcr);
OCILCRRowColumnInfoGet(lcr);
while (OCI_XSTREAM_MORE_ROW_DATA flag set)
{
OCIXStreamReceiveChunk(chunk, flag, );
process_chunk;
}
process_end_of_row;
}
else if (status == OCI_SUCCESS)
{
/* Use fetch low position(fwm)
* to update processed lwm if applied.
*/
/* Update the local lwm so it is sent to
* server during next call.
*/
OCIXStreamOutProcessedLWMSet(lwm);
if (some terminating_condition)
break;
}
}
OCIXStreamOutDetach();
}
用途
ProcessLCRStream()コールバック関数では、現在のLCRのすべてのチャンクを取り出すために(つまりOCI_ERRORまたはOCI_SUCCESSが戻されるまで)クライアント側でOCIXStreamOutGetNextChunk()が繰り返しコールされる必要があります。これが実行されないと、コールバック関数の終了時にエラーが発生します。
構文
sword OCIXStreamOutGetNextChunk ( OCISvcCtx *svchp,
OCIError *errhp,
oratext **column_name,
ub2 *column_name_len,
ub2 *column_dty,
oraub8 *column_flag,
ub4 *rtn_bytes,
ub1 **bufp,
ub4 *op_offset,
ub4 *op_size,
ub4 mode );
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
データが含まれているLOB列の名前です。
列名の長さです。
列のデータ型(SQLT_CHRまたはSQLT_BINのいずれか)です。
列フラグです。有効な値は「コメント」にリストされています。
戻されるバッファのバイト数です。
LCR内のLOBチャンク・データへのポインタです。LCRおよびその内容はこの関数でメンテナンスされるため、クライアント側でこのバッファを事前に割当て解除しないでください。
LOB操作のオフセットです。オプションです。引数がNULLの場合、データは戻されません。LOB_WRITEおよびLOB_TRIM操作にのみ関連します。他の場合はゼロが戻されます。
LOB操作のサイズです。オプションです。引数がNULLの場合、データは戻されません。LOB_TRIMおよびLOB_ERASE操作にのみ関連します。他の場合はゼロが戻されます。
今のところはOCI_DEFAULTを指定します。
コメント
OCIEnv環境ハンドルをOCI_OBJECTモードで作成し、サービス・コンテキストを接続済状態にして、この関数を発行する必要があります。
Streamsでは、REDOログに格納されている形式に基づいて、LOBまたはLONG列データが複数のLCRに分割されます。したがって、Re LONG列を含む行変更の場合、複数のLCRが作成されることがあります。行変更の最初のLCRには、すべてのスカラー列の列データが含まれます。これらのデータは、その行変更の際に後続のLCRで送信されるため、最初のLCRのLOBまたはLONG列はすべてNULLに設定されます。LONG列データはLOBに暗黙的に変換されてからクライアントに送信されます。表26-5に示すように、LOBまたはLONGデータは、RAW (SQLT_BIN)またはVARCHAR2 (SQLT_CHR)としてLCRに格納されます。
OCIXStreamOutProcessLCRStream()関数によりクライアント側で各LOBまたはLONG列のデータを1回に1つのチャンクずつ取り出すことができます。1つの列に属するすべてのチャンクが連続して順に戻されます。1つの列からのチャンク・データがすべて戻されてから、次の列に移ります。列が戻される順序は固定されていません。クライアントはLOB列の順序に依存せずに、戻される列名に依存する必要があります。
現在のLCRがスカラー列のみを含む場合にOCIXStreamOutGetNextChunk()を呼び出すと、列名はNULLになり、データは戻されません。
戻り列フラグは、各チャンク・データの詳細を示します。たとえば、各列の最後のチャンクでは、OCI_LCR_COLUMN_LAST_CHUNKフラグが必ず戻されます。
次のフラグで列プロパティを指定できます。ビット単位のOR演算子を使用して、これらのフラグの倍数を結合できます。
#define OCI_LCR_COLUMN_LOB_DATA /* column contains lob data */ #define OCI_LCR_COLUMN_LONG_DATA /* column contains long data */ #define OCI_LCR_COLUMN_EMPTY_LOB /* column has an empty lob */ #define OCI_LCR_COLUMN_LAST_CHUNK /* last chunk of column */ #define OCI_LCR_COLUMN_AL16UTF16 /* column is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB /* column has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA /* column contains xml data */ #define OCI_LCR_COLUMN_XML_DIFF /* column contains xmldiff */ #define OCI_LCR_COLUMN_ENCRYPTED /* column is encrypted */
OCIXStreamOutProcessLCRStream()コールでは、LCRが取得されるたびにクライアント側でコールバック関数が呼び出されます。LOBまたはLONG列を含むLCRの場合は、行変更の最初のLCRがこのコールバック関数に渡されます。このコールバック関数で、クライアント側ではOCIXStreamOutGetNextChunk()が繰り返しコールされて、各LOBまたはLONG列のチャンクをすべて取り出すことができます。クライアントで現在の行変更のデータがすべて消費されると、この関数はOCI_SUCCESSを戻します。
ProcessLCRStreamコールバック関数では、現在のLCRのすべてのチャンクを取り出すために(つまりOCI_ERRORまたはOCI_SUCCESSが戻されるまで)クライアント側でOCIXStreamOutGetNextChunk()が繰り返しコールされる必要があります。これが実行されないと、コールバック関数の終了時にエラーが発生します。
この関数が有効なのは、ProcessLCRStreamコールバック関数の呼出し中のみです。それ以外の場合は、これが呼び出されるとエラーが発生します。
この関数は、次の値を返します。
OCI_SUCCESSは、現在のLCRのデータがすべて取り出されたことを意味します。戻された列とバッファ情報を確認して、戻された列のデータにアクセスできます。
OCI_NEED_DATAは、現在のLCRのストリームにまだデータがあることを意味します。戻された列とバッファ情報を確認して、戻された列のデータにアクセスできます。
OCI_ERRORは、エラーがあることを意味します。OCIErrorGet()を使用して、エラー・コードを取得できます。
サンプルのクライアント・コード・スニペットを次に示します(簡単にするために、エラー・チェックは含まれていません)。
main()
{
...
OCIServerAttach(...); /* Connect to Oracle db */
/* Attach to the outbound server named ‘TT1' */
OCIXStreamOutAttach(...,“TT1", 3, hwm, hwm_len, (OCIDate *)0, OCI_DEFAULT);
/*--------------------------------------------------------
Initialize the LWM by querying the client's system tables
or set to zero and let the outbound server determines the LWM.
--------------------------------------------------------*/
Init_lwm(&lwm);
/*---------------------------------------------------------
ProcessLCR_CB is a callback function to process each LCR (see below).
usrctxp is the user context to be passed to the callback function.
--------------------------------------------------------*/
while (OCIXStreamOutProcessLCRStream(..., lwm, lwm_len,(OCIDate *)0,
ProcessLCR_CB, usrctxp, 0, OCI_DEFAULT) == OCI_SUCCESS)
{
/* Client maintains LWM. */
Maintain_lwm(&lwm);
...
}
/* detach from the outbound server */
OCIXStreamOutDetach(..., lwm, lwm_len, (OCIDate *)0, OCI_DEFAULT);
}
/* Sample callback routine to OCIXStreamOutProcessLCRStream() */
sb4 ProcessLCR_CB (void *ctxp, void *lcrp, ub1 lcrtyp)
{
/* Get header information for current LCR */
status = OCILCRGetHeader(lcrp,...);
if (status != OCI_SUCCESS)
handle_error();
if (lcrtype == OCI_LCR_XROW)
{
if (OCILcrRowGetColumnInfo(lcrp, ...) != OCI_SUCCESS)
handle_error();
process_scalar_columns(...);
do
{
status = OCIXStreamOutGetNextChunk(..., &colname, &colnamelen,
&coldty, &flag, &rtn_bytes,
bufp, ...);
if (status == OCI_ERROR)
handle_error();
process_lob_chunk(...);
} while (status == OCI_NEED_DATA);
if (status == OCI_ERROR)
handle_error();
}
return OCI_CONTINUE;
}
用途
XStream Out関数のセッション属性を設定します。
構文
sword OCIXStreamOutSessionSet(OCISvcCtx *svchp,
OCIError *errhp,
oratext *attribute_name,
ub2 attribute_name_len,
void *attribute_value,
ub2 attribute_value_len,
ub2 attribute_dty,
ub4 mode);
パラメータ
サービス・ハンドル・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
属性名です。
attribute_nameの有効な値は次のとおりです。
#define OCIXSTREAM_ATTR_ATTACH_TIMEOUT "ATTACH_TIMEOUT_SECS" #define OCIXSTREAM_ATTR_MAX_ATTACH_RETRIES "MAX_ATTACH_RETRIES"
属性名の長さです。
属性値です。
属性値の長さです。
attribute_value_lenの最大値は128です。
属性のデータ型の配列へのポインタです。attribute_dtyの有効な値はDTYUB2のみです。ATTACH_TIMEOUT_SECSおよびMAX_ATTACH_RETRIESにDTYUB2以外のデータ型を指定するとエラーが戻されます。
OCI_DEFAULTを指定します。
コメント
OCIXStreamOutAttach()をコールする前に、OCIXStreamOutSessionSet()を呼び出す必要があります。
戻り値
成功した場合はOCI_SUCCESS、それ以外の場合はOCI_ERROR。
