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されます。

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 関数」を参照してください。

Connection-Related非同期処理の取り消し

関数が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 の呼び出しは無効です。

関連する関数

参照

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