| Oracle® Database PL/SQLパッケージおよびタイプ・リファレンス 11g リリース2(11.2) B56262-06 |
|
 前 |
 次 |
DBMS_AQパッケージは、Oracle Streams Advanced Queuing(AQ)へのインタフェースを提供します。
|
関連項目:
|
この章では、次の項目について説明します。
定数
データ構造
使用上の注意
DBMS_AQパッケージでは、表22-1に示す定数が使用されます。
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)では、順序逸脱機能の使用は推奨されていません。 |
表22-1 列挙定数
| パラメータ | オプション | タイプ | 説明 |
|---|---|---|---|
|
|
|
||
|
. |
|
||
|
|
|
||
|
. |
|
||
|
. |
|
||
|
. |
|
||
|
|
|
||
|
. |
|
||
|
|
|
||
|
. |
|
||
|
. |
|
||
|
. |
|
||
|
|
|
||
|
. |
|
||
|
|
|
|
|
|
. |
|
|
|
|
|
|
||
|
|
|
||
|
|
|
||
|
. |
|
||
|
|
|
|
|
|
|
|
|
|
|
. |
|
|
|
|
|
|
|
表22-2 DBMS_AQのデータ構造
| データ構造 | 説明 |
|---|---|
|
|
データベース・オブジェクトに名前を付けます。 |
|
|
キュー・タイプを定義します。 |
|
Oracle Streams AQ PL/SQLコールバック |
メッセージ通知時に起動されるようにデータベースに定義することで、ユーザー定義のPL/SQLプロシージャを指定します。 |
object_nameデータ構造は、データベース・オブジェクトの名前を付けます。この構造は、キュー、キュー表、エージェント名およびオブジェクト・タイプに適用されます。
構文
object_name := VARCHAR2; object_name := [schema_name.]name;
使用上の注意
オブジェクト名は、オプションのスキーマ名および名前で指定します。スキーマ名が指定されない場合は、現在のスキーマ名が使用されます。名前は、予約語について、『Oracle Database SQL言語リファレンス』のオブジェクト名ガイドラインに従う必要があります。スキーマ、エージェントおよびオブジェクト・タイプの名前は、30バイト以内で設定します。キューおよびキュー表の名前は、24バイト以内で設定します。
type_nameデータ構造は、キュー・タイプを定義します。
構文
type_name := VARCHAR2;
type_name := object_type | "RAW";
属性
表22-3 タイプ名の属性
| 属性 | 説明 |
|---|---|
|
|
オブジェクト・タイプ内の属性の最大数は900です。 |
|
|
|
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);
属性
表22-4 Oracle Streams AQ PL/SQLコールバックの属性
| 属性 | 説明 |
|---|---|
|
|
|
|
|
「AQ$_REG_INFOタイプ」を参照してください。 |
|
|
「AQ$_DESCRIPTORタイプ」を参照してください。 |
|
|
RAWペイロード・エンキューの通知メッセージが要求されている場合、非永続キューにエンキューされたRAWペイロードが含まれます。RAWペイロードが含まれる永続キューの場合、パラメータはNULLです。 |
|
|
|
ユーザー定義タイプのペイロード・エンキューの通知メッセージが要求されている場合、PL/SQLコールバックには次の署名が付加されている必要があります。
procedure plsqlcallback( context IN RAW, reginfo IN SYS.AQ$_REG_INFO, descr IN SYS.AQ$_DESCRIPTOR, payload IN VARCHAR2, payloadl IN NUMBER);
表22-5 DBMS_AQパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
|
LDAPディレクトリにOracle Streams AQエージェントのエントリを作成します。 |
|
|
指定したキューからメッセージをデキューします。 |
|
|
指定したキューからメッセージの配列をデキューします。 |
|
|
指定したキューにメッセージを追加します。 |
|
|
指定したキューにメッセージの配列を追加します。 |
|
|
エージェントのリストにかわって1つ以上のキューをリスニングします。 |
|
|
匿名サブスクリプションに転送します。サブスクリプションに登録された全クライアントが通知を受信できます。 |
|
|
メッセージ通知を登録します。 |
|
|
LDAPディレクトリからOracle Streams AQエージェントのエントリを削除します。 |
|
|
通知をオフにするサブスクリプションを登録解除します。 |
|
注意: DBMS_AQには、純正レベルが定義されていません。したがって、RNDS、WNDS、RNPSまたはWNPS制約が定義されている他のプロシージャからこのパッケージ内のプロシージャをコールできません。 |
このプロシージャは、指定したキューからメッセージをデキューします。
構文
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);
パラメータ
表22-7 DEQUEUEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
キュー名を指定します。 |
|
|
「DEQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
|
「MESSAGE_PROPERTIES_Tタイプ」を参照してください。 |
|
|
Oracle Streams AQによって解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。 |
|
|
システムが生成するメッセージID。 |
使用上の注意
デキューされるメッセージの検索基準は、dequeue_optionsの次のパラメータによって判断されます。
consumer_name
msgid
msgidはデキューされるメッセージを一意に識別します。msgidが指定されていないかぎり、READY状態のメッセージのみがデキューされます。
correlation
相関識別子は、Oracle Streams AQによって解釈されないアプリケーション定義の識別子です。
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 Streams AQは最初のデキュー・コマンド時のスナップショットを生成し続けるため、パフォーマンスが低下します。FIRST_MESSAGEオプションが指定されている場合、Oracle Streams AQはすべてのデキュー・コマンドに対して新しいスナップショットを使用します。 |
同一トランザクションでメッセージのグループ化に対応しているキューにエンキューされたメッセージは、グループを形成します。そのトランザクションでエンキューされたメッセージが1つのみの場合は、実質的に1つのメッセージでグループを形成します。1つのトランザクションでグループ化できるメッセージの数に上限はありません。
メッセージのグループ化に対応していないキューでは、LOCKEDまたはREMOVEモードのデキューは、1つのメッセージのみロックします。これに対して、グループの一部のメッセージをデキューしようとするデキュー操作は、グループ全体をロックします。これは、グループ内のすべてのメッセージを基本単位で処理する必要がある場合に有効です。
グループ内のすべてのメッセージがデキューされている場合、そのデキューはグループ内のすべてのメッセージが処理済であることを示すエラーを戻します。この場合、アプリケーションはNEXT_TRANSACTIONを使用して、次に使用可能なグループからメッセージのデキューを開始します。使用可能なグループがない場合、デキューは指定したWAIT期間後にタイムアウトします。
保護キューの使用方法
保護キューの場合は、dequeue_optionsパラメータにconsumer_nameを指定する必要があります。consumer_nameの詳細は、「DEQUEUE_OPTIONS_Tタイプ」を参照してください。
保護キューを使用するときは、次の事項を満たしている必要があります。
DBMS_AQADM.CREATE_AQ_AGENTを使用して、有効なOracle Streams AQエージェントを作成している必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
保護キューに対するデキュー権限のあるデータベース・ユーザーにOracle Streams AQエージェントをマップする必要があります。これは、DBMS_AQADM.ENABLE_DB_ACCESSを使用して行います。「ENABLE_DB_ACCESSプロシージャ」を参照してください。
|
関連項目: 保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。 |
このファンクションはメッセージの配列をデキューし、ペイロードの配列、メッセージ・プロパティの配列およびメッセージ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;
パラメータ
表22-8 DEQUEUE_ARRAYファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージをデキューするキュー名(単一行デキューと同じ)。 |
|
|
配列内のすべてのメッセージに適用する一連のオプション(単一行デキューと同じ)。 |
|
|
デキューする要素の数。 |
|
|
各メッセージ・プロパティに対応する配列を格納するレコード。各ペイロード要素は、対応する一連のメッセージ・プロパティを持ちます。「MESSAGE_PROPERTIES_ARRAY_Tタイプ」を参照してください。 |
|
|
デキューされたペイロード・データの配列。"<COLLECTION_1>"は連想配列、VARRAYまたはPL/SQL表現でのネストした表です。 |
|
|
デキューされたメッセージのメッセージIDの配列。「MSGID_ARRAY_Tタイプ」を参照してください。 |
|
|
現在、実装されていません。 |
使用上の注意
dequeue_optionsに指定する0(ゼロ)以外の待機時間は、キュー内にメッセージがない場合にのみ認識されます。キューにデキュー可能なメッセージが格納されている場合、DEQUEUE_ARRAYファンクションによって、最大array_sizeメッセージがデキューされ、ただちに戻ります。
message_idによるデキューはサポートしていません。navigationパラメータの詳細は、「DEQUEUEプロシージャ」を参照してください。既存のNAVIGATIONモードをサポートしています。さらに、メッセージのグループ化に対応しているキュー用に、2つの新しいNAVIGATIONモードをサポートしています。
FIRST_MESSAGE_MULTI_GROUP
NEXT_MESSAGE_MULTI_GROUP
トランザクション・グループ・キューおよびONE_GROUPナビゲーションの場合、メッセージはarray_size制限に従って、単一のトランザクション・グループからのみデキューされます。MULTI_GROUPナビゲーションでは、メッセージはarray_size制限に従って、複数のトランザクション・グループからデキューされます。ORA-25235が返され、トランザクション・グループの終わりを示します。
DEQUEUE_ARRAYは、バッファに入れたメッセージではサポートされませんが、1つのメッセージにarray_sizeを設定すると、バッファに入れた個々のメッセージで使用できます。
このプロシージャは、指定したキューにメッセージを追加します。
構文
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);
パラメータ
表22-9 ENQUEUEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このメッセージをエンキューするキュー名を指定します。例外キューは指定できません。 |
|
|
「ENQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
|
「MESSAGE_PROPERTIES_Tタイプ」を参照してください。 |
|
|
Oracle Streams AQによって解釈されません。ペイロードは、関連するキュー表の仕様に基づいて指定する必要があります。 |
|
|
システムが生成するメッセージID。これは、デキュー時にメッセージを識別するために使用するグローバルな一意のIDです。 |
使用上の注意
enqueue_optionsのsequence_deviationパラメータを使用すると、2つのメッセージ間の処理順序を変更できます。参照されるメッセージのIDは、enqueue_optionsのパラメータrelative_msgidで指定できます。関係は、sequence_deviationパラメータによって識別されます。
メッセージにsequence_deviationを指定すると、このメッセージに指定できる遅延および優先の順位値が一部制限されます。遅延の値は、このメッセージより後にエンキューされるメッセージの遅延以下に設定する必要があります。優先順位は、このメッセージより後にエンキューされるメッセージの優先順位以上に設定する必要があります。
|
注意: DBMS_AQADMサブプログラムのmessage_groupingパラメータをTRANSACTIONALに設定すると、sequence_deviation属性は、Oracle Streams AQ 10g リリース1(10.1)以前のリリースでは無効になります。Oracle Streams AQ 10g リリース2(10.2)では、順序逸脱機能の使用は推奨されていません。 |
メッセージが受信者のいないマルチ・コンシューマ・キューにエンキューされ、かつそのキューにサブスクライバが存在しない(またはこのメッセージと一致するルールベースのサブスクライバが存在しない)場合は、OracleエラーORA_24033が発生します。これは、配信可能な受信者またはサブスクライバが存在しないために、そのメッセージが廃棄されることを示す警告です。
保護キューの使用方法
保護キューの場合は、messages_propertiesパラメータにsender_idを指定する必要があります。sender_idの詳細は、「MESSAGE_PROPERTIES_Tタイプ」を参照してください。
保護キューを使用するときは、次の事項を満たしている必要があります。
DBMS_AQADM.CREATE_AQ_AGENTを使用して、有効なOracle Streams AQエージェントを作成している必要があります。「CREATE_AQ_AGENTプロシージャ」を参照してください。
保護キューに対するエンキュー権限のあるデータベース・ユーザーにsender_idをマップする必要があります。これは、DBMS_AQADM.ENABLE_DB_ACCESSを使用して行います。「ENABLE_DB_ACCESSプロシージャ」を参照してください。
|
関連項目: 保護キューの詳細は、『Oracle Streams概要および管理』を参照してください。 |
このファンクションは、対応するメッセージ・プロパティの配列を使用して、ペイロードの配列をエンキューします。出力は、エンキューしたメッセージのメッセージ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;
パラメータ
表22-10 ENQUEUE_ARRAYファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージをエンキューするキュー名(単一行エンキューと同じ)。 |
|
|
「ENQUEUE_OPTIONS_Tタイプ」を参照してください。 |
|
|
エンキューする要素の数。 |
|
|
各メッセージ・プロパティに対応する配列を格納するレコード。プロパティごとに |
|
|
ペイロード・データの配列。"< |
|
|
エンキューされたメッセージのメッセージIDの配列。特定のメッセージでエラーが発生すると、対応するメッセージIDがNULLになります。「MSGID_ARRAY_Tタイプ」を参照してください。 |
|
|
現在、実装されていません。 |
このプロシージャは、エージェントのリストのかわりに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;
パラメータ
表22-11 LISTENプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
リスニングするエージェントのリスト。 |
|
|
リスニング・コールのタイムアウト(秒数)。デフォルトでは、コールは永続的にブロックします。 |
|
|
永続メッセージ、バッファに入れたメッセージまたは両方のタイプのメッセージのいずれを優先するかをコール元が指定します。 |
|
|
コンシューマ用のメッセージがあるエージェント。 |
|
|
メッセージがあるキューおよびコンシューマとともにメッセージ・タイプを戻します。 |
使用上の注意
エージェント・アドレスがマルチ・コンシューマ・キューである場合、エージェント名は必須項目です。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。
このプロシージャは、引数としてエージェントのリストを使用します。リストされた各エージェントのアドレス・フィールドに、監視するキューを指定します。マルチ・コンシューマ・キューを監視するときは、エージェントの名前も指定する必要があります。単一コンシューマ・キューの場合は、エージェント名を指定する必要はありません。ローカル・キューのみアドレスとしてサポートされています。将来使用するためにプロトコルが予約されています。
これは、リスト内のエージェントに対してコンシューマ用のメッセージが準備されているときに戻されるブロック・コールです。複数のエージェントに対するメッセージがある場合は、リストの最初のエージェントのみ戻されます。待機時間が期限切れしてもメッセージが見つからない場合は、エラーが発生します。
LISTENコールが正常に戻された場合でも、指定したキューの中に、リストされたエージェントの1つに対するメッセージがあることのみを示しています。対象となっているエージェントは、関連メッセージを継続してデキューする必要があります。
|
注意: 非永続キューでは、LISTENはコールできません。 |
このプロシージャにより、匿名サブスクリプションのリストに転送します。匿名サブスクリプションの場合、サブスクリプションに登録された全クライアントが通知を受信できます。
パラメータ
表22-12 POSTプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
転送する匿名サブスクリプションのリストを指定します。AQ$_POST_INFO_LISTタイプのリストです。 |
|
|
|
このプロシージャにより、電子メール・アドレス、ユーザー定義のPL/SQLプロシージャまたはメッセージ通知用のHTTP URLを登録します。
パラメータ
表22-13 REGISTERプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。 |
|
|
|
使用上の注意
このプロシージャは、通知の登録に使用します。メッセージ通知の送信先電子メール・アドレスの指定、通知時に起動するプロシージャの登録または通知転送先のHTTP URLの登録ができます。複数のサブスクリプションを一度に登録することもできます。
プロシージャは、次に示す5つのグループ化属性を使用して、グループ化通知を登録する場合にも使用できます。
Class: グループ化の基準(現在、TIME基準のみサポート)
Value: グループ化の基準値(現在、TIME基準の時間(秒)のみ)
Type: 要約または最新の通知で、グループで受信した通知の数も含みます(AQネームスペースに対してのみ。DBCHANGEネームスペースは対象外)
Repeat count: グループ化を実行する回数(デフォルトはFOREVER)
Start time: グループ化を開始する時間(デフォルトは現在の時間)
電子メール通知を登録する場合、データベースが電子メール通知の送信に使用するSMTPサーバーのホスト名およびポート名を設定する必要があります。必要な場合は、データベースのsent fromフィールドを使用して、発信元の電子メール・アドレスを設定してください。この機能を使用するには、Java対応のデータベースが必要です。
HTTP通知を登録する場合、データベースがHTTP通知の転送に使用するプロキシ・サーバーおよび非プロキシ・ドメイン・リストのホスト名およびポート名を設定する必要があります。
このプロシージャでは、通知をオフにするサブスクリプションを登録解除します。
パラメータ
表22-15 UNREGISTERプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
メッセージ通知用に登録するサブスクリプションのリストを指定します。AQ$_REG_INFOタイプのリストです。 |
|
|
|
