この項および表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
。