SQLFetchScroll() - 次の行をフェッチする

SQLFetchScroll() は、照会の結果セットから指定した行セットのデータをフェッチして、すべてのバインドされた列にデータを戻します。 行セットは絶対位置または相対位置で指定できます。

SQLFetchScroll() の ODBC 仕様

表 1. SQLFetchScroll() の仕様
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);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLFetchScroll() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 データをフェッチするステートメント・ハンドルを指定します。
SQLUSMALLINT FetchOrientation 入力 フェッチのタイプ:
  • SQL_FETCH_NEXT
  • SQL_FETCH_PRIOR
  • SQL_FETCH_FIRST
  • SQL_FETCH_LAST
  • SQL_FETCH_ABSOLUTE
  • SQL_FETCH_RELATIVE

Db2® ODBC は SQL_FETCH_BOOKMARK をサポートしません。

詳しくは、使用法を参照してください。

SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 1 FetchOffset 入力 フェッチする行数。この引数の変換処理は、FetchOrientation 引数の値によって変わります。

詳しくは、使用法を参照してください。

注:
  1. 64 ビット・アプリケーションの場合、旧バージョンの Db2 で使用されていたデータ・タイプ SQLINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLLEN の使用をお勧めします。

使用法

SQLFetchScroll() は、結果セットから指定した行セットを戻します。行セットは絶対位置または相対位置によって指定できます。SQLFetchScroll() は、結果セットを作成する呼び出しの後で、結果セットの上にあるカーソルがクローズする前にのみ呼び出せます。列がバインドされると、SQLFetchScroll() は、それらの列にデータを戻します。アプリケーションが、フェッチされた行数を戻す行状況配列またはバッファーにポインターを指定すると、SQLFetchScroll() はこの情報を戻します。SQLFetchScroll() への呼び出しは SQLFetch() への呼び出しと混合使用できます。SQLFetch() 呼び出しは、FetchOrientation 値を SQL_FETCH_NEXT に指定した SQLFetchScroll() に相当します。SQLFetchScroll() 呼び出しは SQLExtendedFetch() 呼び出しと混合使用できません。

カーソルの置き方: 結果セットの作成時に、カーソルを結果セットの先頭の前に置きます。SQLFetchScroll() は FetchOrientation と FetchOffset 引数の値に基づいて、ブロック・カーソルを置きます。 新しい行セットの先頭を判別するための規則は、次のセクションに示されます。

次の表は、FetchOrientation 値を定義します。

表 3. 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() の完了後、行セットのカーソルが行セットの最初の行に置かれます。

カーソル配置規則: 以下の情報で FetchOrientation の各値に対する新規行セットの先頭を判別する規則を説明します。これらの規則では以下の表記を使用します。
フェッチ対応表記 意味
BeforeStart ブロック・カーソルは結果セットの先頭の前に置かれます。行セットの最初の行が結果セットの先頭より前にある場合、SQLFetchScroll() は SQL_NO_DATA を戻します。
AfterEnd ブロック・カーソルは結果セットの最後の後ろに置かれます。行セットの最初の行が結果セットの最後より後にある場合、SQLFetchScroll() は SQL_NO_DATA を戻します。
CurrRowsetStart 現在行セット内の最初の行の番号。
LastResultRow 結果セット内の最後の行の番号。
RowsetSize 行セット・サイズ。
FetchOffset SQLFetchScroll() 呼び出しでの FetchOffset 引数の値。
以下の表では、FetchOrientation の値が SQL_FETCH_NEXT の場合、新規行セットの先頭を判別する規則を説明します。
表 4. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_NEXT の場合のカーソル位置。
条件 新規行セットの最初の行
BeforeStart 1
CurrRowsetStart + RowsetSize <= LastResultRow CurrRowsetStart + RowsetSize
CurrRowsetStart + RowsetSize > LastResultRow AfterEnd
AfterEnd AfterEnd
以下の表では、FetchOrientation の値が SQL_FETCH_PRIOR の場合、新規行セットの先頭を判別する規則を説明します。
表 5. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_PRIOR の場合のカーソル位置。
条件 新規行セットの最初の行
BeforeStart BeforeStart
CurrRowsetStart =1 BeforeStart
1<CurrRowsetStart<=RowsetSize 11
CurrRowsetStart>RowsetSize CurrRowsetStart-RowsetSize
AfterEnd および LastResultRow<RowsetSize 11
AfterEnd および LastResultRow>=RowsetSize LastResultRow-RowsetSize+1
注:
  1. SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行セットを戻す前のフェッチの試み) と SQL_SUCCESS_WITH_INFO を戻します。
以下の表では、FetchOrientation の値が SQL_FETCH_RELATIVE の場合、新規行セットの先頭を判別する規則を説明します。
表 6. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_RELATIVE の場合のカーソル位置。
条件 新規行セットの最初の行
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
注:
  1. SQLFetchScroll() は、FetchOrientation を SQL_FETCH_ABSOLUTE に設定して呼び出した場合に戻されるものと同じ行セットを戻します。
  2. SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行セットを戻す前のフェッチの試み) と SQL_SUCCESS_WITH_INFO を戻します。
  3. これはデータを再びフェッチするための特別なコマンドです。 カーソルがセンシティブ・カーソルの場合、データは基本表から再フェッチされます。 カーソルがインセンシティブ・カーソルの場合は、バッファーは変更されないままです。以下理由のいずれかに対して、カーソルはインセンシティブになります。
    • 関連付けられたステートメントのステートメント属性が SQL_ATTR_CURSOR_SENSITIVITY または SQL_INSENSITIVE である場合。
    • 照会が読み取り専用の場合。
以下の表では、FetchOrientation の値が SQL_FETCH_ABSOLUTE の場合、新規行セットの先頭を判別する規則を説明します。
表 7. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_ABSOLUTE の場合のカーソル位置。
条件 新規行セットの最初の行
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. SQLFetchScroll() は SQLSTATE 01S06 (結果セットが最初の行セットを戻す前のフェッチの試み) と SQL_SUCCESS_WITH_INFO を戻します。
以下の表では、FetchOrientation の値が SQL_FETCH_FIRST の場合、新規行セットの先頭を判別する規則を説明します。
表 8. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_FIRST の場合のカーソル位置。
条件 新規行セットの最初の行
任意 1
以下の表では、FetchOrientation の値が SQL_FETCH_LAST の場合、新規行セットの先頭を判別する規則を説明します。
表 9. SQLFetchScroll() パラメーターの FetchOrientation が SQL_FETCH_LAST の場合のカーソル位置。
条件 新規行セットの最初の行
RowsetSize<=LastResultRow LastResultRow-RowsetSize+1
RowsetSize>LastResultRow 1

バインドされた列内のデータ: SQLFetchScroll() は、SQLFetch() と同じ方法でバインドされた列内のデータを戻します。列がバインドされないと、SQLFetchScroll() はデータを戻しませんが、ブロック・カーソルを指定された位置に移動します。SQLFetch() を使用した場合と同様に、SQLGetData() を使用して、各列の値を取り出すことができます。

バッファー・アドレス: SQLFetchScroll() は SQLFetch() と同様の公式を使用して、データのアドレスとインディケーター・バッファーの長さを決定できます。

エラー処理: SQLFetchScroll() は、SQLFetch() と同じ方法でエラーと警告を戻します。

戻りコード

SQLFetchScroll() の呼び出し後、以下の値のいずれかが戻されます。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

診断

各 SQLSTATE に関連付けられた戻りコードは、他に記載されないかぎり SQL_ERROR です。

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 10. SQLFetchScroll の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(関数は SQL_SUCCESS_WITH_INFO を戻します。)
01004 データが切り捨てられました。 非ブランク文字データまたは非ヌル・バイナリー・データの切り捨てが発生した列に対し戻された、ストリング・データまたはバイナリー・データ。ストリング値は右方切り捨てされます。(関数は SQL_SUCCESS_WITH_INFO を戻します。)
01S06 結果セットが最初の行セットを戻す前に、取り出しを試行しました。 要求された行セットが、現在位置の最初の行を超え、以下の条件のいずれかが真なので結果セットの先頭にオーバーラップしました。
  • FetchOrientation が SQL_PRIOR でした。
  • FetchOrientation が、否定 FetchOffset を指定した SQL_RELATIVE で、絶対値が現行の SQL_ATTR_ROW_ARRAY_SIZE 以下でした。
(関数は SQL_SUCCESS_WITH_INFO を戻します。)
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 キャスト指定の文字の値が無効です。 以下の状態のいずれかが発生しました。
  • 結果セット内の文字列は、文字 C バッファーにバインドされましたが、列にバッファーの文字セットに表記のない文字が含まれていました。
  • 結果セット内の文字列は、近似数値 C バッファーにバインドされましたが、列内の値を有効な近似数値にキャストできませんでした。
  • 結果セット内の文字列は、厳密な数値 C バッファーにバインドされましたが、列内の値を有効な厳密な数値にキャストできませんでした。
  • 結果セット内の文字列は、日時 C バッファーにバインドされましたが、列内の値を有効な日時値にキャストできませんでした。
24000 カーソル状態が無効です。 StatementHandle が実行された状態にあったが、結果セットが StatementHandle と関連付けられていませんでした。
40001 トランザクション・ロールバック。 フェッチが実行されたトランザクションは、デッドロックを避けるために終了されました。
HY000 一般エラー。 特定の SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が *MessageText バッファー に戻したエラー・メッセージに、エラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振れませんでした。アプリケーション・プロセスのためにプロセス・レベルのメモリーを使い尽くした可能性があります。 オペレーティング・システムの構成を調べて、プロセス・レベルのメモリー制限に関する情報を確認してください。
HY008 操作は取り消されました。 関数の実行が完了する前に、マルチスレッド化されたアプリケーションの別のスレッドから、SQLCancel() が StatementHandle で呼び出されました。
HY010 関数シーケンス・エラーが発生しました。 以下の状態のいずれかが発生しました。
  • 指定した StatementHandle が実行状態にありませんでした。SQLExecDirect()、SQLExecute()、またはカタログ関数の、前の呼び出しなしで、関数が呼び出されました。
  • SQLExecute() または SQLExecDirect() が StatementHandle で呼び出され、SQL_NEED_DATA を戻しました。SQLFetchScroll() が、すべての実行時データ・パラメーターまたは列にデータが送られる前に呼び出されました。
  • SQLFetch() が呼び出された後で、SQLFreeStmt() が SQL_CLOSE オプションで呼び出される前か、SQLMoreResults() が呼び出される前に、SQLFetchScroll() が StatementHandle で呼び出されました。ダウン・レベルのサーバーに接続されていました。
  • SQLExtendedFetch() が呼び出された後で、SQL_CLOSE を指定した SQLFreeStmt() が呼び出される前に、SQLFetchScroll() が StatementHandle で呼び出されました。
HY106 フェッチ・タイプが範囲外です。 引数 FetchOrientation に指定した値が無効でした。SQL_CURSOR_TYPE ステートメント属性の値が、SQL_CURSOR_FORWARD_ONLY で、引数 FetchOrientation の値が SQL_FETCH_NEXT ではありませんでした。
HYC00 ドライバーは使用できません。 指定したフェッチ・タイプはサポートされていません。SQLBindCol() の TargetType の組み合わせによって指定された変換、および対応する列の SQL データ・タイプはサポートされていません。