Trabalhando com notificações de consulta

As notificações de consulta foram introduzidas no SQL Server 2005 e SQL Server Native Client. Baseadas na infraestrutura do Service Broker, introduzida no SQL Server 2005, as notificações de consulta permitem que os aplicativos sejam notificados em caso de alteração nos dados. Esse recurso é particularmente útil para aplicativos que fornecem um cache de informações de um banco de dados, como um aplicativo da Web, e precisam ser notificados quando os dados de origem são alterados.

As notificações de consulta permitem que você solicite uma notificação em um tempo limite especificado quando os dados subjacentes de uma consulta são alterados. A solicitação por notificação especifica as opções de notificação, que incluem o nome do serviço, o texto da mensagem e o valor do tempo limite do servidor. As notificações são entregues através de uma fila do Service Broker na qual os aplicativos podem sondar as notificações disponíveis.

A sintaxe da cadeia de caracteres das opções de notificação de consulta é a seguinte:

service=<service-name>[;(local database=<database> | broker instance=<broker instance>)]

Por exemplo:

service=mySSBService;local database=mydb

As assinaturas de notificação duram mais tempo do que o processo que as inicia, já que um aplicativo pode criar uma assinatura de notificação e, em seguida, ser encerrado. A assinatura permanece válida e a notificação será feita se os dados forem alterados no tempo limite especificado na criação da assinatura. Uma notificação é identificada pela consulta executada, pelas opções de notificação e pelo texto da mensagem, podendo ser cancelada definindo-se o valor de seu tempo limite como zero.

As notificações só são enviadas uma vez. Para que as notificações de alteração de dados sejam contínuas, é preciso criar uma nova assinatura e executar novamente a consulta depois que cada notificação foi processada.

Normalmente, os aplicativos do SQL Server Native Client recebem notificações com o comando Transact-SQL RECEIVE para ler as notificações da fila associada ao serviço especificado nas opções de notificação.

Observação
Os nomes de tabela devem ser qualificados nas consultas para as quais a notificação é requerida, por exemplo, dbo.myTable. Os nomes de tabela devem ser qualificados com nomes de duas partes. A assinatura é considerada inválida se nomes com três ou quatro partes são usados.

A infraestrutura de notificação baseia-se em um recurso de fila introduzido no SQL Server 2005. Em geral, as notificações geradas no servidor são enviadas através dessas filas para serem processadas posteriormente.

Para usar notificações de consulta, uma fila e um serviço devem existir no servidor. Eles podem ser criados usando Transact-SQL da seguinte forma:

CREATE QUEUE myQueue
CREATE SERVICE myService ON QUEUE myQueue 

([https://schemas.microsoft.com/SQL/Notifications/PostQueryNotification])

Observação
O serviço deve usar o contrato predefinido https://schemas.microsoft.com/SQL/Notifications/PostQueryNotification como mostrado acima.

Provedor OLE DB do SQL Server Native Client

O provedor OLE DB do SQL Server Native Client dá suporte ao recurso de notificação de consumidor em caso de modificação nos conjunto de linhas. O consumidor recebe uma notificação em cada fase da modificação do conjunto de linhas e em qualquer tentativa de alteração.

Observação
Transmitir uma consulta de notificação ao servidor com ICommand::Execute é a única maneira válida de assinar notificações de consulta com o provedor OLE DB do SQL Server Native Client.

O conjunto de propriedades DBPROPSET_SQLSERVERROWSET

Para dar suporte a notificações de consulta pelo OLE DB, o SQL Server Native Client adiciona as propriedades a seguir ao conjunto de propriedades DBPROPSET_SQLSERVERROWSET.

Nome	Tipo	Descrição
SSPROP_QP_NOTIFICATION_TIMEOUT	VT_UI4	O número de segundos que a notificação de consulta permanece ativa. O padrão é 432000 segundos (5 dias). O valor mínimo é 1 segundo e o valor máximo é 2^31-1 segundos.
SSPROP_QP_NOTIFICATION_MSGTEXT	VT_BSTR	O texto da mensagem da notificação. É definido pelo usuário e não tem um formato predefinido. Por padrão, a cadeia de caracteres fica vazia. Você pode especificar uma mensagem que contenha entre 1-2000 caracteres.
SSPROP_QP_NOTIFICATION_OPTIONS	VT_BSTR	As opções de notificação de consulta. São especificadas em uma cadeia de caracteres com a sintaxe name=value. O usuário é responsável por criar o serviço e ler as notificações da fila. O padrão é uma cadeia de caracteres vazia.

A assinatura de notificação é sempre confirmada, independentemente do fato de a instrução ter sido executada em uma transação de usuário ou em uma confirmação automática ou se a transação na qual a instrução foi executada tiver sido confirmada ou revertida. A notificação do servidor é acionada mediante uma das seguintes condições inválidas de notificação: alteração dos dados subjacentes ou do esquema ou quando o tempo limite expira; a que ocorrer primeiro. Os registros de notificação são excluídos assim que são disparados. Consequentemente, em caso de recebimento de notificações, o aplicativo deve realizar uma nova assinatura caso queira obter mais atualizações.

Outra conexão ou thread pode verificar se há notificações na fila de destino. Por exemplo:

WAITFOR (RECEIVE * FROM MyQueue);   // Where MyQueue is the queue name. 

Observe que SELECT * não exclui a entrada da Fila, porém RECEIVE * FROM exclui. Isso irá interromper um thread de servidor se a fila estiver vazia. Se houver entradas na fila durante o momento da chamada, elas serão retornadas imediatamente; caso contrário, a chamada aguardará até que seja feita a entrada na fila.

RECEIVE * FROM MyQueue

Essa instrução retornará imediatamente um conjunto de resultados vazio se a fila estiver vazia; caso contrário, retornará todas as notificações da fila.

Se SSPROP_QP_NOTIFICATION_MSGTEXT e SSPROP_QP_NOTIFICATION_OPTIONS forem não nulos e não vazios, o cabeçalho do TDS para notificações de consulta que contém as três propriedades definidas acima é enviado ao servidor em cada execução do comando. Se algum deles for nulo (ou vazio), o cabeçalho não será enviado e DB_E_ERRORSOCCURRED será usado, (ou DB_S_ERRORSOCCURRED se as propriedades estiverem marcadas como opcionais), e o valor do status será definido como DBPROPSTATUS_BADVALUE. A validação é feita em Execute/Prepare. De modo semelhante, DB_S_ERRORSOCCURED será usado quando as propriedades de notificação de consulta forem definidas para conexões com versões do SQL Server anteriores ao SQL Server 2005. O valor de status nesse caso é DBPROPSTATUS_NOTSUPPORTED.

Iniciar uma assinatura não garante que as mensagens subsequentes sejam entregues com êxito. Além disso, nenhuma verificação é feita em relação à validade do nome de serviço especificado.

Observação
A preparação de assinaturas nunca fará com que a assinatura seja iniciada; somente a execução da instrução iniciará a assinatura e as notificações de consulta não são impactadas pelo uso dos serviços principais do OLE DB.

Para obter mais informações sobre o conjunto de propriedades DBPROPSET_SQLSERVERROWSET, consulte Propriedades e comportamentos do conjunto de linhas.

Driver ODBC do SQL Server Native Client

O driver ODBC do SQL Server Native Client dá suporte a notificações de consulta por meio da adição de três novos atributos às funções SQLGetStmtAttr e SQLSetStmtAttr:

• SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

• SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

• SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

Se SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT e SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS não forem NULOS, o cabeçalho do TDS das notificações de consulta que contém os três atributos definidos acima será enviado para o servidor toda vez que o comando for executado. Se um deles for nulo, o cabeçalho não será enviado e SQL_SUCCESS_WITH_INFO será retornado. A validação será feita em Função SQLPrepare, SQLExecDirecte SQLExecute, sendo que todos falham se os atributos não forem válidos. De modo semelhante, quando esses atributos de notificação de consulta são definidos para versões do SQL Server anteriores ao SQL Server 2005, ocorre uma falha na execução com SQL_SUCCESS_WITH_INFO.

Observação
A preparação de instruções nunca iniciará a assinatura; a assinatura pode ser iniciada com a execução da instrução.

Casos especiais e restrições

Os seguintes tipos de dados não são suportados para notificações:

• text

• ntext

• image

Se for feita uma solicitação de notificação para um consulta que retorna um desses tipos, a notificação será disparada imediatamente, especificando que não foi possível realizar a assinatura na notificação.

Se uma solicitação de assinatura for feita para um lote ou procedimento armazenado, outra solicitação de assinatura será feita para cada instrução executada no lote ou procedimento armazenado. As instruções EXECUTE não registrarão notificações, mas enviarão a solicitação de notificação para o comando executado. Se for um lote, o contexto será aplicado às instruções executadas e as mesmas regras descritas anteriormente serão aplicadas.

O envio de uma consulta para notificação que foi enviada pelo mesmo usuário no mesmo contexto de banco de dados e que tem o mesmo modelo, os mesmos valores de parâmetros, a mesma ID de notificação e o mesmo local de entrega de uma assinatura ativa existente, renovará a assinatura existente, redefinindo o novo tempo limite especificado. Isso significa que, se for solicitada uma notificação para consultas idênticas, apenas uma notificação será enviada. Isso se aplica a uma consulta duplicada em um lote ou a uma consulta em um procedimento armazenado chamada várias vezes.

Consulte também

Outros recursos

Recursos do SQL Server Native Client