CLI の手引きおよび解説書

SQLEndTran - 接続のトランザクションの終了

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLEndTran() は、接続に関連するステートメントすべてにおける活動中の操作すべてについて、コミットとロールバック操作を要求します。 SQLEndTran() は、環境に関連している接続すべてに対してコミットおよびロールバック操作を実行するよう要求することもできます。

構文

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

関数引き数

表 54. SQLEndTran 引き数
データ・タイプ 引き数 使用法 説明
SQLSMALLINT HandleType 入力 Handle タイプ識別子。 Handle が環境ハンドルの場合は SQL_HANDLE_ENV、または Handle が接続ハンドルの場合は SQL_HANDLE_DBC のどちらかが入ります。
SQLHANDLE Handle 入力 タイプが HandleType によって示されるハンドルは、トランザクションの効力範囲を示します。詳細については、『使用法』のセクションを参照してください。
SQLSMALLINT CompletionType 入力 以下の 2 つの値のどちらかです。
  • SQL_COMMIT
  • SQL_ROLLBACK

使用法

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() ステートメントをサーバーに渡すことはしません。

戻りコード

診断

表 55. SQLEndTran SQLSTATE
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 と関連する StatementHandleSQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。

HY012 トランザクション・コードが無効です。 引き数 CompletionType に指定された値は、 SQL_COMMIT または SQL_ROLLBACK のどちらでもありませんでした。
HY092 オプション・タイプが範囲外です。 引き数 HandleType に指定された値は、 SQL_HANDLE_ENV または SQL_HANDLE_DBC のどちらでもありませんでした。

制約

なし。

CLI サンプル utilcli.c

(ここで完全サンプル 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 ) ;
        }
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]