DB2 CLI バージョン 5 以降におけるこの関数の状況
注: |
ODBC バージョン 3 では、SQLExtendedFetch() は使用すべきではありません。代わりに、SQLFetchScroll() に置き換えられています。詳細については、SQLFetchScroll - バインド列すべての行セットを取り出し、データを返すを参照してください。
このバージョンの DB2 CLI でも引き続き SQLExtendedFetch() をサポートはしていますが、 SQLFetchScroll() の使用を DB2 CLI プログラムから開始するなら最新の規格に適合できるため、この方法をお勧めします。
上記の関数と、その他の使用すべきでない関数の詳細については、 バージョン 5 で使用すべきでない DB2 CLI 関数を参照してください。 |
目的
仕様: | DB2 CLI 2.1 | ODBC 1.0 |
SQLExtendedFetch() は、バインドされた列ごとの配列の形式で、複数行を含むデータのブロック (行セット という) を返すことにより、 SQLFetch() の機能を拡張します。行セットのサイズは、SQLSetStmtAttr() 呼び出しの SQL_ROWSET_SIZE 属性で判別されます。
データ行を一度に 1 行ずつ取り出すには、アプリケーションは SQLFetch() を呼び出す必要があります。
ブロックまたは配列検索の詳細については、配列への結果セットの取り出しを参照してください。
構文
SQLRETURN SQLExtendedFetch ( SQLHSTMT StatementHandle, /* hstmt */ SQLUSMALLINT FetchOrientation, /* fFetchType */ SQLINTEGER FetchOffset, /* irow */ SQLUINTEGER *FAR RowCountPtr, /* pcrow */ SQLUSMALLINT *FAR RowStatusArray); /* rgfRowStatus */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLUSMALLINT | FetchOrientation | 入力 | 取り出しの方向とタイプ。 DB2 CLI は、取り出し方向 SQL_FETCH_NEXT だけ、つまり順方向のみのカーソル方向をサポートします。次のデータ配列 (行セット) が取り出されます。 |
SQLINTEGER | FetchOffset | 入力 | 将来の利用のために予約済み。 |
SQLUINTEGER * | RowCountPtr | 出力 | 実際に取り出された行数。処理中にエラーが発生した場合、 RowCountPtr はエラーが発生した行の前の行 (行セット内) の順位を指定します。取り出し中にエラーが発生した場合、最初の行 RowCountPtr は値 0 を指します。 |
SQLUSMALLINT * | RowStatusArray | 出力 | 状況値の配列。要素数は、行セット内の行数 (SQL_ROWSET_SIZE 属性で定義される) と等しくなければなりません。行取り出しのたびに状況値が返されます。
取り出された行数が状況配列内の要素数より小さい (つまり、行セットのサイズより小さい) 場合、残りの状況要素は SQL_ROW_NOROW に設定されます。
DB2 CLI は、取り出しの開始以降に行が更新または削除されたかどうかを検出できません。そのため、以下の ODBC 定義の状況値は報告されません。
|
使用法
行の集まりの配列取り出しを実行するには、SQLExtendedFetch() を使用します。アプリケーションは、SQL_ROWSET_SIZE オプションを指定して SQLSetStmtAttr() を呼び出し、配列のサイズを指定します。
最初に SQLExtendedFetch() を呼び出す前に、カーソルを最初の行に置いてください。 SQLExtendedFetch() を呼び出した後、ちょうど検索された行セットの最後の行要素に対応する、結果セット内の行に、カーソルが置かれます。
SQLBindCol() または SQLBindFileToCol() 関数によってバインドされた結果セット内の列について、 DB2 CLI は必要に応じてバインドされた列のデータを変換し、これらの列にバインドされた場所にそのデータを保管します。 配列への結果セットの取り出しの節に記述されているように、列方向または行方向に結果セットをバインドすることができます。
結果セットを列方向にバインドする場合、アプリケーションは SQL_ATTR_BIND_TYPE ステートメント属性に SQL_BIND_BY_COLUMN を指定します。 (これは省略時値です。) 次いで、アプリケーションは SQLBindCol() 関数を呼び出します。
アプリケーションが SQLExtendedFetch() を呼び出すと、バッファーの初めに最初の行のデータが保管されます。それ以降のデータの各行は、 cbValueMax バイト (SQLBindCol() 呼び出しの引き数) のオフセットに、または関連付けられている C バッファー・タイプが固定幅 (たとえば、SQL_C_LONG) である場合は、直前の行のデータからのその固定長に対応するオフセットに保管されます。
バインドされた列ごとに、戻りに使用できるバイト数は、列にバインドされた pcbValue (SQLBindCol() の据え置き出力引き数) バッファーに保管されます。列の最初の行の戻りに使用できるバイト数はこのバッファーの先頭に保管され、それ以降の各行の返りに使用できるバイト数は直前の行の値から sizeof(SQLINTEGER) バイトのオフセットに保管されます。列のデータが特定の行に対して NULL であれば、pcbValue 配列内の関連する要素は SQL_NULL_DATA に設定されます。
SQLBindFileToCol() の StringLength と IndicatorValue ポインターは出力配列を指すポインターです。ファイルの実際の長さは StringLength 配列の先頭に、またそれに関連づけられた最初の行の標識値は IndicatorValue 配列の先頭にそれぞれ保管されます。それより後のファイルの長さと標識値は、直前の行から sizeof(SQLINTEGER) バイトのオフセットにある配列に書き込まれます。
最初にアプリケーションは、取り出されるデータの単一行とそれに関連した個々の列データ値のデータ長を保存できる構造のサイズに vParam 引き数を設定し、 SQL_ATTR_BIND_TYPE 属性を指定して、 SQLSetStmtAttr() を呼び出す必要があります。
バインドされた列ごとに、データの最初の行は、 SQLBindCol() 呼び出しの rgbValue に指定されたアドレスに保管され、それ以降の各行は直前の行のデータから vParam バイト (SQLSetStmtAttr() 呼び出しに使用されている) のオフセットに保管されます。
バインドされた列ごとに、最初の行の戻りに使用できるバイト数は SQLBindCol() 呼び出しの pcbValue 引き数で指定されたアドレスに保管され、それ以降の各行の返りに使用できるバイト数は、直前の行の値があるアドレスから vParam バイトのオフセットに保管されます。
ファイル参照の行方向バインドはサポートされていません。
SQLExtendedFetch() が行セット全体に適用されるエラーを戻すと、 SQL_ERROR 関数戻りコードが該当する SQLSTATE とともに報告されます。行セット・バッファーの内容は定義されず、カーソル位置は変更されません。
単一行に適用するエラーが発生する場合:
RowStatusArray 配列に SQL_ROW_ERROR が返された場合にのみ、対応する要素のあるエラーが発生したことを示しています。これは、生成された SQLSTATE の数を示してはいません。それで、SQLSTATE 01S01 は、各行の SQLSTATE の結果における区切り記号として使用されます。 DB2 CLI は行セットから残りの行の取り出しを継続し、関数戻りコードとして SQL_SUCCESS_WITH_INFO を戻します。 SQLExtendedFetch() が返された後、エラーが発生している各行について、 01S01 の SQLSTATE および現在行のエラーを示すゼロまたは複数の追加 SQLSTATE が存在します。これは SQLError() を介して取り出すことができます。特定の行にあてはまっている個々のエラーは、カーソルに影響を及ぼして先に進めなくなることはありません。
RowStatusArray 配列出力バッファー内の要素数は、行セット内の行数 (SQL_ROWSET_SIZE ステートメント属性で定義される) と等しくなければなりません。取り出された行数が状況配列内の要素数より小さい場合、残りの状況要素は SQL_ROW_NOROW に設定されます。
アプリケーションは、 SQLExtendedFetch() 呼び出しと SQLFetch() 呼び出しを混合できません。
戻りコード
診断
表 64. SQLExtendedFetch SQLSTATE
SQLSTATE | 説明 | 解説 | ||
---|---|---|---|---|
01004 | データが切り捨てられました。 | 1 つまたは複数の 列について返されたデータが切り捨てられました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) | ||
01S01 | 行の中にエラーがあります。 | 1つ以上の行をフェッチ中にエラーが起きました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) | ||
07002 | 列が多すぎます。 | バインド中に指定された 1 つまたは複数の列の列番号が、結果セット内の列数より大きい値でした。 | ||
07006 | 変換が無効です。 | データ値を、SQLBindCol() の fCType で指定されたデータ・タイプに有意義な方法で変換できませんでした。 | ||
22002 | 無効な出力または標識バッファーが指定されました。 | SQLBindCol() の引き数 pcbValue に指定されたポインター値はヌル・ポインターでしたが、対応する列の値はヌルです。
SQL_NULL_DATA を報告する手段はありません。
SQLBindFileToCol() の引き数 IndicatorValue に指定されたポインターはヌル・ポインターでしたが、対応する LOB 列は NULL です。 SQL_NULL_DATA を報告する手段はありません。 | ||
22003 | 数値が範囲外です。 | 1 つまたは複数の列の数値を (数値またはストリングとして) 返したため、割り当て時または中間結果の計算時に数値の整数部分が切り捨てられたと考えられます。
ゼロでの除算が行われた算術式からの値が返されました。
| ||
22005 | 割り当てにエラーがありました。 | 返された値は、バインドされた列のデータ・タイプと互換性がありませんでした。
返された LOB ロケーター値は、バインドされた列のデータ・タイプと互換性がありませんでした。 | ||
22007 | 日時形式が無効です。 | 文字ストリングから日時形式への変換が指定されましたが、無効なストリング表示または値が指定されたか、あるいは値が無効な日付になっています。
日付、時刻、またはタイム・スタンプの値が、指定された日付タイプの構文に従っていません。 | ||
22008 | 日時フィールドがオーバーフローしました。 | 日時フィールドのオーバーフローが発生しました。たとえば、日付またはタイム・スタンプに関する算術演算で有効な日付の範囲内にない結果になるか、あるいは、バインドされた変数が小さすぎて、その変数に日時値を割り当てることができません。 | ||
22012 | ゼロによる割算は無効です。 | ゼロでの除算が行われた算術式からの値が返されました。 | ||
24000 | カーソル状態が無効です。 | ステートメント・ハンドルで実行された直前の SQL ステートメントは照会ではありませんでした。 | ||
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 | ||
428A1 | ホスト・ファイル変数で参照されるファイルにアクセスできません。 | これは、次のシナリオで生ずる可能性があります。テキスト内で関連付けられた理由コードは、特定のエラーを表します。
| ||
54028 | 並行 LOB ハンドルが最大数に達しました。 | 割り当てられた最大 LOB ロケーター。
並行 LOB ロケーターの最大数に達しました。新しいロケーターを割り当てることができません。 | ||
56084 | DRDA では、LOB データはサポートされていません。 | LOBが DRDA でサポートされていません。
DRDA サーバーに接続 (DB2 コネクトを使用して行う) しているときには、 LOB 列の選択や更新を行うことができません。 | ||
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 | ||
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 | ||
HY010 | 関数の順序エラーです。 | SQLFetch() を呼び出した後、
SQL_CLOSE オプションを指定して SQLFreeStmt() を呼び出す前に、
StatementHandle のために SQLExtendedFetch() を呼び出しました。
StatementHandle の SQLPrepare() または SQLExecDirect() を呼び出す前に、この関数を呼び出しました。
実行時データ (SQLParamData()、 SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 | ||
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 | ||
HY092 | オプション・タイプが範囲外です。 | 直前の SQLBindFileToCol() 操作の FileOptions 引き数が無効でした。 | ||
HY106 | フェッチ・タイプが範囲外です。 | 引き数 FetchOrientation に指定された値は、認識されませんでした。 | ||
HYC00 | ドライバーが機能していません。 | DB2 CLI またはデータ・ソースは、
SQLBindCol() または SQLBindFileToCol() の fCType および対応する列の SQL データ・タイプの組み合わせによって指定された変換をサポートしません。
DB2 CLI によってサポートされていない列データ・タイプに対して、 SQLBindCol() 呼び出しが行われました。
指定された取り出しタイプは認識されますが、サポートされません。 | ||
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
SQLFetchScroll - バインド列すべての行セットを取り出し、データを返すを参照してください。
参照