DBMS_XA

185 DBMS_XA

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

この章の内容は次のとおりです。

参照:

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

185.1 DBMS_XAの概要

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

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

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

185.2 DBMS_XAのセキュリティ・モデル

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

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

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

185.3 DBMS_XAの定数

DBMS_XAパッケージは、パラメータ値の指定に使用できるいくつかの定数を定義します。

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

表185-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パッケージでは、有効な戻り値に対して表185-2に示す定数が使用されます。

表185-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	リソース・マネージャはグローバル・トランザクション外で処理を実行しています。

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

185.5 DBMS_XAのデータ構造

DBMS_XAパッケージは、このOBJECTタイプおよび関連するTABLEタイプを使用します。

オブジェクト・タイプ

DBMS_XA_XIDオブジェクト・タイプ

表タイプ

DBMS_XA_XID_ARRAY表タイプ

185.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)

属性

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

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

185.5.2 DBMS_XA DBMS_XA_XID_ARRAY表タイプ

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

構文

TYPE DBMS_XA_XID_ARRAY as TABLE of DBMS_XA_XID

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

この表は、DBMS_XAサブプログラムを示し、簡単に説明しています。

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

サブプログラム	説明
DIST_TXN_SYNCプロシージャ	Oracle Real Application Clusters(Oracle 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`で指定したトランザクション・ブランチに、現行セッションを関連付けます。

185.6.1 DIST_TXN_SYNCプロシージャ

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

構文

DBMS_XA.DIST_TXN_SYNC;

185.6.2 XA_COMMITファンクション

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

構文

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

パラメータ

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

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

戻り値

表185-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つを戻します。コードを戻すと、リソース・マネージャはブランチの処理をロールバックし、保持しているすべてのリソースを解放します。

185.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;

パラメータ

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

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

戻り値

表185-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が特定するトランザクションに影響はありません。xidで指定したトランザクションをコミットまたはロールバックするには、トランザクションIDまたはXA_ROLLBACKファンクションファンクションをコミットします。

185.6.4 XA_FORGETファンクション

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

構文

DBMS_XA.XA_FORGET (
   xid       IN  DBMS_XA_XID)
RETURN PLS_INTEGER;

パラメータ

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

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

戻り値

表185-2を参照してください。有効な戻り値は、XA_OK、XAER_RMERR、XAER_RMFAIL、XAER_NOTA、XAER_INVALまたはXAER_PROTOです。

185.6.5 XA_GETLASTOERファンクション

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

構文

DBMS_XA.XA_GETLASTOER  
 RETURN PLS_INTEGER;

戻り値

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

185.6.6 XA_PREPAREファンクション

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

構文

DBMS_XA.XA_PREPARE (
   xid   IN  DBMS_XA_XID)
RETURN PLS_INTEGER;

パラメータ

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

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

戻り値

表185-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のコールを続行できます。

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

185.6.8 XA_ROLLBACKファンクション

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

構文

DBMS_XA.XA_ROLLBACK (
   xid       IN  DBMS_XA_XID)
 RETURN PLS_INTEGER;

パラメータ

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

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

戻り値

表185-2を参照してください。有効な戻り値は、XA_OK、XA_RB*、XA_HEURHAZ、XA_HEURCOM、XA_HEURRBまたはXA_HEURMIXです。

使用上のノート

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

185.6.9 XA_SETTIMEOUTファンクション

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

構文

DBMS_XA.XA_SETTIMEOUT (
   seconds  IN  PLS_INTEGER)
RETURN PLS_INTEGER;

パラメータ

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

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

戻り値

表185-2を参照してください。有効な戻り値は、XA_OK、XAER_RMERR、XAER_RMFAILまたはXAER_INVALです。

使用上のノート

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

185.6.10 XA_STARTファンクション

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

構文

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

パラメータ

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

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

戻り値

表185-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が戻されます。