Register Subscriber メッセージ

Register Subscriber コマンド・メッセージは、 サブスクライバーまたはサブスクライバーの代わりの別のアプリケーションからブローカーに送信され、 サブスクリプション・ポイントで 1 つ以上のトピックをサブスクライブしたいことを示します。メッセージ内容フィルターも指定できます。

パブリッシュ/サブスクライブ・フィルター式では、括弧をネスティングすると、パフォーマンスが大きく低下します。実際には、括弧を 7 以上の深さにネスティングしないようにしてください。

このメッセージは、ブローカーの制御キューである SYSTEM.BROKER.CONTROL.QUEUE に送信されます。 サブスクリプション内のトピックにアクセスする権限 (ブローカーのシステム管理者によって設定される) に加え、 このキューにメッセージを入れる権限も必要です。

トピックの全部ではなく一部だけに対する権限を持つユーザーの場合、権限の対象のものだけが登録されます。登録されないものを知らせる警告が出されます。

ブローカーにコマンド・メッセージを送信する時に必要なメッセージ記述子 (MQMD) パラメーターの詳細については、 ブローカー応答メッセージを参照してください。

キューが一時動的キューである場合、キューのクローズ時に、 サブスクリプションはブローカーによって自動的に登録解除されます。

プロパティー

<Command> (MQPSC_COMMAND)
値は、RegSub (MQPSC_REGISTER_SUBSCRIBER) です。 このプロパティーは、指定する必要があります。
<Topic> (MQPSC_TOPIC)
サブスクライバーが、パブリケーションを受け取るトピック。 トピックの一部としてワイルドカード文字を使用できます。

このプロパティーは必須で、 必要なトピックの数だけ任意に繰り返すことができます。

<SubPoint> (MQPSC_SUBSCRIPTION_POINT)
この値は、 サブスクリプションの接続先のサブスクリプション・ポイントです。

このプロパティーを省略すると、デフォルトのサブスクリプション・ポイントが使用されます。

<Filter> (MQPSC_FILTER)
値は、 パブリケーション・メッセージの内容に対するフィルターとして使用される SQL 式です。 指定したトピックのパブリケーションは、フィルターと一致すると、 サブスクライバーに送信されます。

このプロパティーを省略すると、内容のフィルター操作は行われません。

<RegOpt> (MQPSC_REGISTRATION_OPTION)
Registration Options プロパティーは、 以下の値をとることができます。
AddName  
(MQPSC_ADD_NAME)

この Register Subscription コマンドの従来の ID に一致するが現時点で SubName 値を持たない既存のサブスクリプションに対してこの値を指定した場合、 このコマンドで指定された SubName がサブスクリプションに追加されます。

AddName を指定した場合には SubName フィールドは必須であり、このフィールドに指定しないと MQRCCF_REG_OPTIONS_ERROR が戻されます。

CorrelAsId  
(MQPSC_CORREL_ID_AS_IDENTITY)

メッセージ記述子 (MQMD) の CorrelId を使用するのは、 一致するパブリケーションをサブスクライバー・キューに送信する場合です。CorrelId は、ゼロであってはなりません。

FullResp  
(MQPSC_FULL_RESPONSE)

この値を指定した場合に、コマンドが失敗しなければ、サブスクリプションのすべての属性が応答メッセージで戻されます。

FullResp が有効なのは、コマンド・メッセージが単一のサブスクリプションを参照する場合だけです。 したがって、このコマンドで使用できるトピックは 1 つだけです。 そうでないと、コマンドは戻りコード MQRCCF_REG_OPTIONS_ERROR で失敗します。

InformIfRet  
(MQPSC_INFORM_IF_RETAINED)

ブローカーは、 Register Subscriber または Request Update コマンド・メッセージへの応答として Publish メッセージを送信する時に、 パブリケーションが保存されているかどうかをサブスクライバーに通知します。 ブローカーは、IsRetainedPub パブリケーション・オプションをメッセージに組み込むことによってこれを実行します。

JoinExcl  
(MQPSC_JOIN_EXCLUSIVE)

このオプションでは、指定された SubIdentity を、サブスクリプションの ID セットの排他的メンバーとして追加することと、他の ID をセットに追加できないことを指示します。

その ID がすでに「共用」を結合されていて、しかもセット内の唯一のエントリーである場合、そのセットは、その ID によって保持される排他ロックに変わります。 それ以外の場合、ID セットの中にサブスクリプションの他の ID (共用アクセス権を持つ) が現在あると、コマンドは戻りコード MQRCCF_SUBSCRIPTION_IN_USE で失敗します。

JoinShared  
(MQPSC_JOIN_SHARED)

このオプションは、指定された SubIdentity を、サブスクリプションの ID セットに追加するよう指示します。

現在サブスクリプションが排他的にロックされている (JoinExcl オプションを使って) 場合には、サブスクリプションをロックしている ID がこのコマンド・メッセージのものと同じ ID でないかぎり、コマンドは戻りコード MQRCCF_SUBSCRIPTION_LOCKED で失敗します。 失敗した場合、ロックは自動的に共用ロックに変更されます。

Local  
(MQPSC_LOCAL)

サブスクリプションはローカルで、ネットワーク内の他のブローカーには配布されません。 他のブローカーで作成されたパブリケーションは、対応するグローバル・サブスクリプションがない限り、 このサブスクライバーには送達されません。

NewPubsOnly  
(MQPSC_NEW_PUBS_ONLY)

サブスクリプションの登録時に存在する保存パブリケーションは、サブスクライバーには送信されません。 新規パブリケーションのみが送信されます。

サブスクライバーがこのオプションを再登録して変更し、それ以上設定されないようにした場合、 すでにそのサブスクライバーに送信されたパブリケーションが再び送信されることがあります。

NoAlter  
(MQPSC_NO_ALTER)

一致する既存のサブスクリプションの属性は変更されません。

サブスクリプションが作成されるとき、このオプションは無視されます。指定されている他のオプションはすべて、その新規のサブスクリプションに適用されます。

SubIdentity で結合オプションのうちのいずれか (JoinExcl または JoinShared) も指定されていると、NoAlter が指定されているかどうかに関係なく、その ID

None  
(MQPSC_NONE)

すべての登録オプションがデフォルト値を取ります。

サブスクライバーがすでに登録済みである場合、そのオプションはデフォルト値にリセットされ (これは、「登録オプション」プロパティーを省略するのと同じ効果は生じない ことに注意)、Register Subscriber メッセージの MQMD からサブスクリプション有効期限が更新されます。

他の登録オプションが同時に指定された場合、None は無視されます。

NonPers  
(MQPSC_NON_PERSISTENT)

このサブスクリプションに一致するパブリケーションは、 非持続メッセージとしてサブスクライバーに送達されます。

Pers  
(MQPSC_PERSISTENT)

このサブスクリプションに一致するパブリケーションは、 持続メッセージとしてサブスクライバーに送達されます。

PersAsPub  
(MQPSC_PERSISTENT_AS_PUBLISH)

このサブスクリプションに一致するパブリケーションは、 パブリッシャーが指定する持続性でサブスクライバーに送達されます。 これがデフォルトの動作です。

PersAsQueue  
(MQPSC_PERSISTENT_AS_Q)

このサブスクリプションに一致するパブリケーションは、 サブスクライバー・キューが指定する持続性でサブスクライバーに送達されます。

PubOnReqOnly  
(MQPSC_PUB_ON_REQUEST_ONLY)

ブローカーは、Request Update コマンド・メッセージへの応答を除き、 サブスクライバーにパブリケーションを送信しません。

VariableUserId  
(MQPSC_VARIABLE_USER_ID)

指定された場合、サブスクライバー (キュー、キュー・マネージャー、および correlid) の ID は、単一のユーザー ID に制限されません。 これはブローカーのこれまでの振る舞いとは異なります。これまでの振る舞いでは、元の登録メッセージのユーザー ID がサブスクライバーの ID に関連付けられ、以後は他のユーザーはその ID を使用できなくなります。 よって、新規サブスクライバーが同じ ID の使用を試みると、 MQRCCF_DUPLICATE_SUBSCRIPTION が戻されます。

そのため、適切な権限があればどのユーザーでもサブスクリプションを変更または登録解除することができます。 したがって、そのユーザー ID が、元のサブスクライバーのユーザー ID に一致するかどうかを調べる必要はありません。

このオプションを既存のサブスクリプションに追加するには、コマンドが、元のサブスクリプションそのものと同じユーザー ID に由来するものでなければなりません。

Request Update コマンドのサブスクリプションに VariableUserId が設定されている場合、これを要求更新時に設定して、どのサブスクリプションを指しているかを示さなければなりません。設定されていない場合、Request Update コマンドのユーザー ID が使われて、サブスクリプションの ID が識別されます。サブスクリプション名を指定すれば、上記の設定は他のサブスクライバー ID と一緒にオーバーライドされます。

このオプションが設定されていない Register Subscriber コマンド・メッセージが、このオプションが設定されている既存のサブスクリプションを参照すると、そのサブスクリプションからこのオプションが除去されて、そのサブスクリプションのユーザー ID が修正されます。ID (queue、qmgr、および correlid) は同じであるが異なるユーザー ID が関連付けられているサブスクライバーがすでに存在する場合、 コマンドは戻りコード MQRCCF_DUPLICATE_IDENTITY で失敗します。 なぜなら、サブスクライバー ID に関連付けることのできるユーザー ID は 1 つだけだからです。

登録オプション・プロパティーを省略した場合に、サブスクライバーがすでに登録済みであると、登録オプションは変更されず、サブスクリプション有効期限は Register Subscriber メッセージの MQMD から更新されます。

サブスクライバーがまだ登録されていない場合、デフォルト値をとったうえで、すべての登録オプションを使って新しいサブスクリプションが作成されます。

デフォルト値は PersAsPub で、他のオプションは設定されません。

<QMgrName> (MQPSC_Q_MGR_NAME)
値は、 一致するパブリケーションがブローカーから送信される先のサブスクライバー・キューのキュー・マネージャー名です。

このプロパティーが省略されると、デフォルトは、 メッセージ記述子 (MQMD) の ReplyToQMgr 名になります。結果の名前がブランクである場合、デフォルトでブローカーの QMgrName になります。

<QName> (MQPSC_Q_NAME)
値は、 一致するパブリケーションがブローカーによって送信される先のサブスクライバー・キューの名前です。

このプロパティーが省略されると、デフォルトは、 メッセージ記述子 (MQMD) の ReplyToQ 名になりますが、 この場合ブランクにすることはできません。

キューが一時動的キューである場合、 パブリケーションの非持続送達 (NonPers) を、<RegOpt> プロパティーで指定する必要があります。

キューが一時動的キューである場合、キューのクローズ時に、 サブスクリプションはブローカーによって自動的に登録解除されます。

<SubName> (MQPSC_SUBSCRIPTION_NAME)
これは、特定のサブスクリプションに付ける名前です。 キュー・マネージャー、キュー、およびオプションの correlId の代わりにこれを使って、サブスクリプションを参照することができます。

この SubName の付いたサブスクリプションがすでに存在する場合、そのサブスクリプションの他のすべての属性 (Topic、QMgrName、QName、CorrelId、UserId、RegOpts、UserSubData、および Expiry) は、新規の Register Subscriber コマンド・メッセージで渡された属性 (指定した場合) でオーバーライドされます。ただし、QName フィールドを指定しないで、MQMD ヘッダーに ReplyToQ を指定して、SubName を使用した場合、サブスクライバー・キューは ReplyToQ に変更されます。

このコマンドの従来の ID に一致するサブスクリプションが存在しても、SubName を指定しない場合は、AddName オプションを指定しないかぎり、 Registration コマンドは戻りコード MQRCCF_DUPLICATE_SUBSCRIPTION で失敗します。

同じ SubName を指定する別の Register Subscriber コマンドを使って、 既存の名前付きサブスクリプションの更新を試みた場合に、 新規のコマンド内の Topic、QMgrName、QName、および CorrelId の値が、 SubName を定義されているかどうかに関係なく別の既存のサブスクリプションに一致すると、 コマンドは戻りコード MQRCCF_DUPLICATE_SUBSCRIPTION で失敗します。 これで、2 つのサブスクリプション名が同じサブスクリプションを指す事態は防がれます。

<SubIdentity> (MQPSC_SUBSCRIPTION_IDENTITY)
このストリングは、サブスクリプションと関係するアプリケーションを表すのに使用します。 これは、64 文字の最大長の可変長文字ストリングであって、オプションです。 ブローカーは、サブスクリプションごとに一連のサブスクライバー ID を保守しています。 どのサブスクリプションでも、その ID セット内で、単一の ID だけの保管または無制限の数の ID の保管を行うことができます (JoinShared および JoinExcl オプションを参照)。

JoinShared または JoinExcl オプションを指定する Subscribe コマンドは、 サブスクリプションの ID セットに SubIdentity を追加します。ただしそれは、その ID がセット中にまだなくて、既存の ID セットに対してそのようなアクションをとれる場合、 つまり、他のどのサブスクライバーもまだ排他的に結合していないか、あるいは ID セットが空の場合にかぎります。

SubIdentity が指定された Register Subscriber コマンドの処理結果としてサブスクリプションの属性が変更される場合、その処理は、この ID がそのサブスクリプションの ID セットの唯一のメンバーとなるときにのみ、正常に完了します。 そうでなければ、コマンドは戻りコード MQRCCF_SUBSCRIPTION_IN_USE で失敗します。 これで、関係する他のサブスクライバーが知らないうちにサブスクリプションの属性が変更されることはなくなります。

64 文字を超える文字ストリングを指定すると、コマンドは失敗し、戻りコード MQRCCF_SUB_IDENTITY_ERROR が出されます。

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
これは可変長のテキスト・ストリングです。 この値は、サブスクリプションと一緒にブローカーによって保管されますが、サブスクライバーへのパブリケーションの送達には影響を与えません。 この値を更新するには、別の値を使って同じサブスクリプションに再登録します。この属性は、アプリケーションで使用するためにあります。

SubUserData は、 サブスクリプションの Metatopic 情報 (MQCACF_REG_SUB_USER_DATA) があれば、 そこに戻されます。

複数の登録オプション値 NonPers、PersAsPub、 PersAsQueue、および Pers を指定すると、最後の値だけが使用されます。個々のサブスクリプション内でこれらのオプションを結合することはできません。

以下に、 Register Subscriber コマンド・メッセージの NameValueData の例を示します。 サンプル・アプリケーションでは、 結果サービスはこのメッセージを使用して、「要求したパブリッシュのみ」オプションを設定して、 すべての試合の最新のスコアを含むトピックのサブスクリプションを登録します。 サブスクライバーの ID は、CorrelId を含め、MQMD のデフォルトから取られます。
 <psc>
  <Command>RegSub</Command>
  <RegOpt>PubOnReqOnly</RegOpt>
  <RegOpt>CorrelAsId</RegOpt>
  <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>
特記事項 | 商標 | ダウンロード | ライブラリー | サポート | フィードバック
Copyright IBM Corporation 1999, 2006 最終更新: 08/21/2006
aq06990_