DBMS_AQ

21 DBMS_AQ

DBMS_AQパッケージは、Oracle Streams Advanced Queuing(AQ)へのインタフェースを提供します。

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

参照:

『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』
DBMS_AQと一緒に使用するTYPEについては、「Oracle Databaseアドバンスト・キューイング(AQ)のタイプ」を参照してください。

21.1 DBMS_AQのセキュリティ・モデル

最初は、SYSおよびSYSTEMのみに、DBMS_AQおよびDBMS_AQADM内のプロシージャの実行権限が付与されています。

キューのセキュリティ

エンキューまたはデキューするユーザーには、DBMS_AQのEXECUTE権限の他、ターゲット・キューでのENQUEUEまたはDEQUEUE権限、もしくはENQUEUE_ANY/DEQUEUE_ANYシステム権限のいずれかが必要です。DBMS_AQとDBMS_AQADMのEXECUTE権限が付与されたユーザーは、自分のスキーマで、キューの作成、管理および使用ができます。他のスキーマのキューを作成および管理する場合は、MANAGE_ANY AQシステム権限が使用されます。

データベース・ユーザーは、DBMS_AQに対するEXECUTE権限以外に、オブジェクト・レベルまたはシステム・レベルの明示的な権限を付与されなくても、自分のスキーマでのキューのエンキューおよびデキューが可能です。

参照:

キュー権限およびアクセス制御の詳細は、『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください。

OCIアプリケーションとキュー・アクセス

Oracle Call Interface(OCI)アプリケーションでキューにアクセスするには、セッション・ユーザーに、アクセス先のキューのオブジェクト権限、またはシステム権限(ENQUEUE ANY QUEUEまたはDEQUEUE ANY QUEUE)のいずれかを付与する必要があります。DBMS_AQのEXECUTE権限とセッション・ユーザーの権限が照合されて確認されることはありません。

伝播に必要なセキュリティ

伝播ジョブの所有者はSYSですが、伝播はキュー表の所有者のセキュリティ・コンテキスト内で発生します。以前は、伝播ジョブの所有者は、伝播をスケジューリングするユーザーで、伝播が発生するのは、伝播スケジュールを設定するユーザーのセキュリティ・コンテキスト内でした。キュー表の所有者には、DBMS_AQADMパッケージのEXECUTE権限が必要です。権限がない場合、Oracleデータベース・スナップショット・プロセスは、エラー識別子SYS.DBMS_AQADMが定義されていないトレース・ファイルを伝播および生成しません。伝播には、キュー表の所有者が所有するプライベート・データベース・リンクを使用できます。接続文字列に指定されたユーザーには、リモート・データベース上のDBMS_AQパッケージおよびDBMS_AQADMパッケージに対するEXECUTEアクセス権限が必要です。

参照:

DBMS_AQADM
伝播する際のセキュリティ要件の詳細は、『Oracle Databaseアドバンスト・キューイング・ユーザーズ・ガイド』を参照してください

21.2 DBMS_AQの定数

このトピックでは、DBMS_AQで使用される定数について説明します。

DBMS_AQパッケージでは、次の表に示す定数が使用されます。

BROWSE、LOCKEDまたはREMOVEなどの列挙定数を使用するときは、それを定義しているパッケージの有効範囲内で、PL/SQL定数を指定する必要があります。操作インタフェースに関連付けられているすべてのタイプに、DBMS_AQを付加する必要があります。たとえば、DBMS_AQ.BROWSEのようにします。

ノート:

DBMS_AQADMサブプログラムのmessage_groupingパラメータをTRANSACTIONALに設定すると、sequence_deviation属性は、Oracle Streams AQ 10g リリース1(10.1)以前のリリースでは無効になります。Oracle Streams AQ 10g リリース2(10.2)では、順序逸脱機能の使用は推奨されていません。

表21-1 列挙定数

パラメータ	オプション	タイプ	説明
`VISIBILITY`	`IMMEDIATE`	-	-
-	`ON_COMMIT`	-	-
`DEQUEUE_MODE`	`BROWSE`	-	-
-	`LOCKED`	-	-
-	`REMOVE`	-	-
-	`REMOVE_NODATA`	-	-
`NAVIGATION`	`FIRST_MESSAGE`	-	-
-	`NEXT_MESSAGE`	-	-
`STATE`	`WAITING`	-	-
-	`READY`	-	-
-	`PROCESSED`	-	-
-	`EXPIRED`	-	-
`SEQUENCE_DEVIATION`	`BEFORE`	-	-
-	`TOP`	-	-
`WAIT`	`FOREVER`	`BINARY_INTEGER`	-
-	`NO_WAIT`	`BINARY_INTEGER`	-
`DELAY`	`NO_DELAY`	-	-
`EXPIRATION`	`NEVER`	-	-
`NAMESPACE`	`NAMESPACE_AQ`	-	-
-	`NAMESPACE_ANONYMOUS`	-	-
`NTFN_GROUPING_CLASS`	`NFTN_GROUPING_CLASS_TIME`	`NUMBER`	-
`NTFN_GROUPING_TYPE`	`NTFN_GROUPING_TYPE_SUMMARY`	`NUMBER`	-
-	`NTFN_GROUPING_TYPE_LAST`	`NUMBER`	-
`NTFN_GROUPING_REPEAT_COUNT`	`NTFN_GROUPING_FOREVER`	`NUMBER`	-

21.3 DBMS_AQのデータ・タイプ

このトピックでは、DBMS_AQのデータ・タイプとその説明を示します。

表21-2 DBMS_AQのデータ構造

データ構造	説明
`OBJECT_NAME`	データベース・オブジェクトに名前を付けます。
`TYPE_NAME`	キュー・タイプを定義します。
Oracle Databaseアドバンスト・キューイングのPL/SQLコールバック	メッセージ通知時に起動されるようにデータベースに定義することで、ユーザー定義のPL/SQLプロシージャを指定します。

OBJECT_NAME

object_nameデータ構造は、データベース・オブジェクトの名前を付けます。この構造は、キュー、キュー表、エージェント名およびオブジェクト・タイプに適用されます。

構文

object_name := VARCHAR2;
object_name := [schema_name.]name;

使用上のノート

オブジェクト名は、オプションのスキーマ名および名前で指定します。スキーマ名が指定されない場合は、現在のスキーマ名が使用されます。名前は、予約語について、『Oracle Database SQL言語リファレンス』のオブジェクト名ガイドラインに従う必要があります。スキーマ、エージェントおよびオブジェクト・タイプの名前は、128バイト以内で設定します。キューおよびキュー表の名前は、122バイト以内で設定します。エージェント名およびサブスクライバ名の最大長は、2kより大きいデータブロック・サイズで128です。データブロック・サイズが2kの場合、サブスクライバの最大長は128バイトです。

TYPE_NAME

type_nameデータ構造は、キュー・タイプを定義します。

構文

type_name := VARCHAR2;
type_name := object_type | "RAW";

属性

表21-3 タイプ名の属性

属性説明

属性	説明
`object_type`	オブジェクト・タイプ内の属性の最大数は900です。
`"RAW"`	`RAW`型のペイロードを格納するために、Oracle Databaseアドバンスト・キューイングでは、ペイロード・リポジトリとして`LOB`列を持つキュー表が作成されます。メッセージ・ペイロードの理論上の最大サイズは、`LOB`列に格納可能な最大データ量です。ただし、ペイロードの最大サイズは、Oracle Databaseアドバンスト・キューイングにアクセスするときに使用するプログラム環境によって決まります。PL/SQL、Javaおよびプリコンパイラの場合は32K、OCIの場合は4Gです。PL/SQLのエンキューおよびデキューのインタフェースは、`RAW`バッファをペイロード・パラメータとして受け入れるため、32KBに制限されます。OCIでは、ユーザーの`RAW`データの最大サイズは、OCIオブジェクト・キャッシュによる割当てが可能な最大連続メモリー量(`OCIRaw`が単純にバイト配列の場合)に制限されます。通常は、最低32KBですが、ほとんどの場合それ以上になります。 `LOB`列は`RAW`ペイロードの格納に使用されるため、Oracle Databaseアドバンスト・キューイング管理者は、`LOB`表領域を選択して、キュー表作成時に`storage_clause`パラメータに`LOB`記憶域文字列を設定すると、`LOB`記憶域を構成できます。

object_type

オブジェクト・タイプ内の属性の最大数は900です。

"RAW"

RAW型のペイロードを格納するために、Oracle Databaseアドバンスト・キューイングでは、ペイロード・リポジトリとしてLOB列を持つキュー表が作成されます。メッセージ・ペイロードの理論上の最大サイズは、LOB列に格納可能な最大データ量です。ただし、ペイロードの最大サイズは、Oracle Databaseアドバンスト・キューイングにアクセスするときに使用するプログラム環境によって決まります。PL/SQL、Javaおよびプリコンパイラの場合は32K、OCIの場合は4Gです。PL/SQLのエンキューおよびデキューのインタフェースは、RAWバッファをペイロード・パラメータとして受け入れるため、32KBに制限されます。OCIでは、ユーザーのRAWデータの最大サイズは、OCIオブジェクト・キャッシュによる割当てが可能な最大連続メモリー量(OCIRawが単純にバイト配列の場合)に制限されます。通常は、最低32KBですが、ほとんどの場合それ以上になります。

LOB列はRAWペイロードの格納に使用されるため、Oracle Databaseアドバンスト・キューイング管理者は、LOB表領域を選択して、キュー表作成時にstorage_clauseパラメータにLOB記憶域文字列を設定すると、LOB記憶域を構成できます。

Oracle Databaseアドバンスト・キューイングのPL/SQLコールバック

plsqlcallbackデータ構造は、メッセージ通知時に起動されるようにデータベースで定義することで、ユーザー定義のPL/SQLプロシージャを指定します。

構文

RAWペイロード・エンキューの通知メッセージが要求されている場合、PL/SQLコールバックには次の署名が付加されている必要があります。

procedure plsqlcallback(
  context  IN  RAW, 
  reginfo  IN  SYS.AQ$_REG_INFO, 
  descr    IN  SYS.AQ$_DESCRIPTOR, 
  payload  IN  RAW,
  payloadl IN  NUMBER);

属性

表21-4 Oracle Databaseアドバンスト・キューイングのPL/SQLコールバックの属性

属性	説明
`context`	`dbms_aq.register`により渡されたコールバック関数のコンテキストを指定します。「AQ$_REG_INFOタイプ」を参照してください。
`reginfo`	「AQ$_REG_INFOタイプ」を参照してください。
`descr`	「AQ$_DESCRIPTORタイプ」を参照してください。
`payload`	RAWペイロード・エンキューの通知メッセージが要求されている場合、非永続キューにエンキューされたRAWペイロードが含まれます。RAWペイロードが含まれる永続キューの場合、パラメータはNULLです。
`payloadl`	`payload`の長さを指定します。`payload`がNULLの場合、`payload1` = 0です。

ADTのペイロード・エンキューの通知メッセージが要求されている場合、PL/SQLコールバックには次の署名が付加されている必要があります。

procedure plsqlcallback(
  context  IN RAW, 
  reginfo  IN SYS.AQ$_REG_INFO, 
  descr    IN SYS.AQ$_DESCRIPTOR, 
  payload  IN VARCHAR2,
  payloadl IN NUMBER);

21.4 DBMS_AQの操作上のノート

このトピックでは、DBMS_AQの各種の操作上のノートを示します。

DBMS_AQおよびDBMS_AQADM Javaクラス

DBMS_AQおよびDBMS_AQADMには、Javaインタフェースを使用できます。Javaインタフェースは、$ORACLE_HOME/rdbms/jlib/aqapi.jarにあります。これらのインタフェースを使用するには、ユーザーにDBMS_AQINパッケージのEXECUTE権限が必要です。

21.5 DBMS_AQサブプログラムの要約

DBMS_AQパッケージでは、この表で説明するサブプログラムが使用されます。

表21-5 DBMS_AQパッケージのサブプログラム

サブプログラム	説明
BIND_AGENTプロシージャ	LDAPディレクトリ内にOracle Databaseアドバンスト・キューイング・エージェントのエントリを作成します。
DEQUEUEプロシージャ	指定したキューからメッセージをデキューします。
DEQUEUE_ARRAYファンクション	指定したキューからメッセージの配列をデキューします。
ENQUEUEプロシージャ	指定したキューにメッセージを追加します。
ENQUEUE_ARRAYファンクション	指定したキューにメッセージの配列を追加します。
LISTENプロシージャ	エージェントのリストにかわって1つ以上のキューをリスニングします。
POSTプロシージャ	匿名サブスクリプションに転送します。サブスクリプションに登録された全クライアントが通知を受信できます。
REGISTERプロシージャ	メッセージ通知を登録します。
UNBIND_AGENTプロシージャ	LDAPディレクトリからOracle Databaseアドバンスト・キューイング・エージェントのエントリを削除します。
UNREGISTERプロシージャ	通知をオフにするサブスクリプションを登録解除します。

ノート:

DBMS_AQには、純正レベルが定義されていません。したがって、RNDS、WNDS、RNPSまたはWNPS制約が定義されている他のプロシージャからこのパッケージ内のプロシージャをコールできません。

21.5.1 BIND_AGENTプロシージャ

このプロシージャは、LDAPサーバーにOracle Databaseアドバンスト・キューイング・エージェントのエントリを作成します。

構文

DBMS_AQ.BIND_AGENT(
   agent        IN SYS.AQ$_AGENT,
   certificate  IN VARCHAR2 default NULL);

パラメータ

表21-6 BIND_AGENTプロシージャのパラメータ

パラメータ	説明
`agent`	LDAPサーバーで登録されるエージェント。
`certificate`	このエージェントでデジタル証明書(`usercertificate`属性)が使用されるLDAPにおける、organizationalpersonエントリの場所(LDAPの識別名)。たとえば、"cn=OE, cn=ACME, cn=com"は、指定したエージェントで証明書が使用されるOrganizationalPerson OEの識別名です。

使用上のノート

LDAPサーバーでは、デジタル証明書がOrganizationalPersonエンティティの属性(usercertificate)として格納されます。このOrganizationalPersonの識別名をエージェントのバインド時に指定する必要があります。

21.5.2 DEQUEUEプロシージャ

このプロシージャでは、メッセージを指定のキューからデキューします。

構文

DBMS_AQ.DEQUEUE (
   queue_name          IN      VARCHAR2,
   dequeue_options     IN      dequeue_options_t,
   message_properties  OUT     message_properties_t,
   payload             OUT     "<ADT_1>"
   msgid               OUT     RAW);

パラメータ

表21-7 DEQUEUEプロシージャのパラメータ

パラメータ	説明
`queue_name`	キュー名を指定します。
`dequeue_options`	「DEQUEUE_OPTIONS_Tタイプ」を参照してください。
`message_properties`	「MESSAGE_PROPERTIES_Tタイプ」を参照してください。
`payload`	Oracle Databaseアドバンスト・キューイングでは解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。`type_name`の定義については、「DBMS_AQのデータ・タイプ」の`TYPE_NAME`を参照してください。
`msgid`	システムが生成するメッセージID。

使用上のノート

デキューされるメッセージの検索基準は、dequeue_optionsの次のパラメータによって判断されます。

consumer_name
msgid

msgidはデキューされるメッセージを一意に識別します。msgidを指定しないかぎり、READY状態のメッセージのみがデキューされます。
correlation

相関識別子は、Oracle Database Advanced Queuingでは解釈されない、アプリケーション定義の識別子です。
deq_condition

デキュー条件は、メッセージ・プロパティ、メッセージ・データ・プロパティおよびPL/SQLファンクションに基づいた式です。deq_conditionはSQL問合せのWHERE句と同様の構文を使用して、ブール式で指定されます。このブール式には、メッセージ・プロパティ、ユーザー・データのプロパティ(オブジェクト・ペイロードのみ)、およびPL/SQLファンクションまたはSQLファンクション(SQL問合せのWHERE句で指定)に関する条件を組み込むことができます。メッセージ・プロパティには、priority、corridおよびキュー表におけるその他の列が含まれます。

メッセージ・ペイロード(オブジェクト・ペイロード)のデキュー条件を指定するには、句にオブジェクト・タイプの属性を使用します。ペイロードが格納されたキュー・テーブルの特定の列を指定するには、各属性の前に修飾子としてtab.user_dataを追加する必要があります。

例: tab.user_data.orderstatus='EXPRESS'

デキュー順序は、dequeue_optionsのmsgidと相関IDで上書きされないかぎり、キュー表の作成時に指定した値によって判断されます。

キュー操作には、データベース読込み一貫性メカニズムが適用されます。たとえば、トランザクションによる参照が始まってからエンキューされたメッセージを、BROWSEコールでは参照できません。

デキュー時のデフォルトのNAVIGATIONパラメータは、NEXT_MESSAGEです。この場合、後続のデキューは、最初のデキューで取得したスナップショットに基づいて、キューからメッセージを取り出します。特に、最初のデキュー・コマンド後にエンキューされたメッセージは、キュー内の残りのメッセージがすべて処理されるまで処理されません。これは、すべてのメッセージがすでにキューにエンキューされている場合、またはキューに優先順位が設定されていない場合は、通常問題ありません。ただし、デキュー・コマンドのたびにキュー内の先頭メッセージを処理する必要がある場合は、アプリケーションでFIRST_MESSAGEナビゲーション・オプションを使用する必要があります。この処理は、すでにエンキューされたメッセージの処理中に優先順位の高いメッセージがキューに登録された場合に必要になります。

ノート:

同時にエンキューされている複数のメッセージがある場合は、FIRST_MESSAGEナビゲーション・オプションを使用すると効率が向上します。FIRST_MESSAGEオプションを指定しないと、Oracle Databaseアドバンスト・キューイングでは最初のデキュー・コマンドと同様のスナップショットが継続的に生成されるため、パフォーマンスの低下につながります。FIRST_MESSAGEオプションを指定すると、Oracle Database Advanced Queuingでは、すべてのデキュー・コマンドに新規のスナップショットが使用されます。

同一トランザクションでメッセージのグループ化に対応しているキューにエンキューされたメッセージは、グループを形成します。そのトランザクションでエンキューされたメッセージが1つのみの場合は、実質的に1つのメッセージでグループを形成します。1つのトランザクションでグループ化できるメッセージの数に、上限はありません。

メッセージをグループ化できないキューでは、LOCKEDまたはREMOVEモードのデキューによって1つのメッセージのみがロックされます。これに対して、グループの一部のメッセージをデキューしようとするデキュー操作は、グループ全体をロックします。これは、グループ内のすべてのメッセージを基本単位で処理する必要がある場合に有効です。

グループ内のすべてのメッセージがデキューされている場合、そのデキューはグループ内のすべてのメッセージが処理済であることを示すエラーを戻します。この場合、アプリケーションはNEXT_TRANSACTIONを使用して、次に使用可能なグループからメッセージのデキューを開始します。使用可能なグループがない場合、デキューは指定したWAIT期間後にタイムアウトします。

保護キューの使用方法

保護キューの場合は、dequeue_optionsパラメータにconsumer_nameを指定する必要があります。consumer_nameの詳細は、「DEQUEUE_OPTIONS_Tタイプ」を参照してください。

保護キューを使用する場合の要件は、次のとおりです。

DBMS_AQADM.CREATE_AQ_AGENTを使用して、有効なOracle Database Advanced Queuingエージェントを作成済である必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
Oracle Databaseアドバンスト・キューイング・エージェントを、セキュアなキューに対するデキュー権限を持つデータベース・ユーザーにマッピングする必要があります。これには、DBMS_AQADM.ENABLE_DB_ACCESSを使用します。「ENABLE_DB_ACCESSプロシージャ」を参照してください。

参照:

保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。

21.5.3 DEQUEUE_ARRAYファンクション

このファンクションはメッセージの配列をデキューし、ペイロードの配列、メッセージ・プロパティの配列およびメッセージIDの配列の形式でそれらを戻します。このファンクションは、正常にデキューされたメッセージの数を返します。

構文

DBMS_AQ.DEQUEUE_ARRAY (
   queue_name                IN   VARCHAR2,
   dequeue_options           IN   dequeue_options_t,
   array_size                IN   pls_integer,
   message_properties_array  OUT  message_properties_array_t,
   payload_array             OUT  "<COLLECTION_1>",
   msgid_array               OUT  msgid_array_t,
   error_array               OUT  error_array_t)
RETURN pls_integer;

パラメータ

表21-8 DEQUEUE_ARRAYファンクションのパラメータ

パラメータ	説明
`queue_name`	メッセージをデキューするキュー名(単一行デキューと同じ)。
`dequeue_options`	配列内のすべてのメッセージに適用する一連のオプション(単一行デキューと同じ)。
`array_size`	デキューする要素の数。バッファに入れたメッセージの場合、`array_size`は`1`にする必要があります。
`message_properties_array`	各メッセージ・プロパティに対応する配列を格納するレコード。各ペイロード要素は、対応する一連のメッセージ・プロパティを持ちます。「MESSAGE_PROPERTIES_ARRAY_Tタイプ」を参照してください。
`payload_array`	デキューされたペイロード・データの配列。"<COLLECTION_1>"は連想配列、VARRAYまたはPL/SQL表現でのネストした表です。ユーザーは、`RAW`および`ADT`ペイロードをデキューできます。
`msgid_array`	デキューされたメッセージのメッセージIDの配列。「MSGID_ARRAY_Tタイプ」を参照してください。
`error_array`	現在、実装されていません。

使用上のノート

dequeue_optionsに指定する0(ゼロ)以外の待機時間は、キュー内にメッセージがない場合にのみ認識されます。キューにデキュー可能なメッセージが格納されている場合、DEQUEUE_ARRAYファンクションによって、最大array_sizeメッセージがデキューされ、ただちに戻ります。

message_idによるデキューはサポートしていません。navigationパラメータの詳細は、「DEQUEUEプロシージャ」を参照してください。既存のNAVIGATIONモードをサポートしています。さらに、メッセージのグループ化に対応しているキュー用に、2つの新しいNAVIGATIONモードをサポートしています。

FIRST_MESSAGE_MULTI_GROUP
NEXT_MESSAGE_MULTI_GROUP

参照:

ENQUEUE_OPTIONS_Tタイプ

トランザクション・グループ・キューおよびONE_GROUPナビゲーションの場合、メッセージはarray_size制限に従って、単一のトランザクション・グループからのみデキューされます。MULTI_GROUPナビゲーションでは、メッセージはarray_size制限に従って、複数のトランザクション・グループからデキューされます。ORA-25235が返され、トランザクション・グループの終わりを示します。

DEQUEUE_ARRAYは、バッファに入れたメッセージではサポートされませんが、1つのメッセージにarray_sizeを設定すると、バッファに入れた個々のメッセージで使用できます。

21.5.4 ENQUEUEプロシージャ

このプロシージャは、指定したキューにメッセージを追加します。

構文

DBMS_AQ.ENQUEUE (
   queue_name          IN      VARCHAR2,
   enqueue_options     IN      enqueue_options_t,
   message_properties  IN      message_properties_t,
   payload             IN       "<ADT_1>",
   msgid               OUT     RAW);

パラメータ

表21-9 ENQUEUEプロシージャのパラメータ

パラメータ	説明
`queue_name`	このメッセージをエンキューするキュー名を指定します。例外キューは指定できません。
`enqueue_options`	「ENQUEUE_OPTIONS_Tタイプ」を参照してください。
`message_properties`	「MESSAGE_PROPERTIES_Tタイプ」を参照してください。
`payload`	Oracle Databaseアドバンスト・キューイングでは解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。`NULL`は受け入れ可能なパラメータの1つです。`type_name`の定義については、「DBMS_AQのデータ・タイプ」の`TYPE_NAME`を参照してください。
`msgid`	システムが生成するメッセージID。これは、デキュー時にメッセージを識別するために使用するグローバルな一意のIDです。

使用上のノート

enqueue_optionsのsequence_deviationパラメータを使用すると、2つのメッセージ間の処理順序を変更できます。参照されるメッセージのIDは、enqueue_optionsのパラメータrelative_msgidで指定できます。関係は、sequence_deviationパラメータによって識別されます。

メッセージにsequence_deviationを指定すると、そのメッセージに指定できる遅延および優先順位の値が制限されます。遅延の値は、このメッセージより後にエンキューされるメッセージの遅延以下に設定する必要があります。優先順位は、このメッセージより後にエンキューされるメッセージの優先順位以上に設定する必要があります。

ノート:

メッセージが受信者のいないマルチ・コンシューマ・キューにエンキューされ、かつそのキューにサブスクライバが存在しない(またはこのメッセージと一致するルールベースのサブスクライバが存在しない)場合は、OracleエラーORA_24033が発生します。これは、配信可能な受信者またはサブスクライバが存在しないために、そのメッセージが廃棄されることを示す警告です。

保護キューの使用方法

保護キューの場合は、messages_propertiesパラメータにsender_idを指定する必要があります。sender_idの詳細は、「MESSAGE_PROPERTIES_Tタイプ」を参照してください。

保護キューを使用する場合の要件は、次のとおりです。

DBMS_AQADM.CREATE_AQ_AGENTを使用して、有効なOracle Database Advanced Queuingエージェントを作成済である必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
sender_idを、保護キューに対してエンキュー権限があるデータベース・ユーザーにマップします。これには、DBMS_AQADM.ENABLE_DB_ACCESSを使用します。「ENABLE_DB_ACCESSプロシージャ」を参照してください。

参照:

保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。

21.5.5 ENQUEUE_ARRAYファンクション

このファンクションは、対応するメッセージ・プロパティの配列を使用して、ペイロードの配列をエンキューします。出力は、エンキューしたメッセージのメッセージIDの配列になります。

構文

DBMS_AQ.ENQUEUE_ARRAY (
   queue_name                IN   VARCHAR2,
   enqueue_options           IN   enqueue_options_t,
   array_size                IN   pls_integer,
   message_properties_array  IN   message_properties_array_t,
   payload_array             IN   "<COLLECTION_1>",
   msgid_array               OUT  msgid_array_t,
   error_array               OUT  error_array_t)
RETURN pls_integer;

パラメータ

表21-10 ENQUEUE_ARRAYファンクションのパラメータ

パラメータ	説明
`queue_name`	メッセージをエンキューするキュー名(単一行エンキューと同じ)。
`enqueue_options`	「ENQUEUE_OPTIONS_Tタイプ」を参照してください。
`array_size`	エンキューする要素の数。バッファに入れたメッセージの場合、`array_size`は`1`にする必要があります。
`message_properties_array`	各メッセージ・プロパティに対応する配列を格納するレコード。プロパティごとに`array_size`要素を割り当てる必要があります。「MESSAGE_PROPERTIES_ARRAY_Tタイプ」を参照してください。
`payload_array`	ペイロード・データの配列。"<`COLLECTION_1`>"は連想配列、`VARRAY`またはPL/SQL表現でのネストした表です。ユーザーは、RAWおよびADTペイロードをエンキューできます。
`msgid_array`	エンキューされたメッセージのメッセージIDの配列。特定のメッセージでエラーが発生すると、対応するメッセージIDがNULLになります。「MSGID_ARRAY_Tタイプ」を参照してください。
`error_array`	現在、実装されていません。

使用上のノート

ENQUEUE_ARRAYは、バッファに入れたメッセージではサポートされませんが、1つのメッセージにarray_sizeを設定すると、バッファに入れた個々のメッセージで使用できます。

21.5.6 LISTENプロシージャ

このプロシージャは、エージェントのリストのかわりに1つ以上のキューをリスニングします。エージェントのアドレス・フィールドは、エージェントが監視するキューを示します。アドレスでサポートされているのは、ローカル・キューのみです。プロトコルは、将来の使用に備えて確保されています。

構文

DBMS_AQ.LISTEN (
   agent_list            IN    AQ$_AGENT_LIST_T,
   wait                  IN    BINARY_INTEGER DEFAULT DBMS_AQ.FOREVER, 
   agent                 OUT   SYS.AQ$_AGENT);

DBMS_AQ.LISTEN (
   agent_list             IN   AQ$_AGENT_LIST_T,
   wait                   IN   BINARY_INTEGER DEFAULT FOREVER, 
   listen_delivery_mode   IN   PLS_INTEGER DEFAULT DBMS_AQ.PERSISTENT,
   agent                  OUT  SYS.AQ$_AGENT,
   message_delivery_mode  OUT  PLS_INTEGER);

TYPE aq$_agent_list_t IS TABLE of aq$_agent INDEXED BY BINARY_INTEGER;
TYPE aq$_agent_list_t IS TABLE of aq$_agent INDEXED BY BINARY_INTEGER;

パラメータ

表21-11 LISTENプロシージャのパラメータ

パラメータ	説明
`agent_list`	リスニングするエージェントのリスト。
`wait`	リスニング・コールのタイムアウト(秒数)。デフォルトでは、コールは永続的にブロックします。
`listen_delivery_mode`	永続メッセージ、バッファに入れたメッセージまたは両方のタイプのメッセージのいずれを優先するかをコール元が指定します。`DBMS_AQ.PERSISTENT`、`DBMS_AQ.BUFFERED`または`DBMS_AQ.PERSISTENT_OR_BUFFERED`の配信モードを指定します。
`agent`	コンシューマ用のメッセージがあるエージェント。
`message_delivery_mode`	メッセージがあるキューおよびコンシューマとともにメッセージ・タイプを戻します。

使用上のノート

エージェント・アドレスがマルチ・コンシューマ・キューである場合、エージェント名は必須項目です。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。

このプロシージャは、引数としてエージェントのリストを使用します。監視対象のキューは、リストされている各エージェントのアドレス・フィールドで指定されます。また、マルチコンシューマ・キューを監視する場合は、エージェント名も指定する必要があります。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。アドレスでサポートされているのは、ローカル・キューのみです。プロトコルは、将来の使用に備えて確保されています。

これは、リスト内のエージェントについて消費可能なメッセージがあるときに返されるブロック化コールです。複数のエージェントに対するメッセージがある場合、リストされている最初のエージェントのみが返されます。待機時間が経過したときにメッセージがない場合は、エラーが発生します。

LISTENコールが正常に戻された場合でも、指定したキューの中に、リストされたエージェントの1つに対するメッセージがあることのみを示しています。対象となっているエージェントは、関連メッセージを継続してデキューする必要があります。

ノート:

非永続キューでは、LISTENはコールできません。

21.5.7 POSTプロシージャ

このプロシージャにより、匿名サブスクリプションのリストに転送します。匿名サブスクリプションの場合、サブスクリプションに登録された全クライアントが通知を受信できます。

構文

DBMS_AQ.POST (
  post_list       IN  SYS.AQ$_POST_INFO_LIST,
  post_count      IN  NUMBER);

パラメータ

表21-12 POSTプロシージャのパラメータ

パラメータ	説明
`post_list`	転送する匿名サブスクリプションのリストを指定します。AQ$_POST_INFO_LISTタイプのリストです。
`post_count`	`post_list`のエントリ数を指定します。

使用上のノート

このプロシージャにより、匿名サブスクリプションに転送しますが、匿名サブスクリプションでは、サブスクリプションに登録された全クライアントが通知を受信できます。一度に、複数のサブスクリプションを転送できます。

21.5.8 REGISTERプロシージャ

このプロシージャでは、メッセージ通知に使用する電子メール・アドレス、ユーザー定義PL/SQLプロシージャまたはHTTP URLを登録します。

構文

DBMS_AQ.REGISTER (
   reg_list     IN  SYS.AQ$_REG_INFO_LIST,
   count        IN  NUMBER);

パラメータ

表21-13 REGISTERプロシージャのパラメータ

パラメータ	説明
`reg_list`	メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。
`count`	`reg_list`のエントリ数を指定します。

使用上のノート

このプロシージャは、通知の登録に使用します。メッセージ通知の送信先電子メール・アドレスの指定、通知時に起動するプロシージャの登録または通知転送先のHTTP URLの登録ができます。一度に、複数のサブスクリプションを登録できます。
プロシージャは、次に示す5つのグループ化属性を使用して、グループ化通知を登録する場合にも使用できます。
- Class: グループ化の基準(現在、TIME基準のみサポート)
- Value: グループ化の基準値(現在、TIME基準の時間(秒)のみ)
- Type: 要約または最新の通知で、グループで受信した通知の数も含みます(AQネームスペースに対してのみ。DBCHANGEネームスペースは対象外)
- Repeat count: グループ化を実行する回数(デフォルトはFOREVER)
- Start time: グループ化を開始する時間(デフォルトは現在の時間)
電子メール通知を登録する場合、データベースが電子メール通知の送信に使用するSMTPサーバーのホスト名およびポート名を設定する必要があります。必要な場合は、データベースのsent fromフィールドを使用して、発信元の電子メール・アドレスを設定してください。この機能を使用するには、Java対応のデータベースが必要です。
HTTP通知を登録する場合、データベースがHTTP通知の転送に使用するプロキシ・サーバーおよび非プロキシ・ドメイン・リストのホスト名およびポート名を設定する必要があります。

参照:

電子メールとHTTP通知の詳細は、「DBMS_AQELM」を参照してください。

21.5.9 UNBIND_AGENTプロシージャ

このプロシージャでは、LDAPサーバーからOracle Database Advanced Queuingエージェントのエントリを削除します。

構文

DBMS_AQ.UNBIND_AGENT(
   agent    IN SYS.AQ$_AGENT);

パラメータ

表21-14 BIND_AGENTプロシージャのパラメータ

パラメータ	説明
`agent`	LDAPサーバーから削除されるエージェント

21.5.10 UNREGISTERプロシージャ

このプロシージャでは、通知をオフにするサブスクリプションを登録解除します。

構文

DBMS_AQ.UNREGISTER (
   reg_list     IN  SYS.AQ$_REG_INFO_LIST,
   reg_count    IN  NUMBER);

パラメータ

表21-15 UNREGISTERプロシージャのパラメータ

パラメータ	説明
`reg_list`	メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。
`reg_count`	`reg_list`のエントリ数を指定します。

使用上のノート

このプロシージャにより、通知をオフにするサブスクリプションを登録解除します。複数のサブスクリプションを一度に登録解除することもできます。