SQLEndTran 関数

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

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

構文

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

引数

HandleType
[入力]ハンドル型識別子。 SQL_HANDLE_ENV ( Handle が環境ハンドルの場合) またはSQL_HANDLE_DBC ( Handle が接続ハンドルの場合) のいずれかを格納します。

Handle
[入力]トランザクションのスコープを示す、 HandleType で示される型のハンドル。 詳細については、「コメント」を参照してください。

CompletionType
[入力]次の 2 つの値のいずれか。

SQL_COMMIT SQL_ROLLBACK

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_STILL_EXECUTING。

診断

SQLEndTranがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合は、適切なHandleTypeとHandleでSQLGetDiagRecを呼び出すことによって、関連付けられている SQLSTATE 値を取得できます。 次の表に、 SQLEndTran によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

ODBC 3. の場合x ドライバーは、 HandleType がSQL_HANDLE_ENVされ、 Handle が有効な環境ハンドルである場合、ドライバー マネージャーは、環境に関連付けられている各ドライバーで SQLEndTran を呼び出します。 ドライバーへの呼び出しの Handle 引数は、ドライバーの環境ハンドルになります。 ODBC 2. の場合x ドライバーは、 HandleType がSQL_HANDLE_ENVで Handle が有効な環境ハンドルであり、その環境に接続された状態で複数の接続がある場合、ドライバー マネージャーは、その環境内の接続状態の接続ごとにドライバーで SQLTransact を 1 回呼び出します。 各呼び出しの Handle 引数は、接続のハンドルになります。 いずれの場合も、ドライバーは、 CompletionType の値に応じて、その環境で接続状態にあるすべての接続でトランザクションのコミットまたはロールバックを試みます。 アクティブでない接続は、トランザクションに影響しません。

ドライバー マネージャーは、接続ごとにSQL_SUCCESSを受け取った場合にのみ、SQL_SUCCESSを返します。 ドライバー マネージャーは、1 つ以上の接続でSQL_ERRORを受け取ると、アプリケーションにSQL_ERRORを返し、診断情報は環境の診断データ構造に配置されます。 コミットまたはロールバック操作中に失敗した接続を特定するために、アプリケーションは接続ごとに SQLGetDiagRec を呼び出すことができます。

CompletionTypeがSQL_COMMITの場合、SQLEndTranは、影響を受ける接続に関連付けられているステートメントに対するすべてのアクティブな操作に対してコミット要求を発行します。 CompletionTypeがSQL_ROLLBACKの場合、SQLEndTran は、影響を受ける接続に関連付けられているステートメントに対するすべてのアクティブな操作に対してロールバック要求を発行します。 アクティブなトランザクションがない場合、 SQLEndTran はデータ ソースに影響を与えずにSQL_SUCCESSを返します。 詳細については、「トランザクションのコミットとロールバックを参照してください。

ドライバーが手動コミット モードの場合 ( SQLSetConnectAttr を呼び出すことによって SQL_ATTR_AUTOCOMMIT属性をSQL_AUTOCOMMIT_OFFに設定すると)、トランザクション内に含めることができる SQL ステートメントが現在のデータ ソースに対して実行されると、新しいトランザクションが暗黙的に開始されます。 詳細については、「 コミット モード」を参照してください。

トランザクション操作がカーソルに与える影響を判断するために、アプリケーションはSQL_CURSOR_ROLLBACK_BEHAVIORオプションとSQL_CURSOR_COMMIT_BEHAVIORオプションを使用してSQLGetInfo を呼び出します。 詳細については、次の段落を参照してください カーソルと準備されたステートメントのトランザクションの効果も参照してください。

SQL_CURSOR_ROLLBACK_BEHAVIORまたはSQL_CURSOR_COMMIT_BEHAVIORの値がSQL_CB_DELETEと等しい場合、 SQLEndTran は接続に関連付けられているすべてのステートメントで開いているすべてのカーソルを閉じて削除し、保留中のすべての結果を破棄します。 SQLEndTran は、割り当てられた (準備されていない) 状態のステートメントを残します。アプリケーションは、後続の SQL 要求に対してステートメントを再利用したり、 SQLFreeStmt または SQLFreeHandle HandleType SQL_HANDLE_STMT を使用してステートメントの割り当てを解除したりできます。

SQL_CURSOR_ROLLBACK_BEHAVIORまたはSQL_CURSOR_COMMIT_BEHAVIORの値がSQL_CB_CLOSEと等しい場合、 SQLEndTran は、接続に関連付けられているすべてのステートメントで開いているすべてのカーソルを閉じます。 SQLEndTran は準備された状態のステートメントを残します。アプリケーションは、最初に SQLPrepare を呼び出さずに、接続に関連付けられているステートメントに対して SQLExecute を呼び出すことができます。

SQL_CURSOR_ROLLBACK_BEHAVIORまたはSQL_CURSOR_COMMIT_BEHAVIORの値がSQL_CB_PRESERVEと等しい場合、 SQLEndTran は接続に関連付けられている開いているカーソルには影響しません。 カーソルは、 SQLEndTran の呼び出しの前に指した行に残ります。

トランザクションをサポートするドライバーとデータ ソースの場合はトランザクションがアクティブでない場合にSQL_COMMITまたはSQL_ROLLBACKSQLEndTran を呼び出すとSQL_SUCCESSが返され (コミットまたはロールバックする作業がないことを示します)、データ ソースには影響しません。

ドライバーが自動コミット モードの場合、ドライバー マネージャーはドライバーで SQLEndTran を呼び出しません。 SQLEndTran は、SQL_COMMITまたはSQL_ROLLBACKの CompletionType を使用して呼び出されたかどうかに関係なく、常にSQL_SUCCESSを返します。

トランザクション (SQLGetInfo option SQL_TXN_CAPABLE がSQL_TC_NONE) をサポートしていないドライバーまたはデータ ソースは、実質的に常に自動コミット モードであるため、SQL_COMMITまたはSQL_ROLLBACKのCompletionTypeで呼び出されたかどうかにかかわらず常にSQLEndTran のSQL_SUCCESSが返されます。 このようなドライバーとデータ ソースは、要求されたときにトランザクションを実際にロールバックしません。

中断状態

Windows 7 より前にリリースされたドライバー マネージャーでは、 SQLEndTran がドライバーからSQL_ERROR返された場合、トランザクションはアクティブでした。 ただし、トランザクションがサーバーで正常にコミットされたが、クライアント上のドライバーに通知されなかった可能性があります (たとえば、ネットワーク エラーが発生したため)。 これにより、接続が無効な状態になります。 Windows 7 以降では、 SQLEndTran がSQL_ERRORを返すと、接続が中断状態になる可能性があります。 中断状態では、読み取り専用関数を呼び出すこともできます。 最終的に、アプリケーションは中断された接続 SQLDisconnect を呼び出してリソースを解放する必要があります。

次の条件がすべて満たされている場合、接続は中断状態になります。

• ドライバーは、 SQLEndTran からSQL_ERRORを返します。

• ドライバーは ODBC バージョン 3.8 以降です。

• アプリケーションのバージョンは 3.8 以降です。または、再コンパイルされた ODBC 2.x または 3.x アプリケーションが、 SQLEndTran 関数 SQLCancelHandle を介して正常に取り消。

• ドライバーは、トランザクションが完了しなかったことを確認する次のメッセージのいずれかを返しませんでした。

  • 25S03: トランザクションがロールバックされる

  • 40001: シリアル化エラー

  • 40002: 整合性制約

  • HYC00: オプション機能が実装されていません

SQLEndTranが環境ハンドルで呼び出され、その接続のいずれかが上記の条件を満たしている場合、同じドライバーに接続するすべての接続が中断状態になります。

アプリケーションが中断された接続で SQLDisconnect を呼び出した後、接続を使用して別のデータ ソースまたは同じデータ ソースに再接続できます。

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
非同期実行 (ポーリング メソッド)