26.5 ダイレクト・パス・ロード関数
ダイレクト・パス・ロード関数をリストし、説明します。
表26-4は、この項で説明しているダイレクト・パス・ロード関数を示しています。
表26-4 ダイレクト・パス・ロード関数
関数 | 用途 |
---|---|
ダイレクト・パス処理を終了します。 |
|
列配列内の特定のエントリを取得します。 |
|
列配列内の特定のエントリを特定の値に設定します。 |
|
行配列の状態をリセットします。 |
|
特定の行番号の基本行ポインタを取得します。 |
|
列配列からダイレクト・パス・ストリーム形式に変換します。 |
|
データ・セーブポイントを実行するか、またはロードされたデータをコミットしてロード操作を終了します。 |
|
ロードされたデータを終了およびコミットします。 |
|
非推奨です。 |
|
ダイレクト・パス・ストリーム形式に変換されたデータをロードします。 |
|
行の変換またはロードを行うために、ダイレクト・パス・インタフェースを準備します。 |
|
ダイレクト・パス・ストリームの状態をリセットします。 |
26.5.1 OCIDirPathAbort()
ダイレクト・パス処理を終了します。
用途
ダイレクト・パス処理を終了します。
構文
sword OCIDirPathAbort ( OCIDirPathCtx *dpctx, OCIError *errhp );
コメント
ダイレクト・パス処理のかわりにサーバーによって維持されていたすべての状態は、終了によって破棄されます。ダイレクト・パス・ロードの場合、終了操作前にロードされたデータは問合せで参照できなくなります。ロードされていなかったデータが、まだセグメントの領域を使用している可能性があります。索引メンテナンス処理などのロード完了処理は行われません。
26.5.2 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
パラメータには値が設定されません。
26.5.3 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);
26.5.4 OCIDirPathColArrayReset()
列配列の状態をリセットします。
用途
列配列の状態をリセットします。
構文
sword OCIDirPathColArrayReset ( OCIDirPathColArray *dpca, OCIError *errhp );
コメント
列配列の状態は、大きな列内でピース単位操作を行うとき、および列のロード中にエラーが発生したときに、リセットする必要があります。最後のOCIDirPathColArrayReset()
コールによってOCI_NEED_DATA
またはOCI_CONTINUE
が戻された場合、列配列はリセットしないでください。これは、まだ行の変換中であるためです。OCI_DIRPATH_COL_ERRORを使用して、OCI_NEED_DATA
から現在の行を削除してください。
26.5.5 OCIDirPathColArrayRowGet()
特定の行番号の列配列行ポインタを取得します。
用途
特定の行番号の列配列行ポインタを取得します。
構文
sword OCIDirPathColArrayRowGet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub1 ***cvalppp, ub4 **clenpp, ub1 **cflgpp );
パラメータ
コメント
指定行の列配列エントリにポインタが戻ります。ポインタが戻ると、アプリケーションでは簡単なポインタ計算をして特定行の列間で反復処理を行います。このインタフェースを使用すると、各列でOCIDirPathColArrayEntrySet()
をコールする場合と比べて、行の列配列エントリの取得または設定を効率的に行うことができます。アプリケーションから、列配列の境界を超えてメモリーを参照解除しないでください。列配列の次元は、列配列の属性として取得できます。
26.5.6 OCIDirPathColArrayToStream()
列配列形式からダイレクト・パス・ストリーム形式に変換します。
用途
列配列形式からダイレクト・パス・ストリーム形式に変換します。
構文
sword OCIDirPathColArrayToStream ( OCIDirPathColArray *dpca, OCIDirPathCtx const *dpctx, OCIDirPathStream *dpstr, OCIError *errhp, ub4 rowcnt, ub4 rowoff );
パラメータ
コメント
このインタフェースは、外部形式の列配列表現データを、ダイレクト・パス・ストリーム形式に変換するときに使用します。変換された形式は、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
には、不完全であるとマークが付けられた列の列配列に対する列索引が含まれています。
26.5.7 OCIDirPathDataSave()
要求されたアクションに応じて、データ・セーブポイントを実行するか、またはロードされたデータをコミットしてダイレクト・パス・ロード操作を終了します。
用途
要求されたアクションに応じて、データ・セーブポイントを実行するか、またはロードされたデータをコミットしてダイレクト・パス・ロード操作を終了します。
構文
sword OCIDirPathDataSave ( OCIDirPathCtx *dpctx, OCIError *errhp, ub4 action );
パラメータ
コメント
戻り値OCI_SUCCESS
は、バックエンドによるデータ・セーブポイントまたは終了ロジックが正常に実行されたことを示します。
LOBでは、データ・セーブポイントは実行できません。
終了ロジックの実行は、割り当てられたリソースが解放されないため、ロードの正常終了とは異なります。
26.5.8 OCIDirPathFinish()
ダイレクト・パス・ロード操作を終了します。
用途
ダイレクト・パス・ロード操作を終了します。
構文
sword OCIDirPathFinish ( OCIDirPathCtx *dpctx, OCIError *errhp );
パラメータ
コメント
ロードが完了して、ロードされたデータがコミットされるときに、ダイレクト・パス終了関数がコールされます。すべてのストリームがロードされるまで終了はできず、部分的にロードされた行というものは存在しません。
戻り値OCI_SUCCESS
は、バックエンドによるロードが正常に終了したことを示します。
26.5.9 OCIDirPathFlushRow()
サーバーから部分的にロードされた行をフラッシュします。この関数は非推奨です。
用途
サーバーから部分的にロードされた行をフラッシュします。この関数は非推奨です。
構文
sword OCIDirPathFlushRow ( OCIDirPathCtx *dpctx, OCIError *errhp );
パラメータ
コメント
この関数は、行の一部がロードされたときに必要ですが、アプリケーションで次に処理するピースで変換エラーが発生します。現在、部分状態の行のみが廃棄されます。サーバーが、現在、ダイレクト・パス・コンテキストに関連するオブジェクトに対する部分状態の行を処理していない場合、この関数は何も行いません。
26.5.10 OCIDirPathLoadStream()
ダイレクト・パス・ストリーム形式に変換されたデータをロードします。
用途
ダイレクト・パス・ストリーム形式に変換されたデータをロードします。
構文
sword OCIDirPathLoadStream ( OCIDirPathCtx *dpctx, OCIDirPathStream *dpstr, OCIError *errhp );
パラメータ
コメント
インタフェースからエラーが戻されたときは、ストリームのソースとなった列配列内の列に関する情報を、ダイレクト・パス・ストリームの属性として取得できます。また、エラーが発生したストリーム内のオフセットも、ストリームの属性として取得できます。
この関数のリターン・コードは次のとおりです。
-
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()
から戻された場合、ストリームはリセットできません。
26.5.11 OCIDirPathPrepare()
用途
行の変換またはロードを行う前に、ダイレクト・パス・ロード・インタフェースを準備します。
構文
sword OCIDirPathPrepare ( OCIDirPathCtx *dpctx, OCISvcCtx *svchp, OCIError *errhp );
パラメータ
コメント
操作するオブジェクトの名前、列データの外部属性、およびすべてのロード・オプションの設定後、行の変換またはロードの前にOCIDirPathPrepare()
を使用してダイレクト・パス・インタフェースを準備する必要があります。
戻り値OCI_SUCCESS
は、ダイレクト・パス・ロード操作を行うために、バックエンドが適切に初期化されたことを示しています。0 (ゼロ)以外の戻り値は、エラーを示します。戻される可能性のあるエラーは次のとおりです。
-
コンテキストが無効です
-
サーバーに接続されていません。
-
オブジェクト名が設定されていません。
-
すでに準備されています(2度準備することはできません)。
-
オブジェクトがダイレクト・パス処理に適切ではありません。
26.5.12 OCIDirPathStreamReset()
ダイレクト・パス・ストリームの状態をリセットします。
用途
ダイレクト・パス・ストリームの状態をリセットします。
構文
sword OCIDirPathStreamReset ( OCIDirPathStream *dpstr, OCIError *errhp );
コメント
ダイレクト・パス・ストリームでは、次のOCIDirPathColArrayToStream()
コールがストリームへの書込みを開始する場所を示す状態を維持します。通常、データはストリームの末尾に追加されます。ストリームは、正常にロードされる(ロードによってOCI_SUCCESS
、OCI_NEED_DATA
またはOCI_NO_DATA
が戻される)まではリセットできません。