SQLEndTran 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLEndTran は 、接続に関連付けられているすべてのステートメントに対するすべてのアクティブな操作に対してコミット操作またはロールバック操作を要求します。 SQLEndTran は、環境に関連付けられているすべての接続に対してコミット操作またはロールバック操作を実行するように要求することもできます。
Note
ドライバー マネージャーが ODBC 3 の場合にこの関数をマップする方法について詳しくは、x アプリケーションが ODBC 2 で動作しています。x ドライバーについては、「アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。
構文
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。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08003 | 接続が開かない | (DM) HandleType がSQL_HANDLE_DBCされ、ハンドルが接続された状態ではなかった。 |
| 08007 | トランザクション中の接続エラー | HandleType がSQL_HANDLE_DBCされ、関数の実行中にハンドルに関連付けられた接続が失敗し、要求された COMMIT または ROLLBACK が失敗する前に発生したかどうかを判断できません。 |
| 25S01 | トランザクションの状態が不明 | ハンドル内の 1 つ以上の接続が、指定された結果でトランザクションを完了できませんでした。結果は不明です。 |
| 25S02 | トランザクションがまだアクティブです | ドライバーは、グローバル トランザクション内のすべての作業をアトミックに完了でき、トランザクションがまだアクティブであることを保証できませんでした。 |
| 25S03 | トランザクションがロールバックされる | ドライバーは、グローバル トランザクション内のすべての作業をアトミックに完了でき、ハンドルでアクティブなトランザクション内のすべての作業がロールバックされたことを保証できませんでした。 |
| 40001 | シリアル化エラー | 別のトランザクションでリソースのデッドロックが発生したため、トランザクションがロールバックされました。 |
| 40002 | 整合性制約違反 | CompletionType がSQL_COMMITされ、変更のコミットメントによって整合性制約違反が発生しました。 その結果、トランザクションはロールバックされました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *szMessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因について説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。 |
| HY008 | 操作が取り消されました | ConnectionHandle に対して非同期処理が有効になりました。 関数が呼び出され、SQLCancelHandle 関数の実行が完了する前に ConnectionHandle で呼び出されました。 その後、ConnectionHandle で関数が再度呼び出されました。 関数が呼び出され、SQLCancelHandle の実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから ConnectionHandle で呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) 非同期実行関数が ConnectionHandle に関連付けられたステートメント ハンドルに対して呼び出され、SQLEndTran が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではない) が ConnectionHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) ConnectionHandle に関連付けられたステートメント ハンドルに対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではない) は、HandleType が SQL_HANDLE_DBC に設定された Handle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) ハンドルに関連付けられているステートメント ハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 |
| HY012 | トランザクション操作コードが無効です | (DM) 引数 CompletionType に指定された値は、SQL_COMMITでもSQL_ROLLBACKでもありません。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY092 | 無効な属性/オプション識別子 | (DM) 引数 HandleType に指定された値は、SQL_HANDLE_ENVでもSQL_HANDLE_DBCでもありません。 |
| HY115 | 非同期関数の実行が有効になっている接続を含む環境では、SQLEndTran は許可されません | (DM) 環境内の接続に対して接続関数の非同期実行が有効になっている場合、HandleType を SQL_HANDLE_ENV に設定できません。 |
| HY117 | 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、このトピックの「コメント」セクションを参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | ドライバーまたはデータ ソースは ROLLBACK 操作をサポートしていません。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) ConnectionHandle に関連付けられているドライバーは、関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 | ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、 後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
Comments
ODBC 3 の場合。x ドライバー。HandleType がSQL_HANDLE_ENVで、ハンドルが有効な環境ハンドルである場合、ドライバー マネージャーは、環境に関連付けられている各ドライバーで SQLEndTran を呼び出します。 ドライバーへの呼び出しの Handle 引数は、ドライバーの環境ハンドルになります。 ODBC 2 の場合。x ドライバー。HandleType がSQL_HANDLE_ENVされ、ハンドルが有効な環境ハンドルであり、その環境に接続状態の接続が複数ある場合、ドライバー マネージャーは、その環境内の接続状態の接続ごとに、ドライバーの SQLTransact を 1 回呼び出します。 各呼び出しの Handle 引数は、接続のハンドルになります。 いずれの場合も、ドライバーは、CompletionType の値に応じて、その環境で接続状態にあるすべての接続でトランザクションのコミットまたはロールバックを試みます。 アクティブでない接続は、トランザクションに影響しません。
Note
SQLEndTran を使用して、共有環境でトランザクションをコミットまたはロールバックすることはできません。 SQLState HY092 (無効な属性/オプション識別子) は、共有環境のハンドルまたは共有環境での接続のハンドルに設定されたハンドルで SQLEndTran が呼び出された場合に返されます。
ドライバー マネージャーは、接続ごとにSQL_SUCCESSを受け取った場合にのみ、SQL_SUCCESSを返します。 ドライバー マネージャーは、1 つ以上の接続でSQL_ERRORを受け取ると、アプリケーションにSQL_ERRORを返し、診断情報は環境の診断データ構造に配置されます。 コミットまたはロールバック操作中に失敗した接続を特定するために、アプリケーションは接続ごとに SQLGetDiagRec を呼び出すことができます。
Note
ドライバー マネージャーは、すべての接続でグローバル トランザクションをシミュレートしないため、2 フェーズ コミット プロトコルを使用しません。
CompletionType がSQL_COMMIT場合、SQLEndTran は、影響を受ける接続に関連付けられているステートメントに対するすべてのアクティブな操作に対してコミット要求を発行します。 CompletionType がSQL_ROLLBACK場合、SQLEndTran は、影響を受ける接続に関連付けられているステートメントに対するすべてのアクティブな操作に対してロールバック要求を発行します。 アクティブなトランザクションがない場合、 SQLEndTran はデータ ソースに影響を与えるSQL_SUCCESSを返します。 詳細については、「トランザクションのコミットとロールバック」を参照してください。
ドライバーが手動コミット モードの場合 (SQL_ATTR_AUTOCOMMIT属性を SQL_AUTOCOMMIT_OFF に設定して SQLSetConnectAttr を呼び出すことによって)、トランザクション内に含めることができる SQL ステートメントが現在のデータ ソースに対して実行されると、新しいトランザクションが暗黙的に開始されます。 詳細については、「コミット モード」を参照してください。
トランザクション操作がカーソルに与える影響を判断するために、アプリケーションは、SQL_CURSOR_ROLLBACK_BEHAVIORオプションとSQL_CURSOR_COMMIT_BEHAVIORオプションを使用して SQLGetInfo を呼び出します。 詳細については、次の段落を参照し、カーソルおよび準備されたステートメントに対するトランザクションの影響も参照してください。
SQL_CURSOR_ROLLBACK_BEHAVIORまたはSQL_CURSOR_COMMIT_BEHAVIORの値がSQL_CB_DELETEと等しい場合、 SQLEndTran は接続に関連付けられているすべてのステートメントで開いているすべてのカーソルを閉じて削除し、保留中のすべての結果を破棄します。 SQLEndTran は、割り当てられた (準備されていない) 状態のステートメントを残します。アプリケーションは、後続の SQL 要求に対してステートメントを再利用したり、HandleType をSQL_HANDLE_STMTで SQLFreeStmt または SQLFreeHandle を呼び出して割り当てを解除したりできます。
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_ROLLBACKで SQLEndTran を呼び出すと、SQL_SUCCESSが返され (コミットまたはロールバックする作業がないことを示します)、データ ソースには影響しません。
ドライバーが自動コミット モードの場合、ドライバー マネージャーはドライバーで SQLEndTran を呼び出しません。 SQLEndTran は、SQL_COMMIT の CompletionType とSQL_ROLLBACKのどちらを使用して呼び出されるかに関係なく、常にSQL_SUCCESSを返します。
トランザクションをサポートしていないドライバーまたはデータ ソース (SQLGetInfo オプション 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 アプリケーションが SQLCancelHandle を介して SQLEndTran 関数を正常に取り消します。
ドライバーは、トランザクションが完了しなかったことを確認する次のメッセージのいずれかを返しませんでした。
25S03: トランザクションがロールバックされる
40001: シリアル化エラー
40002: 整合性制約
HYC00: オプション機能が実装されていません
環境ハンドルで SQLEndTran が呼び出され、その接続のいずれかが上記の条件を満たしている場合、同じドライバーに接続するすべての接続が中断状態になります。
アプリケーションが中断された接続で SQLDisconnect を呼び出した後、接続を使用して別のデータ ソースまたは同じデータ ソースに再接続できます。
関連する関数
| 情報 | 参照トピック |
|---|---|
| 接続ハンドルで非同期的に実行されている関数を取り消す。 | SQLCancelHandle 関数 |
| ドライバーまたはデータ ソースに関する情報を返す | SQLGetInfo 関数 |
| ハンドルの解放 | SQLFreeHandle 関数 |
| ステートメント ハンドルの解放 | SQLFreeStmt 関数 |