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
[入力]トランザクションのスコープを示す 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を返すときは、適切な HandleTypeHandle を使用して SQLGetDiagRec を呼び出すことによって、関連付けられている SQLSTATE 値を取得できます。 次の表に、 SQLEndTran によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE Error 説明
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) SqlExecuteSQLExecDirectSQLBulkOperations、または SQLSetPosConnectionHandle に関連付けられたステートメント ハンドルに対して呼び出され、SQL_NEED_DATA返されました。 この関数は、実行中のすべてのデータ パラメーターまたは列に対してデータが送信される前に呼び出されました。

(DM) HandleType が SQL_HANDLE_DBC に設定された Handle に対して非同期に実行される関数 (この関数ではなく) が呼び出され、この関数が呼び出されたときにまだ実行されていました。

(DM) Handle に関連付けられているステートメント ハンドルの 1 つに対して SQLExecuteSQLExecDirect、または 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され、 ハンドル が有効な環境ハンドルであり、その環境に接続された状態で複数の接続がある場合、ドライバー マネージャーはその環境の接続状態の接続ごとに 1 回、ドライバーで SQLTransact を 呼び出します。 各呼び出しの 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を返します。

トランザクションをサポートしていないドライバーまたはデータ ソース (SQLGetInfooption 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 関数

参照

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