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され、関数の実行中に Handle に関連付けられた接続が失敗し、要求された COMMIT または ROLLBACK が失敗する前に発生したかどうかを判断できません。 |
| 25S01 | トランザクションの状態が不明です | Handle の 1 つ以上の接続が、指定された結果でトランザクションを完了できず、結果が不明です。 |
| 25S02 | トランザクションがまだアクティブです | ドライバーは、グローバル トランザクション内のすべての作業をアトミックに完了でき、トランザクションがまだアクティブであることを保証できませんでした。 |
| 25S03 | トランザクションがロールバックされる | ドライバーは、グローバル トランザクション内のすべての作業をアトミックに完了でき、 Handle でアクティブなトランザクション内のすべての作業がロールバックされたことを保証できませんでした。 |
| 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) Handle に関連付けられたステートメント ハンドルの 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 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) ConnectionHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
説明
ODBC 3 の場合。x ドライバー( HandleType がSQL_HANDLE_ENVで 、Handle が有効な環境ハンドルである場合、ドライバー マネージャーは環境に関連付けられている各ドライバーで SQLEndTran を呼び出します。 ドライバーの呼び出しの Handle 引数は、ドライバーの環境ハンドルになります。 ODBC 2 の場合。x ドライバー。 HandleType がSQL_HANDLE_ENVされ、 Handle が有効な環境ハンドルであり、その環境に接続状態に複数の接続がある場合、ドライバー マネージャーは、その環境の接続状態の接続ごとにドライバーで SQLTransact を 1 回呼び出します。 各呼び出しの Handle 引数は、接続のハンドルになります。 どちらの場合も、ドライバーは、 CompletionType の値に応じて、その環境の接続状態にあるすべての接続でトランザクションのコミットまたはロールバックを試みます。 アクティブでない接続はトランザクションに影響しません。
Note
SQLEndTran を 使用して、共有環境でトランザクションをコミットまたはロールバックすることはできません。 SQLSTATE HY092 (無効な属性/オプション識別子) は、共有環境のハンドルまたは共有環境上の接続のハンドルに設定された Handle で 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 ステートメントが現在のデータ ソースに対して実行されると、新しいトランザクションが暗黙的に開始されます。 詳細については、「 コミット モード」を参照してください。
トランザクション操作がカーソルに与える影響を判断するために、アプリケーションは SQLGetInfo をSQL_CURSOR_ROLLBACK_BEHAVIORオプションとSQL_CURSOR_COMMIT_BEHAVIORオプションで呼び出します。 詳細については、次の段落を参照し、「カーソルに 対するトランザクションの影響」および「準備されたステートメント」も参照してください。
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 は 、 CompletionType が SQL_COMMIT または 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 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示