166 DBMS_STREAMS_MESSAGING

DBMS_STREAMS_MESSAGINGパッケージは、Oracle Streamsパッケージ・セットの1つであり、ANYDATAキューにメッセージをエンキューおよびデキューするインタフェースを提供しています。

この章のトピックは、次のとおりです:

166.1 DBMS_STREAMS_MESSAGINGの概要

このパッケージは、ANYDATAキューへのメッセージのエンキューおよびデキューを行うインタフェースを提供します。

注意:

現在、メッセージ・クライアントはバッファに入れたメッセージをデキューできません。また、DBMS_STREAMS_MESSAGINGパッケージを使用してバッファ・キューにメッセージをエンキューしたり、バッファ・キューからメッセージをデキューすることはできません。ただし、DBMS_AQパッケージを使用して、バッファに入れられたメッセージをエンキューおよびデキューできます。

参照:

キュー、メッセージおよびDBMS_AQパッケージの詳細は、『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください。

166.2 DBMS_STREAMS_MESSAGINGのセキュリティ・モデル

このパッケージのセキュリティは、選択したユーザーまたはロールにこのパッケージのEXECUTE権限を付与するか、選択したユーザーまたはロールにEXECUTE_CATALOG_ROLEを付与することで制御できます。

パッケージのサブプログラムをストアド・プロシージャ内から実行する場合、そのサブプログラムを実行するユーザーには、パッケージのEXECUTE権限を直接付与する必要があります。ロールを通して付与することはできません。

このパッケージ内のサブプログラムを実行するユーザーが必要な権限を所有するには、Oracle Streams管理者を構成し、このパッケージを使用するときにOracle Streams管理者として接続します。

参照:

Oracle Streams管理者の構成の詳細は、『Oracle Streamsレプリケーション管理者ガイド』を参照してください。

166.3 DBMS_STREAMS_MESSAGINGサブプログラムの要約

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

表166-1 DBMS_STREAMS_MESSAGINGパッケージのサブプログラム

サブプログラム 説明

DEQUEUEプロシージャ

指定したOracle Streamsメッセージ・クライアントを使用して、指定したキューからメッセージをデキューします。

ENQUEUEプロシージャ

現在のユーザーが指定したキューにメッセージをエンキューします。

注意:

このパッケージのサブプログラムはコミットしません。

166.3.1 DEQUEUEプロシージャ

このプロシージャは、指定したOracle Streamsメッセージ・クライアントを使用して、指定したキューからメッセージをデキューします。

このプロシージャはオーバーロードされています。このプロシージャの一方のバージョンには、msgid OUTパラメータがあり、他方のバージョンにはこのパラメータがありません。

構文

DBMS_STREAMS_MESSAGING.DEQUEUE(
   queue_name    IN   VARCHAR2,    
   streams_name  IN   VARCHAR2,    
   payload       OUT  ANYDATA,   
   dequeue_mode  IN   VARCHAR2        DEFAULT 'REMOVE',
   navigation    IN   VARCHAR2        DEFAULT 'NEXT MESSAGE',
   wait          IN   BINARY_INTEGER  DEFAULT FOREVER,
   msgid         OUT  RAW);

DBMS_STREAMS_MESSAGING.DEQUEUE(
   queue_name    IN   VARCHAR2,    
   streams_name  IN   VARCHAR2,    
   payload       OUT  ANYDATA,   
   dequeue_mode  IN   VARCHAR2        DEFAULT 'REMOVE',
   navigation    IN   VARCHAR2        DEFAULT 'NEXT MESSAGE',
   wait          IN   BINARY_INTEGER  DEFAULT FOREVER);

パラメータ

表166-2 DEQUEUEプロシージャのパラメータ

パラメータ 説明

queue_name

メッセージをデキューするローカル・キューの名前で、[schema_name.]queue_nameの形式で指定します。現在のデータベースにキューが含まれていて、そのキューはANYDATAタイプの保護キューである必要があります。

たとえば、strmadminスキーマ内のstreams_queueという名前のキューを指定するには、このパラメータにstrmadmin.streams_queueと入力します。スキーマを指定しない場合は、現行のユーザー名がデフォルトで使用されます。

streams_name

Oracle Streamsメッセージ・クライアントの名前。たとえば、ユーザーstrmadminがメッセージ・クライアントである場合、strmadminと指定します。

このパラメータがNULLで、キューの関連メッセージ・クライアントが1つ存在する場合は、関連メッセージ・クライアントが使用されます。このパラメータがNULLで、キューの関連メッセージ・クライアントが複数存在する場合は、エラーが発生します。

payload

デキューするペイロード。

dequeue_mode

次のいずれかの設定を指定します。

REMOVE: メッセージを読み取り、削除します。この設定がデフォルトです。メッセージは保存プロパティに基づいてキュー表に保存されます。

LOCKED: メッセージを読み取り、その書込みロックを取得します。ロックは、トランザクションの間、存続します。この設定は、SELECT FOR UPDATE文と同じです。

BROWSE: メッセージのロックを取得せずにメッセージを読み取ります。この仕様は、SELECT文と同じです。

navigation

取り出されるメッセージの位置。最初に位置が判断されます。次に検索基準が適用されます。最後にメッセージが取り出されます。

次のいずれかの設定を指定します。

NEXT MESSAGE: 使用可能で検索基準と一致する次のメッセージを取り出します。前のメッセージがメッセージ・グループに属している場合は、検索基準と一致し、そのメッセージ・グループに属している次の使用可能メッセージが取り出されます。この設定がデフォルトです。

NEXT TRANSACTION: 現行メッセージ・グループの残り(ある場合)をスキップし、次のメッセージ・グループの最初のメッセージを取り出します。この設定は、現行キューに対してメッセージ・グループが使用可能な場合にのみ使用できます。

FIRST MESSAGE: 使用可能で検索基準と一致する最初のメッセージを取り出します。この設定により、位置がキューの先頭に再設定されます。

注意: 各メッセージ・グループには、単一のトランザクションのメッセージが含まれます。

関連項目: デキュー・オプションの詳細は、『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください。

wait

FOREVERまたはNO_WAIT

FOREVERの場合、キュー内のメッセージが使用可能になるまで、タイムアウトなしで、デキュー・コールがブロックされます。

NO_WAITの場合、0(ゼロ)秒の待機時間が使用されます。この場合、キュー内にメッセージがない場合でも、デキューはただちに戻ります。

msgid

デキューするメッセージのメッセージID。

例外

表166-3 DEQUEUEプロシージャの例外

例外 説明

ENDOFCURTRANS

デキューは現在のトランザクションの最後のメッセージに達しました。この例外は次のように指定します。

SYS.DBMS_STREAMS_MESSAGING.ENDOFCURTRANS

すべてのデキュー・プロシージャに、この例外を処理する例外ハンドラを含める必要があります。

NOMOREMSGS

キュー内にデキュー操作の対象となるメッセージがありません。この例外は次のように指定します。

SYS.DBMS_STREAMS_MESSAGING.NOMOREMSGS

waitパラメータにNO_WAITを指定するデキュー・プロシージャには、この例外を処理する例外ハンドラを含める必要があります。

166.3.2 ENQUEUEプロシージャ

このプロシージャを使用して、現在のユーザーが指定したキューにメッセージをエンキューできます。

このプロシージャはオーバーロードされています。このプロシージャの一方のバージョンには、msgid OUTパラメータがあり、他方のバージョンにはこのパラメータがありません。

構文

DBMS_STREAMS_MESSAGING.ENQUEUE(
   queue_name  IN   VARCHAR2,  
   payload     IN   ANYDATA,  
   msgid       OUT  RAW);

DBMS_STREAMS_MESSAGING.ENQUEUE(
   queue_name  IN   VARCHAR2,  
   payload     IN   ANYDATA);

パラメータ

表166-4 ENQUEUEプロシージャのパラメータ

パラメータ 説明

queue_name

メッセージをエンキューするローカル・キューの名前で、[schema_name.]queue_nameの形式で指定します。現在のデータベースにキューが含まれていて、そのキューはANYDATAタイプの保護キューである必要があります。

たとえば、strmadminスキーマ内のstreams_queueという名前のキューを指定するには、このパラメータにstrmadmin.streams_queueと入力します。スキーマを指定しない場合は、現行のユーザー名がデフォルトで使用されます。

payload

エンキューするペイロード。

msgid

エンキューするメッセージのメッセージID。

使用上の注意

メッセージを正しくキューにエンキューするには、現在のユーザーを現在のユーザーと同じ名前で、一意のアドバンスト・キューイング・エージェントにマップする必要があります。DBMS_STREAMS_ADM.SET_UP_QUEUEプロシージャを実行し、ユーザーをキュー・ユーザーとして指定して、エンキューの実行に必要な権限をユーザーに付与できます。SET_UP_QUEUEを実行し、キュー・ユーザーを指定すると、アドバンスト・キューイング・エージェントが自動的に作成されます。