SQLFetchScroll() - 次の行をフェッチする
SQLFetchScroll() は、照会の結果セットから指定した行セットのデータをフェッチして、すべてのバインドされた列にデータを戻します。 行セットは絶対位置または相対位置で指定できます。
SQLFetchScroll() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
31 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLFetchScroll (
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLINTEGER FetchOffset);
64 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQLFetchScroll (
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | データをフェッチするステートメント・ハンドルを指定します。 |
| SQLUSMALLINT | FetchOrientation | 入力 | フェッチのタイプ:
Db2® ODBC は SQL_FETCH_BOOKMARK をサポートしません。 詳しくは、使用法を参照してください。 |
| SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 1 | FetchOffset | 入力 | フェッチする行数。この引数の変換処理は、FetchOrientation 引数の値によって変わります。 詳しくは、使用法を参照してください。 |
注:
|
|||
使用法
SQLFetchScroll() は、結果セットから指定した行セットを戻します。行セットは絶対位置または相対位置によって指定できます。SQLFetchScroll() は、結果セットを作成する呼び出しの後で、結果セットの上にあるカーソルがクローズする前にのみ呼び出せます。列がバインドされると、SQLFetchScroll() は、それらの列にデータを戻します。アプリケーションが、フェッチされた行数を戻す行状況配列またはバッファーにポインターを指定すると、SQLFetchScroll() はこの情報を戻します。SQLFetchScroll() への呼び出しは SQLFetch() への呼び出しと混合使用できます。SQLFetch() 呼び出しは、FetchOrientation 値を SQL_FETCH_NEXT に指定した SQLFetchScroll() に相当します。SQLFetchScroll() 呼び出しは SQLExtendedFetch() 呼び出しと混合使用できません。
カーソルの置き方: 結果セットの作成時に、カーソルを結果セットの先頭の前に置きます。SQLFetchScroll() は FetchOrientation と FetchOffset 引数の値に基づいて、ブロック・カーソルを置きます。 新しい行セットの先頭を判別するための規則は、次のセクションに示されます。
次の表は、FetchOrientation 値を定義します。
| FetchOrientation 値 | 意味 |
|---|---|
| SQL_FETCH_NEXT | 次の行セットを戻します。これは、SQLFetch() の呼び出しに相当します。SQLFetchScroll() は、FetchOffset の値を無視します。 |
| SQL_FETCH_PRIOR | 前の行セットを戻します。SQLFetchScroll() は、FetchOffset の値を無視します。 |
| SQL_FETCH_RELATIVE | 現在行セットの先頭から FetchOffset である行セットを戻します。 |
| SQL_FETCH_ABSOLUTE | 行 FetchOffset で開始する行セットを戻します。 |
| SQL_FETCH_FIRST | 結果セットの最初の行セットを戻します。SQLFetchScroll() は、FetchOffset の値を無視します。 |
| SQL_FETCH_LAST | 結果セットの最後の完全な行セットを戻します。SQLFetchScroll() は、FetchOffset の値を無視します。 |
SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。SQLFetchScroll() でフェッチされている行セットが、結果セットの最後を越えると、SQLFetchScroll() は、部分の行セットを戻します。すなわち、S が、行セットの開始行で、R が行セット・サイズで、L が結果セットの長さで、S+R-1 が L より大きい場合、行セットの最初の L-S+1 行のみが有効です。残りの行は空で、状況が SQL_ROW_NOROW です。
SQLFetchScroll() の完了後、行セットのカーソルが行セットの最初の行に置かれます。
| フェッチ対応表記 | 意味 |
|---|---|
| BeforeStart | ブロック・カーソルは結果セットの先頭の前に置かれます。行セットの最初の行が結果セットの先頭より前にある場合、SQLFetchScroll() は SQL_NO_DATA を戻します。 |
| AfterEnd | ブロック・カーソルは結果セットの最後の後ろに置かれます。行セットの最初の行が結果セットの最後より後にある場合、SQLFetchScroll() は SQL_NO_DATA を戻します。 |
| CurrRowsetStart | 現在行セット内の最初の行の番号。 |
| LastResultRow | 結果セット内の最後の行の番号。 |
| RowsetSize | 行セット・サイズ。 |
| FetchOffset | SQLFetchScroll() 呼び出しでの FetchOffset 引数の値。 |
| 条件 | 新規行セットの最初の行 |
|---|---|
| BeforeStart | 1 |
| CurrRowsetStart + RowsetSize <= LastResultRow | CurrRowsetStart + RowsetSize |
| CurrRowsetStart + RowsetSize > LastResultRow | AfterEnd |
| AfterEnd | AfterEnd |
| 条件 | 新規行セットの最初の行 |
|---|---|
| BeforeStart | BeforeStart |
| CurrRowsetStart =1 | BeforeStart |
| 1<CurrRowsetStart<=RowsetSize | 11 |
| CurrRowsetStart>RowsetSize | CurrRowsetStart-RowsetSize |
| AfterEnd および LastResultRow<RowsetSize | 11 |
| AfterEnd および LastResultRow>=RowsetSize | LastResultRow-RowsetSize+1 |
注:
|
|
| 条件 | 新規行セットの最初の行 |
|---|---|
| BeforeStart AND FetchOffset>0 | 1 |
| AfterEnd ANDFetchOffset<0 | 1 |
| BeforeStart ANDFetchOffset<=0 | BeforeStart |
| CurrRowsetStart=1 ANDFetchOffset< 0 | BeforeStart |
| CurrRowsetStart>1 ANDCurrRowsetStart+FetchOffset< 1 AND ABS(FetchOffset)>RowsetSize | BeforeStart |
| CurrRowsetStart>1 ANDCurrRowsetStart+FetchOffset< 1 AND ABS(FetchOffset)<=RowsetSize | 12 |
| 1<=(CurrRowsetStart + FetchOffset)<=LastResultRow | CurrRowsetStart+FetchOffset |
| (CurrRowsetStart + FetchOffset)>LastResultRow | AfterEnd |
| AfterEnd AND FetchOffset>=0 | AfterEnd |
| FetchOffset=0 | 変更されない3 |
注:
|
|
| 条件 | 新規行セットの最初の行 |
|---|---|
| FetchOffset<0 AND ABS(FetchOffset)<=LastResultRow | LastResultRow+FetchOffset+1 |
| FetchOffset<0 AND ABS(FetchOffset)>LastResultRow AND ABS(FetchOffset)>RowSetSize | BeforeStart |
| FetchOffset<0 AND ABS(FetchOffset)>LastResultRow AND ABS(FetchOffset)<=RowSetSize | 11 |
| FetchOffset=0 | BeforeStart |
| 1<=FetchOffset<=LastResultRow | FetchOffset |
| FetchOffset>LastResultRow | AfterEnd |
注:
|
|
| 条件 | 新規行セットの最初の行 |
|---|---|
| 任意 | 1 |
| 条件 | 新規行セットの最初の行 |
|---|---|
| RowsetSize<=LastResultRow | LastResultRow-RowsetSize+1 |
| RowsetSize>LastResultRow | 1 |
バインドされた列内のデータ: SQLFetchScroll() は、SQLFetch() と同じ方法でバインドされた列内のデータを戻します。列がバインドされないと、SQLFetchScroll() はデータを戻しませんが、ブロック・カーソルを指定された位置に移動します。SQLFetch() を使用した場合と同様に、SQLGetData() を使用して、各列の値を取り出すことができます。
バッファー・アドレス: SQLFetchScroll() は SQLFetch() と同様の公式を使用して、データのアドレスとインディケーター・バッファーの長さを決定できます。
エラー処理: SQLFetchScroll() は、SQLFetch() と同じ方法でエラーと警告を戻します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
診断
各 SQLSTATE に関連付けられた戻りコードは、他に記載されないかぎり SQL_ERROR です。
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。(関数は SQL_SUCCESS_WITH_INFO を戻します。) |
| 01004 | データが切り捨てられました。 | 非ブランク文字データまたは非ヌル・バイナリー・データの切り捨てが発生した列に対し戻された、ストリング・データまたはバイナリー・データ。ストリング値は右方切り捨てされます。(関数は SQL_SUCCESS_WITH_INFO を戻します。) |
| 01S06 | 結果セットが最初の行セットを戻す前に、取り出しを試行しました。 | 要求された行セットが、現在位置の最初の行を超え、以下の条件のいずれかが真なので結果セットの先頭にオーバーラップしました。
|
| 01S07 | 小数部分が切り捨てられました。 | 列に対して戻されるデータが切り捨てられました。数値データ・タイプの場合は、数値の小数部分が切り捨てられました。TIME または TIMESTAMP データ・タイプ、あるいは時間をコンポーネントに持つ INTERVAL データ・タイプの場合、時刻の一部分が切り捨てられました。 |
| 07002 | 列が多すぎます。 | 1 つ以上の列のバインドで指定された列番号が、結果セット内の列数より大きい値でした。 |
| 07006 | 変換が無効です。 | 結果セット内の列のデータ値が、SQLBindCol() の TargetType で指定された C データ・タイプに変換できませんでした。 |
| 08S01 | 通信リンクに障害が起きました。 | 関数が処理を完成する前に、Db2 ODBC とデータ・ソースとの間の通信リンクで接続障害が発生しました。 |
| 22001 | ストリング・データの右側が切り捨てられました。 | 行に対して戻される可変長ブックマークが切り捨てられました。 |
| 22002 | 無効な出力または標識バッファーが指定されました。 | SQLBindCol() によって設定された pcbValue が NULL ポインターである列に NULL データがフェッチされました。 |
| 22003 | 数値が範囲外です。 | データが戻されませんでした。これは 1 つ以上のバインドされた列に数値 (数値またはストリング) を戻すことで、数値全体 (一部とは対照的に) が切り捨てられる可能性あったためです。 |
| 22007 | 日時形式が無効です。 | 結果セット内の文字列は、日付、時刻、またはタイム・スタンプ C 構造にバインドされましたが、列内の値が無効な日付、時刻、タイム・スタンプでした。 |
| 22012 | ゼロによる除算は無効です。 | 算術式がゼロで割り算されました。 |
| 22018 | キャスト指定の文字の値が無効です。 | 以下の状態のいずれかが発生しました。
|
| 24000 | カーソル状態が無効です。 | StatementHandle が実行された状態にあったが、結果セットが StatementHandle と関連付けられていませんでした。 |
| 40001 | トランザクション・ロールバック。 | フェッチが実行されたトランザクションは、デッドロックを避けるために終了されました。 |
| HY000 | 一般エラー。 | 特定の SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が *MessageText バッファー に戻したエラー・メッセージに、エラーとその原因が記述されています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振れませんでした。アプリケーション・プロセスのためにプロセス・レベルのメモリーを使い尽くした可能性があります。 オペレーティング・システムの構成を調べて、プロセス・レベルのメモリー制限に関する情報を確認してください。 |
| HY008 | 操作は取り消されました。 | 関数の実行が完了する前に、マルチスレッド化されたアプリケーションの別のスレッドから、SQLCancel() が StatementHandle で呼び出されました。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | 以下の状態のいずれかが発生しました。
|
| HY106 | フェッチ・タイプが範囲外です。 | 引数 FetchOrientation に指定した値が無効でした。SQL_CURSOR_TYPE ステートメント属性の値が、SQL_CURSOR_FORWARD_ONLY で、引数 FetchOrientation の値が SQL_FETCH_NEXT ではありませんでした。 |
| HYC00 | ドライバーは使用できません。 | 指定したフェッチ・タイプはサポートされていません。SQLBindCol() の TargetType の組み合わせによって指定された変換、および対応する列の SQL データ・タイプはサポートされていません。 |