16 DBMS_AQ

DBMS_AQの使用方法

• 定数

• データ構造

• 使用上の注意

---

定数

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

属性

Oracle Streams AQ 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);

属性

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

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

---

使用上の注意

• DBMS_AQおよびDBMS_AQADM Javaクラス

DBMS_AQおよびDBMS_AQADM Javaクラス

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

DBMS_AQサブプログラムの要約

---

BIND_AGENTプロシージャ

このプロシージャによって、LDAPサーバーにOracle Streams AQエージェントのエントリを作成します。

構文

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

パラメータ

使用上の注意

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

---

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);

パラメータ

使用上の注意

デキューされるメッセージの検索基準は、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ナビゲーション・オプションを使用する必要があります。 この処理は、すでにエンキューされたメッセージの処理中に優先順位の高いメッセージがキューに登録された場合に必要になります。

同一トランザクションでメッセージのグループ化に対応しているキューにエンキューされたメッセージは、グループを形成します。 そのトランザクションでエンキューされたメッセージが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概要および管理』を参照してください。

  
  

---

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;

パラメータ

使用上の注意

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を設定すると、バッファに入れた個々のメッセージで使用できます。

---

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);

パラメータ

使用上の注意

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 Streams AQエージェントを作成している必要があります。 詳細は、「CREATE_AQ_AGENTプロシージャ」を参照してください。

• 保護キューに対するエンキュー権限のあるデータベース・ユーザーにsender_idをマップする必要があります。 これは、DBMS_AQADM.ENABLE_DB_ACCESSを使用して行います。 詳細は、「ENABLE_DB_ACCESSプロシージャ」を参照してください。

  
  

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

  
  

---

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;

パラメータ

使用上の注意

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

---

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;

パラメータ

使用上の注意

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

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

これは、リスト内のエージェントに対してコンシューマ用のメッセージが準備されているときに戻されるブロック・コールです。 複数のエージェントに対するメッセージがある場合は、リストの最初のエージェントのみ戻されます。 待機時間が期限切れしてもメッセージが見つからない場合は、エラーが発生します。

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

---

POSTプロシージャ

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

構文

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

パラメータ

使用上の注意

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

---

REGISTERプロシージャ

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

構文

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

パラメータ

使用上の注意

このプロシージャは、通知の登録に使用します。 メッセージ通知の送信先電子メール・アドレスの指定、通知時に起動するプロシージャの登録または通知転送先のHTTP URLの登録ができます。 複数のサブスクリプションを一度に登録することもできます。

電子メール通知を登録する場合、データベースが電子メール通知の送信に使用するSMTPサーバーのホスト名およびポート名を設定する必要があります。 必要であれば、発信元電子メール・アドレスを設定します。これは、データベースのsent fromフィールドで設定します。 この機能を使用するには、Java対応のデータベースが必要です。

HTTP通知を登録する場合、データベースがHTTP通知の転送に使用するプロキシ・サーバーおよび非プロキシ・ドメイン・リストのホスト名およびポート名を設定する必要があります。

---

UNBIND_AGENTプロシージャ

このプロシージャにより、LDAPサーバーからOracle Streams AQエージェントのエントリを削除します。

構文

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

パラメータ

---

UNREGISTERプロシージャ

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

構文

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

パラメータ

使用上の注意

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