SQLCancel 関数

準拠
導入されたバージョン: ODBC 1.0 標準準拠: 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 値を取得するには、SQL_HANDLE_STMT の HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLCancel によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

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

(DM) StatementHandle に関連付けられている接続ハンドルで非同期操作が進行中であるため、操作の取り消し操作が失敗しました。
HY013 メモリ管理エラー 基になるメモリ オブジェクトにアクセスできなかったため、メモリの状態が低いため、関数呼び出しを処理できませんでした。
HY018 サーバーがキャンセル要求を拒否しました サーバーがキャンセル要求を拒否しました。
HY117 不明なトランザクション状態のため、接続が中断されます。 切断および読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、 SQLEndTran 関数を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。

コメント

SQLCancel は、ステートメントで次の種類の処理を取り消すことができます。

  • ステートメントで非同期的に実行されている関数。

  • データを必要とするステートメントの関数。

  • 別のスレッドのステートメントで実行されている関数。

ODBC 2。x、ステートメントに対して処理が実行されていないときにアプリケーションが SQLCancel を呼び出す場合、 SQLCancelsqlFreeStmt と同じ効果を持ち、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 以外の SQLSTATE (操作が取り消SQL_ERROR) されます。

注意

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 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル