195 DBMS_XA
DBMS_XA
パッケージには、PL/SQLでXAインタフェースをコールするアプリケーション用のXA/Openインタフェースが含まれています。このパッケージによって、アプリケーション開発者は、PL/SQLを使用してSQL*Plusセッションまたはプロセス間でトランザクションの切替えまたは共有を実行できます。
この章の内容は次のとおりです。
参照:
Oracle XAによるアプリケーションの開発の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。
195.1 DBMS_XAの概要
これらのサブプログラムを使用すると、PL/SQLアプリケーションでグローバル・トランザクション・ブランチID(XID
)を定義し、現行のセッションをトランザクション・ブランチに関連付けたり、関連付けを解除できます。
その後、2フェーズ・コミット・プロトコルに従って、これらのトランザクション・ブランチを準備およびコミットできます。含まれるリソース・マネージャが1つの場合にのみ、1フェーズ・コミット・プロトコルもサポートされます。
また、現行セッションで開始する可能性のある新しいグローバル・トランザクション・ブランチのタイムアウト値を設定するPL/SQLアプリケーションのインタフェースも提供されています。
195.2 DBMS_XAのセキュリティ・モデル
このパッケージは、SYS
の下に作成されます。このパッケージが提供する操作は、パッケージ所有者SYS
ではなく、現行のコール・ユーザーのもとで実行されます。無名PL/SQLブロックからコールされたDBMS_XA
サブプログラムは、現行ユーザーの権限を使用して実行されます。ストアド・プロシージャからコールされたDBMS_XA
サブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。
XA_RECOVER
サブプログラムを実行する必要があるユーザーには、SYS
.DBA_PENDING_TRANSACTIONS
に関するSELECT
またはREAD
権限が必要です。
他のユーザーによって作成されたXAトランザクションを操作する必要があるユーザーには、FORCE ANY TRANSACTION
権限が必要です。
195.3 DBMS_XAの定数
DBMS_XA
パッケージは、パラメータ値の指定に使用できるいくつかの定数を定義します。
パッケージでは、XA_STARTファンクションおよびXA_ENDファンクションのフラグ・フィールドに、表195-1に示す定数が使用されます。
表195-1 XA_STARTおよびXA_ENDファンクションのフラグ・フィールドのDBMS_XA定数
名前 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
00000000 |
フラグ値が選択されていないことを示します。 |
|
|
|
コール元をトランザクション・ブランチから分離します。 |
|
|
|
呼出し側が既存のトランザクション・ブランチに参加します。 |
|
|
|
コール元は関連付けを終了せずに、中断しています。 |
|
|
|
コール元は中断したトランザクション・ブランチとの関連付けを再開しています。 |
DBMS_XA
パッケージでは、有効な戻り値に対して表195-2に示す定数が使用されます。
表195-2 有効な戻り値に対するDBMS_XA定数
名前 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
100 |
ロールバック・コードの下限(下限値を含む)。 |
|
|
|
詳細不明の理由によってロールバックが行われました。 |
|
|
|
通信障害によってロールバックが行われました。 |
|
|
|
デッドロックが検出されました。 |
|
|
|
リソースの整合性に違反する状態が検出されました。 |
|
|
|
リストにない理由によって、リソース・マネージャがトランザクションをロールバックしました。 |
|
|
|
リソース・マネージャでプロトコル・エラーが発生しました。 |
|
|
|
トランザクション・ブランチに時間がかかりすぎました。 |
|
|
|
トランザクション・ブランチを再試行する場合があります。 |
|
|
|
ロールバック・コードの上限(上限値を含む)。 |
|
|
9 |
トランザクション・ブランチがヒューリスティックに完了した可能性があります。 |
|
|
8 |
トランザクション・ブランチがヒューリスティックに完了した可能性があります。 |
|
|
7 |
トランザクション・ブランチがヒューリスティックにコミットされました。 |
|
|
6 |
トランザクション・ブランチがヒューリスティックにロールバックされました。 |
|
|
5 |
一部のトランザクション・ブランチはヒューリスティックにコミットされ、その他はロールバックされました。 |
|
|
4 |
ルーチンが効果なしに戻され、再発行される場合があります。 |
|
|
3 |
トランザクションは読取り専用であり、コミットされています。 |
|
|
0 |
正常実行。 |
|
|
-2 |
すでに未処理となった非同期操作です。 |
|
|
-3 |
トランザクション・ブランチでリソース・マネージャ・エラーが発生しました。 |
|
|
-4 |
XIDは有効ではありません。 |
|
|
-5 |
無効な引数が指定されました。 |
|
|
-6 |
誤ったコンテキストでルーチンが起動されました。 |
|
|
-7 |
リソース・マネージャは使用不可です。 |
|
|
-8 |
XIDはすでに存在します。 |
|
|
-9 |
リソース・マネージャはグローバル・トランザクション外で処理を実行しています。 |
195.4 DBMS_XAの操作上のノート
分散トランザクション処理におけるX/Open CAE標準のXA仕様に従い、トランザクションが現行セッションに関連付けられている場合、XA_PREPARE
/COMMIT
/ROLLBACK
/FORGET
はコールされない場合があります。現行セッションに関連付けられたトランザクションがなくなるようにXA_END
がコールされた後にのみ、アプリケーションはXA_PREPARE
/COMMIT
/ROLLBACK
/FORGET
をコールできます。
トランザクションが現行セッションに関連付けられている場合、XA_PREPARE
/COMMIT
/ROLLBACK
/FORGET
からXAER_PROTO
エラーが戻されます。
パッケージのサブプログラムをコールする前に、Oracle Databaseサーバーのバックエンド(リソース・マネージャ)に対して接続/セッションを確立しておく必要があります。リソース・マネージャの識別子はサポートされていません。複数のリソース・マネージャが含まれている場合は、パッケージのサブプログラムをコールする前に、各リソース・マネージャに対して接続/セッションをあらかじめ確立しておく必要があります。グローバル・トランザクション処理の過程で複数の接続/セッションが確立された場合、コール元は特定のグローバル・トランザクション・ブランチの識別子(XID)に関連付けられたそれらのすべての接続/セッションが、同じリソース・マネージャに対して確立されていることを確認する必要があります。
195.5 DBMS_XAのデータ構造
DBMS_XA
パッケージは、このOBJECT
タイプおよび関連するTABLE
タイプを使用します。
オブジェクト・タイプ
195.5.1 DBMS_XA DBMS_XA_XIDオブジェクト・タイプ
PL/SQL XAインタフェースを使用すると、PL/SQLアプリケーションでグローバル・トランザクション・ブランチID(XID)を定義し、現行のセッションをトランザクション・ブランチに関連付けたり、関連付けを解除できます。XIDは、PL/SQLオブジェクト・タイプとして定義されます。
ノート:
詳細は、公開されているXA標準の『Distributed Transaction Processing: The XA Specification』を参照してください。
構文
TYPE DBMS_XA_XID IS OBJECT( formatid NUMBER, gtrid RAW(64), bqual RAW(64), constructor function DBMS_XA_XID( gtrid IN NUMBER) RETURN SELF AS RESULT, constructor function DBMS_XA_XID ( gtrid IN RAW, bqual IN RAW)RETURN SELF AS RESULT
, constructor function DBMS_XA_XID( formatid IN NUMBER, gtrid IN RAW, bqual IN RAW DEFAULT HEXTORAW('00000000000000000000000000000001'))RETURN SELF AS RESULT
)
属性
表195-3 DBMS_XA_XIDオブジェクト・タイプ
属性 | 説明 |
---|---|
|
形式識別子。異なるトランザクション・マネージャ(TM)を識別する数値。 |
|
グローバル・トランザクションを一意に識別するグローバル・トランザクション識別子。最大サイズは64バイト。 |
|
ブランチ修飾子。最大サイズは64バイト。 |
195.6 DBMS_XAサブプログラムの要約
この表は、DBMS_XA
サブプログラムを示し、簡単に説明しています。
表195-4 DBMS_XAパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
Oracle Real Application Clusters(Oracle RAC)の利用時に同期化のリカバリで使用します。 |
|
|
|
|
|
ヒューリスティックにコミットまたはロールバックされたトランザクション・ブランチについての情報を消去するよう、リソース・マネージャに通知します。 |
|
前のXAコールが失敗した場合に、最後のOracleエラー・コードを取得します。 |
|
|
|
準備されたか、またはヒューリスティックに完了したトランザクション・ブランチのリストをリソース・マネージャから取得します。 |
|
実行された処理をトランザクション・ブランチにかわってロールバックするよう、リソース・マネージャに通知します。 |
|
現行セッションのトランザクション・タイムアウトを秒単位で設定します。 |
|
|
195.6.1 DIST_TXN_SYNCプロシージャ
このプロシージャを使用すると、Oracle Real Application Clusters(Oracle RAC)インスタンスが失敗した場合に、インダウト・トランザクションを同期化できます。
構文
DBMS_XA.DIST_TXN_SYNC;
195.6.2 XA_COMMITファンクション
このファンクションは、xid
で指定したグローバル・トランザクションをコミットします。
構文
DBMS_XA.XA_COMMIT ( xid IN DBMS_XA_XID, onePhase IN BOOLEAN) RETURN PLS_INTEGER;
パラメータ
表195-5 XA_COMMITファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
|
|
戻り値
表195-2を参照してください。エラーを示す有効な戻り値は、XAER_RMERR
、XAER_RMFAIL
、XAER_NOTA
、XAER_INVAL
またはXAER_PROTO
です。その他にも有効な戻り値として、XA_OK
、XA_RB
*、XA_HEURHAZ
、XA_HEURCOM
、XA_HEURRB
、XA_HEURMIX
などがあります。
使用上のノート
-
アプリケーションは、
COMMIT
ではなく、XA_COMMIT
をコールして、xid
で指定したグローバル・トランザクションをコミットする必要があります。他のユーザーによって作成されたトランザクション・ブランチをコミットする必要があるユーザーには、FORCE
ANY
TRANSACTION
を付与する必要があります。 -
onePhase
がTRUE
の場合、リソース・マネージャは1フェーズ・コミット・プロトコルを使用して、実行された処理をxid
のかわりにコミットする必要があります。そうでない場合は、グローバル・トランザクションのすべてのブランチが正常に準備され、先行のXA_PREPARE
コールがXA_OK
を戻した場合にのみ、XA_COMMIT
がコールされます。 -
アプリケーションは、
XA_PREPARE
がXA_OK
を戻したグローバル・トランザクションの各トランザクション・ブランチに対して、個別のXA_COMMIT
コールを行う必要があります。 -
リソース・マネージャがトランザクションをコミットせず、
onePhase
パラメータがTRUE
に設定されている場合、リソース・マネージャはXA_RB
*コードの1つを戻します。コードを戻すと、リソース・マネージャはブランチの処理をロールバックし、保持しているすべてのリソースを解放します。
195.6.3 XA_ENDファンクション
このファンクションは、xid
で指定したトランザクション・ブランチから、現行セッションの関連付けを解除します。
コントロールのスレッドがトランザクション・ブランチを終了したか、または処理を中断する必要がある場合、トランザクション・マネージャはXA_END
をコールします。これは、アプリケーションが動作の一部を部分的または完全に完了する場合に発生します(たとえば、コントロールの他のスレッドがブランチで機能させるために、一部のイベントをブロックする前など)。XA_END
が正常に値を戻されると、コントロールのコール元のスレッドとブランチとの関連付けはアクティブではなくなりますが、ブランチは引き続き存在します。
構文
DBMS_XA.XA_END ( xid IN DBMS_XA_XID, flag IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
表195-6 XA_ENDファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
|
表195-1を参照してください。 |
戻り値
表195-2を参照してください。エラーにおける有効な戻り値は、XAER_RMERR
、XAER_RMFAILED
、XAER_NOTA
、XAER_INVAL
、XAER_PROTO
またはXA_RB
*です。
使用上のノート
-
フラグに
TMSUCCESS
またはTMSUSPEND
を指定でき、戻り値がXA_OK
の場合、トランザクション・ブランチは連結解除の状態で現行セッションとの関連付けを解除されます。TMFAIL
はサポートされていません。TMSUCCESS
またはTMSUSPEND
を指定してXA_END
をコールし、xidで識別されたトランザクション・ブランチの関連付けを現行セッションから解除することがあります。 -
XA_END
が成功すると、XA_OK
が戻されます。アプリケーションは、戻り値をチェックしてエラーを処理する必要があります。XA_OK
が戻された場合にのみ、アプリケーションはその他の通常の処理を続行する必要があります。 -
最初に
XA_END
をコールしないでROLLBACK
文を実行すると、現行のトランザクションで行われた変更がロールバックされます。ただし、トランザクション・コンテキストは、XA_END
がコールされるまで現行セッションに関連付けられています。 -
最初に
XA_END
をコールしないでCOMMIT
文を実行すると、「ORA
-02089
: 下位セッションにCOMMIT
は使用できません。」が発生します。 -
XA_END
の後にCOMMIT
またはROLLBACK
文を実行しても、このトランザクションは現在のセッションとの関連付けがなくなっているため、xid
で特定されているトランザクションに影響はありません。
195.6.4 XA_FORGETファンクション
このファンクションは、ヒューリスティックにコミットまたはロールバックされたトランザクション・ブランチについての情報を消去するよう、リソース・マネージャに通知します。
構文
DBMS_XA.XA_FORGET ( xid IN DBMS_XA_XID) RETURN PLS_INTEGER;
パラメータ
表195-7 XA_FORGETファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
戻り値
表195-2を参照してください。有効な戻り値は、XA_OK
、XAER_RMERR
、XAER_RMFAIL
、XAER_NOTA
、XAER_INVAL
またはXAER_PROTO
です。
195.6.5 XA_GETLASTOERファンクション
このファンクションは、前のXAコールが失敗した場合に、最後のOracleエラー・コードを取得します。
構文
DBMS_XA.XA_GETLASTOER RETURN PLS_INTEGER;
戻り値
戻り値には、最後のOracleエラー・コードが示されます。
195.6.6 XA_PREPAREファンクション
このファンクションは、xid
で指定したトランザクション・ブランチを準備して、可能な場合に続けてトランザクションをコミットできるようにします。
構文
DBMS_XA.XA_PREPARE ( xid IN DBMS_XA_XID) RETURN PLS_INTEGER;
パラメータ
表195-8 XA_PREPAREファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
戻り値
表195-2を参照してください。有効なリターン・コードは、XA_OK
、XA_RDONLY
、XA_RB
*、XAER_RMERR
、XAER_RMFAIL
、XAER_NOTA
、XAER_INVAL
またはXAER_PROTO
です。
使用上のノート
-
他のユーザーによって作成されたトランザクション・ブランチを準備する必要があるユーザーには、
FORCE
ANY
TRANSACTION
を付与する必要があります。 -
アプリケーションは、1つのグローバル・トランザクションのすべてのブランチを追跡し、各トランザクション・ブランチを準備する必要があります。グローバル・トランザクションのすべてのブランチが正常に準備され、
XA_PREPARE
がXA_OK
を戻した場合にのみ、アプリケーションは、XA_COMMIT
のコールを続行できます。
195.6.7 XA_RECOVERファンクション
このファンクションは、準備されたか、またはヒューリスティックに完了したトランザクション・ブランチのリストをリソース・マネージャから取得します。
構文
DBMS_XA.XA_RECOVER RETURN DBMS_XA_XID_ARRAY;
戻り値
「DBMS_XA_XID_ARRAY表タイプ」を参照してください。
使用上のノート
-
TMSTARTSCAN
、TMENDSCAN
、TMNOFLAGS
フラグはサポートされていません。 -
XA_RECOVER
をコールする必要があるユーザーに、SELECT
ON
DBA_PENDING_TRANSACTIONS
権限を付与する必要があります。
195.6.8 XA_ROLLBACKファンクション
このファンクションは、実行された処理をトランザクション・ブランチにかわってロールバックするよう、リソース・マネージャに通知します。
構文
DBMS_XA.XA_ROLLBACK ( xid IN DBMS_XA_XID) RETURN PLS_INTEGER;
パラメータ
表195-9 XA_ROLLBACKファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
戻り値
表195-2を参照してください。有効な戻り値は、XA_OK
、XA_RB
*、XA_HEURHAZ
、XA_HEURCOM
、XA_HEURRB
またはXA_HEURMIX
です。
使用上のノート
他のユーザーによって作成されたトランザクション・ブランチをロールバックする必要があるユーザーには、FORCE
ANY
TRANSACTION
権限を付与する必要があります。
195.6.9 XA_SETTIMEOUTファンクション
このファンクションは、現行セッションのトランザクション・タイムアウトを秒単位で設定します。
構文
DBMS_XA.XA_SETTIMEOUT ( seconds IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
表195-10 XA_SETTIMEOUTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
タイムアウト値は、トランザクションがシステムによって自動的に終了される前に、トランザクション・ブランチの関連付けがセッションから解除される可能性がある最大時間(秒)を示します。デフォルト値は60秒です。 |
戻り値
表195-2を参照してください。有効な戻り値は、XA_OK
、XAER_RMERR
、XAER_RMFAIL
またはXAER_INVAL
です。
使用上のノート
戻り値がXA_OK
の場合にのみ、タイムアウト値は正常に設定されます。
195.6.10 XA_STARTファンクション
このファンクションは、xid
で指定したトランザクション・ブランチに現行セッションを関連付けます。
構文
DBMS_XA.XA_START ( xid IN DBMS_XA_XID, flag IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
表195-11 XA_STARTファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。 |
|
表195-1を参照してください。 |
戻り値
表195-2を参照してください
使用上のノート
-
フラグに
TMJOIN
またはTMRESUME
を指定すると、xid
で識別された既存のトランザクション・ブランチが結合されます。TMJOIN
フラグは、トランザクションがTMSUCCESS
フラグによって連結解除された場合に使用する必要があります。TMRESUME
は、トランザクション・ブランチがTMSUSPEND
フラグによって連結解除された場合に使用する必要があります。XA_START
は、既存のトランザクション・ブランチを結合するために、どちらかのフラグが指定されてコールされることがあります。 -
フラグに
TMNOFLAGS
を指定し、TMJOIN
およびTMRESUME
のいずれも指定しないと、新しいトランザクション・ブランチが開始されます。xid
で指定したトランザクション・ブランチがすでに存在すると、XA_START
はXAER_DUPID
エラー・コードを戻します。 -
エラーにおける有効な戻り値は、
XAER_RMERR
、XAER_RMFAIL
、XAER_DUPID
、XAER_OUTSIDE
、XAER_NOTA
、XAER_INVAL
およびXAER_PROTO
です。 -
XA_START
が成功すると、XA_OK
が戻されます。アプリケーションは、戻り値をチェックしてエラーを処理する必要があります。XA_OK
が戻された場合にのみ、PL/SQLアプリケーションはその他の通常の処理を続行する必要があります。トランザクション・スタックはサポートされていません。現行セッションに関連付けられたアクティブなトランザクションがあると、別のトランザクションの開始または結合のためのコールは行われないことがあります。セッションに関連付けられたアクティブなグローバル・トランザクション・ブランチによってXA_START
がコールされた場合には、XAER_PROTO
が戻されます。現行セッションに関連付けられたローカル・トランザクションによってXA_START
がコールされた場合には、XAER_OUTSIDE
が戻されます。