SQLCancel 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLCancel は、ステートメントの処理を取り消します。
接続またはステートメントの処理を取り消すには、 SQLCancelHandle 関数を使用します。
構文
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
引数
StatementHandle
[入力]ステートメント ハンドル。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLCancel がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLCancel によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 引数 *MessageText buffer 内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLCancel 関数が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に関連付けられている接続ハンドルで非同期操作が進行中のため、キャンセル操作が失敗しました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY018 | サーバーがキャンセル要求を拒否しました | サーバーがキャンセル要求を拒否しました。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
説明
SQLCancel は、ステートメントに対して次の種類の処理を取り消すことができます。
ステートメントで非同期的に実行されている関数。
データを必要とするステートメントの関数。
別のスレッドの ステートメントで実行されている関数。
ODBC 2 の場合。x、 ステートメントに対して処理が実行されていないときにアプリケーションが SQLCancel を呼び出す場合、 SQLCancel は sqlFreeStmt と同じ効果をSQL_CLOSEオプションで持ちます。この動作は完全な場合にのみ定義され、アプリケーションは SQLFreeStmt または SQLCloseCursor を呼び出してカーソルを閉じる必要があります。
データを必要とするステートメントまたはステートメントの関数で非同期的に実行されている関数を取り消すために SQLCancel が呼び出されると、取り消される関数によってポストされた診断レコードがクリアされ、 SQLCancel は独自の診断レコードをポストします。 SQLCancel を呼び出して別のスレッドのステートメントで実行されている関数を取り消すと、取り消される関数の診断レコードはクリアされず、独自の診断レコードはポストされません。
非同期処理の取り消し
アプリケーションは、関数を非同期的に呼び出した後、関数を繰り返し呼び出して、処理が完了したかどうかを判断します。 関数がまだ処理中の場合は、SQL_STILL_EXECUTINGを返します。 関数が処理を完了すると、別のコードが返されます。
SQL_STILL_EXECUTINGを返す関数を呼び出した後、アプリケーションは SQLCancel を 呼び出して関数を取り消すことができます。 取り消し要求が成功した場合、ドライバーはSQL_SUCCESSを返します。 このメッセージは、関数が実際に取り消されたことを示すものではありません。これは、取り消し要求が処理されたことを示します。 関数が実際に取り消された場合、または取り消された場合は、ドライバーに依存し、データ ソースに依存します。 戻りコードがSQL_STILL_EXECUTINGされないまで、アプリケーションは元の関数を引き続き呼び出す必要があります。 関数が正常に取り消された場合、戻りコードはSQL_ERRORされ、SQLSTATE HY008 (操作は取り消されました)。 関数が通常の処理を完了した場合、戻りコードは、関数が成功した場合はSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFO、関数が失敗した場合は HY008 (Operation canceled) 以外の SQLSTATE をSQL_ERRORします。
Note
ODBC 3.5 では、ステートメントに対して処理が実行されていない場合の SQLCancel の呼び出しは、SQL_CLOSE オプションを使用した SQLFreeStmt として扱われませんが、まったく効果はありません。 カーソルを閉じるには、アプリケーションは SQLCancel ではなく SQLCloseCursor を呼び出す必要があります。
非同期処理の詳細については、「 非同期実行」を参照してください。
データが必要な関数の取り消し
SQLExecute または SQLExecDirect がSQL_NEED_DATAを返した後、実行中のすべてのパラメーターに対してデータが送信される前に、アプリケーションは SQLCancel を呼び出してステートメントの実行を取り消すことができます。 ステートメントが取り消されると、アプリケーションは SQLExecute または SQLExecDirect を再度呼び出すことができます。 詳細については、「 SQLBindParameter」を参照してください。
SQLBulkOperations または SQLSetPos がSQL_NEED_DATAを返した後、実行中のすべての列に対してデータが送信される前に、アプリケーションは SQLCancel を呼び出して操作を取り消すことができます。 操作が取り消されると、アプリケーションは SQLBulkOperations または SQLSetPos を再度呼び出すことができます。取り消しは、カーソルの状態や現在のカーソル位置には影響しません。 詳細については、「 SQLBulkOperations 」または 「SQLSetPos」を参照してください。
別のスレッドで実行されている関数の取り消し
マルチスレッド アプリケーションでは、アプリケーションは別のスレッドで実行されている関数を取り消すことができます。 関数を取り消すために、アプリケーションは、ターゲット関数で使用されているのと同じステートメント ハンドルを使用して SQLCancel を呼び出しますが、別のスレッドで呼び出します。 関数の取り消し方法は、ドライバーとオペレーティング システムによって異なります。 非同期的に実行されている関数を取り消す場合と同様に、 SQLCancel のリターン コードは、ドライバーが要求を正常に処理したかどうかを示します。 SQL_SUCCESSまたはSQL_ERRORのみを返すことができます。診断情報は返されません。 元の関数が取り消されると、SQL_ERRORと SQLSTATE HY008 (操作が取り消されました) が返されます。
SQLCancel が別のスレッドで呼び出されてステートメントの実行を取り消すときに SQL ステートメントが実行されている場合、取り消しも成功している間に実行が成功し、SQL_SUCCESSが返される可能性があります。 この場合、ドライバー マネージャーは、ステートメントの実行によって開かれたカーソルがキャンセルによって閉じられていると想定するため、アプリケーションはカーソルを使用できません。
スレッド処理の詳細については、「 マルチスレッド」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| バッファーをパラメーターにバインドする | SQLBindParameter 関数 |
| 一括挿入または更新操作の実行 | SQLBulkOperations 関数 |
| SQLCancel の機能に加えて、接続ハンドルで非同期的に実行されている関数を取り消します。 | SQLCancelHandle 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| ステートメント ハンドルの解放 | SQLFreeStmt |
| 診断レコードのフィールドまたは診断ヘッダーのフィールドの取得 | SQLGetDiagField 関数 |
| 診断データ構造の複数のフィールドを取得する | SQLGetDiagRec 関数 |
| データを送信する次のパラメーターを返す | SQLParamData 関数 |
| 実行時のパラメーター データの送信 | SQLPutData 関数 |
| カーソルを行セット内に配置する、行セット内のデータを更新する、または結果セット内のデータを更新または削除する | SQLSetPos 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示