ダイレクト・パス・ロード関数

表17-4は、この項で説明しているダイレクト・パス・ロード関数を示しています。

表17-4 ダイレクト・パス・ロード関数

関数	用途
「OCIDirPathAbort()」	ダイレクト・パス処理を終了します。
「OCIDirPathColArrayEntryGet()」	列配列内の特定のエントリを取得します。
「OCIDirPathColArrayEntrySet()」	列配列内の特定のエントリを特定の値に設定します。
「OCIDirPathColArrayReset()」	行配列の状態をリセットします。
「OCIDirPathColArrayRowGet()」	特定の行番号の基本行ポインタを取得します。
「OCIDirPathColArrayToStream()」	列配列からダイレクト・パス・ストリーム形式に変換します。
「OCIDirPathDataSave()」	データ・セーブポイントを実行するか、またはロードされたデータをコミットしてロード操作を終了します。
「OCIDirPathFinish()」	ロードされたデータを終了およびコミットします。
「OCIDirPathFlushRow()」	非推奨です。
「OCIDirPathLoadStream()」	ダイレクト・パス・ストリーム形式に変換されたデータをロードします。
「OCIDirPathPrepare()」	行の変換またはロードを行うために、ダイレクト・パス・インタフェースを準備します。
「OCIDirPathStreamReset()」	ダイレクト・パス・ストリームの状態をリセットします。

OCIDirPathAbort()

用途

ダイレクト・パス処理を終了します。

構文

sword OCIDirPathAbort   ( OCIDirPathCtx          *dpctx,
                          OCIError               *errhp );

パラメータ

dpctx (IN): ダイレクト・パス・コンテキスト・ハンドルです。
errhp (IN/OUT): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ダイレクト・パス処理のかわりにサーバーによって維持されていたすべての状態は、終了によって破棄されます。ダイレクト・パス・ロードの場合、終了操作前にロードされたデータは問合せで参照できなくなります。ロードされていなかったデータが、まだセグメントの領域を使用している可能性があります。索引メンテナンス処理などのロード完了処理は行われません。

OCIDirPathColArrayEntryGet()

用途

列配列内の指定のエントリを取得します。

構文

sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray   *dpca,
                                   OCIError             *errhp,
                                   ub4                  rownum,
                                   ub2                  colIdx,
                                   ub1                  **cvalpp,
                                   ub4                  *clenp,
                                   ub1                  *cflgp );

パラメータ

dpca (IN/OUT)

ダイレクト・パス列配列ハンドルです。

errhp (IN)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

rownum (IN)

0 (ゼロ)ベースの行オフセットです。

colIdx (IN)

列パラメータ・リストの作成時に使用される列の索引です。

cvalpp (IN/OUT)

列データのポインタへのポインタです。

clenp (IN/OUT)

列データの長さへのポインタです。

cflgp (IN/OUT)

列フラグへのポインタです。

次のいずれかの値が戻されます。

OCI_DIRPATH_COL_COMPLETE - 列にすべてのデータが存在します。
OCI_DIRPATH_COL_NULL - 列がNULLです。
OCI_DIRPATH_COL_PARTIAL - 一部の列データが提供されます。

cflgpがOCI_DIRPATH_COL_NULLに設定されている場合、cvalppパラメータおよびclenpパラメータには値が設定されません。

OCIDirPathColArrayEntrySet()

用途

列配列内の指定のエントリを提供される値に設定します。

構文

sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray   *dpca,
                                   OCIError             *errhp,
                                   ub4                  rownum,
                                   ub2                  colIdx,
                                   ub1                  *cvalp,
                                   ub4                  clen,
                                   ub1                  cflg );

パラメータ

dpca (IN/OUT): ダイレクト・パス列配列ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
rownum (IN): 0 (ゼロ)ベースの行オフセットです。
colIdx (IN): 列パラメータ・リストの作成時に使用される列の索引です。
cvalp (IN): 列データへのポインタです。
clen (IN): 列データの長さです。
cflg (IN): 列フラグです。次のいずれかの値が戻されます。

OCI_DIRPATH_COL_COMPLETE - 列にすべてのデータが存在します。
OCI_DIRPATH_COL_NULL - 列がNULLです。
OCI_DIRPATH_COL_PARTIAL - 一部の列データが提供されます。

cflgがOCI_DIRPATH_COL_NULLに設定されている場合、cvalpパラメータおよびclenパラメータは使用されません。

例

次の例では、列配列内の最初の行のデータのソースにaddr、長さにlenを設定します。この例では、列は、colIdによって識別されます。

err = OCIDirPathColArrayEntrySet(dpca, errhp, (ub2)0, colId, addr, len,
          OCI_DIRPATH_COL_COMPLETE);

OCIDirPathColArrayReset()

用途

列配列の状態をリセットします。

構文

sword OCIDirPathColArrayReset ( OCIDirPathColArray   *dpca,
                                OCIError             *errhp );

パラメータ

dpca (IN): ダイレクト・パス列配列ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

列配列の状態は、大きな列内でピース単位操作を行うとき、および列のロード中にエラーが発生したときに、リセットする必要があります。最後のOCIDirPathColArrayReset()コールによってOCI_NEED_DATAまたはOCI_CONTINUEが戻された場合、列配列はリセットしないでください。これは、まだ行の変換中であるためです。OCI_DIRPATH_COL_ERRORを使用して、OCI_NEED_DATAから現在の行を削除してください。

OCIDirPathColArrayRowGet()

用途

特定の行番号の列配列行ポインタを取得します。

構文

sword OCIDirPathColArrayRowGet ( OCIDirPathColArray   *dpca,
                                 OCIError             *errhp,
                                 ub4                  rownum,
                                 ub1                  ***cvalppp,
                                 ub4                  **clenpp,
                                 ub1                  **cflgpp );

パラメータ

dpca (IN/OUT): ダイレクト・パス列配列ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
rownum (IN): 0 (ゼロ)ベースの行オフセットです。
cvalppp (IN/OUT): 列データのポインタのベクトルへのポインタです。
clenpp (IN/OUT): 列データの長さのベクトルへのポインタです。
cflgpp (IN/OUT): 列フラグのベクトルへのポインタです。

指定行の列配列エントリにポインタが戻ります。ポインタが戻ると、アプリケーションでは簡単なポインタ計算をして特定行の列間で反復処理を行います。このインタフェースを使用すると、各列でOCIDirPathColArrayEntrySet()をコールする場合と比べて、行の列配列エントリの取得または設定を効率的に行うことができます。アプリケーションから、列配列の境界を超えてメモリーを参照解除しないでください。列配列の次元は、列配列の属性として取得できます。

OCIDirPathColArrayToStream()

用途

列配列形式からダイレクト・パス・ストリーム形式に変換します。

構文

sword OCIDirPathColArrayToStream ( OCIDirPathColArray     *dpca,
                                   OCIDirPathCtx  const   *dpctx,
                                   OCIDirPathStream       *dpstr,
                                   OCIError               *errhp, 
                                   ub4                    rowcnt,
                                   ub4                    rowoff );

パラメータ

dpca (IN): ダイレクト・パス列配列ハンドルです。
dpctx (IN): ロードされているオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
dpstr (IN/OUT): ダイレクト・パス・ストリーム・ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
rowcnt (IN): 列配列内の行数です。
rowoff (IN): 列配列内の開始索引です。

このインタフェースは、外部形式の列配列表現データを、ダイレクト・パス・ストリーム形式に変換するときに使用します。変換された形式は、OCIDirPathLoadStream()を使用したロードに適しています。

ダイレクト・パス・ストリーム形式の列データは、Oracle Databaseの内部表現のデータに変換されます。すべての変換は、この2タスク・インタフェースのクライアント側で行われ、すべての変換エラーは、このインタフェースへのコールと同時に発生します。エラーが発生した行および列に関する情報は、列配列ハンドルの属性として取得できます。

スレッド環境では、同時に行われるOCIDirPathColArrayToStream()操作によって同じダイレクト・パス・コンテキスト・ハンドルが参照されることがあります。ただし、このインタフェースでは、ダイレクト・パス・コンテキスト・ハンドルは変更されません。

このコールのリターン・コードは次のとおりです。

OCI_SUCCESS－列配列内のすべてのデータがストリーム形式に正常に変換されました。列配列属性OCI_ATTR_ROW_COUNTは処理された行数です。
OCI_ERROR - 変換時に発生したエラーです。エラー・ハンドルにはエラー情報が含まれています。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。属性OCI_ATTR_COL_COUNTには、エラーの原因となった列の列配列に対する列索引が含まれています。ストリーム変換に対する列配列がOCI_ERRORを戻した後は、必ずストリームをロードする必要があります。ストリームは、ロードされるまでリセットまたは変換できません。
OCI_CONTINUE －列配列内のすべてのデータがストリーム形式に変換できたわけではありません。ストリーム・バッファの領域が不足しているため、すべての列配列データを格納できません。コール元は、データをロードするか、ファイルにデータを保存するか、または別のストリームを使用して再度OCIDirPathColArrayToStream()をコールし、列配列データの残りを変換する必要があります。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。行オフセットは次の変換のために更新する必要があります。内部状態は列を追跡して変換を続行します。OCI_ATTR_ROW_COUNT値は、コール元が前の行オフセットに追加する必要があります。
OCI_NEED_DATA - 列配列内のデータはすべて正常に変換されましたが、不完全な列が生成されました。コール元は生成されたストリームをロードし、必要な場合は行の残りを繰り返し指定する必要があります。列配列属性OCI_ATTR_ROW_COUNTは、最後のコールで正常に変換された行数です。属性OCI_ATTR_COL_COUNTには、不完全であるとマークが付けられた列の列配列に対する列索引が含まれています。

OCIDirPathDataSave()

用途

要求されたアクションに応じて、データ・セーブポイントを実行するか、またはロードされたデータをコミットしてダイレクト・パス・ロード操作を終了します。

構文

sword OCIDirPathDataSave ( OCIDirPathCtx          *dpctx,
                           OCIError               *errhp,
                           ub4                    action  );

パラメータ

dpctx (IN): ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
errhp (IN/OUT): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
action (IN): OCIDirPathDataSave()のアクション・パラメータの値は次のとおりです。

OCI_DIRPATH_DATASAVE_SAVEONLY - データ・セーブポイントのみ実行します。
OCI_DIRPATH_DATASAVE_FINISH - ロードされたデータをコミットしてダイレクト終了関数をコールします。

戻り値OCI_SUCCESSは、バックエンドによるデータ・セーブポイントまたは終了ロジックが正常に実行されたことを示します。

LOBでは、データ・セーブポイントは実行できません。

終了ロジックの実行は、割り当てられたリソースが解放されないため、ロードの正常終了とは異なります。

OCIDirPathFinish()

用途

ダイレクト・パス・ロード操作を終了します。

構文

sword OCIDirPathFinish (   OCIDirPathCtx          *dpctx,
                           OCIError               *errhp );

パラメータ

dpctx (IN): ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
errhp (IN/OUT): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ロードが完了して、ロードされたデータがコミットされるときに、ダイレクト・パス終了関数がコールされます。すべてのストリームがロードされるまで終了はできず、部分的にロードされた行というものは存在しません。

戻り値OCI_SUCCESSは、バックエンドによるロードが正常に終了したことを示します。

OCIDirPathFlushRow()

用途

サーバーから部分的にロードされた行をフラッシュします。この関数は非推奨です。

構文

sword OCIDirPathFlushRow (   OCIDirPathCtx          *dpctx,
                             OCIError               *errhp );

パラメータ

dpctx (IN): ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
errhp (IN/OUT): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

この関数は、行の一部がロードされたときに必要ですが、アプリケーションで次に処理するピースで変換エラーが発生します。現在、部分状態の行のみが廃棄されます。サーバーが、現在、ダイレクト・パス・コンテキストに関連するオブジェクトに対する部分状態の行を処理していない場合、この関数は何も行いません。

OCIDirPathLoadStream()

用途

ダイレクト・パス・ストリーム形式に変換されたデータをロードします。

構文

sword OCIDirPathLoadStream (   OCIDirPathCtx          *dpctx,
                               OCIDirPathStream       *dpstr,
                               OCIError               *errhp );

パラメータ

dpctx (IN): ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
dpstr (IN): ロードするストリームのダイレクト・パス・ストリーム・ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

インタフェースからエラーが戻されたときは、ストリームのソースとなった列配列内の列に関する情報を、ダイレクト・パス・ストリームの属性として取得できます。また、エラーが発生したストリーム内のオフセットも、ストリームの属性として取得できます。

この関数のリターン・コードは次のとおりです。

OCI_SUCCESS－ストリーム内のすべてのデータが正常にロードされました。
OCI_ERROR－データのロード中にエラーが発生しました。問題は、パーティションのマッピング・エラー、NULL制約の違反、ファンクション索引評価エラー、またはエクステントを割り当てられないなどの領域条件の不足である可能性があります。OCI_ATTR_ROW_COUNTは、最後のコールで正常にロードされた行数です。
OCI_NEED_DATA－最後の行が完全な行ではありませんでした。コール元は、行の残りをロードする必要があります。ストリームのソースが列配列である場合は、属性OCI_ATTR_ROW_COUNTは、最後のコールで正常にロードされた完全な行の数になります。
OCI_NO_DATA - 空のストリームまたは完全に処理されているストリームをロードしようとしました。

OCI_SUCCESS、OCI_NEED_DATAまたはOCI_NO_DATAが戻されるまでは、ストリームを何度でもロードする必要があります。たとえば、OCI_ERRORがOCIDirPathLoadStream()から戻された場合、ストリームはリセットできません。

OCIDirPathPrepare()

用途

行の変換またはロードを行う前に、ダイレクト・パス・ロード・インタフェースを準備します。

構文

sword OCIDirPathPrepare (   OCIDirPathCtx          *dpctx,
                            OCISvcCtx              *svchp,
                            OCIError               *errhp );

パラメータ

dpctx (IN): ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
svchp (IN): サービス・コンテキストです。
errhp (IN/OUT): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

操作するオブジェクトの名前、列データの外部属性、およびすべてのロード・オプションの設定後、行の変換またはロードの前にOCIDirPathPrepare()を使用してダイレクト・パス・インタフェースを準備する必要があります。

戻り値OCI_SUCCESSは、ダイレクト・パス・ロード操作を行うために、バックエンドが適切に初期化されたことを示しています。0 (ゼロ)以外の戻り値は、エラーを示します。戻される可能性のあるエラーは次のとおりです。

コンテキストが無効です。
サーバーに接続されていません。
オブジェクト名が設定されていません。
すでに準備されています(2度準備することはできません)。
オブジェクトがダイレクト・パス処理に適切ではありません。

OCIDirPathStreamReset()

用途

ダイレクト・パス・ストリームの状態をリセットします。

構文

sword OCIDirPathStreamReset ( OCIDirPathStream       *dpstr,
                              OCIError               *errhp );

パラメータ

dpstr (IN): ダイレクト・パス・ストリーム・ハンドルです。
errhp (IN): エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

ダイレクト・パス・ストリームでは、次のOCIDirPathColArrayToStream()コールがストリームへの書込みを開始する場所を示す状態を維持します。通常、データはストリームの末尾に追加されます。ストリームは、正常にロードされる(ロードによってOCI_SUCCESS、OCI_NEED_DATAまたはOCI_NO_DATAが戻される)まではリセットできません。