仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLEndTran() は、接続に関連するステートメントすべてにおける活動中の操作すべてについて、コミットとロールバック操作を要求します。 SQLEndTran() は、環境に関連している接続すべてに対してコミットおよびロールバック操作を実行するよう要求することもできます。
構文
SQLRETURN SQLEndTran (SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT CompletionType);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLSMALLINT | HandleType | 入力 | Handle タイプ識別子。 Handle が環境ハンドルの場合は SQL_HANDLE_ENV、または Handle が接続ハンドルの場合は SQL_HANDLE_DBC のどちらかが入ります。 |
SQLHANDLE | Handle | 入力 | タイプが HandleType によって示されるハンドルは、トランザクションの効力範囲を示します。詳細については、『使用法』のセクションを参照してください。 |
SQLSMALLINT | CompletionType | 入力 | 以下の 2 つの値のどちらかです。
|
使用法
HandleType が SQL_HANDLE_ENV であり、 Handle が有効な環境ハンドルである場合、 DB2 CLI はこの環境において接続状態にある接続に対して、一度に 1 つずつトランザクションをコミットするか、またはロールバックします。どちらを行うかは、CompletionType の値によって異なります。 SQL_SUCCESS が返されるのは、各接続に SQL_SUCCESS を受け取るときだけです。 1 つまたは複数の接続に対して SQL_ERROR を受け取る場合、アプリケーションに SQL_ERROR を返し、診断情報がこの環境の診断データ構造に入れられます。コミットまたはロールバック操作中に障害が生じた接続を判別するには、アプリケーションは各接続に対して SQLGetDiagRec() を呼び出すことができます。
分散作業単位環境を使用しているときは SQLEndTran() は使用できません。代わりにトランザクション・マネージャー API を使用する必要があります。
CompletionType が SQL_COMMIT である場合、SQLEndTran() は、影響がある接続に関連しているステートメントすべてにおいて活動中の操作すべてに対してコミット要求を出します。 CompletionType が SQL_ROLLBACK である場合、SQLEndTran() は、影響がある接続に関連しているステートメントすべてにおいて活動中の操作すべてに対してロールバック要求を出します。活動状態にあるトランザクションがない場合は、SQLEndTran() は、データ・ソースに影響しないようにして SQL_SUCCESS を返します。
DB2 CLI が手動コミット・モードにある場合 (SQLSetConnectAttr() を呼び出し、 SQL_ATTR_AUTOCOMMIT 属性を SQL_AUTOCOMMIT_OFF に設定するとこのモードになる)、トランザクションに入れることのできる SQL ステートメントを現行データ・ソースに対して実行するときに、新しいトランザクションが暗黙的に開始されます。
トランザクションがカーソルにどのように影響するかを判別するには、アプリケーションは SQLGetInfo() に SQL_CURSOR_ROLLBACK_BEHAVIOR と SQL_CURSOR_COMMIT_BEHAVIOR オプションを付けて呼び出します。
SQL_CURSOR_ROLLBACK_BEHAVIOR または SQL_CURSOR_COMMIT_BEHAVIOR 値が SQL_CB_DELETE と等しい場合、 SQLEndTran() は、接続に関連しているすべてのステートメントにおいて、オープンしているカーソルすべてをクローズし、削除して、保留中の結果をすべて破棄します。 SQLEndTran() は、割り当てられている (準備されていない) 状態にあるステートメントは残します。これらをアプリケーションは次の SQL 要求で使用するか、あるいは SQLFreeStmt() または SQLFreeHandle() に SQL_HANDLE_STMT の HandleType を指定して割り振り解除することができます。
SQL_CURSOR_ROLLBACK_BEHAVIOR または SQL_CURSOR_COMMIT_BEHAVIOR 値が SQL_CB_CLOSE と等しい場合、 SQLEndTran() は、接続に関連しているすべてのステートメントにおいて、オープンしているカーソルすべてをクローズします。 SQLEndTran() は、準備済み状態にあるステートメントは残します。アプリケーションは、接続に関連のあるステートメントの SQLExecute() を呼び出すときに、最初に SQLPrepare() を呼び出す必要がなくなります。
SQL_CURSOR_ROLLBACK_BEHAVIOR または SQL_CURSOR_COMMIT_BEHAVIOR 値が SQL_CB_PRESERVE と等しい場合、 SQLEndTran() は、接続に関連している、オープンしているカーソルに影響しません。カーソルは、SQLEndTran() を呼び出す前に指していた行に残ります。
自動コミット・モードがオンになっているときに、トランザクションが 1 つも活動中でない状態で SQLEndTran() に SQL_COMMIT または SQL_ROLLBACK を指定して呼び出すと、 SQL_SUCCESS が返され (コミット可能な、またはロールバック可能な作業がないことを示す)、データ・ソースには何も影響を与えません。
自動コミット・モードがオフになっているときに、 SQLEndTran() に SQL_COMMIT か SQL_ROLLBACK のどちらかの CompletionType を指定して呼び出すと、常に SQL_SUCCESS が返されます。
DB2 CLI アプリケーションが自動コミット・モードで実行されている場合、 DB2 CLI ドライバーは SQLEndTran() ステートメントをサーバーに渡すことはしません。
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
08003 | 接続がクローズされています。 | ConnectionHandle は、接続状態にありませんでした。 |
08007 | トランザクション中に、接続に障害が起きました。 | ConnectionHandle に関連した接続は、要求された COMMIT または ROLLBACK が失敗する前に行われたかどうかを判別できません。 |
40001 | トランザクション・ロールバック。 | トランザクションは、別のトランザクションとの資源デッドロックのためにロールバックされました。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY010 | 関数の順序エラーです。 | 非同期的に実行する関数が ConnectionHandle に関連している StatementHandle のために呼び出され、
SQLEndTran() を呼び出したときにもまだ実行中でした。
ConnectionHandle と関連する StatementHandle の SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。 |
HY012 | トランザクション・コードが無効です。 | 引き数 CompletionType に指定された値は、 SQL_COMMIT または SQL_ROLLBACK のどちらでもありませんでした。 |
HY092 | オプション・タイプが範囲外です。 | 引き数 HandleType に指定された値は、 SQL_HANDLE_ENV または SQL_HANDLE_DBC のどちらでもありませんでした。 |
制約
なし。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ printf( "\nRolling back the transaction nb. %d ...\n", db_nb + 1) ; sqlrc = SQLEndTran( SQL_HANDLE_DBC, a_hdbc[db_nb], SQL_ROLLBACK ); rc = HandleInfoPrint( SQL_HANDLE_DBC, a_hdbc[db_nb], sqlrc, __LINE__, __FILE__); if( rc == 0) { printf( "The transaction nb. %d rolled back.\n", db_nb + 1 ) ; }
参照