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 値は、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を使用して SQLGetDiagRec を呼び出すことによって取得できます。 次の表に、 SQLFetchScroll によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。 1 つの列でエラーが発生した場合、 SQLGetDiagField を SQL_DIAG_COLUMN_NUMBER の DiagIdentifier で呼び出して、エラーが発生した列を特定できます。 SQLGetDiagField は、SQL_DIAG_ROW_NUMBER の DiagIdentifier を使用して呼び出して、その列を含む行を決定できます。
SQL_SUCCESS_WITH_INFOまたはSQL_ERRORを返すことができるすべての SQLSTATEs (01xxx SQLSTATEs を除く) に対して、複数行操作の 1 つ以上の行でエラーが発生した場合はSQL_SUCCESS_WITH_INFOが返され、単一行操作でエラーが発生した場合は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 に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle が StatementHandle で呼び出されました。 その後、 StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| 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 | タイムアウトに達しました | データ ソースが要求された結果セットを返す前に、クエリのタイムアウト期間が期限切れになりました。 タイムアウト期間は、SQLSetStmtAttr (SQL_ATTR_QUERY_TIMEOUT) によって設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルを使用するたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する以前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
説明
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 の各値の正確な規則について説明します。 これらの規則では、次の表記が使用されます。
| Notation | 意味 |
|---|---|
| 開始前 | ブロック カーソルは、結果セットの開始前に配置されます。 新しい行セットの最初の行が結果セットの先頭より前の場合、 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] |
| 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 (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ビットマスクを調べることで、アプリケーションは特定のドライバーによって実装されたカーソルがこれを行うかどうかを判断します。 削除された行を検出して削除できるドライバーの場合、次の段落では、この動作の影響について説明します。 削除された行を検出できるが削除できないドライバーの場合、削除はカーソルの移動には影響せず、次の段落は適用されません。
カーソルが結果セットに追加された行を検出するか、結果セットから削除された行を削除すると、データをフェッチするときにのみこれらの変更が検出されたかのように表示されます。 これには、 SQLFetchScroll が呼び出され、FetchOrientation が SQL_FETCH_RELATIVE に設定され、FetchOffset が 0 に設定されて同じ行セットを再フェッチする場合が含まれますが、sqlSetPos が fOption を SQL_REFRESH に設定して呼び出される場合は含まれません。 後者の場合、行セット バッファー内のデータは更新されますが、再表示されず、削除された行は結果セットから削除されません。 したがって、行が現在の行セットから削除されたり、現在の行セットに挿入されたりしても、カーソルは行セット バッファーを変更しません。 代わりに、以前に削除された行を含んだ行セット、または挿入された行が含まれる行セットをフェッチすると、変更が検出されます。
次に例を示します。
// 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 が追加の SQLSTATEs を返すことができない場合でも、この 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 引数 | 値 |
|---|---|
| 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」セクションを参照してください。
コード例
「列方向のバインド」、「行方向のバインド」、「配置された Update ステートメントと Delete ステートメント」、「SQLSetPos を使用した行セット内の行の更新」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol 関数 |
| 一括挿入、更新、または削除操作の実行 | SQLBulkOperations 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 結果セット内の列に関する情報を返す | SQLDescribeCol 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| 1 つの行またはデータ ブロックを前方専用方向にフェッチする | SQLFetch 関数 |
| ステートメントのカーソルを閉じる | SQLFreeStmt 関数 |
| 結果セット列の数を返す | SQLNumResultCols 関数 |
| カーソルの配置、行セット内のデータの更新、または結果セット内のデータの更新または削除 | SQLSetPos 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示