SQLFetchScroll 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLFetchScroll は、結果セットから指定されたデータ行セットをフェッチし、バインドされているすべての列のデータを返します。 行セットは、絶対位置または相対位置、またはブックマークで指定できます。
ODBC 2.x ドライバーを使用する場合、ドライバー マネージャーは、この関数を SQLExtendedFetch にマップします。 詳細については、「アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。
構文
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
引数
StatementHandle
[入力]ステートメント ハンドル。
FetchOrientation
[入力]
フェッチの種類:
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
詳細については、「コメント」セクションの「カーソルの配置」を参照してください。
FetchOffset
[入力]
フェッチする行の番号。 この引数の解釈は、FetchOrientation 引数の値によって異なります。 詳細については、「コメント」セクションの「カーソルの配置」を参照してください。
返品
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLFetchScroll がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、SQLFetchScroll によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATE の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。 1 つの列でエラーが発生した場合は、エラーが発生した列を特定するために、SQL_DIAG_COLUMN_NUMBERの DiagIdentifier を使用して SQLGetDiagField を呼び出すことができます。SQLGetDiagField は、SQL_DIAG_ROW_NUMBERの DiagIdentifier で呼び出して、その列を含む行を特定できます。
SQL_SUCCESS_WITH_INFOまたはSQL_ERRORを返すことができるすべての SQLSTATEs (01xxx SQLSTATEs を除く) に対して、複数行操作の 1 つ以上の行でエラーが発生した場合はSQL_SUCCESS_WITH_INFOが返され、1 行の操作でエラーが発生した場合はSQL_ERRORが返されます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | 列に対して返された文字列またはバイナリ データは、非空白文字または NULL 以外のバイナリ データが切り捨てられました。 文字列値の場合は、右に切り捨てられました。 |
| 01S01 | 行のエラー | 1 つ以上の行のフェッチ中にエラーが発生しました。 (ODBC 3*.x* アプリケーションが ODBC 2*.x* ドライバーを操作しているときにこの SQLSTATE が返される場合は、無視できます)。 |
| 01S06 | 結果セットが最初の行セットを返す前にフェッチを試みる | FetchOrientation がSQL_FETCH_PRIORされたとき、現在の位置が最初の行を超え、現在の行の数が行セット のサイズ以下である場合、要求された行セットは結果セットの先頭と重なっていました。 FetchOrientation がSQL_FETCH_PRIOR、現在の位置が結果セットの末尾を超え、行セットのサイズが結果セットのサイズより大きかった場合、要求された行セットは結果セットの先頭と重なっていました。 FetchOrientation がSQL_FETCH_RELATIVE、FetchOffset が負の値、FetchOffset の絶対値が行セット のサイズ以下であった場合、要求された行セットは結果セットの先頭と重複していました。 FetchOrientation がSQL_FETCH_ABSOLUTE、FetchOffset が負の値、FetchOffset の絶対値が結果セットのサイズより大きかったが、行セットのサイズ以下である場合、要求された行セットは結果セットの先頭と重複していました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S07 | 小数部の切り捨て | 列に対して返されたデータが切り捨てられました。 数値データ型の場合、数値の小数部が切り捨てられました。 時刻、タイムスタンプ、および時刻コンポーネントを含む間隔データ型の場合、時刻の小数部が切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07006 | 制限付きデータ型属性違反 | 結果セット内の列のデータ値を、SQLBindCol の TargetType で指定されたデータ型に変換できませんでした。 列 0 はSQL_C_BOOKMARKのデータ型でバインドされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_VARIABLE に設定されました。 列 0 はSQL_C_VARBOOKMARKのデータ型でバインドされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_VARIABLE に設定されませんでした。 |
| 07009 | 記述子インデックスが無効です | ドライバーは、SQLExtendedFetch をサポートしていない ODBC 2*.x* ドライバーであり、列のバインドで指定された列番号は 0 でした。 列 0 がバインドされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 22001 | 文字列データ、右切り捨て | 列に対して返された可変長ブックマークが切り捨てられました。 |
| 22002 | インジケーター変数は必須ですが、指定されていません | SQLBindCol によって設定されたStrLen_or_IndPtr (または SQLSetDescField または SQLSetDescRec によって設定されたSQL_DESC_INDICATOR_PTR) が null ポインターである列に NULL データがフェッチされました。 |
| 22003 | 範囲外の数値 | 1 つ以上の連結列の数値 (数値または文字列) を返すと、数値の一部全体 (小数部ではなく) が切り捨てられる可能性があります。 詳細については、「付録 D: データ型」の「SQL から C へのデータ型の変換」を参照してください。 |
| 22007 | datetime 形式が無効です | 結果セット内の文字列が日付、時刻、またはタイムスタンプ C 構造体にバインドされ、列の値がそれぞれ無効な日付、時刻、またはタイムスタンプでした。 |
| 22012 | 0 で除算しました | 算術式から値が返され、結果として 0 で除算されました。 |
| 22015 | 間隔フィールドのオーバーフロー | 正確な数値または間隔の SQL 型から間隔 C 型に割り当てると、先頭フィールドの有効桁数が失われます。 間隔 C 型にデータをフェッチするときに、間隔 C 型の SQL 型の値の表現がありませんでした。 |
| 22018 | キャスト指定の文字値が無効です | 結果セット内の文字列が文字 C バッファーにバインドされ、その列にバッファーの文字セットに表現がない文字が含まれていました。 C 型は、正確または概数、datetime、または間隔データ型でした。列の SQL 型は文字データ型でした。列の値が、バインドされた C 型の有効なリテラルではありません。 |
| 24000 | カーソル状態が無効 | StatementHandle は実行された状態でしたが、結果セットは StatementHandle に関連付けされませんでした。 |
| 40001 | シリアル化エラー | デッドロックを防ぐために、フェッチが実行されたトランザクションが終了しました。 |
| 40003 | ステートメントの入力候補が不明です | この関数の実行中に関連付けられた接続が失敗し、トランザクションの状態を特定できません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、SQLCancel または SQLCancelHandle がマルチスレッド アプリケーション内の別のスレッドから StatementHandle で呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、SQLFetchScroll 関数が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 指定された StatementHandle が実行された状態にありません。 この関数は、SQLExecDirect、SQLExecute、またはカタログ関数を最初に呼び出さずに呼び出されました。 (DM) 非同期実行関数 (この関数ではない) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) SQLExtendedFetch が呼び出された後、および sqlFreeStmt と SQL_CLOSE オプションが呼び出される前に、StatementHandle に対して SQLFetch が呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | SQL_ATTR_USE_BOOKMARK ステートメント属性は SQL_UB_VARIABLE に設定され、列 0 は、この結果セットのブックマークの最大長と等しくない長さのバッファーにバインドされました。 (この長さは IRD の SQL_DESC_OCTET_LENGTH フィールドで使用でき、呼び出 しによって取得できます。SQLDescribeCol、 SQLColAttribute、または SQLGetDescField。 |
| HY106 | フェッチの種類が範囲外 | DM) 引数 FetchOrientation に指定された値が無効です。 (DM) 引数 FetchOrientation がSQL_FETCH_BOOKMARKされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。 SQL_ATTR_CURSOR_TYPE ステートメント属性の値がSQL_CURSOR_FORWARD_ONLYされ、引数 FetchOrientation の値がSQL_FETCH_NEXTされませんでした。 SQL_ATTR_CURSOR_SCROLLABLE ステートメント属性の値がSQL_NONSCROLLABLEされ、引数 FetchOrientation の値がSQL_FETCH_NEXTされませんでした。 |
| HY107 | 範囲外の行の値 | SQL_ATTR_CURSOR_TYPE ステートメント属性で指定された値はSQL_CURSOR_KEYSET_DRIVENされましたが、SQL_ATTR_KEYSET_SIZE ステートメント属性で指定された値が 0 より大きく、SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で指定された値より小さくなっています。 |
| HY111 | ブックマーク値が無効です | 引数 FetchOrientation がSQL_FETCH_BOOKMARKされ、SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性の値によって指されているブックマークが無効であるか、null ポインターでした。 |
| HY117 | 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | ドライバーまたはデータ ソースは、SQLBindCol の TargetType と、対応する列の SQL データ型の組み合わせで指定された変換をサポートしていません。 |
| HYT00 | タイムアウトの期限が切れました | データ ソースが要求された結果セットを返す前に、クエリのタイムアウト期間の有効期限が切れています。 タイムアウト期間は、SQL_ATTR_QUERY_TIMEOUT SQLSetStmtAttr を使用して設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 | ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、 後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
Comments
SQLFetchScroll は、結果セットから指定された行セットを返します。 行セットは、絶対位置または相対位置、またはブックマークで指定できます。 SQLFetchScroll は、結果セットが存在する間、つまり結果セットを作成する呼び出しの後、その結果セット上のカーソルが閉じられる前にのみ呼び出すことができます。 バインドされている列がある場合は、それらの列のデータが返されます。 アプリケーションで、フェッチされた行数を返す行状態配列またはバッファーへのポインターが指定されている場合、 SQLFetchScroll もこの情報を返します。 SQLFetchScroll への呼び出しは、SQLFetch の呼び出しと混在させることができますが、SQLExtendedFetch の呼び出しと混在させることはできません。
詳細については、「ブロック カーソルの使用」および「スクロール可能カーソルの使用」を参照してください。
カーソルの配置
結果セットが作成されると、カーソルは結果セットの開始前に配置されます。 SQLFetchScroll は、次の表に示すように、FetchOrientation 引数と FetchOffset 引数の値に基づいてブロック カーソルを配置します。 新しい行セットの開始を決定するための正確な規則を次のセクションに示します。
| 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_FETCH_BOOKMARK | SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性で指定されたブックマークから行セット FetchOffset 行を返します。 |
ドライバーは、すべてのフェッチ方向をサポートする必要はありません。アプリケーションは、(カーソルの種類に応じて) SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1、またはSQL_STATIC_CURSOR_ATTRIBUTES1の情報の種類を使用して SQLGetInfo を呼び出して、ドライバーでサポートされているフェッチの向きを決定します。 アプリケーションでは、これらの情報の種類のSQL_CA1_NEXT、SQL_CA1_RELATIVE、SQL_CA1_ABSOLUTE、およびWQL_CA1_BOOKMARKビットマスクを調べておく必要があります。 さらに、カーソルが前方専用で、FetchOrientation がSQL_FETCH_NEXTされていない場合、 SQLFetchScroll は SQLSTATE HY106 (Fetch 型が範囲外) を返します。
SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。 SQLFetchScroll によってフェッチされる行セットが結果セットの末尾と重複する場合、SQLFetchScroll は部分的な行セットを返します。 つまり、S + R - 1 が L より大きい場合(S はフェッチされる行セットの開始行、R は行セット サイズ、L は結果セットの最後の行)、最初の L - S + 1 行のみが有効です。 残りの行は空で、状態はSQL_ROW_NOROW。
SQLFetchScroll が戻った後、現在の行は行セットの最初の行になります。
カーソル配置ルール
次のセクションでは、FetchOrientation の各値の正確な規則について説明します。 これらの規則では、次の表記が使用されます。
| 表記 | 説明 |
|---|---|
| 開始前 | ブロック カーソルは、結果セットの先頭の前に配置されます。 新しい行セットの最初の行が結果セットの先頭より前の場合、 SQLFetchScroll はSQL_NO_DATAを返します。 |
| 終了後 | ブロック カーソルは、結果セットの末尾の後に配置されます。 新しい行セットの最初の行が結果セットの末尾の後にある場合、 SQLFetchScroll はSQL_NO_DATAを返します。 |
| CurrRowsetStart | 現在の行セットの最初の行の番号。 |
| LastResultRow | 結果セット内の最後の行の番号。 |
| RowsetSize | 行セットのサイズ。 |
| FetchOffset | FetchOffset 引数の値。 |
| BookmarkRow | SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性で指定されたブックマークに対応する行。 |
SQL_FETCH_NEXT
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| 開始前 | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | 終了後 |
| 終了後 | 終了後 |
[1] 行をフェッチする前回の呼び出し以降に行セットのサイズが変更された場合、これは前の呼び出しで使用された行セット サイズです。
SQL_FETCH_PRIOR
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| 開始前 | 開始前 |
| CurrRowsetStart = 1 | 開始前 |
| 1 < CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
| After end AND LastResultRow < RowsetSize [2] | 1 [1] |
| After end AND LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll は SQLSTATE 01S06 (結果セットが最初の行セットを返す前にフェッチを試行) を返し、SQL_SUCCESS_WITH_INFO。
[2] 行をフェッチする前回の呼び出し以降に行セットのサイズが変更された場合、これは新しい行セット サイズです。
SQL_FETCH_RELATIVE
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| (START AND FetchOffset > 0 より前) OR (After end AND FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | 開始前 |
| CurrRowsetStart = 1 AND FetchOffset < 0 | 開始前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | > RowsetSize [3] | 開始前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | <= RowsetSize [3] | 1 [2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | 終了後 |
| After end AND FetchOffset >= 0 | 終了後 |
[1] SQLFetchScroll は、FetchOrientation を SQL_FETCH_ABSOLUTE に設定して呼び出された場合と同じ行セットを返します。 詳細については、「SQL_FETCH_ABSOLUTE」セクションを参照してください。
[2] SQLFetchScroll は SQLSTATE 01S06 (結果セットが最初の行セットを返す前にフェッチを試行) を返し、SQL_SUCCESS_WITH_INFO。
[3] 行をフェッチする前回の呼び出し以降に行セットのサイズが変更された場合、これは新しい行セット サイズです。
SQL_FETCH_ABSOLUTE
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| FetchOffset < 0 AND |FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | > RowsetSize [2] | 開始前 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | 開始前 |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | 終了後 |
[1] SQLFetchScroll は SQLSTATE 01S06 (結果セットが最初の行セットを返す前にフェッチを試行) を返し、SQL_SUCCESS_WITH_INFO。
[2] 行をフェッチする前回の呼び出し以降に行セットのサイズが変更された場合、これは新しい行セット サイズです。
動的カーソルに対して実行される絶対フェッチは、動的カーソル内の行位置が決定されないため、必要な結果を提供できません。 このような操作は、フェッチの最初の後にフェッチの相対値が続く操作と同じです。静的カーソルの絶対フェッチと同様に、アトミック操作ではありません。
SQL_FETCH_FIRST
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| [任意] | 1 |
SQL_FETCH_LAST
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] 行をフェッチする前回の呼び出し以降に行セットのサイズが変更された場合、これは新しい行セット サイズです。
SQL_FETCH_BOOKMARK
次の規則が適用されます。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| BookmarkRow + FetchOffset < 1 | 開始前 |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | 終了後 |
ブックマークの詳細については、「ブックマーク (ODBC)」を参照してください。
削除された行、追加された行、およびエラー行がカーソル移動に与える影響
静的カーソルとキーセット ドリブン カーソルは、結果セットに追加された行を検出し、結果セットから削除された行を削除することがあります。 SQL_STATIC_CURSOR_ATTRIBUTES2オプションとSQL_KEYSET_CURSOR_ATTRIBUTES2オプションを使用して SQLGetInfo を呼び出し、SQL_CA2_SENSITIVITY_ADDITIONS、SQL_CA2_SENSITIVITY_DELETIONS、およびSQL_CA2_SENSITIVITY_UPDATESビットマスクを調べることで、アプリケーションは特定のドライバーによって実装されたカーソルがこれを行うかどうかを判断します。 削除された行を検出して削除できるドライバーについては、次の段落でこの動作の影響について説明します。 削除された行を検出できるが削除できないドライバーの場合、削除はカーソルの移動には影響せず、次の段落は適用されません。
カーソルが結果セットに追加された行を検出した場合、または結果セットから削除された行を削除すると、データをフェッチするときにのみ、これらの変更が検出されたかのように表示されます。 これには、FetchOrientation を SQL_FETCH_RELATIVE に設定し、FetchOffset を 0 に設定して同じ行セットを再フェッチして SQLFetchScroll を呼び出したが、fOption を SQL_REFRESH に設定して SQLSetPos を呼び出す場合は含まれません。 後者の場合、行セット バッファー内のデータは更新されますが、再フェッチされず、削除された行は結果セットから削除されません。 したがって、行が現在の行セットから削除されたり、現在の行セットに挿入されたりしても、カーソルは行セット バッファーを変更しません。 代わりに、以前に削除された行が含まれていた行セット、または挿入された行が含まれる行セットをフェッチするときに、変更が検出されます。
次に例を示します。
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
SQLFetchScroll が、現在の行セットに対する相対位置を持つ新しい行セット (FetchOrientation がSQL_FETCH_NEXT、SQL_FETCH_PRIOR、またはSQL_FETCH_RELATIVE) を返す場合、新しい行セットの開始位置を計算するときに現在の行セットに対する変更は含まれません。 ただし、現在の行セットを検出できる場合は、現在の行セットの外部の変更が含まれます。 さらに、SQLFetchScroll が現在の行セットとは独立した位置を持つ新しい行セットを返す場合 (つまり、FetchOrientation がSQL_FETCH_FIRST、SQL_FETCH_LAST、SQL_FETCH_ABSOLUTE、またはSQL_FETCH_BOOKMARK) には、現在の行セット内にある場合でも、検出できるすべての変更が含まれます。
新しく追加された行が現在の行セットの内側か外側かを判断する場合、部分的な行セットは最後の有効な行で終わると見なされます。つまり、行の状態がSQL_ROW_NOROWされていない最後の行です。 たとえば、カーソルが新しく追加された行を検出でき、現在の行セットが部分的な行セットであり、アプリケーションが新しい行を追加し、カーソルが結果セットの末尾にこれらの行を追加するとします。 FetchOrientation を SQL_FETCH_NEXT に設定してアプリケーションが SQLFetchScroll を呼び出した場合、SQLFetchScroll は新しく追加された最初の行から始まる行セットを返します。
たとえば、現在の行セットが行 21 から 30 で構成され、行セット のサイズが 10 で、カーソルが結果セットから削除された行を削除し、カーソルが結果セットに追加された行を検出するとします。 次の表は、SQLFetchScroll がさまざまな状況で返す行を示しています。
| Change | フェッチの種類 | FetchOffset | 新しい行セット[1] |
|---|---|---|---|
| 行 21 を削除する | NEXT | 0 | 31 から 40 |
| 行 31 を削除する | NEXT | 0 | 32 から 41 |
| 行 21 から 22 の間に行を挿入する | NEXT | 0 | 31 から 40 |
| 行 30 ~ 31 の間に行を挿入する | NEXT | 0 | 挿入された行、31 から 39 |
| 行 21 を削除する | PRIOR | 0 | 11 から 20 |
| 行 20 を削除する | PRIOR | 0 | 10 から 19 |
| 行 21 から 22 の間に行を挿入する | PRIOR | 0 | 11 から 20 |
| 行 20 から 21 の間に行を挿入する | PRIOR | 0 | 12 から 20、挿入された行 |
| 行 21 を削除する | RELATIVE | 0 | 22 ~ 31[2] |
| 行 21 を削除する | RELATIVE | 1 | 22 から 31 |
| 行 21 から 22 の間に行を挿入する | RELATIVE | 0 | 21、挿入された行、22 から 29 |
| 行 21 から 22 の間に行を挿入する | RELATIVE | 1 | 22 から 31 |
| 行 21 を削除する | ABSOLUTE | 21 | 22 ~ 31[2] |
| 行 22 を削除する | ABSOLUTE | 21 | 21、23 から 31 |
| 行 21 から 22 の間に行を挿入する | ABSOLUTE | 22 | 挿入された行、22 から 29 |
[1] この列では、行が挿入または削除される前の行番号が使用されます。
[2] この場合、カーソルは行 21 から始まる行を返そうとします。 行 21 は削除されているため、返される最初の行は行 22 です。
エラー行 (つまり、状態が SQL_ROW_ERROR の行) は、カーソルの移動には影響しません。 たとえば、現在の行セットが行 11 で始まり、行 11 の状態がSQL_ROW_ERRORされている場合、FetchOrientation を SQL_FETCH_RELATIVE に設定して SQLFetchScroll を呼び出し、FetchOffset を 5 に設定すると、行 11 の状態がSQL_SUCCESSされた場合と同様に、行 16 から始まる行セットが返されます。
バインドされた列のデータを返す
SQLFetchScroll は、SQLFetch と同じ方法でバインドされた列のデータを返します。 詳細については、SQLFetch 関数の「バインドされた列のデータを返す」を参照してください。
列がバインドされていない場合、 SQLFetchScroll はデータを返しませんが、ブロック カーソルを指定された位置に移動します。 SQLGetData を使用してブロック カーソルのバインドされていない列からデータを取得できるかどうかは、ドライバーによって異なります。 この機能は、SQLGetInfo の呼び出しがSQL_GETDATA_EXTENSIONS情報型のSQL_GD_BLOCK ビットを返す場合にサポートされます。
バッファー アドレス
SQLFetchScroll は、同じ数式を使用して、SQLFetch としてデータおよび長さ/インジケーター バッファーのアドレスを決定します。 詳細については、SQLBindCol 関数の「バッファー アドレス」を参照してください。
行の状態の配列
SQLFetchScroll は、SQLFetch と同じ方法で行状態配列の値を設定します。 詳細については、SQLFetch 関数の「行の状態配列」を参照してください。
フェッチされたバッファーの行
SQLFetchScroll は、SQLFetch と同じ方法で、フェッチされたバッファーの行でフェッチされた行の数を返します。 詳細については、SQLFetch 関数の「行フェッチ バッファー」を参照してください。
エラー処理
アプリケーションが ODBC 3.x ドライバーで SQLFetchScroll を呼び出すと、ドライバー マネージャーはドライバーで SQLFetchScroll を呼び出します。 アプリケーションが ODBC 2.x ドライバーで SQLFetchScroll を呼び出すと、ドライバー マネージャーはドライバーで SQLExtendedFetch を呼び出します。 SQLFetchScroll と SQLExtendedFetch ではエラーが若干異なる方法で処理されるため、ODBC 2.x および ODBC 3.x ドライバーで SQLFetchScroll を呼び出すと、アプリケーションでエラー動作が若干異なります。
SQLFetchScroll は、SQLFetch と同じ方法でエラーと警告を返します。詳細については、SQLFetch の「エラー処理」を参照してください。 SQLExtendedFetch は SQLFetch と同じ方法でエラーを返しますが、次の例外があります。
行セット内の特定の行に適用される警告が発生すると、SQLExtendedFetch は、行ステータス配列内の対応するエントリをSQL_ROW_SUCCESS_WITH_INFOではなく、SQL_ROW_SUCCESSに設定します。
行セット内のすべての行でエラーが発生した場合、SQLExtendedFetch はSQL_ERRORではなく、SQL_SUCCESS_WITH_INFOを返します。
個々の行に適用される状態レコードの各グループでは、SQLExtendedFetch によって返される最初の状態レコードに SQLSTATE 01S01 (行内のエラー) が含まれている必要があります。 SQLFetchScroll はこの SQLSTATE を返しません。 SQLExtendedFetch が追加の SQLSTATE を返すことができない場合でも、この SQLSTATE を返す必要があります。
SQLFetchScroll とオプティミスティック コンカレンシー
カーソルでオプティミスティック コンカレンシー (つまり、SQL_ATTR_CONCURRENCY ステートメント属性の値が SQL_CONCUR_VALUES または SQL_CONCUR_ROWVER) を使用している場合、 SQLFetchScroll はデータ ソースで使用されるオプティミスティック コンカレンシー値を更新して、行が変更されたかどうかを検出します。 これは、SQLFetchScroll が新しい行セット (現在の行セットを再フェッチするときなど) をフェッチするたびに発生します。 (FetchOrientation を SQL_FETCH_RELATIVE に設定し、FetchOffset を 0 に設定して呼び出します)。
SQLFetchScroll ドライバーと ODBC 2.x ドライバー
アプリケーションが ODBC 2.x ドライバーで SQLFetchScroll を呼び出すと、ドライバー マネージャーはこの呼び出しを SQLExtendedFetch にマップします。 SQLExtendedFetch の引数に次の値を渡します。
| SQLExtendedFetch 引数 | Value |
|---|---|
| StatementHandle | SQLFetchScroll の StatementHandle。 |
| FetchOrientation | SQLFetchScroll の FetchOrientation。 |
| FetchOffset | FetchOrientation がSQL_FETCH_BOOKMARKされていない場合は、SQLFetchScroll の FetchOffset 引数の値が使用されます。 FetchOrientation がSQL_FETCH_BOOKMARKされている場合は、SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性で指定されたアドレスに格納されている値が使用されます。 |
| RowCountPtr | SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性で指定されたアドレス。 |
| RowStatusArray | SQL_ATTR_ROW_STATUS_PTR ステートメント属性で指定されたアドレス。 |
詳細については、「付録 G: 下位互換性に関するドライバー ガイドライン」の「ブロック カーソル、スクロール可能なカーソル、および下位互換性」を参照してください。
記述子と SQLFetchScroll
SQLFetchScroll は、SQLFetch と同じ方法で記述子と対話します。 詳細については、SQLFetch 関数の「記述子と SQLFetchScroll」セクションを参照してください。
コード例
SQLSetPos を使用した行セットの列方向のバインド、行方向のバインド、位置指定された更新ステートメントと Delete ステートメント、および行セット内の行の更新を参照してください。
関連する関数
| 情報 | 参照トピック |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol 関数 |
| 一括挿入、更新、または削除操作の実行 | SQLBulkOperations 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 結果セット内の列に関する情報を返す | SQLDescribeCol 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| 1 つの行またはデータ ブロックを順方向にフェッチする | SQLFetch 関数 |
| ステートメントのカーソルを閉じる | SQLFreeStmt 関数 |
| 結果セット列の数を返す | SQLNumResultCols 関数 |
| カーソルの配置、行セット内のデータの更新、または結果セット内のデータの更新または削除 | SQLSetPos 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |