Befehlsnachricht zum Abmelden eines Subskribenten

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 für 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 zu derselben 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. Das Problem kann von der Anwendung umgangen werden, indem der MQCLOSE-Aufruf von Zeit zu Zeit inaktiviert und 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 sich der Wert SubIdentity im Identitätssatz für die Subskription befindet, wird er aus dem Satz entfernt. Wenn sich daraus ein leerer Identitätssatz ergibt, wird die Subskription vom Broker entfernt, es sei denn, LeaveOnly ist als Wert für die Eigenschaft RegOpt angegeben. Wenn der Identitätssatz noch weitere Identitäten enthält, wird die Subskription nicht vom Broker entfernt, und der Veröffentlichungsablauf wird 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 sowie 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 Auswahl aus der Gesamtmenge 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) darf nicht null sein und dient zur Identifizierung des Subskribenten. Sie muss mit der CorrelId übereinstimmen, die in der ursprünglichen Subskription angegeben wurde.

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)

Für alle Optionen gelten die Standardwerte. Dies entspricht dem Weglassen der Eigenschaft für die Registrierungsoptionen. Wenn gleichzeitig andere Optionen angegeben sind, wird die Option Keine ignoriert.

VariableUserId  
(MQPSC_VARIABLE_USER_ID)

Wenn dieser Wert angegeben ist, wird die Identität des Subskribenten (Warteschlange, WS-Manager und Korrelations-ID) nicht auf eine einzige Benutzer-ID beschränkt. 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.

Wenn diese Option einer vorhandenen Subskription hinzugefügt werden soll, muss der Befehl mit derselben Benutzer-ID ausgegeben werden, wie die ursprüngliche Subskription.

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 ID wird zusammen mit den anderen Subskribenten-IDs überschrieben, wenn ein Subskriptionsname angegeben wird.

Wird diese Eigenschaft ausgelassen, wird die Standardeinstellung verwendet, nach der keine Registrierungsoptionen festgelegt werden.

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

Wird diese Eigenschaft nicht angegeben, wird standardmäßig der im Nachrichtendeskriptor (MQMD) angegebene Name ReplyToQMgr 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 übereinstimmen, der in der ursprünglichen Subskription angegeben wurde.

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

<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 durch eine erneute Anmeldung für dieselbe Subskription mit einem neuen Wert geändert werden. Dieses Attribut ist für die Verwendung durch die Anwendung vorgesehen.

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

Beispiel

Hier finden Sie 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. Für die Identität des Subskribenten, einschließlich des Werts CorrelId, werden die Standardeinstellungen aus dem 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: 18.05.2006
aq06970_