147 DBMS_XA

DBMS_XAパッケージには、PL/SQLでXAインタフェースをコールするアプリケーション用のXA/Openインタフェースが含まれています。 このパッケージによって、アプリケーション開発者は、PL/SQLを使用してSQL*Plusセッションまたはプロセス間でトランザクションの切替えまたは共有を実行できます。

関連項目: Oracle XAによるアプリケーションの開発の詳細は、『Oracle Databaseアドバンスト・アプリケーション開発者ガイド』を参照してください。

この章では、次の項目について説明します。

• DBMS_XAの使用方法

  • 概要

  • セキュリティ・モデル

  • 定数

  • 使用上の注意

• データ構造

  • オブジェクト・タイプ

  • 表タイプ

• DBMS_XAサブプログラムの要約

---

DBMS_XAの使用方法

• 概要

• セキュリティ・モデル

• 定数

• 使用上の注意

---

概要

これらのサブプログラムを使用すると、PL/SQLアプリケーションでグローバル・トランザクション・ブランチID（XID）を定義し、現行のセッションをトランザクション・ブランチに関連付けたり、関連付けを解除できます。

その後、2フェーズ・コミット・プロトコルに従って、これらのトランザクション・ブランチを準備およびコミットできます。含まれるリソース・マネージャが1つの場合にのみ、1フェーズ・コミット・プロトコルもサポートされます。

また、現行セッションで開始する可能性のある新しいグローバル・トランザクション・ブランチのタイムアウト値を設定するPL/SQLアプリケーションのインタフェースも提供されています。

---

セキュリティ・モデル

このパッケージは、SYSの下に作成されます。 このパッケージが提供する操作は、パッケージ所有者SYSではなく、現行のコール・ユーザーのもとで実行されます。無名PL/SQLブロックからコールされたDBMS_XAサブプログラムは、現行のユーザーの権限を使用して実行されます。 ストアド・プロシージャからコールされたDBMS_XAサブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。

XA_RECOVERサブプログラムを実行する必要があるユーザーには、SYS.DBA_PENDING_TRANSACTIONSに関するSELECT権限が必要です。

他のユーザーによって作成されたXAトランザクションを操作する必要があるユーザーには、FORCE ANY TRANSACTION権限が必要です。

---

定数

DBMS_XAパッケージでは、XA_STARTファンクションおよびXA_ENDファンクションのフラグ・フィールドに、表147-1に示す定数が使用されます。

表147-1 XA_STARTおよびXA_ENDファンクションのフラグ・フィールドのDBMS_XA定数

名前	型	値	説明
TMNOFLAGS	PLS_INTEGER	00000000	フラグ値が選択されていないことを示します。
TMSUCCESS	PLS_INTEGER	UTL_RAW.CAST_TO_BINARY_INTEGER ('04000000')	コール元をトランザクション・ブランチから分離します。
TMJOIN	PLS_INTEGER	UTL_RAW.CAST_TO_BINARY_INTEGER ('00200000')	コール元は既存のトランザクション・ブランチを結合しています。
TMSUSPEND	PLS_INTEGER	UTL_RAW.CAST_TO_BINARY_INTEGER ('02000000')	コール元は関連付けを終了せずに、中断しています。
TMRESUME	PLS_INTEGER	UTL_RAW.CAST_TO_BINARY_INTEGER ('08000000')	コール元は中断したトランザクション・ブランチとの関連付けを再開しています。

DBMS_XAパッケージでは、有効な戻り値に対して表147-2に示す定数が使用されます。

表147-2 有効な戻り値に対するDBMS_XA定数

名前	型	値	説明
XA_RBBASE	PLS_INTEGER	100	ロールバック・コードの下限（下限値を含む）。
XA_RBROLLBACK	PLS_INTEGER	XA_RBBASE	詳細不明の理由によってロールバックが行われました。
XA_RBCOMMFAIL	PLS_INTEGER	XA_RBBASE+1	通信障害によってロールバックが行われました。
XA_RBDEADLOCK	PLS_INTEGER	XA_RBBASE+2	デッドロックが検出されました。
XA_RBINTEGRITY	PLS_INTEGER	XA_RBBASE+3	リソースの整合性に違反する状態が検出されました。
XA_RBOTHER	PLS_INTEGER	XA_RBBASE+4	リストにない理由によって、リソース・マネージャがトランザクションをロールバックしました。
XA_RBPROTO	PLS_INTEGER	XA_RBBASE+5	リソース・マネージャでプロトコル・エラーが発生しました。
XA_RBTIMEOUT	PLS_INTEGER	XA_RBBASE+6	トランザクション・ブランチに時間がかかりすぎました。
XA_RBTRANSIENT	PLS_INTEGER	XA_RBBASE+7	トランザクション・ブランチを再試行する場合があります。
XA_RBEND	PLS_INTEGER	XA_RBTRANSIENT	ロールバック・コードの上限（上限値を含む）。
XA_NOMIGRATE	PLS_INTEGER	9	トランザクション・ブランチがヒューリスティックに完了した可能性があります。
XA_HEURHAZ	PLS_INTEGER	8	トランザクション・ブランチがヒューリスティックに完了した可能性があります。
XA_HEURCOM	PLS_INTEGER	7	トランザクション・ブランチがヒューリスティックにコミットされました。
XA_HEURRB	PLS_INTEGER	6	トランザクション・ブランチがヒューリスティックにロールバックされました。
XA_HEURMIX	PLS_INTEGER	5	一部のトランザクション・ブランチはヒューリスティックにコミットされ、その他はロールバックされました。
XA_RETRY	PLS_INTEGER	4	ルーチンが効果なしに戻され、再発行される場合があります。
XA_RDONLY	PLS_INTEGER	3	トランザクションは読取り専用であり、コミットされています。
XA_OK	PLS_INTEGER	0	正常実行。
XAER_ASYNC	PLS_INTEGER	-2	すでに未処理となった非同期操作です。
XAER_RMERR	PLS_INTEGER	-3	トランザクション・ブランチでリソース・マネージャ・エラーが発生しました。
XAER_NOTA	PLS_INTEGER	-4	XIDは有効ではありません。
XAER_INVAL	PLS_INTEGER	-5	無効な引数が指定されました。
XAER_PROTO	PLS_INTEGER	-6	誤ったコンテキストでルーチンが起動されました。
XAER_RMFAIL	PLS_INTEGER	-7	リソース・マネージャは使用不可です。
XAER_DUPID	PLS_INTEGER	-8	XIDはすでに存在します。
XAER_OUTSIDE	PLS_INTEGER	-9	リソース・マネージャはグローバル・トランザクション外で処理を実行しています。

---

使用上の注意

分散トランザクション処理における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）に関連付けられたそれらのすべての接続/セッションが、同じリソース・マネージャに対して確立されていることを確認する必要があります。

---

データ構造

DBMS_XAパッケージでは、次のオブジェクト・タイプおよび関連する表タイプが使用されます。

オブジェクト・タイプ

• DBMS_XA_XIDオブジェクト・タイプ

表タイプ

• DBMS_XA_XID_ARRAY表タイプ

---

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)

属性

表147-3 DBMS_XA_XIDオブジェクト・タイプ

属性	説明
formatid	形式識別子。異なるトランザクション・マネージャ（TM）を識別する数値。
gtrid	グローバル・トランザクションを一意に識別するグローバル・トランザクション識別子。最大サイズは64バイト。
bqual	ブランチ修飾子。最大サイズは64バイト。

---

DBMS_XA_XID_ARRAY表タイプ

このタイプは、グローバル・トランザクション・ブランチのリストに相当するxidの配列を定義する場合に使用します。

構文

TYPE DBMS_XA_XID_ARRAY as TABLE of DBMS_XA_XID

---

DBMS_XAサブプログラムの要約

表147-4 DBMS_XAパッケージのサブプログラム

サブプログラム	説明
DIST_TXN_SYNCプロシージャ	Oracle Real Application Clusters（RAC）の利用時に同期化のリカバリで使用します。
XA_COMMITファンクション	xidで指定したグローバル・トランザクションをコミットします。
XA_ENDファンクション	xidで指定したトランザクション・ブランチから、現行セッションの関連付けを解除します。
XA_FORGETファンクション	ヒューリスティックにコミットまたはロールバックされたトランザクション・ブランチについての情報を消去するよう、リソース・マネージャに通知します。
XA_GETLASTOERファンクション	前のXAコールが失敗した場合に、最後のOracleエラー・コードを取得します。
XA_PREPAREファンクション	xidで指定したトランザクション・ブランチを準備して、可能な場合に続けてトランザクションをコミットできるようにします。
XA_RECOVERファンクション	準備されたか、またはヒューリスティックに完了したトランザクション・ブランチのリストをリソース・マネージャから取得します。
XA_ROLLBACKファンクション	実行された処理をトランザクション・ブランチにかわってロールバックするよう、リソース・マネージャに通知します。
XA_SETTIMEOUTファンクション	現行セッションのトランザクション・タイムアウトを秒単位で設定します。
XA_STARTファンクション	xidで指定したトランザクション・ブランチに、現行セッションを関連付けます。

---

DIST_TXN_SYNCプロシージャ

このプロシージャを使用すると、Oracle Real Application Clusters（RAC）インスタンスが失敗した場合に、インダウト・トランザクションを同期化できます。

構文

DBMS_XA.DIST_TXN_SYNC;

---

XA_COMMITファンクション

このファンクションは、xidで指定したグローバル・トランザクションをコミットします。

構文

DBMS_XA.XA_COMMIT (
   xid       IN  DBMS_XA_XID,
   onePhase  IN  BOOLEAN)
RETURN PLS_INTEGER;

パラメータ

表147-5 XA_COMMITファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。
onePhase	TRUEの場合、1フェーズ・コミットを適用します。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 エラーを示す有効な戻り値は、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つを戻します。コードを戻すと、リソース・マネージャはブランチの処理をロールバックし、保持しているすべてのリソースを解放します。

---

XA_ENDファンクション

このファンクションは、xidで指定したトランザクション・ブランチから、現行セッションの関連付けを解除します。

コントロールのスレッドがトランザクション・ブランチを終了したか、または処理を中断する必要がある場合、トランザクション・マネージャはXA_ENDをコールします。これは、アプリケーションが処理の一部を部分的に、または完全に完了する場合に発生します。たとえば、コントロールの他のスレッドをブランチで機能させるために、一部のイベントをブロックする前などに発生します。 XA_ENDが正常に戻されると、コントロールのコール元のスレッドとブランチとの関連付けはアクティブではなくなりますが、ブランチは引き続き存在します。

構文

DBMS_XA.XA_END (
   xid   IN  DBMS_XA_XID,
   flag  IN  PLS_INTEGER)
RETURN PLS_INTEGER;

パラメータ

表147-6 XA_ENDファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。
flag	詳細は、表147-1「XA_STARTおよびXA_ENDファンクションのフラグ・フィールドのDBMS_XA定数」を参照してください。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 エラーにおける有効な戻り値は、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で識別されたトランザクションには影響しません。これは、このトランザクションと現行セッションとの関連付けが解除されているためです。 xidで指定したトランザクションをコミットまたはロールバックするには、トランザクションIDまたはXA_ROLLBACKファンクションをコミットします。

---

XA_FORGETファンクション

このファンクションは、ヒューリスティックにコミットまたはロールバックされたトランザクション・ブランチについての情報を消去するよう、リソース・マネージャに通知します。

構文

DBMS_XA.XA_FORGET (
   xid       IN  DBMS_XA_XID)
RETURN PLS_INTEGER;

パラメータ

表147-7 XA_FORGETファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 有効な戻り値は、XA_OK、XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVALまたはXAER_PROTOです。

---

XA_GETLASTOERファンクション

このファンクションは、前のXAコールが失敗した場合に、最後のOracleエラー・コードを取得します。

構文

DBMS_XA.XA_GETLASTOER
 RETURN PLS_INTEGER;

戻り値

戻り値には、最後のOracleエラー・コードが示されます。

---

XA_PREPAREファンクション

このファンクションは、xidで指定したトランザクション・ブランチを準備して、可能な場合に続けてトランザクションをコミットできるようにします。

構文

DBMS_XA.XA_PREPARE (
   xid   IN  DBMS_XA_XID)
RETURN PLS_INTEGER;

パラメータ

表147-8 XA_PREPAREファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 有効なリターン・コードは、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のコールを続行できます。

---

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権限を付与する必要があります。

---

XA_ROLLBACKファンクション

このファンクションは、実行された処理をトランザクション・ブランチにかわってロールバックするよう、リソース・マネージャに通知します。

構文

DBMS_XA.XA_ROLLBACK (
   xid       IN  DBMS_XA_XID)
 RETURN PLS_INTEGER;

パラメータ

表147-9 XA_ROLLBACKファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 有効な戻り値は、XA_OK、XA_RB*、XA_HEURHAZ、XA_HEURCOM、XA_HEURRBまたはXA_HEURMIXです。

使用上の注意

他のユーザーによって作成されたトランザクション・ブランチをロールバックする必要があるユーザーには、FORCE ANY TRANSACTION権限を付与する必要があります。

---

XA_SETTIMEOUTファンクション

このファンクションは、現行セッションのトランザクション・タイムアウトを秒単位で設定します。

構文

DBMS_XA.XA_SETTIMEOUT (
   seconds  IN  PLS_INTEGER)
RETURN PLS_INTEGER;

パラメータ

表147-10 XA_SETTIMEOUTファンクションのパラメータ

パラメータ	説明
seconds	タイムアウト値は、トランザクションがシステムによって自動的に終了される前に、トランザクション・ブランチの関連付けがセッションから解除される可能性がある最大時間（秒）を示します。デフォルト値は60秒です。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。 有効な戻り値は、XA_OK、XAER_RMERR、XAER_RMFAILまたはXAER_INVALです。

使用上の注意

戻り値がXA_OKの場合にのみ、タイムアウト値は正常に設定されます。

---

XA_STARTファンクション

このファンクションは、xidで指定したトランザクション・ブランチに現行セッションを関連付けます。

構文

DBMS_XA.XA_START (
   xid   IN  DBMS_XA_XID,    flag  IN  PLS_INTEGER)  RETURN PLS_INTEGER;

パラメータ

表147-11 XA_STARTファンクションのパラメータ

パラメータ	説明
xid	詳細は、「DBMS_XA_XIDオブジェクト・タイプ」を参照してください。
flag	詳細は、表147-1「XA_STARTおよびXA_ENDファンクションのフラグ・フィールドのDBMS_XA定数」を参照してください。

戻り値

詳細は、表147-2「有効な戻り値に対するDBMS_XA定数」を参照してください。

使用上の注意

• フラグに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が戻されます。