SQLMoreResults 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ODBC
まとめ
SQLMoreResults は、 SELECT、 UPDATE、 INSERT、または DELETE ステートメントを含むステートメントでより多くの結果を使用できるかどうかを判断し、存在する場合は、それらの結果の処理を初期化します。
構文
SQLRETURN SQLMoreResults(
SQLHSTMT StatementHandle);
引数
StatementHandle
[入力]ステートメント ハンドル。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE、OR SQL_PARAM_DATA_AVAILABLE。
診断
SQLMoreResults がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLMoreResults によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S02 | オプション値が変更されました | バッチの処理中にステートメント属性の値が変更されました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 40001 | シリアル化エラー | 別のトランザクションでリソースのデッドロックが発生したため、トランザクションがロールバックされました。 |
| 40003 | ステートメントの完了が不明です | この関数の実行中に関連付けられた接続が失敗し、トランザクションの状態を特定できません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました |
StatementHandle に対して非同期処理が有効になりました。
SQLMoreResults 関数が呼び出され、実行が完了する前に、 StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、 SQLMoreResults 関数が StatementHandle で再度呼び出されました。 SQLMoreResults 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLMoreResults 関数が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
説明
SELECT ステートメントは結果セットを返します。 UPDATE、 INSERT、 および DELETE ステートメントは、影響を受ける行の数を返します。 これらのステートメントのいずれかがバッチ処理され、パラメーターの配列 (パラメーターの順序が増え、バッチ内に出現する順序で番号が付けられます) またはプロシージャで送信された場合、複数の結果セットまたは行数を返すことができます。 ステートメントのバッチとパラメーターの配列の詳細については、「 SQL ステートメントのバッチ」 および「 パラメーター値の配列」を参照してください。
バッチを実行すると、アプリケーションは最初の結果セットに配置されます。 アプリケーションは、1 つの結果セットがある場合と同様に、最初または後続の結果セットで SQLBindCol、 SQLBulkOperations、 SQLFetch、 SQLGetData、 SQLFetchScroll、 SQLSetPos、およびすべてのメタデータ関数を呼び出すことができます。 最初の結果セットで完了すると、アプリケーションは SQLMoreResults を呼び出して次の結果セットに移動します。 別の結果セットまたはカウントが使用可能な場合、 SQLMoreResults はSQL_SUCCESSを返し、追加の処理のために結果セットまたはカウントを初期化します。 結果セット生成ステートメントの間に行数生成ステートメントが出現する場合は、SQLMoreResults を呼び出すことによってステップオーバーできます。UPDATE、INSERT、または DELETE ステートメントに対して SQLMoreResults を呼び出した後、アプリケーションは SQLRowCount を呼び出すことができます。
行がフェッチされていない現在の結果セットがあった場合、 SQLMoreResults はその結果セットを破棄し、次の結果セットまたはカウントを使用できるようにします。 すべての結果が処理された場合、 SQLMoreResults は SQL_NO_DATAを返します。 一部のドライバーでは、すべての結果セットと行数が処理されるまで、出力パラメーターと戻り値は使用できません。 このようなドライバーでは、 SQLMoreResults がSQL_NO_DATAを返すと、出力パラメーターと戻り値が使用可能になります。
前の結果セットに対して確立されたバインディングは、引き続き有効です。 この結果セットで列構造が異なる場合、SQLFetch または SQLFetchScroll を呼び出すと、エラーまたは切り捨てが発生する可能性があります。 これを防ぐために、アプリケーションは SQLBindCol を呼び出して、必要に応じて明示的に再バインドする必要があります (または、記述子フィールドを設定して再バインドする必要があります)。 または、アプリケーションで SQLFreeStmt を呼び出し、 option をSQL_UNBINDしてすべての列バッファーのバインドを解除することもできます。
カーソルの種類、カーソルのコンカレンシー、キーセット サイズ、最大長など、ステートメント属性の値は、 アプリケーションが SQLMoreResults の呼び出しによってバッチ内を移動すると変更される可能性があります。 この場合、 SQLMoreResults は SQL_SUCCESS_WITH_INFO と SQLSTATE 01S02 を返します (オプション値が変更されました)。
SQLCloseCursor を呼び出す場合、または Option が SQL_CLOSE の SQLFreeStmt を呼び出すと、バッチの実行の結果として使用可能であったすべての結果セットと行数が破棄されます。 ステートメント ハンドルは、割り当てられた状態または準備された状態に戻ります。 SQLCancel を呼び出して、バッチが実行され、ステートメント ハンドルが実行、カーソル位置、または非同期状態にある場合に非同期実行関数を取り消すと、キャンセル呼び出しが成功した場合に、バッチによって生成されたすべての結果セットと行数が破棄されます。 その後、 ステートメントは準備済みまたは割り当て済み状態に戻ります。
ステートメントまたはプロシージャのバッチが他の SQL ステートメントと SELECT、 UPDATE、 INSERT、 および DELETE ステートメントを混在させる場合、これらの他のステートメントは SQLMoreResults には影響しません。
詳細については、「 複数の結果」を参照してください。
ステートメントのバッチ内の検索された更新、挿入、または削除ステートメントがデータ ソースの行に影響しない場合、 SQLMoreResults はSQL_SUCCESSを返します。 これは、SQLExecDirect、SQLExecute、または SQLParamData を介して実行される検索された更新、挿入、または削除ステートメントの場合とは異なります。これは、データ ソースの行に影響を与えない場合にSQL_NO_DATAを返します。 SQLMoreResults の呼び出しで行数が影響を受けなかった後、アプリケーションが SQLRowCount を呼び出して行数を取得した場合、SQLRowCount はSQL_NO_DATAを返します。
結果処理関数の有効なシーケンス処理の詳細については、「 付録 B: ODBC 状態遷移テーブル」を参照してください。
SQL_PARAM_DATA_AVAILABLEおよびストリーム出力パラメーターの詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。
行数の可用性
バッチに複数の連続する行数生成ステートメントが含まれている場合、これらの行数が 1 つの行数にロールアップされる可能性があります。 たとえば、バッチに 5 つの挿入ステートメントがある場合、特定のデータ ソースは 5 つの個々の行数を返すことができます。 他の特定のデータ ソースでは、5 つの個々の行数の合計を表す行数が 1 つだけ返されます。
バッチに結果セット生成ステートメントと行カウント生成ステートメントの組み合わせが含まれている場合、行数はまったく使用できない場合があります。 行数の可用性に関するドライバーの動作は、 SQLGetInfo の呼び出しによって使用可能なSQL_BATCH_ROW_COUNT情報の種類に列挙されます。 たとえば、バッチに SELECT が含まれており、その後に 2 つの INSERTと別の SELECT が含まれていると します。 その後、次のケースが考えられます。
2 つの INSERT ステートメントに対応する行数は、まったく使用できません。 SQLMoreResults を最初に呼び出すと、2 番目の SELECT ステートメントの結果セットに配置されます。
2 つの INSERT ステートメントに対応する行数は、個別に使用できます。 ( SQLGetInfo を呼び出しても、SQL_BATCH_ROW_COUNT情報型のSQL_BRC_ROLLED_UP ビットは返されません)。 SQLMoreResults の最初の呼び出しは、最初の INSERT の行数に配置され、2 番目の呼び出しでは 2 番目の INSERT の行数に配置されます。 SQLMoreResults の 3 番目の呼び出しでは、2 番目の SELECT ステートメントの結果セットに配置されます。
2 つの INSERT に対応する行数は、使用可能な 1 つの行数にロールアップされます。 ( SQLGetInfo を呼び出すと、SQL_BATCH_ROW_COUNT情報型のSQL_BRC_ROLLED_UP ビットが返されます)。 SQLMoreResults を最初に呼び出すと、ロールアップ行数に移動し、 SQLMoreResults を 2 回目に呼び出すと、2 番目の SELECT の結果セットに配置されます。
特定のドライバーでは、行数は明示的なバッチでのみ使用でき、ストアド プロシージャでは使用できません。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| ステートメント処理の取り消し | SQLCancel 関数 |
| データブロックのフェッチまたは結果セットのスクロール | SQLFetchScroll 関数 |
| 1 つの行またはデータ ブロックを前方専用方向にフェッチする | SQLFetch 関数 |
| データ列の一部またはすべてをフェッチする | SQLGetData 関数 |