SQLFetchScroll - スクロール可能カーソルからの取り出し

SQLFetchScroll() 要求された方向に基づいてカーソルの位置を決定し、バインド列を 検索します。

SQLFetchScroll() を使って、 SQLBindCol() で指定した変数内にデータを直接受信することができますが、 SQLGetData() を呼び出して、 取り出し後の列を 1 つずつ受信することもできます。 また、列バインド時に変換が指示されている場合は、SQLFetchScroll() の呼び出し時にデータ変換も実行されます。

構文

SQLRETURN SQLFetchScroll (SQLHSTMT    hstmt,
                          SQLSMALLINT fOrient,
                          SQLINTEGER  fOffset);

関数引数

表 1. SQLFetchScroll の引数
データ・タイプ 引数 Use 説明
SQLHSTMT hstmt (hstmt) 入力 ステートメント・ハンドル。
SQLSMALLINT fOrient 入力 取り出しの方向。 可能な値については、 表 2 を参照してください。
SQLINTEGER fOffset 入力 相対的位置付けのための行オフセット。

使用法

SQLFetchScroll() を呼び出せるのは、hstmt で処理された最新のステートメントが SELECT の場合だけです。

SQLFetchScroll() は SQLFetch()のように動作しますが、 fOrient パラメーターは、データが取り出される前にカーソルを位置付けます。 SQLFetchScroll() で SQL_FETCH_NEXT 以外の方向を使用する場合、 カーソルはスクロール可能カーソルでなければなりません。

この関数を使って SQL プロシージャーの結果セットから行を取り出す場合、 SQL_FETCH_NEXT の方向だけがサポートされます。

SQLFetchScroll() は、SQLExtendedFetch() が提供する配列取り出しサポートの代わりの配列取り出しをサポートします。 配列取り出しについて詳細は、SQLExtendedFetch() のトピックを参照してください。

SQLExtendedFetch()のRowCountPtrとRowStatusArrayパラメータで返される情報は、SQLFetchScroll()で以下のように処理される：
  • RowCountPtr: SQLFetchScroll() は、取り出した行数を SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性が指すバッファーに戻します。
  • RowStatusArray: SQLFetchScroll() は、各行の状況の配列を SQL_ATTR_ROW_STATUS_PTR ステートメント属性が指すバッファーに戻します。
表 2. ステートメント属性
fOrient 説明
SQL_FETCH_ABSOLUTE fOffset 引数で指定された結果セットの行に移動。
SQL_FETCH_FIRST 結果セットの先頭行に移動。
SQL_FETCH_LAST 結果セットの最終行に移動。
SQL_FETCH_NEXT 現行カーソル位置の後の行に移動。
SQL_FETCH_PRIOR 現行カーソル位置の前の行に移動。
SQL_FETCH_RELATIVE fOffset が次のようになっているとします。
  • 正。指定した行数だけカーソルを進める。
  • 負。指定した行数だけカーソルを後退させる。
  • ゼロ。カーソルを移動しない。

戻りコード

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

診断

テーブル3。 SQLFetchScroll SQLSTATE
SQLSTATE 説明 説明
01004 データは切り捨てられる 戻された 1 つ以上の列のデータが切り捨てられています。 ストリング値の右桁が切り捨てられます。 (エラーが発生しなければ SQL_SUCCESS_WITH_INFO が戻されます。)
HY001 メモリーの割り振りの失敗 ドライバーは、関数の処理または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 引数値が無効 無効な方向。
HY010 年 関数シーケンス・エラー 指定された hstmt が処理済み状態になっていません。 先に SQLExecute または SQLExecDirect を呼び出さないで、 この関数が呼び出されています。
HY 013 * メモリー管理の問題 ドライバーは、関数の処理または完了をサポートするのに必要なメモリーにアクセスできません。
HY021 内部記述子が無効 内部記述子がアドレッシングできない、割り振れない、または無効な値を持っています。

参照