SQLFetch 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLFetch は 、結果セットからデータの次の行セットをフェッチし、バインドされたすべての列のデータを返します。
構文
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
引数
StatementHandle
[入力]ステートメント ハンドル。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLFetch がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec 関数を呼び出します。 次の表に、 SQLFetch によって通常返される 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が返され、1 行の操作でエラーが発生した場合はSQL_ERRORが返されます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | 列に対して返される文字列またはバイナリ データにより、空白以外の文字または NULL 以外のバイナリ データが切り捨てられました。 文字列値の場合は、右に切り捨てられました。 |
| 01S01 | 行のエラー | 1 つ以上の行のフェッチ中にエラーが発生しました。 (ODBC 3*.x* アプリケーションが ODBC 2*.x* ドライバーを操作しているときにこの SQLSTATE が返される場合は、無視できます。 |
| 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 に対して非同期処理が有効になりました。 SQLFetch 関数が呼び出され、実行が完了する前に、 StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、 SQLFetch 関数が StatementHandle で再度呼び出されました。 または、SQLFetch 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLFetch 関数が呼び出されたときにも実行されていました。 (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 を呼び出すことで取得できます)。 |
| HY107 | 行の値が範囲外 | SQL_ATTR_CURSOR_TYPE ステートメント属性で指定された値はSQL_CURSOR_KEYSET_DRIVENされましたが、SQL_ATTR_KEYSET_SIZE ステートメント属性で指定された値が 0 より大きく、SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で指定された値より小さくなっています。 |
| 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 を呼び出す必要があります。 |
説明
SQLFetch は 、結果セット内の次の行セットを返します。 これは、結果セットが存在する間、つまり、結果セットを作成する呼び出しの後、その結果セット上のカーソルが閉じられる前にのみ呼び出すことができます。 列がバインドされている場合は、それらの列のデータが返されます。 アプリケーションで、フェッチされた行数を返す行状態配列またはバッファーへのポインターが指定されている場合、 SQLFetch もこの情報を返します。 SQLFetch の呼び出しは SQLFetchScroll の呼び出しと混在させることができますが、SQLExtendedFetch の呼び出しと混合することはできません。 詳細については、「 データ行のフェッチ」を参照してください。
ODBC 3*.x* アプリケーションが ODBC 2*.x* ドライバーで動作する場合、ドライバー マネージャーは SQLExtendedFetch をサポートする ODBC 2*.x* ドライバーの SQLExtendedFetch に SQLFetch 呼び出しをマップします。 ODBC 2*.x* ドライバーが SQLExtendedFetch をサポートしていない場合、ドライバー マネージャーは SQLFetch 呼び出しを ODBC 2*.x* ドライバーの SQLFetch にマップします。これは、1 つの行のみをフェッチできます。
詳細については、「付録 G: 下位互換性のためのドライバー ガイドライン」の 「ブロック カーソル、スクロール可能カーソル、および下位 互換性」を参照してください。
カーソルの配置
結果セットが作成されると、カーソルは結果セットの開始前に配置されます。 SQLFetch は 、次の行セットをフェッチします。 これは、FetchOrientation を SQL_FETCH_NEXT に設定して SQLFetchScroll を呼び出すことと同じです。 カーソルの詳細については、「 カーソル と ブロック カーソル」を参照してください。
SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性は、行セット内の行数を指定します。 SQLFetch によってフェッチされる行セットが結果セットの末尾と重複する場合、SQLFetch は部分的な行セットを返します。 つまり、S + R - 1 が L より大きい場合(S はフェッチされる行セットの開始行、R は行セット サイズ、L は結果セットの最後の行)、行セットの最初の L - S + 1 行のみが有効です。 残りの行は空で、状態はSQL_ROW_NOROW。
SQLFetch が戻った後、現在の行は行セットの最初の行になります。
次の表に示す規則では、このセクションの 2 番目の表に示されている条件に基づいて、 SQLFetch の呼び出し後のカーソル位置について説明します。
| 条件 | 新しい行セットの最初の行 |
|---|---|
| 開始前 | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | 終了後 |
| 終了後 | 終了後 |
[1] フェッチの間に行セットのサイズが変更された場合、これは前のフェッチで使用された行セット サイズです。
[2] フェッチの間に行セットのサイズが変更された場合、これは新しいフェッチで使用された行セット サイズです。
| Notation | 意味 |
|---|---|
| 開始前 | ブロック カーソルは、結果セットの開始前に配置されます。 新しい行セットの最初の行が結果セットの先頭より前の場合、 SQLFetch はSQL_NO_DATAを返します。 |
| 終了後 | ブロック カーソルは、結果セットの末尾の後に配置されます。 新しい行セットの最初の行が結果セットの末尾の後にある場合、 SQLFetch はSQL_NO_DATAを返します。 |
| CurrRowsetStart | 現在の行セット内の最初の行の番号。 |
| LastResultRow | 結果セット内の最後の行の番号。 |
| RowsetSize | 行セットのサイズ。 |
たとえば、結果セットの行数が 100 で、行セットのサイズが 5 であるとします。 次の表は、 SQLFetch によって異なる開始位置に対して返される行セットとリターン コードを示しています。
| 現在の行セット | リターン コード | 新しい行セット | フェッチされた行の数 |
|---|---|---|---|
| 開始前 | SQL_SUCCESS | 1 から 5 | 5 |
| 1 から 5 | SQL_SUCCESS | 6 から 10 | 5 |
| 52 から 56 | SQL_SUCCESS | 57 から 61 | 5 |
| 91 から 95 | SQL_SUCCESS | 96 から 100 | 5 |
| 93 から 97 | SQL_SUCCESS | 98 から 100。 行の状態配列の行 4 と行 5 は、SQL_ROW_NOROWに設定されます。 | 3 |
| 96 から 100 | SQL_NO_DATA | [なし] : | 0 |
| 99 から 100 | SQL_NO_DATA | [なし] : | 0 |
| 終了後 | SQL_NO_DATA | [なし] : | 0 |
バインドされた列のデータを返す
SQLFetch は各行を返すので、バインドされた各列のデータを、その列にバインドされたバッファーに格納します。 列がバインドされていない場合、 SQLFetch はデータを返しませんが、ブロック カーソルを前方に移動します。 データは引き続き SQLGetData を使用して取得できます。 カーソルが複数行カーソルの場合 (つまり、SQL_ATTR_ROW_ARRAY_SIZEが 1 より大きい場合)、SQLGetData は、infoType が SQL_GETDATA_EXTENSIONS の SQLGetInfo が呼び出されたときにSQL_GD_BLOCKが返された場合にのみ呼び出すことができます。 (詳細については、「 SQLGetData」を参照してください)。
SQLFetch は、1 行のバインドされた列ごとに次の処理を行います。
長さ/インジケーター バッファーをSQL_NULL_DATAに設定し、データが NULL の場合は次の列に進みます。 データが NULL で、長さ/インジケーター バッファーがバインドされていない場合、 SQLFetch は行の SQLSTATE 22002 (インジケーター変数は必須ですが、指定されていません) を返し、次の行に進みます。 長さ/インジケーター バッファーのアドレスを確認する方法については、 SQLBindCol の「バッファー アドレス」を参照してください。
列のデータが NULL でない場合、 SQLFetch は手順 2 に進みます。
SQL_ATTR_MAX_LENGTH ステートメント属性が 0 以外の値に設定されていて、列に文字またはバイナリ データが含まれている場合、データは SQL_ATTR_MAX_LENGTH バイトに切り捨てられます。
Note
SQL_ATTR_MAX_LENGTH ステートメント属性は、ネットワーク トラフィックを減らすことを目的としています。 これは通常、データ ソースによって実装され、ネットワーク経由でデータを返す前にデータが切り捨てられます。 ドライバーとデータ ソースは、サポートするために必要ありません。 そのため、データが特定のサイズに切り捨てられることを保証するために、アプリケーションはそのサイズのバッファーを割り当て、SQLBindCol の cbValueMax 引数にサイズを指定する必要があります。
SQLBindCol の TargetType で指定された型にデータを変換します。
データが文字やバイナリなどの可変長データ型に変換された場合、 SQLFetch はデータの長さがデータ バッファーの長さを超えているかどうかを確認します。 文字データの長さ (null 終端文字を含む) がデータ バッファーの長さを超える場合、 SQLFetch は データをデータ バッファーの長さに切り捨てて、null 終端文字の長さを減らします。 次に、データを null 終了します。 バイナリ データの長さがデータ バッファーの長さを超える場合、 SQLFetch はデータ バッファーの長さに切り捨てます。 データ バッファーの長さは、SQLBindCol の BufferLength で指定します。
SQLFetch では 、固定長データ型に変換されたデータが切り捨てられることはありません。常に、データ バッファーの長さがデータ型のサイズであることを前提としています。
変換された (および切り捨てられた可能性がある) データをデータ バッファーに格納します。 データ バッファーのアドレスを確認する方法については、 SQLBindCol の「バッファー アドレス」を参照してください。
データの長さを長さ/インジケーター バッファーに格納します。 インジケーター ポインターと長さポインターの両方が同じバッファーに設定されている場合 ( SQLBindCol の呼び出しと同様)、長さは有効なデータのバッファーに書き込まれ、SQL_NULL_DATAは NULL データのバッファーに書き込まれます。 長さ/インジケーター バッファーがバインドされていない場合、 SQLFetch は長さを返しません。
文字データまたはバイナリ データの場合、データ バッファーが小さすぎるため、変換後と切り捨て前のデータの長さです。 ドライバーが変換後にデータの長さを判断できない場合 (長いデータの場合と同様) は、長さを SQL_NO_TOTAL に設定します。 SQL_ATTR_MAX_LENGTH ステートメント属性が原因でデータが切り捨てられた場合、この属性の値は、実際の長さ ではなく長さ/インジケーター バッファーに格納されます。 これは、ドライバーが実際の長さを把握する方法がないように、変換前にサーバー上のデータを切り捨てるようにこの属性が設計されているためです。
他のすべてのデータ型の場合、これは変換後のデータの長さです。つまり、データが変換された型のサイズです。
長さ/インジケーター バッファーのアドレスを確認する方法については、 SQLBindCol の「バッファー アドレス」を参照してください。
変換中に有効桁数を失わずにデータが切り捨てられる場合 (たとえば、実数 1.234 は変換時に整数 1 に切り捨てられます)、 SQLFetch は SQLSTATE 01S07 (小数部の切り捨て) を返し、SQL_SUCCESS_WITH_INFOします。 データ バッファーの長さが小さすぎるためにデータが切り捨てられた場合 (たとえば、文字列 "abcdef" が 4 バイトのバッファーに格納されている場合)、 SQLFetch は SQLSTATE 01004 (データが切り捨てられた) を返し、SQL_SUCCESS_WITH_INFO。 SQL_ATTR_MAX_LENGTH ステートメント属性が原因でデータが切り捨てられた場合、 SQLFetch はSQL_SUCCESSを返し、SQLSTATE 01S07 (小数部の切り捨て) または SQLSTATE 01004 (データの切り捨て) を返しません。 変換中に有効桁数を失ってデータが切り捨てられた場合 (たとえば、100,000 を超えるSQL_INTEGER値がSQL_C_TINYINTに変換された場合)、 SQLFetch は SQLSTATE 22003 (範囲外の数値) とSQL_ERROR (行セット サイズが 1 の場合) またはSQL_SUCCESS_WITH_INFO (行セット サイズが 1 より大きい場合) を返します。
SQLFetch または SQLFetchScroll がSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返さない場合、バインドされたデータ バッファーと長さ/インジケーター バッファーの内容は未定義です。
行の状態の配列
行状態配列は、行セット内の各行の状態を返すために使用されます。 この配列のアドレスは、SQL_ATTR_ROW_STATUS_PTR ステートメント属性で指定します。 配列はアプリケーションによって割り当てられ、SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で指定された数の要素を持つ必要があります。 その値は、 SQLFetch、 SQLFetchScroll、 および SQLBulkOperations または SQLSetPos によって設定されます (カーソルが SQLExtendedFetch によって配置された後に呼び出された場合を除く)。 SQL_ATTR_ROW_STATUS_PTR ステートメント属性の値が null ポインターの場合、これらの関数は行の状態を返しません。
SQLFetch または SQLFetchScroll がSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返さない場合、行状態配列バッファーの内容は未定義です。
行の状態配列には、次の値が返されます。
| 行の状態の配列値 | 説明 |
|---|---|
| SQL_ROW_SUCCESS | 行は正常にフェッチされ、この結果セットから最後にフェッチされてから変更されていません。 |
| SQL_ROW_SUCCESS_WITH_INFO | 行は正常にフェッチされ、この結果セットから最後にフェッチされてから変更されていません。 ただし、行に関する警告が返されました。 |
| SQL_ROW_ERROR | 行のフェッチ中にエラーが発生しました。 |
| SQL_ROW_UPDATED[1],[2], [3] | 行は正常にフェッチされ、この結果セットから最後にフェッチされてから変更されました。 行がこの結果セットから再度フェッチされるか、 SQLSetPos によって更新された場合、状態は行の新しい状態に変更されます。 |
| SQL_ROW_DELETED[3] | 行は、この結果セットから最後にフェッチされてから削除されています。 |
| SQL_ROW_ADDED[4] | SQLBulkOperations によって行が挿入されました。 行がこの結果セットから再度フェッチされるか、 SQLSetPos によって更新された場合、その状態はSQL_ROW_SUCCESS。 |
| SQL_ROW_NOROW | 行セットは結果セットの末尾と重複しており、行状態配列のこの要素に対応する行は返されませんでした。 |
[1] キーセット、混合、動的カーソルの場合、キー値が更新されると、データの行が削除され、新しい行が追加されたと見なされます。
[2] 一部のドライバーはデータの更新を検出できないため、この値を返すことができません。 ドライバーが再フェッチされた行の更新を検出できるかどうかを判断するために、アプリケーションは SQL_ROW_UPDATES オプションを使用して SQLGetInfo を呼び出します。
[3] SQLFetch は、SQLFetchScroll の呼び出しと混在している場合にのみ、この値を返すことができます。 これは、 SQLFetch が結果セット内を前方に移動し、排他的に使用される場合、行を再フェッチしないためです。 行は再フェッチされないため、 SQLFetch は、以前にフェッチされた行に対して行われた変更を検出しません。 ただし、 SQLFetchScroll が以前にフェッチした行の前にカーソルを配置し、 SQLFetch を使用してそれらの行をフェッチする場合、 SQLFetch はそれらの行に対する変更を検出できます。
[4] SQLBulkOperations によってのみ返されます。 SQLFetch または SQLFetchScroll によって設定されません。
行フェッチバッファー
フェッチされた行バッファーは、フェッチ中にエラーが発生したためにデータが返されなかった行を含め、フェッチされた行の数を返すために使用されます。 つまり、行ステータス配列の値がSQL_ROW_NOROWされていない行数です。 このバッファーのアドレスは、SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性で指定します。 バッファーはアプリケーションによって割り当てられます。 SQLFetch と SQLFetchScroll によって設定されます。 SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性の値が null ポインターの場合、これらの関数はフェッチされた行数を返しません。 結果セット内の現在の行の数を確認するために、アプリケーションは SQL_ATTR_ROW_NUMBER 属性を使用して SQLGetStmtAttr を呼び出すことができます。
SQLFetch または SQLFetchScroll がSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返さない場合、SQL_NO_DATAが返される場合を除き、フェッチされた行バッファーの内容は未定義になります。この場合、フェッチされた行バッファーの値は 0 に設定されます。
エラー処理
エラーと警告は、個々の行または関数全体に適用できます。 診断レコードの詳細については、「 診断 」と 「SQLGetDiagField」を参照してください。
関数全体のエラーと警告
SQLSTATE HYT00 (タイムアウト期限切れ) や SQLSTATE 24000 (無効なカーソル状態) などのエラーが関数全体に適用される場合 、SQLFetch はSQL_ERRORと該当する SQLSTATE を返します。 行セット バッファーの内容は未定義であり、カーソル位置は変更されません。
警告が関数全体に適用される場合、 SQLFetch はSQL_SUCCESS_WITH_INFOと該当する SQLSTATE を返します。 関数全体に適用される警告の状態レコードは、個々の行に適用される状態レコードの前に返されます。
個々の行のエラーと警告
エラー (SQLSTATE 22012 (0 除算) など) または警告 (SQLSTATE 01004 (データの切り捨て) など) が 1 つの行に適用される場合、 SQLFetchは次の処理を行います。
行ステータス配列の対応する要素を、エラーの場合はSQL_ROW_ERROR、警告の場合はSQL_ROW_SUCCESS_WITH_INFOに設定します。
エラーまたは警告の SQLSTATEs を含む 0 個以上の状態レコードを追加します。
状態レコードの行番号フィールドと列番号フィールドを設定します。 SQLFetch で行番号または列番号を特定できない場合は、その番号をそれぞれSQL_ROW_NUMBER_UNKNOWNまたはSQL_COLUMN_NUMBER_UNKNOWNに設定します。 状態レコードが特定の列に適用されない場合、 SQLFetch は列番号をSQL_NO_COLUMN_NUMBERに設定します。
SQLFetch は、行セット内のすべての行をフェッチするまで、行のフェッチを続行します。 行セットのすべての行でエラーが発生しない限り、SQL_SUCCESS_WITH_INFOを返します (状態がSQL_ROW_NOROW行は含まれません)。その場合は、SQL_ERRORが返されます。 特に、行セットのサイズが 1 で、その行でエラーが発生した場合、 SQLFetch はSQL_ERRORを返します。
SQLFetch は、状態レコードを行番号順に返します。 つまり、不明な行 (存在する場合) のすべての状態レコードが返されます。次に、最初の行のすべての状態レコード (存在する場合) を返し、2 番目の行 (存在する場合) のすべての状態レコードを返します。 各行のステータス レコードは、ステータス レコードの順序付けに関する通常のルールに従って並べ替えられます。詳細については、 SQLGetDiagField の「状態レコードのシーケンス」を参照してください。
記述子と SQLFetch
次のセクションでは、 SQLFetch が記述子と対話する方法について説明します。
引数マッピング
ドライバーは、 SQLFetch の引数に基づいて記述子フィールドを設定しません。
その他の記述子フィールド
SQLFetch では、次の記述子フィールドが使用されます。
| 記述子フィールド | Desc。 | のフィールド | を使用して設定する |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | Ard | header | ステートメント属性SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | Ird | header | ステートメント属性SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | Ard | header | ステートメント属性SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | Ard | header | SQL_ATTR_ROW_BIND_TYPE ステートメント属性 |
| SQL_DESC_COUNT | Ard | header | SQLBindCol の ColumnNumber 引数 |
| SQL_DESC_DATA_PTR | Ard | records | SQLBindCol の TargetValuePtr 引数 |
| SQL_DESC_INDICATOR_PTR | Ard | records | SQLBindCol のStrLen_or_IndPtr引数 |
| SQL_DESC_OCTET_LENGTH | Ard | records | SQLBindCol の BufferLength 引数 |
| SQL_DESC_OCTET_LENGTH_PTR | Ard | records | SQLBindCol のStrLen_or_IndPtr引数 |
| SQL_DESC_ROWS_PROCESSED_PTR | Ird | header | ステートメント属性SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | Ard | records | SQLBindCol の TargetType 引数 |
すべての記述子フィールドは、 SQLSetDescField を使用して設定することもできます。
個別の長さとインジケーター バッファー
アプリケーションは、長さとインジケーターの値を保持するために使用できる 1 つのバッファーまたは 2 つの個別のバッファーをバインドできます。 アプリケーションが SQLBindCol を呼び出すと、ドライバーは ARD のSQL_DESC_OCTET_LENGTH_PTRフィールドとSQL_DESC_INDICATOR_PTR フィールドを同じアドレスに設定します。これは 、StrLen_or_IndPtr 引数に渡されます。 アプリケーションが SQLSetDescField または SQLSetDescRec を呼び出すときに、これら 2 つのフィールドを異なるアドレスに設定できます。
SQLFetch は、アプリケーションで個別の長さとインジケーター バッファーを指定したかどうかを判断します。 この場合、データが NULL でない場合、 SQLFetch はインジケーター バッファーを 0 に設定し、長さバッファーの長さを返します。 データが NULL の場合、 SQLFetch はインジケーター バッファーをSQL_NULL_DATAに設定し、長さバッファーは変更しません。
コード例
「SQLBindCol、SQLColumns、SQLGetData、SQLProcedures」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 結果セット内の列にバッファーをバインドする | SQLBindCol 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 結果セット内の列に関する情報を返す | SQLDescribeCol 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| データブロックのフェッチまたは結果セットのスクロール | SQLFetchScroll 関数 |
| ステートメントのカーソルを閉じる | SQLFreeStmt 関数 |
| データの列の一部またはすべてをフェッチする | SQLGetData 関数 |
| 結果セット列の数を返す | SQLNumResultCols 関数 |
| 実行のためのステートメントの準備 | SQLPrepare 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示