表17-4は、この項で説明しているダイレクト・パス・ロード関数を示しています。
表17-4 ダイレクト・パス・ロード関数
関数 | 用途 |
---|---|
|
ダイレクト・パス処理を終了します。 |
「OCIDirPathColArrayEntryGet()」 |
列配列内の特定のエントリを取得します。 |
「OCIDirPathColArrayEntrySet()」 |
列配列内の特定のエントリを特定の値に設定します。 |
|
行配列の状態をリセットします。 |
|
特定の行番号の基本行ポインタを取得します。 |
「OCIDirPathColArrayToStream()」 |
列配列からダイレクト・パス・ストリーム形式に変換します。 |
|
データ・セーブポイントを実行するか、またはロードされたデータをコミットしてロード操作を終了します。 |
|
ロードされたデータを終了およびコミットします。 |
|
非推奨です。 |
|
ダイレクト・パス・ストリーム形式に変換されたデータをロードします。 |
|
行の変換またはロードを行うために、ダイレクト・パス・インタフェースを準備します。 |
|
ダイレクト・パス・ストリームの状態をリセットします。 |
構文
sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub2 colIdx, ub1 **cvalpp, ub4 *clenp, ub1 *cflgp );
パラメータ
ダイレクト・パス列配列ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
0 (ゼロ)ベースの行オフセットです。
列パラメータ・リストの作成時に使用される列の索引です。
列データのポインタへのポインタです。
列データの長さへのポインタです。
列フラグへのポインタです。
次のいずれかの値が戻されます。
OCI_DIRPATH_COL_COMPLETE
- 列にすべてのデータが存在します。
OCI_DIRPATH_COL_NULL
- 列がNULL
です。
OCI_DIRPATH_COL_PARTIAL
- 一部の列データが提供されます。
構文
sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub2 colIdx, ub1 *cvalp, ub4 clen, ub1 cflg );
パラメータ
ダイレクト・パス列配列ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
0 (ゼロ)ベースの行オフセットです。
列パラメータ・リストの作成時に使用される列の索引です。
列データへのポインタです。
列データの長さです。
列フラグです。次のいずれかの値が戻されます。
OCI_DIRPATH_COL_COMPLETE
- 列にすべてのデータが存在します。
OCI_DIRPATH_COL_NULL
- 列がNULL
です。
OCI_DIRPATH_COL_PARTIAL
- 一部の列データが提供されます。
構文
sword OCIDirPathColArrayRowGet ( OCIDirPathColArray *dpca, OCIError *errhp, ub4 rownum, ub1 ***cvalppp, ub4 **clenpp, ub1 **cflgpp );
パラメータ
ダイレクト・パス列配列ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
0 (ゼロ)ベースの行オフセットです。
列データのポインタのベクトルへのポインタです。
列データの長さのベクトルへのポインタです。
列フラグのベクトルへのポインタです。
コメント
指定行の列配列エントリにポインタが戻ります。ポインタが戻ると、アプリケーションでは簡単なポインタ計算をして特定行の列間で反復処理を行います。このインタフェースを使用すると、各列でOCIDirPathColArrayEntrySet()をコールする場合と比べて、行の列配列エントリの取得または設定を効率的に行うことができます。アプリケーションから、列配列の境界を超えてメモリーを参照解除しないでください。列配列の次元は、列配列の属性として取得できます。
構文
sword OCIDirPathColArrayToStream ( OCIDirPathColArray *dpca, OCIDirPathCtx const *dpctx, OCIDirPathStream *dpstr, OCIError *errhp, ub4 rowcnt, ub4 rowoff );
パラメータ
ダイレクト・パス列配列ハンドルです。
ロードされているオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
ダイレクト・パス・ストリーム・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
列配列内の行数です。
列配列内の開始索引です。
コメント
このインタフェースは、外部形式の列配列表現データを、ダイレクト・パス・ストリーム形式に変換するときに使用します。変換された形式は、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
には、不完全であるとマークが付けられた列の列配列に対する列索引が含まれています。
パラメータ
ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
OCIDirPathDataSave()のアクション・パラメータの値は次のとおりです。
パラメータ
ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
パラメータ
ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
パラメータ
ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
ロードするストリームのダイレクト・パス・ストリーム・ハンドルです。
エラー発生時の診断情報のために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()
から戻された場合、ストリームはリセットできません。
パラメータ
ロードされるオブジェクトのダイレクト・パス・コンテキスト・ハンドルです。
サービス・コンテキストです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
操作するオブジェクトの名前、列データの外部属性、およびすべてのロード・オプションの設定後、行の変換またはロードの前にOCIDirPathPrepare()
を使用してダイレクト・パス・インタフェースを準備する必要があります。
戻り値OCI_SUCCESS
は、ダイレクト・パス・ロード操作を行うために、バックエンドが適切に初期化されたことを示しています。0 (ゼロ)以外の戻り値は、エラーを示します。戻される可能性のあるエラーは次のとおりです。
コンテキストが無効です。
サーバーに接続されていません。
オブジェクト名が設定されていません。
すでに準備されています(2度準備することはできません)。
オブジェクトがダイレクト・パス処理に適切ではありません。
コメント
ダイレクト・パス・ストリームでは、次のOCIDirPathColArrayToStream()コールがストリームへの書込みを開始する場所を示す状態を維持します。通常、データはストリームの末尾に追加されます。ストリームは、正常にロードされる(ロードによってOCI_SUCCESS
、OCI_NEED_DATA
またはOCI_NO_DATA
が戻される)まではリセットできません。