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タイプを使用します。

オブジェクト・タイプ

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_RMERRXAER_RMFAILXAER_NOTAXAER_INVALまたはXAER_PROTOです。その他にも有効な戻り値として、XA_OKXA_RB*、XA_HEURHAZXA_HEURCOMXA_HEURRBXA_HEURMIXなどがあります。

使用上の注意

  • アプリケーションは、COMMITではなく、XA_COMMITをコールして、xidで指定したグローバル・トランザクションをコミットする必要があります。他のユーザーによって作成されたトランザクション・ブランチをコミットする必要があるユーザーには、FORCE ANY TRANSACTIONを付与する必要があります。

  • onePhaseTRUEの場合、リソース・マネージャは1フェーズ・コミット・プロトコルを使用して、実行された処理をxidのかわりにコミットする必要があります。そうでない場合は、グローバル・トランザクションのすべてのブランチが正常に準備され、先行のXA_PREPAREコールがXA_OKを戻した場合にのみ、XA_COMMITがコールされます。

  • アプリケーションは、XA_PREPAREXA_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_RMERRXAER_RMFAILEDXAER_NOTAXAER_INVALXAER_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_OKXAER_RMERRXAER_RMFAILXAER_NOTAXAER_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_OKXA_RDONLYXA_RB*、XAER_RMERRXAER_RMFAILXAER_NOTAXAER_INVALまたはXAER_PROTOです。

使用上の注意

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

  • アプリケーションは、1つのグローバル・トランザクションのすべてのブランチを追跡し、各トランザクション・ブランチを準備する必要があります。グローバル・トランザクションのすべてのブランチが正常に準備され、XA_PREPAREXA_OKを戻した場合にのみ、アプリケーションは、XA_COMMITのコールを続行できます。

185.6.7 XA_RECOVERファンクション

このファンクションは、準備されたか、またはヒューリスティックに完了したトランザクション・ブランチのリストをリソース・マネージャから取得します。

構文

DBMS_XA.XA_RECOVER 
 RETURN DBMS_XA_XID_ARRAY;

戻り値

「DBMS_XA_XID_ARRAY表タイプ」を参照してください。

使用上の注意

  • TMSTARTSCANTMENDSCANTMNOFLAGSフラグはサポートされていません。

  • 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_OKXA_RB*、XA_HEURHAZXA_HEURCOMXA_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_OKXAER_RMERRXAER_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_STARTXAER_DUPIDエラー・コードを戻します。

  • エラーにおける有効な戻り値は、XAER_RMERRXAER_RMFAILXAER_DUPIDXAER_OUTSIDEXAER_NOTAXAER_INVALおよびXAER_PROTOです。

  • XA_STARTが成功すると、XA_OKが戻されます。アプリケーションは、戻り値をチェックしてエラーを処理する必要があります。XA_OKが戻された場合にのみ、PL/SQLアプリケーションはその他の通常の処理を続行する必要があります。トランザクション スタッキングはサポートされていません。現行セッションに関連付けられたアクティブなトランザクションがあると、別のトランザクションの開始または結合のためのコールは行われないことがあります。セッションに関連付けられたアクティブなグローバル・トランザクション・ブランチによってXA_STARTがコールされた場合には、XAER_PROTOが戻されます。現行セッションに関連付けられたローカル・トランザクションによってXA_STARTがコールされた場合には、XAER_OUTSIDEが戻されます。