SQLCancel() - ステートメントを取り消す

SQLCancel() は、SQLExecDirect() または SQLExecute() シーケンスを早めに終了します。

SQLCancel() の ODBC 仕様

表 1. SQLCancel() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLCancel        (SQLHSTMT          hstmt);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLCancel() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル

使用法

ステートメントで次のタイプの処理をキャンセルするには、SQLCancel() を使用します。

  • 現在のスレッド上の実行時データ・シーケンス。
  • 別のスレッド上のステートメントで動作する関数。

実行時データ・シーケンスのキャンセル

SQLExecDirect() または SQLExecute() が SQL_NEED_DATA を戻し、実行時データ・パラメーターの値を 請求した後、SQLCancel() を使用して実行時データ・シーケンスを取り消すことができ ます。 SQLCancel() は、シーケンス内の最後の SQLParamData() の前であれば、いつでも呼び出すことができます。 このシーケンスを取り消した後に、SQLExecute() または SQLExecDirect() を呼び出して、 実行時データ・シーケンスを再開することができます。

実行時データ・シーケンスに関連していないステートメント・ハンドルで SQLCancel() を呼び出すと、SQLCancel() は、HandleType が SQL_HANDLE_STMT に設定されている SQLFreeHandle() と同じ効果があります。 カーソルをクローズするには、SQLCancel() を呼び出すのではなく、SQLCloseCursor() を使用する必要があります。

マルチスレッド・アプリケーションでの関数の取り消し

マルチスレッド・アプリケーションを実行するときに、別のスレッドで同時に動作している関数を取り消すことができます。 関数を取り消すには、ターゲットの関数が使用しているのと同じステートメント・ハンドルを持つ別のスレッドで SQLCancel() を呼び出し、ODBC 初期設定ファイルの INTERRUPT キーワードを、INTERRUPT=1 (デフォルト設定) または INTERRUPT=2 に設定します。 Db2® ODBC では、INTERRUPT=1 と INTERRUPT=2 は同じ振る舞いになり、SQLCancel() で接続が常にドロップされるように設定されます。 SQLCancel() を呼び出した後で、Db2 ODBC は戻りコードを SQL_SUCCESS または SQL_ERROR (SQLSTATE なし) のいずれかに設定し、取り消し要求の処理が正常に完了したかどうかを示します。 要求が正常に完了した場合、ステートメント・ハンドルに関連付けられている接続はドロップされ、取り消された関数は SQLCODE -924 および SQLSTATE 58006 を返します。 このステートメント・ハンドルで追加のデータベース要求を処理するには、データベース・サーバーとの新しい接続を確立する必要があります。

SQL ステートメントの実行中に、このステートメントの実行を取り消すために SQLCancel() が別のスレッドで呼び出されると、その実行が成功して SQL_SUCCESS が返される一方、取り消しも成功する可能性があります。 この場合、ステートメントに関連付けられた接続は、戻りコードに関係なくドロップされるため、接続を再確立するまでは、そのステートメントで追加のデータベース要求を処理できません。

戻りコード

SQLCancel() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_INVALID_HANDLE
  • SQL_ERROR

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLCancel() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。

制約事項

Db2 ODBC は、非同期ステートメントの実行をサポートしていません。