SQLEndTran() - 接続のトランザクションを終了する
SQLEndTran() は、接続に関連付けられたすべてのステートメントの、 アクティブなすべてのトランザクションについて、コミットまたはロールバック操作を要求します。また、SQLEndTran() は、環境に関連付けられたすべての接続の、 コミットまたはロールバック操作の実行を要求することもできます。
SQLEndTran() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
SQLRETURN SQLEndTran (SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLSMALLINT | HandleType | 入力 | ハンドル・タイプを示します。 Handle が環境ハンドルの場合は SQL_HANDLE_ENV 、Handle が接続ハンドルの場合は SQL_HANDLE_DBC を含みます。 |
| SQLHANDLE | Handle | 入力 | HandleType によって示されるタイプのハンドルを 指定します。トランザクションの有効範囲を示します。 詳しくは、使用法を参照してください。 |
| SQLSMALLINT | CompletionType | 入力 | コミットまたはロールバックを実行するかどうかを指定します。
以下のいずれかの値を使用します。
|
使用法
トランザクションに含まれている可能性のある SQL ステートメントが現行データ・ソース に対して実行されると、新しいトランザクションが暗黙的に開始されます。 アプリケーションは、実行状況に基づき、コミットまたはロールバックが必要になることがあります。
引数 HandleType を SQL_HANDLE_ENV に設定し、引数 Handle を 有効な環境ハンドルに設定した場合、Db2® ODBC は、接続状態にあるすべての接続上で、 一つずつトランザクションをコミットまたはロールバックしようとします。トランザクションは、引数 CompletionType の値に応じて、コミットまたは ロールバックされます。
引数 CompletionType を SQL_COMMIT に設定した場合、SQLEndTran() は 接続上のすべてのステートメントにコミット要求を出します。CompletionType が SQL_ROLLBACK の場合、SQLEndTran() は接続上のすべての ステートメントにロールバック要求を出します。
SQLEndTran() はそれぞれの接続ごとに、SQL_SUCCESS を受け取ると、SQL_SUCCESS を戻します。SQLEndTran() は、1 つ以上の接続で SQL_ERROR を受け取ると、SQL_ERROR をアプリケーション に戻し、環境の診断データ構造に診断情報が入れます。コミットまたはロールバック操作中にどの接続が失敗したかを判別するには、 それぞれの接続ごとに SQLGetDiagRec() を呼び出します。
重要: 1 フェーズまたは 2 フェーズ・コミット・プロトコルが行われる整合 グローバル・トランザクションを Db2 ODBC が提供するために、 接続属性 SQL_ATTR_CONNECTTYPE を SQL_COORDINATED_TRANS (整合分散トランザクションを示す) に 設定する必要があります。
- 準備済み SQL ステートメント (SQLPrepare() が準備した) は複数のトランザクションにわたって存続しています。したがって、最初に SQLPrepare() を呼び出さなくても、再び実行できます。
- 以下の 1 つ以上の条件が満たされない限り、カーソル位置はコミット後も維持されます。
- サーバーが Db2 Server (VSE 版および VM 版) である。
- このハンドルの SQL_CURSOR_HOLD ステートメント属性 が SQL_CURSOR_HOLD_OFF に設定されている。
- Db2 ODBC 初期化ファイルで CURSORHOLD キーワードが設定されており、それによって、保留カーソルが 有効とならないようにしてあり、かつ、SQL_CURSOR_HOLD ステートメント属性をリセットすることに よって CURSORHOLD 設定がオーバーライド済みでない。
- CURSORHOLD キーワードが SQLDriverConnect() 接続ストリングにあり、 保留のカーソルの動作を無効にする指定になっている。 また、SQL_ATTR_CURSOR_HOLD ステートメント属性をリセットすることによって、この設定を オーバーライドしてはならない。
上記の状況のいずれかの理由で、カーソル位置が維持されない場合、 カーソルはクローズされ、すべてのペンディング結果が破棄されます。
カーソル位置をコミット後に維持する場合、 残りの結果セットの処理を続行する前に、アプリケーションはカーソルを位置変更 (次の行に) するために フェッチする必要があります。
トランザクション操作によるカーソルへの影響を判別する には、SQL_CURSOR_ROLLBACK_BEHAVIOR および SQL_CURSOR_COMMIT_BEHAVIOR 属性 を用いて SQLGetInfo() を呼び出します。
- カーソルは、ロールバック後にクローズされ、すべてのペンディング結果は廃棄されます。
- ステートメント・ハンドルは、SQLEndTran() 呼び出しの後も依然として有効であり、後続の SQL ステートメントで再利用が可能です。 あるいは SQLFreeStmt() を呼び出すか、または SQL_HANDLE_STMT に 設定した HandleType を 用いて SQLFreeHandle() を呼び出すことによって、割り振り解除することもできます。
- カーソル名、バインド済みパラメーター、列のバインドは、トランザクション間で存続します。
Db2 ODBC が自動コミット・モードか手動コミット・モードかには関係なく、SQLEndTran() は、 常にデータベースの実行要求を送信します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージが生成されました。(SQLEndTran() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 08003 | 接続はクローズされています。 | 接続ハンドルは接続状態にありません。 |
| 08007 | トランザクションの処理中に接続障害が発生しました。 | この関数実行時に、引数 Handle に関連した接続に 障害が起こりました。この障害発生前に、要求したコミットまたはロールバックが行われたかどうか は示されていません。 |
| 40001 | トランザクション・ロールバック。 | このトランザクションは別トランザクションとの リソース・デッドロックのため、ロールバックされました。 |
| HY000 | 一般エラー。 | 具体的な SQLSTATE が存在しないエラーが起こりました。引数 MessageText が指定するバッファーに SQLGetDiagRec() が戻す エラー・メッセージに、このエラーとその原因が記述されています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | ステートメント・ハンドルで SQLExecute() または SQLExecDirect() が 呼び出され、SQL_NEED_DATA が戻されました。この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に 呼び出されました。 実行時データ条件を取り消すには、SQLCancel() を呼び出してください。 |
| HY012 | トランザクション・コードが無効です。 | 引数 CompletionType に指定された値 は、SQL_COMMIT でも SQL_ROLLBACK でもありませんでした。 |
| HY092 | オプションのタイプが範囲外です。 | 引数 HandleType に指定された値は 、SQL_HANDLE_ENV でも SQL_HANDLE_DBC でもありませんでした。 |
制約事項
ODBC アプリケーションをストアード・プロシージャーとして実行する場合は 、SQLEndTran() は使用できません。
例
サンプル・アプリケーション DSN8P3VP、あるいは DSN1110.SDSNSAMP データ・セットのオンラインを参照してください。