SQLExtendedFetch 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: Deprecated
まとめ
SQLExtendedFetch は、結果セットから指定されたデータ行セットをフェッチし、バインドされたすべての列のデータを返します。 行セットは、絶対位置または相対位置、またはブックマークで指定できます。
Note
ODBC 3*.x* では、 SQLExtendedFetch は SQLFetchScroll に置き換えられました。 ODBC 3*.x* アプリケーションでは SQLExtendedFetch を呼び出さないでください。代わりに 、SQLFetchScroll を呼び出す必要があります。 ドライバー マネージャーは、ODBC 2*.x* ドライバーを操作するときに SQLFetchScroll を SQLExtendedFetch にマップします。 ODBC 3*.x* ドライバーは、それを呼び出す ODBC 2*.x* アプリケーションを操作する場合、 SQLExtendedFetch をサポートする必要があります。 詳細については、「付録 G: ドライバーの下位互換性のためのガイドライン」の「コメント」 および「ブロック カーソル、スクロール可能カーソル、および下位 互換性」を参照してください。
構文
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
引数
StatementHandle
[入力]ステートメント ハンドル。
FetchOrientation
[入力]フェッチの種類。 これは、SQLFetchScroll の FetchOrientation と同じです。
FetchOffset
[入力]フェッチする行の番号。 これは SQLFetchScroll の FetchOffset と同じですが、1 つの例外があります。 FetchOrientation がSQL_FETCH_BOOKMARKされると、FetchOffset は固定長ブックマークであり、ブックマークからのオフセットではありません。 つまり、 SQLExtendedFetch は、SQL_ATTR_FETCH_BOOKMARK_PTR ステートメント属性ではなく、この引数からブックマークを取得します。 可変長ブックマークはサポートされておらず、ブックマークからのオフセット (0 以外) での行セットのフェッチはサポートされていません。
RowCountPtr
[出力]実際にフェッチされた行数を返すバッファーへのポインター。 このバッファーは、SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性で指定されたバッファーと同じ方法で使用されます。 このバッファーは、 SQLExtendedFetch によってのみ使用されます。 SQLFetch または SQLFetchScroll では使用されません。
RowStatusArray
[出力]各行の状態を返す配列へのポインター。 この配列は、SQL_ATTR_ROW_STATUS_PTR ステートメント属性で指定された配列と同じ方法で使用されます。
ただし、この配列のアドレスは、IRD の SQL_DESC_STATUS_ARRAY_PTR フィールドには格納されません。 さらに、この配列は、SQLExtendedFetch の後に呼び出されたときに、sqlExtendedFetch と SQLBulkOperations によってのみ使用され、SQL_ADDまたは SQLSetPos の操作で使用されます。 SQLFetch または SQLFetchScroll では使用されず、SQLFetch または SQLFetchScroll の後に呼び出される場合、SQLBulkOperations または SQLSetPos では使用されません。 また、フェッチ関数が呼び出される前に、SQL_ADDの操作を含む SQLBulkOperations が呼び出される場合にも使用されません。 つまり、ステートメント状態 S7 でのみ使用されます。 ステートメントの状態 S5 または S6 では使用されません。 詳細については、「付録 B: ODBC 状態遷移テーブル」の 「ステートメント 遷移」を参照してください。
アプリケーションでは、RowStatusArray 引数に有効なポインターを指定する必要があります。そうでない場合、カーソルが SQLExtendedFetch によって配置された後の SQLExtendedFetch の動作と SQLBulkOperations または SQLSetPos の呼び出しの動作は未定義です。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLExtendedFetch が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返す場合は、SQLError を呼び出すことによって、関連付けられている SQLSTATE 値を取得できます。 次の表に、 SQLExtendedFetch によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。 1 つの列でエラーが発生した場合、 SQLGetDiagField を SQL_DIAG_COLUMN_NUMBER の DiagIdentifier で呼び出して、エラーが発生した列を特定できます。 SQLGetDiagField は、 SQL_DIAG_ROW_NUMBERの DiagIdentifier を使用して呼び出して、その列を含む行を特定できます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | 列に対して返される文字列またはバイナリ データにより、空白以外の文字または NULL 以外のバイナリ データが切り捨てられました。 文字列値の場合は、右に切り捨てられました。 数値の場合は、数値の小数部が切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S01 | 行のエラー | 1 つ以上の行のフェッチ中にエラーが発生しました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S06 | 結果セットが最初の行セットを返す前にフェッチを試みる | 要求された行セットは、現在の位置が最初の行を超えたときに結果セットの先頭と重複し、 FetchOrientation がSQL_PRIORされたか、 FetchOrientation が負の FetchOffset でSQL_RELATIVEされ、その絶対値が現在のSQL_ROWSET_SIZE以下である。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S07 | 小数部の切り捨て | 列に対して返されたデータが切り捨てられました。 数値データ型の場合、数値の小数部が切り捨てられました。 時刻、タイムスタンプ、および時刻コンポーネントを含む間隔データ型の場合、時刻の小数部が切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07006 | 制限付きデータ型の属性違反 | SQLBindCol の TargetType で指定された C データ型にデータ値を変換できませんでした。 |
| 07009 | 記述子インデックスが無効です | 列 0 は SQLBindCol にバインドされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_OFF に設定されました。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 22002 | インジケーター変数は必須ですが、指定されていません | SQLBindCol によって設定されたStrLen_or_IndPtrが null ポインターである列に NULL データがフェッチされました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 22003 | 範囲外の数値 | 1 つ以上の列の数値 (数値または文字列) を返すと、数値の一部 (小数部ではなく) 全体が切り捨てられます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 詳細については、「付録 D: データ型」の「間隔データ型と数値データ型のガイドライン 」を参照してください。 |
| 22007 | datetime 形式が無効です | 結果セット内の文字列が日付、時刻、またはタイムスタンプ C 構造体にバインドされ、列の値はそれぞれ無効な日付、時刻、またはタイムスタンプでした。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 22012 | 0 で除算しました | 算術式から値が返され、0 で除算されました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 22015 | 間隔フィールドのオーバーフロー | 正確な数値型または間隔 SQL 型から間隔 C 型に割り当てると、先頭フィールドの有効桁数が失われます。 間隔 C 型にデータをフェッチするときに、間隔 C 型の SQL 型の値の表現がありませんでした。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 22018 | キャスト指定の文字値が無効です | C 型は、正確または概数、datetime、または間隔データ型でした。列の SQL 型は文字データ型でした。列の値が、バインドされた C 型の有効なリテラルではありません。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 24000 | カーソル状態が無効 | StatementHandle が実行された状態でしたが、結果セットが StatementHandle に関連付けられなかった。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLError によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出され、その後、その関数が StatementHandle で再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLExtendedFetch 関数が呼び出されたときにも実行されていました。 (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) SQLFetch または SQLFetchScroll が呼び出され、sqlFreeStmt が SQL_CLOSE オプションで呼び出される前に、StatementHandle に対して SQLExtendedFetch が呼び出されました。 (DM) SQLFetch、SQLFetchScroll、または SQLExtendedFetch が呼び出される前にステートメントに対して SQLBulkOperations が呼び出され、sqlFreeStmt が SQL_CLOSE オプションで呼び出される前に SQLExtendedFetch が呼び出されました。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY106 | フェッチの種類が範囲外 | (DM) 引数 FetchOrientation に指定された値が無効です。 (「コメント」を参照してください)。) 引数 FetchOrientation がSQL_FETCH_BOOKMARKされ、SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。 SQL_CURSOR_TYPE ステートメント オプションの値がSQL_CURSOR_FORWARD_ONLYされ、引数 FetchOrientation の値がSQL_FETCH_NEXTされませんでした。 引数 FetchOrientation がSQL_FETCH_RESUMEされました。 |
| HY107 | 行の値が範囲外 | SQL_CURSOR_TYPE ステートメント オプションで指定された値はSQL_CURSOR_KEYSET_DRIVENされましたが、SQL_KEYSET_SIZE ステートメント属性で指定された値が 0 より大きく、SQL_ROWSET_SIZE ステートメント属性で指定された値より小さくなっています。 |
| HY111 | ブックマーク値が無効です | 引数 FetchOrientation がSQL_FETCH_BOOKMARKされ、 FetchOffset 引数で指定されたブックマークが無効でした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | ドライバーまたはデータ ソースは、指定されたフェッチの種類をサポートしていません。 ドライバーまたはデータ ソースは、SQLBindCol の TargetType と対応する列の SQL データ型の組み合わせで指定された変換をサポートしていません。 このエラーは、列の SQL データ型がドライバー固有の SQL データ型にマップされている場合にのみ適用されます。 |
| HYT00 | タイムアウトに達しました | データ ソースが結果セットを返す前に、クエリのタイムアウト期間が期限切れになりました。 タイムアウト期間は、 SQLSetStmtOption (SQL_QUERY_TIMEOUT) によって設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
説明
SQLExtendedFetch の動作は SQLFetchScroll の動作と同じですが、次の例外があります。
SQLExtendedFetch と SQLFetchScroll は、フェッチされた行数を返すためにさまざまなメソッドを使用します。 SQLExtendedFetch は 、*RowCountPtr でフェッチされた行の数を返します。 SQLFetchScroll は、SQL_ATTR_ROWS_FETCHED_PTRが指すバッファーに直接フェッチされた行の数を返します。 詳細については、「 RowCountPtr 引数」を参照してください。
SQLExtendedFetch と SQLFetchScroll は、異なる配列内の各行の状態を返します。 詳細については、 RowStatusArray 引数を参照してください。
SQLExtendedFetch と SQLFetchScroll では 、FetchOrientation がSQL_FETCH_BOOKMARKされたときに、さまざまなメソッドを使用してブックマークを取得します。 SQLExtendedFetch では、可変長ブックマークや、ブックマークから 0 以外のオフセットで行セットをフェッチすることはできません。 詳細については、 FetchOffset 引数を参照してください。
SQLExtendedFetch と SQLFetchScroll では、異なる行セット サイズが使用されます。 SQLExtendedFetch は SQL_ROWSET_SIZE ステートメント属性の値を使用し、 SQLFetchScroll は SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性の値を使用します。
SQLExtendedFetch には、 SQLFetchScroll とは若干異なるエラー処理セマンティクスがあります。 詳細については、 SQLFetchScroll の「コメント」セクションの「エラー処理」を参照してください。
SQLExtendedFetch では、バインディング オフセット (SQL_ATTR_ROW_BIND_OFFSET_PTR ステートメント属性) はサポートされていません。
SQLExtendedFetch の呼び出しを SQLFetch または SQLFetchScroll の呼び出しと混合することはできません。また、フェッチ関数が呼び出される前に SQLBulkOperations が呼び出された場合、カーソルを閉じて再度開くまで SQLExtendedFetch を呼び出すことはできません。 つまり、 SQLExtendedFetch はステートメント状態 S7 でのみ呼び出すことができます。 詳細については、「付録 B: ODBC 状態遷移テーブル」の 「ステートメント 遷移」を参照してください。
ODBC 2*.x* ドライバーの使用中にアプリケーションが SQLFetchScroll を呼び出すと、ドライバー マネージャーはこの呼び出しを SQLExtendedFetch にマップします。 詳細については、SQLFetchScroll の「SQLFetchScroll および ODBC 2*.x* ドライバー」を参照してください。
ODBC 2*.x* では、複数の行をフェッチするために SQLExtendedFetch が呼び出され、 SQLFetch が呼び出されて 1 つの行がフェッチされました。 一方、ODBC 3*.x* では、 SQLFetch を呼び出して複数の行をフェッチできます。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol 関数 |
| 一括挿入、更新、または削除操作の実行 | SQLBulkOperations 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 結果セット内の列に関する情報を返す | SQLDescribeCol 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| 結果セット列の数を返す | SQLNumResultCols 関数 |
| カーソルの配置、行セット内のデータの更新、または結果セット内のデータの更新または削除 | SQLSetPos 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示