仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLCancel() を使用して、 長形式データの分割送信 / 取り出しで説明している実行時データ 順序列を永久終了することができます。
マルチ・スレッド・アプリケーションでは、SQLCancel() は元の要求を取り消し、 HY008 の SQLSTATE を返します。
構文
SQLRETURN SQLCancel (SQLHSTMT StatementHandle); /* hstmt */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル |
使用法
SQLExecDirect() または SQLExecute() が SQL_NEED_DATA を返して実行時データ・パラメーターの値を請求した後で、 SQLCancel() を使用して 長形式データの分割送信 / 取り出しに記述されている実行時データ・シーケンスを取り消すことができます。 SQLCancel() は、シーケンスの中の最後の SQLParamData() の前であれば、いつでも呼び出すことができます。このシーケンスを取り消した後で、アプリケーションは、 SQLExecute() または SQLExecDirect() を呼び出して、実行時データ・シーケンスを再開することができます。
DB2 CLI バージョン 2 で、または SQL_ATTR_ODBC_VERSION 環境属性が SQL_OV_ODBC2 に設定されている場合に、ステートメントについて何も処理が行われていないときにアプリケーションが SQLCancel() を呼び出すと、 SQLCancel() は、 SQL_CLOSE オプションを選択した SQLFreeStmt() と同じ効果を持ちます。このことは、DB2 CLI バージョン 5 の場合、または SQL_ATTR_ODBC_VERSION 環境属性が SQL_OV_ODBC5 に設定されている場合には、該当しません。ステートメントについて何も処理が行われていないときに、 SQLCancel() への呼び出しがなされると、 SQL_CLOSE オプションを指定したときの SQLFreeStmt() と同じ取り扱いにはならず、何の効果もありません。カーソルをクローズするには、アプリケーションが SQLCancel() を呼び出すのではなく、 SQLFreeStmt() を使用する必要があります。
非同期処理の取り消し
アプリケーションは、関数を非同期に呼び出した後に、関数を繰り返し呼び出して、処理を完了したかどうかを判別します。関数がまだ処理中の場合は、SQL_STILL_EXECUTING を返します。関数が処理を完了した場合は、異なるコードを返します。
SQL_STILL_EXECUTING を返した関数に任意の呼び出しをした後で、アプリケーションは、 SQLCancel() を呼び出して、関数を取り消すことができます。取り消し要求が成功したときは、SQL_SUCCESS が返されます。このメッセージは、関数が実際に取り消されたことを示すものではなく、取り消し要求が処理されたことを示すものです。アプリケーションは引き続き、戻りコードが SQL_STILL_EXECUTING でなくなるまで、元の関数を呼び出す必要があります。関数が正常に取り消された場合は、戻りコードは、 SQL_ERROR および SQLSTATE HY008 (操作が取り消されました。) になります。関数が通常の処理を終了した場合、戻りコードは、関数が成功すれば、SQL_SUCCESS または SQL_SUCCESS_WITH_INFO になり、関数が失敗すれば、SQL_ERROR および HY008 (操作が取り消されました。) 以外の SQLSTATE になります。
非同期処理の詳細については、CLI の非同期実行を参照してください。
マルチ・スレッド・アプリケーションでの関数の取り消し
マルチ・スレッド・アプリケーションでは、ステートメントについて非同期に実行中の関数を取り消すことができます。関数を取り消すには、アプリケーションは、ターゲット関数で使用されたのと同様 (ただし異なるスレッドで)、同じステートメント・ハンドルを指定して SQLCancel() を呼び出します。関数を取り消す方法は、オペレーティング・システムによって異なります。非同期に実行している関数の取り消しに関して、 SQLCancel() の戻りコードは DB2 CLI が要求を正常に処理したかどうかを示すだけです。返される可能性があるのは SQL_SUCCESS または SQL_ERROR だけで、SQLSTATE は返されません。元の関数が取り消される場合、SQL_ERROR および SQLSTATE HY008 (操作が取り消されました。) が返されます。
SQL ステートメントの実行中に、ステートメントの実行を取り消すために SQLCancel() が別のスレッドで呼び出される場合、実行が成功して SQL_SUCCESS を返す一方で、取り消しも成功することが可能です。この場合、DB2 CLI は、ステートメント実行によりオープンされたカーソルが取り消しによってクローズされたと想定するので、アプリケーションはそのカーソルを使用できなくなります。
スレッド化の詳細については、マルチスレッドのアプリケーション作成を参照してください。
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY018 | サーバーが取消し要求を拒否しました。 | サーバーが取り消し要求を拒否しました。 |
HY506 | ファイルのクローズ・エラーが起きました。 | SQLParamData()/SQLPutData() を使用して LOB データを分割挿入しているときに、 DB2 CLI によって生成された一時ファイルがクローズし、エラーが発生しました。 |
制約
なし。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */ /* ... */ /* cancel the DATA AT EXEC state for hstmt */ sqlrc = SQLCancel(hstmt); STMT_HANDLE_CHECK( hstmt, sqlrc); }
参照