次の方法で共有

SQLCancelHandle 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.8 標準コンプライアンス: なし

ほとんどの ODBC 3.8 (以降) ドライバーでは、この関数が実装されることが想定されています。 ドライバーがそうでない場合、Handle パラメーターの接続ハンドルを使用して SQLCancelHandle を呼び出すと、SQLSTATE が IM001 のSQL_ERRORが返され、メッセージ 'Driver does not support this function'' A call to SQLCancelHandle with a statement handle as the Handle parameter will be mapped to a call to SQLCancel by the Driver Manager and can be processed if the driver implements SQLCancel. アプリケーションでは 、SQLGetFunctions を使用して、ドライバーが SQLCancelHandle をサポートしているかどうかを判断できます。

まとめ
SQLCancelHandle は、接続またはステートメントの処理を取り消します。 Driver Manager は、HandleType がSQL_HANDLE_STMTされると、SQLCancelHandle への呼び出しを SQLCancel への呼び出しにマップします。

構文

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

引数

HandleType
[入力]カセル処理を行うハンドルの型。 有効な値は、SQL_HANDLE_DBCまたはSQL_HANDLE_STMTです。

Handle
[入力]処理を取り消すハンドル。

Handle が HandleType で指定された型の有効なハンドルでない場合、SQLCancelHandle はSQL_INVALID_HANDLEを返します。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLCancelHandle がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、 HandleType が SQL_HANDLE_STMT で、ステートメント ハンドル Handle または HandleType がSQL_HANDLE_DBCと接続ハンドル ハンドルを使用して SQLGetDiagRec を呼び出します。

次の表に、 SQLCancelHandle によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 引数 *MessageText buffer 内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010 関数シーケンス エラー Handle に関連付けられているステートメント ハンドルの 1 つに対して非同期的に実行されるステートメント関連の関数が呼び出され、HandleType が SQL_HANDLE_DBC に設定されました。 SQLCancelHandle が呼び出されたときに、非同期関数はまだ実行されていました。

(DM) HandleType 引数がSQL_HANDLE_STMTされました。関連付けられた接続ハンドルで非同期実行関数が呼び出されました。この関数が呼び出されたとき、関数はまだ実行されていました。

(DM) Handle と HandleType に関連付けられているステートメント ハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_HANDLE_DBCに設定され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。

ConnectionHandle に対して SQLBrowseConnect が呼び出され、SQL_NEED_DATA返されました。 この関数は、参照プロセスが完了する前に呼び出されました。
HY013 メモリ管理エラー メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY092 属性/オプション識別子が無効です HandleType が SQL_HANDLE_ENV または SQL_HANDLE_DESC に設定されました。
HY117 トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) ハンドル に関連付けられているドライバーは、 関数をサポートしていません。

HandleType を SQL_HANDLE_STMT に設定して SQLCancelHandle を呼び出すと、関数 SQLCancel によって返すことができる任意の SQLSTATE を返すことができます。

説明

この関数は SQLCancel に似ていますが、ステートメント ハンドルだけでなく、接続ハンドルまたはステートメント ハンドルをパラメーターとして受け取る場合があります。 Driver Manager は、HandleType がSQL_HANDLE_STMTされると、SQLCancelHandle への呼び出しを SQLCancel への呼び出しにマップします。 これにより、ドライバーが SQLCancelHandle を 実装していない場合でも、アプリケーションは SQLCancelHandle を使用してステートメント操作を取り消すことができます。

ステートメント操作の取り消しの詳細については、「 SQLCancel 関数」を参照してください。

[ハンドル] で進行中の操作がない場合、SQLCancelHandle の呼び出しは無効です。

接続ハンドルの SQLCancelHandle は、次の種類の処理を取り消すことができます。

  • 接続で非同期的に実行されている関数。

  • 別のスレッドの接続ハンドルで実行されている関数。

接続で非同期的に実行されている関数を取り消すために SQLCancelHandle が呼び出されると、 SQLCancelHandle によってポストされた診断レコードは、取り消される操作によって返された診断レコードに追加されます。 ただし、SQLCancelHandle は、別のスレッド上の接続で実行されている関数を取り消すときに診断レコードを返しません。

SQLCancelHandle を使用して SQLEndTran をキャンセルすると、接続が中断状態になることがあります。 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。

Note

Windows 7 より前の Windows オペレーティング システムに展開されるアプリケーションで SQLCancelHandle を使用する方法については、「 互換性マトリックス」を参照してください。

関数がSQL_STILL_EXECUTINGを返す場合、アプリケーションは SQLCancelHandle を呼び出して操作を取り消すことができます。 キャンセル要求が成功した場合、 SQLCancelHandle はSQL_SUCCESSを返します。 これは、元の関数が取り消されたことを意味するものではありません。これは、取り消し要求が処理されたことを示します。 ドライバーとデータ ソースによって、操作が取り消されるタイミングと取り消し日時が決まります。 戻りコードがSQL_STILL_EXECUTINGされないまで、アプリケーションは元の関数を引き続き呼び出す必要があります。 元の関数が取り消された場合、戻りコードはSQL_ERRORされ、SQLSTATE HY008 (操作は取り消されました)。 元の関数が通常の処理を完了した場合 (取り消されなかった場合)、元の関数が失敗した場合、戻りコードはSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFO、またはSQL_ERRORと HY008 以外の SQLSTATE (Operation canceled) になります。

別のスレッドで実行されている関数の取り消し

マルチスレッド アプリケーションでは、アプリケーションは別のスレッドで実行されている操作を取り消すことができます。 操作を取り消すために、アプリケーションは関数によって使用されるハンドルを使用して SQLCancelHandle を呼び出しますが、別のスレッドで呼び出します。 ドライバーとオペレーティング システムによって、操作の取り消し方法が決まります。 SQLCancelHandle のリターン コードは、ドライバーが要求を処理したか、SQL_SUCCESSまたはSQL_ERRORを返したかを示します (診断情報は返されません)。 元の関数の処理が取り消された場合、元の関数は SQL_ERROR を返し、SQLSTATE HY008 (操作は取り消されました) を返します。

関数を取り消すために別のスレッドで SQLCancelHandle が呼び出されたときに関数が実行されている場合、その関数は成功し、取り消しが有効になる前にSQL_SUCCESSを返すことができます。 SQLCancelHandle が操作を取り消す前に操作が完了した場合、SQLCancelHandle の呼び出しは無効です。

対象 解決方法については、
ステートメント ハンドルで非同期的に実行されている関数の取り消し、データを必要とするステートメントの関数の取り消し、または別のスレッドのステートメントで実行されている関数の取り消し。 SQLCancel 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
非同期実行 (ポーリング メソッド)