Mensagem Cancelar Registro de Assinante

A mensagem de comando Cancelar Registro de Assinante é enviada a um intermediário de um assinante ou a outro aplicativo em nome de um assinante, para indicar que ele não deseja mais receber mensagens correspondentes aos parâmetros dados.

Essa mensagem é enviada a SYSTEM.BROKER.CONTROL.QUEUE, a fila de controle do intermediário. O usuário precisa ter a autoridade necessária para colocar uma mensagem nessa fila.

Consulte Definições de MQMD em Mensagens de Comando para o Intermediário para obter detalhes sobre os parâmetros do descritor de mensagem (MQMD) que são necessários ao enviar uma mensagem de comando ao intermediário.

O registro de uma assinatura individual pode ser cancelado especificando os valores do tópico, ponto de assinatura e filtro correspondentes da assinatura original. Se algum dos valores não tiver sido especificado (ou seja, eles assumiram os valores padrão) na assinatura original, eles devem ser omitidos quando o registro da assinatura for cancelado.

Todas as assinaturas de um assinante, ou de um grupo de assinantes, podem ter seus registros cancelados utilizando a opção DeregAll.Por exemplo, se DeregAll for especificado junto com um ponto de assinatura (mas sem tópico ou filtro), todas as assinaturas do assinante no ponto de assinatura especificado têm seus registros cancelados, independente do tópico e filtro.Qualquer combinação de tópico, filtro e ponto de assinatura é permitida; se todos os três forem especificados somente uma assinatura pode corresponder, e a opção DeregAll será ignorada.

A mensagem deve ser enviada pelo assinante que registrou a assinatura; isso é confirmado verificando-se o ID do usuário do assinante.

Os registros de assinaturas também podem ser cancelados por um administrador do sistema. Entretanto, as assinaturas registradas com uma fila dinâmica temporária são associadas à fila, não apenas ao nome da fila. Se a fila for excluída, seja explicitamente ou pela desconexão do aplicativo do gerenciador de filas, não é mais possível utilizar o comando Cancelar Registro de Assinante para cancelar o registro das assinaturas para essa fila. As assinaturas podem ter o registro cancelado utilizando o workbench e são removidas automaticamente pelo intermediário na próxima vez que corresponder uma publicação a uma assinatura ou na próxima vez que o intermediário for reiniciado. Em circunstâncias normais, os aplicativos devem cancelar o registro de suas assinaturas antes de excluir a fila ou de se desconectarem do gerenciador de filas.

Se um assinante enviar uma mensagem para cancelar o registro de uma assinatura, e receber uma mensagem de resposta para dizer que isso foi processado com êxito, algumas publicações ainda poderão alcançar a fila do assinante se elas estavam sendo processadas pelo intermediário ao mesmo tempo que o registro da assinatura estava sendo cancelado. Se as mensagens não forem removidas da fila, poderá haver um acúmulo de mensagens não processadas na fila do assinante. Se o aplicativo executar um loop que inclua uma chamada MQGET com o CorrelId apropriado, depois de permanecer por algum tempo, essas mensagens serão limpas da fila.Se você estiver utilizando o Protocolo de Dispositivo SCADA existe uma opção de início e finalização limpos. Isso significa que as mensagens foram limpas em outro lugar para o cliente.

De forma semelhante, se o assinante utilizar uma fila dinâmica permanente, e cancelar o registro e fechar a fila com a opção MQCO_DELETE_PURGE em uma chamada MQCLOSE, a fila pode não estar vazia. Se alguma publicação do intermediário ainda não tiver sido consolidada quando a fila for excluída, um código de retorno MQRC_Q_NOT_EMPTY será emitido pela chamada MQCLOSE. O aplicativo pode evitar esse problema repousando e emitindo novamente a chamada MQCLOSE de tempos em tempos.

Propriedades

<Comando> (MQPSC_COMMAND)
O valor é DeregSub (MQPSC_DEREGISTER_SUBSCRIBER).

Essa propriedade precisa ser especificada.

<Tópico> (MQPSC_TOPIC)
O valor é uma cadeia que contém o tópico cujo registro deve ser cancelado.

Essa propriedade pode opcionalmente ser repetida se vários tópicos tiverem que ter seus registros cancelados. Ela pode ser omitida se DeregAll for especificado em <RegOpt>.

Os tópicos especificados podem ser um subconjunto dos que estão registrados se o assinante desejar reter assinaturas para outros tópicos. Caracteres curinga são permitidos, mas uma cadeia de tópico contendo caracteres curinga deve corresponder exatamente à cadeia correspondente que foi especificada na mensagem de comando Registrar Assinante.

<SubPoint> (MQPSC_SUBSCRIPTION_POINT)
O valor é uma cadeia que especifica o ponto de assinatura do qual a assinatura deve ser desconectada.
Essa propriedade não pode ser repetida. Ela poderá ser omitida se um <Tópico> estiver especificado ou se DeregAll estiver especificado em <RegOpt>. Se você omitir essa propriedade acontecerá o seguinte:
  • Se você não especificar DeregAll, as assinaturas correspondentes à propriedade <Topic> (e à propriedade <Filter>, se estiver presente) terão seus registros cancelados do ponto de assinatura padrão.
  • Se você especificar DeregAll, todas as assinaturas (correspondentes às propriedades <Tópico> e <Filtro>, se presentes) terão seus registros cancelados de todos os pontos de assinatura.

Observe que não é possível especificar o ponto de assinatura padrão explicitamente. Portanto, não há modo de cancelar os registros de todas as assinaturas somente deste ponto de assinatura; é preciso especificar os tópicos.

<SubIdentity> (MQPSC_SUBSCRIPTION_IDENTITY)
Esta é uma cadeia de comprimento variável com um comprimento máximo de 64 caracteres. É utilizada para representar um aplicativo com um interesse em uma assinatura. O intermediário mantém um conjunto de identidades de assinantes para cada assinatura. Cada assinatura pode permitir que seu conjunto de identidades contenha somente uma identidade ou um número ilimitado de identidades.

Se a SubIdentity estiver no conjunto de identidades para a assinatura, ela será removida do conjunto. Se o conjunto de identidades se tornar vazio como resultado disso, a assinatura será removida do intermediário, a menos que LeaveOnly seja especificado como um valor da propriedade RegOpt. Se o conjunto de identidades ainda contiver outras identidades, a assinatura não será removida do intermediário e o fluxo de publicação não será interrompido.

Se SubIdentity estiver especificado, mas SubIdentity não estiver no conjunto de identidades para a assinatura, o comando Cancelar Registro de Assinante falhará com o código de retorno MQRCCF_SUB_IDENTITY_ERROR.

<Filtro> (MQPSC_FILTER)
O valor é uma cadeia especificando o filtro cujo registro deve ser cancelado. Ele deve corresponder exatamente, incluindo maiúsculas e minúsculas e quaisquer espaços, a um filtro de assinatura registrado anteriormente.

Essa propriedade pode opcionalmente ser repetida se os registros de mais de um filtro tiverem que ser cancelados. Ela poderá ser omitida se um <Tópico> estiver especificado ou se DeregAll estiver especificado em <RegOpt>.

Os filtros especificados podem ser um subconjunto dos que estão registrados se o assinante quiser reter assinaturas para outros filtros.

<RegOpt> (MQPSC_REGISTRATION_OPTION)
A propriedade registration options pode ter os seguintes valores:
DeregAll  
(MQPSC_DEREGISTER_ALL)

Todas as assinaturas correspondentes registradas para este assinante devem ter seus registros cancelados.

Se você especificar DeregAll:
  • <Tópico>, <SubPoint> e <Filtro> podem ser omitidos.
  • <Topic> e <Filter> podem ser repetidos, se necessário.
  • <SubPoint> não pode ser repetido.
Se você não especificar DeregAll:
  • <Topic> deve ser especificado e pode ser repetido se necessário.
  • <SubPoint> e <Filtro> podem ser omitidos.
  • <SubPoint> não pode ser repetido.
  • <Filtro> pode ser repetido, se necessário.
CorrelAsId  
(MQPSC_CORREL_ID_AS_IDENTITY)

O CorrelId no descritor de mensagem (MQMD), que não pode ser zero, é utilizado para identificar o assinante. Ele deve corresponder ao CorrelId utilizado na assinatura original.

FullResp  
()

Quando FullResp for especificado todos os atributos da assinatura são retornados na mensagem de resposta, se o comando não falhar.

Quando FullResp está especificado DeregAll não é permitido no comando Cancelar Registro de Assinante. Também não é possível especificar vários tópicos. O comando falhará com o código de retorno MQRCCF_REG_OPTIONS_ERROR, no dois casos.

LeaveOnly  
(MQPSC_LEAVE_ONLY)

Quando especificar isto com um SubIdentity que esteja no conjunto de identidade para a assinatura, SubIdentity será removido do conjunto de identidades da assinatura. A assinatura não será removida do intermediário, mesmo que o conjunto de identidades resultante esteja vazio. Se o valor de SubIdentity não estiver no conjunto de identidades o comando falhará com o código de retorno MQRCCF_SUB_IDENTITY_ERROR.

Se LeaveOnly estiver especificado com nenhuma SubIdentity, o comando falhará com o código de retorno MQRCCF_REG_OPTIONS_ERROR.

Se nem LeaveOnly nem uma SubIdentity forem especificados, a assinatura será removida independente do conteúdo do conjunto de identidades da assinatura.

Nenhum  
(MQPSC_NONE)

Todas as opções assumem seus valores padrão. Isto tem o mesmo efeito que omitir a propriedade registration options. Se outras opções forem especificadas ao mesmo tempo, Nenhuma será ignorada.

VariableUserId  
(MQPSC_VARIABLE_USER_ID)

Quando especificado, a identidade do assinante (fila, gerenciador de filas e correlid) não será restrita a um único ID do usuário. Isso difere do comportamento existente do intermediário que associa o ID do usuário da mensagem de registro original à identidade do assinante e a partir daí impede que outros usuários utilizem essa identidade. Se um novo assinante tentar utilizar a mesma identidade, o código de retorno MQRCCF_DUPLICATE_SUBSCRIPTION será retornado.

Qualquer usuário pode modificar a assinatura ou cancelar seu registro quando tiver autoridade apropriada, evitando a verificação existente de que o ID do usuário deve corresponder ao do assinante original.

Para incluir essa opção a uma assinatura existente o comando deve vir do mesmo ID do usuário da própria assinatura original.

Se a assinatura que terá seu registro cancelado tiver VariableUserId definido, isto deve ser definido na hora de cancelamento do registro para indicar qual assinatura deve ter seu registro cancelado. Caso contrário, o ID do usuário do comando Cancelar Registro de Assinante será utilizado para identificar a assinatura. Isso é substituído, junto com os outros identificadores do assinante, se for fornecido um nome de assinatura.

O padrão, se essa propriedade for omitida, é que nenhuma opção de registro seja definida.

<QMgrName> (MQPSC_Q_MGR_NAME)
O valor é o nome do gerenciador de filas para a fila do assinante. Ele deve corresponder ao QMgrName utilizado na assinatura original.

Se essa propriedade for omitida, o padrão é o nome de ReplyToQMgr no descritor da mensagem (MQMD). Se o nome resultante estiver em branco, ele assumirá o padrão do nome do gerenciador de filas do intermediário.

<QName> (MQPSC_Q_NAME)
O valor é o nome da fila do assinante. Ele deve corresponder ao QName utilizado na assinatura original.

Se esta propriedade for omitida, o padrão é o nome de ReplyToQ no descritor da mensagem (MQMD), o qual não pode estar em branco.

<SubName> (MQPSC_SUBSCRIPTION_NAME)
Se você especificar SubName em um comando Cancelar Registro de Assinante, o valor de SubName terá preferência sobre todos os outros campos de identificador exceto o ID do usuário, a menos que VariableUserId seja definido na própria assinatura. Se o VariableUserId não estiver definido, o comando Cancelar Registro de Assinante terá êxito apenas se o ID do usuário da mensagem de comando corresponder ao da assinatura, caso contrário, o comando falhará com o código de retorno MQRCCF_DUPLICATE_IDENTITY.

Se existir uma assinatura que corresponda à identidade tradicional desse comando mas que não tenha nenhum SubName, o comando Cancelar Registro de Assinante falhará com o código de retorno MQRCCF_SUB_NAME_ERROR. Se for feita uma tentativa de cancelar o registro de uma assinatura que tenha um SubName utilizando uma mensagem de comando que corresponda à identidade tradicional, mas sem SubName especificado, o comando obterá êxito.

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
Esta é uma cadeia de texto de comprimento variável. O valor é armazenado pelo intermediário com a assinatura, mas não tem influência na entrega da publicação ao assinante. O valor pode ser alterado registrando novamente para a mesma assinatura com um novo valor. Esse atributo existe para uso pelo aplicativo.

O SubUserData é retornado nas informações de Metatópico (MQCACF_REG_SUB_USER_DATA) para uma assinatura, se estiver presente.

Exemplo

Exemplo de NameValueData para uma mensagem de comando Cancelar Registro de Assinante. Neste exemplo, o aplicativo de amostra está cancelando o registro de sua assinatura aos tópicos que contêm o último placar para todos os jogos. A identidade do assinante, incluindo o CorrelId é obtida dos padrões no MQMD.
 <psc>
    <Command>DeregSub</Command>
    <RegOpt>CorrelAsId</RegOpt>
    <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>
Avisos | Marcas Registradas | Downloads | Biblioteca | Suporte | Feedback
Direitos Autorais IBM Corporation 1999, 2006 Última Atualização: 1 Sep 2006
aq06970_