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.
Diese Eigenschaft muss angegeben werden.
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.
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.
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.
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.
Alle entsprechenden Subskriptionen, die für diesen Subskribenten eingerichtet sind, werden beendet.
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.
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.
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.
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.
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.
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.
Wird diese Eigenschaft nicht angegeben, wird standardmäßig der im Feld ReplyToQ des Nachrichtendeskriptors (MQMD) angegebene Name, der nicht aus Leerzeichen bestehen darf, verwendet.
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.
Falls vorhanden, werden die SubUserData in der Metathema-Information (MQCACF_REG_SUB_USER_DATA) für eine Subskription zurückgegeben.
<psc> <Command>DeregSub</Command> <RegOpt>CorrelAsId</RegOpt> <Topic>Sport/Soccer/State/LatestScore/#</Topic> </psc>