| 仕様: | DB2 CLI 5.0 | ODBC 3.0 |
|
SQLFetchScroll() は、指定した行セットのデータを結果セットから取り出し、 すべてのバインドされた列のデータを戻します。行セットは、絶対位置または相対位置で 指定できます。
構文
SQLRETURN SQLFetchScroll (
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLINTEGER FetchOffset);
関数の引き数
| データ・タイプ | 引き数 | 用途 | 説明 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
| SQLSMALLINT | FetchOrientation | 入力 | フェッチのタイプ:
|
| SQLINTEGER | FetchOffset | 入力 | 取り出す行数。FetchOrientation 引き数の値によって、この引き数の解釈は変わります。 |
使用法
SQLFetchScroll() は、結果セットから指定した行セットを戻します。 行セットは、絶対位置または相対位置で指定できます。SQLFetchScroll() は、 結果セットが存在するときだけ呼び出すことができます。つまり、 結果セットを作成する呼び出しの後から、その結果セットに関するカーソルがクローズ されるまでの間です。バインドされた列があれば、それらの列にデータが戻されます。 取り出した行数を入れるバッファーまたは行状況配列を指すポインターを アプリケーションが指定している場合は、SQLFetchScroll() は、 その情報も戻します。SQLFetchScroll() の呼び出しと SQLFetch() の 呼び出しを混ぜることもできます。
カーソルの位置決め
結果セットが作成されると、カーソルは結果セットの先頭の前に位置付けさ れます。 次のリストに示されているように SQLFetchScroll() は、 FetchOrientation と FetchOffset 引き数の値に基づいて ブロック・カーソルの位置を指定します。新規行セットの先頭を決める厳密な規則は、 次のセクションで説明します。
SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。 SQLFetchScroll() で取り出す行セットが結果セットの終わりと オーバーラップしている場合、SQLFetchScroll() は部分的な行セットを 戻します。つまり、S が取り出す行セットの開始行、R が行セットのサイズ、L が 結果セット内の最後の行として、S + R - 1 が L より大である場合は、 行セットの内の最初から L - S + 1 行が有効な行となります。 残りの行の状況は SQL_ROW_NOROW で、空です。
SQLFetchScroll() が戻ると、行セット・カーソルは結果セットの最初の行に配置されます。
カーソル位置指定の規則
以下のセクションでは、FetchOrientation のそれぞれの値についての 厳密な規則を説明しています。これらの規則では、以下の表記を使用しています。
SQL_FETCH_NEXT の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| Before start | 1 |
| CurrRowsetStart + RowsetSize <= LastResultRow | CurrRowsetStart + RowsetSize |
| CurrRowsetStart + RowsetSize > LastResultRow | After end |
| After end | After end |
SQL_FETCH_PRIOR の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| Before start | Before start |
| CurrRowsetStart = 1 | Before start |
| 1 < CurrRowsetStart <= RowsetSize | 1a |
| CurrRowsetStart > RowsetSize | CurrRowsetStart - RowsetSize |
| After end AND LastResultRow < RowsetSize | 1a |
| After end AND LastResultRow >= RowsetSize | LastResult - RowRowsetSize + 1 |
SQL_FETCH_RELATIVE の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| (Before start AND FetchOffset > 0) OR (After end AND FetchOffset < 0) | --a |
| Before start AND FetchOffset <= 0 | Before start |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Before start |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| > RowsetSize | Before start |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| <= RowsetSize | 1b |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | After end |
| After end AND FetchOffset >= 0 | After end |
SQL_FETCH_ABSOLUTE の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| FetchOffset < 0 AND |FetchOffset| <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND |FetchOffset| > LastResultRow AND |FetchOffset| > RowsetSize | Before start |
| FetchOffset < 0 AND |FetchOffset| > LastResultRow AND |FetchOffset| <= RowsetSize | 1a |
| FetchOffset = 0 | Before start |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | After end |
SQL_FETCH_FIRST の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| すべて | 1 |
SQL_FETCH_LAST の規則
| 状態 | 新規行セットの最初の行 |
|---|---|
| RowsetSize <= LastResultRow | LastResultRow - RowsetSize + 1 |
| RowsetSize > LastResultRow | 1 |
バインドされた列へのデータの戻し
SQLFetchScroll() は、SQLFetch() と同じようにバインドされた 列にデータを戻します。詳細は、SQLFetch - 次の行の取り出しを参照してください。
バインドされた列がない場合は、SQLFetchScroll() はデータは戻さずに、 ブロック・カーソルを指定された位置に移動させます。このケースでは、SQLFetch() と同様に、SQLGetData() を使用して情報を 取り出すことができます。
バッファー・アドレス
SQLFetchScroll() は SQLFetch() と同じ数式を使用して データのアドレスと、長さ/標識バッファーを判別します。詳細については、SQLBindCol - アプリケーション変数への列のバインドを参照してください。
行状況配列
行状況配列は、行セット内の各行の状況を戻すために使用されます。 この配列のアドレスは、SQL_ATTR_ROW_STATUS_PTR ステートメント属性で指定します。 この配列はアプリケーションで割り振り、SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で 指定されただけのエレメントがなければなりません。 この値は、SQLFetch() および SQLFetchScroll() で セットされます。 SQL_ATTR_ROW_STATUS_PTR ステートメント属性の値がヌル・ポインターである場合は、 これらの関数は行の状況を戻しません。
SQLFetch() または SQLFetchScroll() が、 SQL_SUCCESS あるいは SQL_SUCCESS_WITH_INFO を戻していない場合は、 行状況配列バッファーの内容は不確定です。
以下の値が行状況配列に戻されます。
取り出された行バッファー
取り出された行バッファーは、取り出された (取り出し中にエラーが起きたために データが戻らなかった行を含む) 行数を戻すために使用されます。これは行状況配列の値 が SQL_ROW_NOROW でない行の数です。このバッファーのアドレスは、 SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性で指定します。 このバッファーは、アプリケーションが割り振ります。これは、SQLFetch() および SQLFetchScroll() でセットされます。 SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性の値がヌル・ポインターであれば、 これらの関数は取り出した行の番号を戻しません。結果セット内の現在行の番号を判断する には、アプリケーションで SQLGetStmtAttr() に SQL_ATTR_ROW_NUMBER 属性を 指定して呼び出します。
SQLFetch() または SQLFetchScroll() が、 SQL_SUCCESS あるいは SQL_SUCCESS_WITH_INFO を戻していない場合は、 行取り出しバッファーの内容は不確定です。ただし SQL_NO_DATA が戻った場合は 例外であり、行取り出しバッファーはゼロにセットされます。
戻りコード
診断
| SQLSTATE | 説明 | 解説 |
|---|---|---|
| 01000 | 警告 | 通知メッセージ。(関数は、SQL_SUCCESS_WITH_INFO を戻す。) |
| 01004 | データが切り捨てられた。 | 1 つ以上の列に対して戻されたデータが切り捨てられる。 ストリング値または数値は右側が切り捨てられる。(エラーがない場合には 、SQL_SUCCESS_WITH_INFO が戻される。) |
| 01S06 | 結果セットが最初の行セットを戻す前に、取り出そうとした。 | 現在位置が最初の行より後であり、かつ、FetchOrientation が SQL_PRIOR であるか、または SQL_RELATIVE であって、 絶対値が現在の SQL_ATTR_ROW_ARRAY_SIZE 以下である負の FetchOffset が指定されている際に、 要求された行セットが結果セットの先頭とオーバーラップした。(関数は、SQL_SUCCESS_WITH_INFO を戻す。) |
| 07006 | 無効な変換。 | SQLBindCol() の fCType により指定したデータ・タイ プへのデータ値の変換が無意味である。 |
| 22002 | 無効な出力バッファーまたは標識バッファーの指定。 | SQLBindCol() 内の引き数 pcbValue に指定したポインター値が ヌル・ポインターで、対応する列の値がヌルである。 SQL_NULL_DATA を報告する方法がない。 |
| 22003 | 数値が範囲外。 | 1 つ以上のバインドされた列について (数値またはストリングとして) 数値を 戻すと、(部分的にではなく) その番号全体が切り捨てられる。 |
| 24000 | カーソル状態が無効。 | StatementHandle は実行された状態であるが、 StatementHandle に関連付けられた結果セットがない。 |
| HY000 | 一般エラー。 | エラーは発生したが、特定の SQLSTATE は無い。 SQLGetDiagRec() が *MessageText バッファーに戻したエラー・メッセージが、 エラーとその原因を示しています。 |
| HY001 | メモリーの割り振りの失敗。 | DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを 割り当てることができない。 |
| HY010 | 関数のシーケンス・エラー。 | StatementHandle に対して、SQLPrepare() または SQLExecDirect() が呼び出される前に関数が呼び出された。 |
| HY106 | 取り出しタイプが範囲外。 | 引き数 FetchOrientation に指定された値が無効である。
SQL_CURSOR_TYPE ステートメント属性の値が SQL_CURSOR_FORWARD_ONLY で、FetchOrientation 引き数の 値が SQL_FETCH_NEXT でない。 |
| HY107 | 行の値が範囲外。 | SQL_ATTR_CURSOR_TYPE ステートメント属性で指定した値は SQL_CURSOR_KEYSET_DRIVEN で あるが、SQL_ATTR_KEYSET_SIZE ステートメント属性で指定した値がゼロより大きく、 SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で指定した値より小さい。 |
制約事項
なし。
関連した解説