DBMS_STREAMS_MESSAGING

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`を指定するデキュー・プロシージャには、この例外を処理する例外ハンドラを含める必要があります。

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。

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を実行し、キュー・ユーザーを指定すると、アドバンスト・キューイング・エージェントが自動的に作成されます。

参照:

SET_UP_QUEUEプロシージャ