Il messaggio di comando Registra sottoscrittore (subscriber) viene inviato ad un broker da un sottoscrittore (subscriber) o da un'altra applicazione per conto di un sottoscrittore (subscriber), per indicare che si desidera sottoscrivere uno o più argomenti in un punto di sottoscrizione. E' possibile specificare anche un filtro del contenuto del messaggio.
Nelle espressioni filtro di pubblicazione/sottoscrizione, l'uso di parentesi nidificate provoca una riduzione esponenziale delle prestazioni. In pratica, evitare di ricorrere a più di 6 parentesi nidificate.
Il messaggio viene inviato a SYSTEM.BROKER.CONTROL.QUEUE, che è la coda di controllo del broker. E' necessario disporre dell'autorizzazione ad inserire messaggi in questa coda oltre che dell'autorizzazione (impostata dall'amministratore di sistema del broker) ad accedere all'argomento o agli argomenti nella sottoscrizione.
Se l'utente dispone dell'autorizzazione solo su alcuni argomenti, non su tutti, vengono registrati solo quegli argomenti; una risposta di avvertenza indica gli argomenti non registrati.
Per informazioni dettagliate sui parametri del descrittore di messaggi (MQMD), necessari quando si invia un messaggio di comando al broker, fare riferimento a Messaggio Risposta del broker.
Se la coda, è una coda dinamica temporanea, viene annullata automaticamente la registrazione della sottoscrizione dal broker quando la coda è chiusa.
Questa proprietà è richiesta e può essere ripetuta per tutti gli eventuali argomenti necessari.
Se questa proprietà è omessa, viene utilizzato il punto di sottoscrizione predefinito.
Se questa proprietà è omessa, non viene eseguito alcun filtro del contento.
Quando specificato per una sottoscrizione esistente che corrisponde all'identità tradizionale di questo comando di registrazione della sottoscrizione, ma senza alcun valore SubName corrente, il SubName specificato in questo comando viene aggiunto alla sottoscrizione.
Se è specificato AddName, il campo SubName è obbligatorio, altrimenti viene restituito MQRCCF_REG_OPTIONS_ERROR.
Il CorrelId presente nel descrittore di messaggi (MQMD), viene utilizzato quando si inviano pubblicazioni corrispondenti alla coda del sottoscrittore (subscriber). CorrelId non deve corrispondere a zero.
Quando specificato, tutti gli attributi della sottoscrizione vengono restituiti nel messaggio di risposta, se il comando non ha esito negativo.
FullResp è valido solo quando il messaggio di comando fa riferimento ad una sola sottoscrizione. Quindi, nel comando è consentito un solo un argomento; altrimenti il comando ha esito negativo e viene restituito il codice di ritorno MQRCCF_REG_OPTIONS_ERROR.
Il broker informa il sottoscrittore (subscriber) se una pubblicazione è conservata quando invia il messaggio di pubblicazione in risposta al messaggio di comando Registra sottoscrittore (subscriber) o Richiedi aggiornamento. Il broker esegue ciò includendo nel messaggio l'opzione di pubblicazione IsRetainedPub.
Questa opzione indica che la specifica di SubIdentity deve essere aggiunta come membro esclusivo della serie di identità del sottoscrittore (subscriber) e che non è possibile aggiungere alla serie altre identità.
Se l'identità è già stata unita ed è l'unica voce della serie, tale serie viene cambiata come esclusiva di questa identità. Altrimenti, se la sottoscrizione ha attualmente altre identità nella serie (con accesso condiviso) il comando non ha esito positivo e viene restituito il codice di ritorno MQRCCF_SUBSCRIPTION_IN_USE.
Questa opzione indica che la specifica di SubIdentity deve essere aggiunta alla serie di identità per la sottoscrizione.
Se la sottoscrizione è attualmente bloccata in modo esclusivo (mediante l'opzione JoinExcl), il comando ha esito negativo e viene restituito il codice di ritorno MQRCCF_SUBSCRIPTION_LOCKED, a meno che l'identità la cui sottoscrizione è bloccata è la stessa di quella nel messaggio di comando. In tale caso il blocco viene modificato automaticamente in un blocco condiviso.
La sottoscrizione è locale è non viene distribuita agli altri broker nella rete. Le pubblicazioni eseguite sugli altri broker non vengono distribuite a questo sottoscrittore (subscriber), a meno che questi non abbia anche una corrispondente sottoscrizione globale.
Le pubblicazioni conservate esistenti al momento della registrazione della sottoscrizione non vengono inviate al sottoscrittore (subscriber); vengono inviate solo quelle nuove.
Se un sottoscrittore (subscriber) esegue una nuova registrazione e modifica questa opzione in modo che non è più impostata, potrebbe verificarsi che una pubblicazione che gli è già è stata inviata venga inoltrata nuovamente.
Non vengono modificati gli attributi di una sottoscrizione corrispondente esistente.
Quando viene creata una sottoscrizione, questa opzione viene ignorata. Sono attive per la nuova sottoscrizione tutte le altre opzioni specificate.
Se SubIdentity dispone anche di una delle opzioni di unione (JoinExcl o JoinShared) specificate, l'identità viene aggiunta alla relativa serie, indipendentemente dalla specifica di NoAlter.
Tutte le opzioni di registrazione assumono i relativi valori predefiniti.
Se il sottoscrittore (subscriber) è già registrato, vengono ripristinati i valori predefiniti delle relative opzioni (tenere presente che ciò non ha lo stesso effetto di omettere la proprietà delle opzioni di registrazione), e il termine della sottoscrizione viene aggiornato da MQMD del messaggio Registra sottoscrittore (subscriber).
Se sono specificate altre opzioni di registrazione in contemporanea, None viene ignorato.
Le pubblicazioni che corrispondono a questa sottoscrizione vengono distribuite al sottoscrittore (subscriber) come messaggi non permanenti.
Le pubblicazioni che corrispondono a questa sottoscrizione vengono distribuite al sottoscrittore (subscriber) come messaggi permanenti.
Le pubblicazioni che corrispondono a questa sottoscrizione vengono distribuite al sottoscrittore (subscriber) con la permanenza specificata dall'autore (publisher). Questo è il comportamento predefinito.
Le pubblicazioni che corrispondono a questa sottoscrizione vengono distribuite al sottoscrittore (subscriber) con la permanenza specificata nella relativa coda.
Il broker non invia le pubblicazioni al sottoscrittore (subscriber), tranne che in risposta ad un messaggio di comando Richiedi aggiornamento.
Quando specificata, l'identità del sottoscrittore (subscriber), coda, gestore code e correlid, non è limitata ad un solo ID utente. Ciò differisce dal comportamento esistente del broker che associa l'ID utente del messaggio di registrazione di origine con l'identità del sottoscrittore (subscriber) in modo da impedire l'utilizzo di tale identità da parte di qualsiasi altro utente. Se un nuovo sottoscrittore (subscriber) tenta di utilizzare la stessa identità, viene restituito MQRCCF_DUPLICATE_SUBSCRIPTION.
Ciò consente ad ogni utente di modificare o annullare la registrazione della sottoscrizione se l'utente dispone dell'autorizzazione appropriata. Non c'è quindi nessuna necessità di verificare che l'ID utente corrisponda a quello del sottoscrittore (subscriber) di origine.
Per aggiungere questa opzione ad una sottoscrizione esistente il comando deve provenire dallo stesso ID utente della sottoscrizione di origine.
Se nella sottoscrizione del comando Richiedi aggiornamento è impostato VariableUserId, questo deve essere impostato in fase di richiesta dell'aggiornamento per indicare a quale sottoscrizione fa riferimento. Altrimenti, per individuare la sottoscrizione, viene utilizzato l'ID utente del comando Richiedi aggiornamento. Questo viene sovrascritto, insieme agli altri identificativi del sottoscrittore (subscriber), se viene fornito un nome di sottoscrizione.
Se un messaggio di comando Registra sottoscrittore (subscriber) senza l'impostazione di questa opzione, fa riferimento ad una sottoscrizione esistente in cui tale opzione è impostata, l'opzione viene eliminata da tale sottoscrizione e l'ID utente della sottoscrizione viene quindi fissato. Se esiste già un sottoscrittore (subscriber) con la stessa identità (coda, qmgr e correlid), ma con un diverso ID utente associato ad esso, il comando ha esito negativo e viene restituito il codice di ritorno MQRCCF_DUPLICATE_IDENTITY, in quanto può esserci un solo ID utente associato ad un'identità del sottoscrittore (subscriber).
Se la proprietà delle opzioni di registrazione è omessa e il sottoscrittore (subscriber) è già registrato, le relative opzioni di registrazione non vengono modificate e il termine della sottoscrizione viene aggiornato da MQMD del messaggio Registra sottoscrittore (subscriber).
Se il sottoscrittore (subscriber) non è ancora registrato, viene creata una nuova sottoscrizione in cui tutte le opzioni di registrazione assumono i relativi valori predefiniti.
I valori predefiniti sono PersAsPub e nessuna altra opzione impostata.
Se questa proprietà è omessa, il valore predefinito è il nome ReplyToQMgr nel descrittore di messaggi (MQMD). Se il nome risultante è vuoto, viene assunto come valore predefinito il QMgrName del broker.
Se questa proprietà è omessa, il valore predefinito è il nome ReplyToQ nel descrittore di messaggi (MQMD), che in questo caso non deve essere vuoto.
Se la coda è una coda dinamica temporanea, nella proprietà <RegOpt> deve essere specificata la distribuzione non permanente delle pubblicazioni (NonPers).
Se la coda, è una coda dinamica temporanea, viene annullata automaticamente la registrazione della sottoscrizione dal broker quando la coda è chiusa.
Se esiste già una sottoscrizione con questo SubName, qualsiasi altro attributo della sottoscrizione (Topic, QMgrName, QName, CorrelId, UserId, RegOpts, UserSubData ed Expiry) viene sovrascritto con gli attributi, se specificati, passati nel nuovo messaggio di comando Register Subscriber. Tuttavia, se SubName viene utilizzato senza la specifica del campo QName e nell'intestazione MQMD è specificato ReplyToQ, la coda del sottoscrittore (subscriber) viene modificata in ReplyToQ.
Se già esiste una sottoscrizione che corrisponde all'identità tradizionale di questo comando, ma non dispone di SubName, il comando di registrazione ha esito negativo e viene restituito il codice di ritorno MQRCCF_DUPLICATE_SUBSCRIPTION, a meno che non sia specificata l'opzione AddName.
Se si tenta di modificare una sottoscrizione esistente con nome, utilizzando un altro comando Registra sottoscrittore (subscriber) che specifica lo stesso SubName, ed i valori di Topic, QMgrName, QName e CorrelId nel nuovo comando corrispondono ad un'altra sottoscrizione esistente, con o senza definizione di SubName, il comando ha esito negativo e viene restituito il codice di ritorno MQRCCF_DUPLICATE_SUBSCRIPTION. Ciò impedisce a due nomi di sottoscrizione di fare riferimento alla stessa sottoscrizione.
Un comando di sottoscrizione che specifica l'opzione JoinShared o JoinExcl aggiunge SubIdentity alla serie di identità della sottoscrizione, se non è già presente e se la serie di identità esistente consente tale azione; ovvero, nessun altro sottoscrittore (subscriber) è stato unito in modo esclusivo o la serie di identità è vuota.
Qualsiasi modifica degli attributi della sottoscrizione come risultato di un comando Registra sottoscrittore (subscriber) in cui è presente una specifica SubIdentity, ha esito positivo solo se è l'unico membro della serie di identità di questa sottoscrizione. Altrimenti, il comando ha esito negativo e viene restituito il codice di ritorno MQRCCF_SUBSCRIPTION_IN_USE. Ciò impedisce la modifica degli attributi della sottoscrizione senza che ne siano a conoscenza altri sottoscrittori (subscriber) interessati.
Se si specifica una stringa di caratteri più lunga di 64 caratteri, il comando ha esito negativo e viene restituito il codice di ritornoMQRCCF_SUB_IDENTITY_ERROR.
SubUserData viene restituito nelle informazioni meta-argomento (MQCACF_REG_SUB_USER_DATA) relative ad una sottoscrizione, se presente.
Se si specifica più di un valore di opzione di registrazione NonPers, PersAsPub, PersAsQueue e Pers, viene utilizzato solo l'ultimo. Non è possibile combinare queste opzioni in una sola sottoscrizione.
<psc> <Command>RegSub</Command> <RegOpt>PubOnReqOnly</RegOpt> <RegOpt>CorrelAsId</RegOpt> <Topic>Sport/Soccer/State/LatestScore/#</Topic> </psc>