次の方法で共有

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の HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、SQLCancel によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 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 に関連付けられているドライバーは、関数をサポートしていません。

Comments

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

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

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

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

ODBC 2 の場合。x、ステートメントで処理が実行されていないときにアプリケーションが SQLCancel を呼び出す場合、SQLCancel は、SQL_CLOSE オプションを持つ SQLFreeStmt と同じ効果を持ちます。この動作は完全のためにのみ定義され、アプリケーションは 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 関数

参照

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