Nachricht zum Abmelden als Subskribent

Die Befehlsnachricht zum Abmelden als Subskribent (DeregSub) wird von einem Subskribenten an einen Broker oder im Namen eines Subskribenten an eine andere Anwendung gesendet, um mitzuteilen, dass er keine weiteren Nachrichten zu den in den Parametern angegebenen Themen empfangen möchte.

Diese Nachricht wird an die Steuerwarteschlange des Brokers, SYSTEM.BROKER.CONTROL.QUEUE, gesendet. Der Benutzer muss über die erforderliche Berechtigung verfügen, eine Nachricht in diese Warteschlange zu stellen.

Ausführliche Informationen zu den Parametern des Nachrichtendeskriptors (MQMD), die zum Senden einer Befehlsnachricht an den Broker erforderlich sind, finden Sie unter MQMD-Einstellungen in Befehlsnachrichten an den Broker.

Eine Einzelsubskription kann beendet werden, indem das entsprechende Thema, der Subskriptionspunkt und Filterwerte der ursprünglichen Subskription angegeben werden. Falls einer dieser Werte in der ursprünglichen Subskription nicht angegeben wurde (d. h., es wurde der Standardwert verwendet), sollte er auch beim Beenden der Subskription nicht angegeben werden.

Alle Subskriptionen für einen Subskribenten oder eine Gruppe von Subskribenten können mit Hilfe der Option DeregAll beendet werden. Wenn beispielsweise DeregAll zusammen mit einem Subskriptionspunkt (aber ohne Thema oder Filter) angegeben wird, werden alle Subskriptionen für den Subskribenten auf dem angegebenen Subskriptionspunkt beendet (ohne Berücksichtigung von Thema und Filter). Jede Kombination von Thema, Filter und Subskriptionspunkt ist zulässig: Werden alle drei angegeben, gilt die Nachricht nur für eine bestimmte Subskription, und die Option DeregAll wird ignoriert.

Die Nachricht muss von dem Subskribenten gesendet werden, der die Subskription eingerichtet hat. Dies wird anhand der Benutzer-ID des Subskribenten überprüft.

Subskriptionen können auch von einem Systemadministrator beendet werden. Allerdings sind Subskriptionen, die mit einer temporären dynamischen Warteschlange eingerichtet werden, nicht einfach dem Warteschlangennamen zugeordnet, sondern der Warteschlange selbst. Wenn die Warteschlange gelöscht wird, entweder explizit oder dadurch, dass die Anwendung die Verbindung mit dem Warteschlangenmanager trennt, können Subskriptionen für diese Warteschlange nicht mehr mit dem Befehl zum Abmelden des Subskribenten beendet werden. Die Subskriptionen können über die Workbench beendet werden und werden dann automatisch vom Broker gelöscht, wenn er das nächste Mal eine Veröffentlichung mit der Subskription abgleicht oder wenn er das nächste Mal erneut gestartet wird. Unter normalen Umständen sollten Anwendungen ihre Subskriptionen beenden, bevor die Warteschlange gelöscht oder die Verbindung mit dem Warteschlangenmanager getrennt wird.

Wenn ein Subskribent eine Nachricht zum Beenden einer Subskription sendet und eine Antwortnachricht erhält, dass seine Nachricht erfolgreich verarbeitet wurde, werden möglicherweise noch einige Veröffentlichungen in die Warteschlange des Subskribenten gestellt. Dabei handelt es sich um Veröffentlichungen, die zur selben Zeit wie die Nachricht zum Beenden der Subskription vom Broker verarbeitet wurden. Falls die Nachrichten nicht aus der Warteschlange entfernt werden, stauen sich möglicherweise unverarbeitete Nachrichten in der Warteschlange des Subskribenten. Wenn die Anwendung nach dem Ende eines Ruhemodus eine Schleife ausführt, die einen MQGET-Aufruf mit der entsprechenden CorrelId (Korrelations-ID) enthält, werden diese Nachrichten aus der Warteschlange gelöscht. Bei Verwendung des SCADA-Geräteprotokolls gibt es eine Option zum Starten und Beenden eines Löschvorgangs. Das heißt, dass die Nachrichten automatisch für den Client gelöscht werden.

Die Warteschlange ist möglicherweise auch dann nicht leer, wenn der Subskribent eine permanente dynamische Warteschlange verwendet und diese mit der Option MQCO_DELETE_PURGE in einem MQCLOSE-Aufruf schließt. Falls Veröffentlichungen vom Broker noch nicht festgeschrieben sind, wenn die Warteschlange gelöscht wird, gibt der MQCLOSE-Aufruf den Rückkehrcode MQRC_Q_NOT_EMPTY zurück. Die Anwendung kann dieses Problem vermeiden, indem ein Ruhemodus eingelegt und der MQCLOSE-Aufruf nur von Zeit zu Zeit erneut ausgegeben wird.

Eigenschaften

<Command> (MQPSC_COMMAND)
Der Wert ist DeregSub (MQPSC_DEREGISTER_SUBSCRIBER).

Diese Eigenschaft muss angegeben werden.

<Topic> (MQPSC_TOPIC)
Der Wert ist eine Zeichenfolge, die das Thema angibt, für das die Subskription beendet werden soll.

Diese Eigenschaft kann mehrfach angegeben werden, wenn die Subskription für mehrere Themen beendet werden soll. Wenn DeregAll als Wert für <RegOpt> angegeben wird, kann diese Eigenschaft weggelassen werden.

Bei den angegebenen Themen kann es sich um eine Auswahl aus der Gesamtmenge der subskribierten Themen handeln, wenn der Subskribent die Subskriptionen für andere Themen beibehalten möchte. Platzhalterzeichen sind zulässig, aber eine Zeichenfolge, die ein Thema angibt und Platzhalterzeichen enthält, muss exakt mit der entsprechenden Zeichenfolge, die in der Befehlsnachricht zum Anmelden als Subskribent angegeben wurde, übereinstimmen.

<SubPoint> (MQPSC_SUBSCRIPTION_POINT)
Der Wert ist eine Zeichenfolge, die den Subskriptionspunkt angibt, für den die Subskription beendet werden soll.
Diese Eigenschaft darf nur einmal angegeben werden. Sie kann weggelassen werden, wenn ein <Topic> angegeben ist oder wenn DeregAll als Wert für <RegOpt> angegeben wird. Wird diese Eigenschaft weggelassen, gilt Folgendes:
  • Wenn DeregAll nicht angegeben ist, werden Subskriptionen, die der Eigenschaft <Topic> (und der Eigenschaft <Filter>, falls angegeben) entsprechen, für den Standardsubskriptionspunkt beendet.
  • Wenn DeregAll angegeben ist, werden alle Subskriptionen, die den Eigenschaften <Topic> und <Filter> (falls angegeben) entsprechen, für alle Subskriptionspunkte beendet.

Der Standardsubskriptionspunkt kann nicht explizit angegeben werden. Deshalb ist es nicht möglich, alle Subskriptionen nur für diesen Subskriptionspunkt zu beenden. Sie müssen die Themen angeben.

<SubIdentity> (MQPSC_SUBSCRIPTION_IDENTITY)
Dies ist eine Zeichenfolge variabler Länge mit einer maximalen Länge von 64 Zeichen. Sie steht für den Namen einer Anwendung, die an einer Subskription interessiert ist. Der Broker verwaltet für jede Subskription einen Satz von Subskribenten-IDs. Der ID-Satz kann für jede Subskription aus einer einzigen ID oder einer unbegrenzten Anzahl von IDs bestehen.

Wenn die SubIdentity im ID-Satz für die Subskription enthalten ist, wird sie daraus entfernt. Ist die ID-Gruppe anschließend leer, wird die Subskription vom Broker entfernt, außer wenn LeaveOnly als Wert für die Eigenschaft RegOpt angegeben ist. Enthält der ID-Satz aber noch andere IDs, wird die Subskription nicht vom Broker entfernt und der Veröffentlichungsablauf nicht unterbrochen.

Wenn SubIdentity zwar angegeben, SubIdentity aber im ID-Satz für die Subskription nicht enthalten ist, schlägt der Befehl zum Abmelden als Subskribent mit dem Rückkehrcode MQRCCF_SUB_IDENTITY_ERROR fehl.

<Filter> (MQPSC_FILTER)
Der Wert ist eine Zeichenfolge, die den Filter angibt, für den die Subskription beendet werden soll. Sie muss exakt (einschließlich Groß-/Kleinschreibung und irgendwelcher Leerzeichen) mit einem Subskriptionsfilter übereinstimmen, für den zuvor eine Subskription eingerichtet wurde.

Diese Eigenschaft kann mehrfach angegeben werden, wenn die Subskription für mehrere Filter beendet werden soll. Sie kann weggelassen werden, wenn ein <Topic> angegeben ist oder wenn DeregAll als Wert für <RegOpt> angegeben wird.

Bei den angegebenen Filtern kann es sich um eine Untermenge der subskribierten Filter handeln, wenn der Subskribent die Subskriptionen für andere Filter beibehalten möchte.

<RegOpt> (MQPSC_REGISTRATION_OPTION)
Für diese Eigenschaft stehen folgende Registrierungsoptionen zur Verfügung:
DeregAll  
(MQPSC_DEREGISTER_ALL)

Alle entsprechenden Subskriptionen, die für diesen Subskribenten eingerichtet sind, werden beendet.

Wenn DeregAll angegeben wird:
  • <Topic>, <SubPoint> und <Filter> können weggelassen werden.
  • <Topic> und <Filter> können bei Bedarf mehrfach angegeben werden.
  • <SubPoint> darf nur einmal angegeben werden.
Wenn DeregAll nicht angegeben wird:
  • <Topic> muss vorhanden sein und kann bei Bedarf mehrfach angegeben werden.
  • <SubPoint> und <Filter> können weggelassen werden.
  • <SubPoint> darf nur einmal angegeben werden.
  • <Filter> kann bei Bedarf mehrfach angegeben werden.
CorrelAsId  
(MQPSC_CORREL_ID_AS_IDENTITY)

Die CorrelId (Korrelations-ID) im Nachrichtendeskriptor (MQMD), die nicht null sein darf, dient zur Identifizierung des Subskribenten. Sie muss mit der CorrelId, die in der ursprünglichen Subskription angegeben wurde, übereinstimmen.

FullResp  
()

Wenn FullResp angegeben ist, werden bei erfolgreicher Ausführung des Befehls alle Attribute der Subskription in der Antwortnachricht zurückgegeben.

Wenn FullResp angegeben wird, ist die Angabe von DeregAll im Befehl zum Abmelden als Subskribent nicht zulässig. Auch die Angabe mehrerer Themen ist nicht möglich. In beiden Fällen würde der Befehl mit Rückkehrcode MQRCCF_REG_OPTIONS_ERROR fehlschlagen.

LeaveOnly  
(MQPSC_LEAVE_ONLY)

Wenn diese Option zusammen mit einer SubIdentity, die im ID-Satz für die Subskription enthalten ist, angegeben wird, wird die SubIdentity aus dem ID-Satz für die Subskription entfernt. Die Subskription wird nicht vom Broker entfernt, auch wenn der ID-Satz anschließend leer ist. Wenn die angegebene SubIdentity nicht im ID-Satz enthalten ist, schlägt der Befehl mit dem Rückkehrcode MQRCCF_SUB_IDENTITY_ERROR fehl.

Wird LeaveOnly, aber keine SubIdentity angegeben, schlägt der Befehl mit dem Rückkehrcode MQRCCF_REG_OPTIONS_ERROR fehl.

Werden weder LeaveOnly noch eine SubIdentity angegeben, wird die Subskription entfernt, unabhängig vom Inhalt des ID-Satzes für die Subskription.

None  
(MQPSC_NONE)

Alle Optionen erhalten ihre Standardwerte. Dies ist gleichbedeutend mit dem Weglassen der Eigenschaft für die Registrierungsoptionen. Wenn gleichzeitig andere Optionen angegeben werden, wird None ignoriert.

VariableUserId  
(MQPSC_VARIABLE_USER_ID)

Bei Angabe dieser Option ist die ID des Subskribenten (Warteschlange, WS-Manager und Korrelations-ID) nicht auf eine einzige Benutzer-ID begrenzt. In diesem Punkt gibt es einen Unterschied zum bestehenden Verhalten des Brokers, der die Benutzer-ID der ursprünglichen Registrierungsnachricht der ID des Subskribenten zuordnet und dann verhindert, dass ein anderer Benutzer diese ID verwendet. Wenn ein neuer Subskribent versucht, dieselbe ID zu verwenden, wird der Rückkehrcode MQRCCF_DUPLICATE_SUBSCRIPTION zurückgegeben.

Jeder Benutzer kann die Subskription ändern oder beenden, falls er über die entsprechende Berechtigung verfügt, wobei die bestehende Überprüfung, ob die Benutzer-ID mit der des ursprünglichen Subskribenten übereinstimmt, vermieden wird.

Um diese Option zu einer bestehenden Subskription hinzuzufügen, muss der Befehl von derselben Benutzer-ID wie die der ursprünglichen Subskription ausgegeben werden.

Wenn für die Subskription, die beendet werden soll, die Option VariableUserId angegeben wurde, muss diese bei der Beendigung der Subskription angegeben werden, um anzuzeigen, welche Subskription beendet werden soll. Andernfalls wird die Subskription anhand der Benutzer-ID des Befehls zum Abmelden als Subskribent identifiziert. Diese wird ebenso wie die anderen Subskribenten-IDs überschrieben, wenn ein Subskriptionsname angegeben wird.

Wenn diese Eigenschaft nicht angegeben ist, bedeutet dies standardmäßig, dass keine Registrierungsoptionen festgelegt wurden.

<QMgrName> (MQPSC_Q_MGR_NAME)
Der Wert ist der Name des Warteschlangenmanagers für die Warteschlange des Subskribenten. Der Name muss mit dem QMgrName, der in der ursprünglichen Subskription angegeben ist, übereinstimmen.

Wird diese Eigenschaft nicht angegeben, wird standardmäßig der im Feld ReplyToQMgr des Nachrichtendeskriptors (MQMD) angegebene Name verwendet. Wenn der Name aus Leerzeichen besteht, wird standardmäßig der Name des Warteschlangenmanagers des Brokers verwendet.

<QName> (MQPSC_Q_NAME)
Der Wert ist der Name der Warteschlange des Subskribenten. Er muss mit dem QName, der in der ursprünglichen Subskription angegeben wurde, übereinstimmen.

Wird diese Eigenschaft nicht angegeben, wird standardmäßig der im Feld ReplyToQ des Nachrichtendeskriptors (MQMD) angegebene Name, der nicht aus Leerzeichen bestehen darf, verwendet.

<SubName> (MQPSC_SUBSCRIPTION_NAME)
Wenn Sie SubName in einem Befehl zum Abmelden als Subskribent angeben, hat der Wert von SubName Vorrang vor allen anderen ID-Feldern außer der Benutzer-ID, es sei denn, VariableUserId ist in der Subskription selbst festgelegt. Ist VariableUserId nicht festgelegt, ist der Befehl zum Abmelden als Subskribent nur erfolgreich, wenn die Benutzer-ID der Befehlsnachricht mit der der Subskription übereinstimmt. Andernfalls schlägt der Befehl mit dem Rückkehrcode MQRCCF_DUPLICATE_IDENTITY fehl.

Wenn eine Subskription vorhanden ist, die mit der herkömmlichen ID dieses Befehls übereinstimmt, aber kein SubName angegeben ist, schlägt der Befehl zum Abmelden als Subskribent mit dem Rückkehrcode MQRCCF_SUB_NAME_ERROR fehl. Wird versucht, eine Subskription mit einem SubName mit Hilfe einer Befehlsnachricht zu beenden, die der herkömmlichen ID entspricht, aber kein SubName angegeben ist, wird der Befehl erfolgreich ausgeführt.

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
Dies ist eine Textzeichenfolge variabler Länge. Der Wert wird vom Broker mit der Subskription gespeichert, hat aber keinen Einfluss auf die Zustellung der Veröffentlichung an den Subskribenten. Der Wert kann geändert werden, indem für dieselbe Subskription eine erneute Anmeldung mit einem neuen Wert durchgeführt wird. Dieses Attribut wird von der Anwendung benutzt.

Falls vorhanden, werden die SubUserData in der Metathema-Information (MQCACF_REG_SUB_USER_DATA) für eine Subskription zurückgegeben.

Beispiel

Es folgt ein Beispiel für NameValueData für eine Befehlsnachricht zum Abmelden als Subskribent. In diesem Beispiel beendet die Musteranwendung die Subskription für die Themen, die die aktuellen Spielstände aller Spiele enthalten. Die ID des Subskribenten, einschließlich der CorrelId, wird von den Standardwerten im MQMD übernommen.
 <psc>
  <Command>DeregSub</Command>
  <RegOpt>CorrelAsId</RegOpt>
  <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Rückmeldung
Copyright IBM Corporation 1999, 2006 Letzte Aktualisierung: 23. Aug. 2006
aq06970_