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され、 Handle が接続状態にありません。
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) SQLExecute、 SQLExecDirect、 SQLBulkOperations、または SQLSetPos が呼び出され、 ConnectionHandle に関連付けられたステートメント ハンドルが返され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではなく) が Handle HandleType SQL_HANDLE_DBC に設定され、この関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、または SQLMoreResults Handle に関連付けられているステートメント ハンドルの 1 つに対して呼び出され、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され、 Handle が有効な環境ハンドルである場合、ドライバー マネージャーは、環境に関連付けられている各ドライバーで SQLEndTran を呼び出します。 ドライバーへの呼び出しの Handle 引数は、ドライバーの環境ハンドルになります。 ODBC 2. の場合x ドライバーは、 HandleType がSQL_HANDLE_ENVで Handle が有効な環境ハンドルであり、その環境に接続された状態で複数の接続がある場合、ドライバー マネージャーは、その環境内の接続状態の接続ごとにドライバーで SQLTransact を 1 回呼び出します。 各呼び出しの Handle 引数は、接続のハンドルになります。 いずれの場合も、ドライバーは、 CompletionType の値に応じて、その環境で接続状態にあるすべての接続でトランザクションのコミットまたはロールバックを試みます。 アクティブでない接続は、トランザクションに影響しません。

Note

SQLEndTran を使用して、共有環境でトランザクションをコミットまたはロールバックすることはできません。 SQLSTATE HY092 (無効な属性/オプション識別子) は、 SQLEndTran が Handle 共有環境のハンドルまたは共有環境での接続のハンドルに設定されている場合に返されます。

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

Note

ドライバー マネージャーは、すべての接続でグローバル トランザクションをシミュレートしないため、2 フェーズ コミット プロトコルを使用しません。

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 を呼び出した後、接続を使用して別のデータ ソースまたは同じデータ ソースに再接続できます。

関連する関数

情報	参照トピック
接続ハンドルで非同期的に実行されている関数を取り消す。	SQLCancelHandle 関数
ドライバーまたはデータ ソースに関する情報を返す	SQLGetInfo 関数
ハンドルの解放	SQLFreeHandle 関数
ステートメント ハンドルの解放	SQLFreeStmt 関数

参照

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