SQLEndTran() - 接続のトランザクションを終了する

SQLEndTran() は、接続に関連付けられたすべてのステートメントの、 アクティブなすべてのトランザクションについて、コミットまたはロールバック操作を要求します。また、SQLEndTran() は、環境に関連付けられたすべての接続の、 コミットまたはロールバック操作の実行を要求することもできます。

SQLEndTran() の ODBC 仕様

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

構文

SQLRETURN  SQLEndTran (SQLSMALLINT       HandleType,
                       SQLHANDLE         Handle,
                       SQLSMALLINT       CompletionType);

関数の引数

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

表 2. SQLEndTran() の引数
データ・タイプ 引数 使用法 説明
SQLSMALLINT HandleType 入力 ハンドル・タイプを示します。 Handle が環境ハンドルの場合は SQL_HANDLE_ENV 、Handle が接続ハンドルの場合は SQL_HANDLE_DBC を含みます。
SQLHANDLE Handle 入力 HandleType によって示されるタイプのハンドルを 指定します。トランザクションの有効範囲を示します。 詳しくは、使用法を参照してください。
SQLSMALLINT CompletionType 入力 コミットまたはロールバックを実行するかどうかを指定します。 以下のいずれかの値を使用します。
  • SQL_COMMIT
  • SQL_ROLLBACK

使用法

トランザクションに含まれている可能性のある 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() は、 常にデータベースの実行要求を送信します。

戻りコード

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

診断

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

表 3. SQLEndTran() の 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 データ・セットのオンラインを参照してください。