CREATE QUEUE (Transact-SQL)

Cria uma fila nova em um banco de dados. Enfileira mensagens de armazenamento. Quando uma mensagem chega para um serviço, o Service Broker põe a mensagem na fila associada ao serviço.

Convenções de sintaxe Transact-SQL

Sintaxe

CREATE QUEUE <object>
   [ WITH
     [ STATUS = { ON | OFF }  [ , ] ]
     [ RETENTION = { ON | OFF } [ , ] ] 
     [ ACTIVATION (
         [ STATUS = { ON | OFF } , ] 
           PROCEDURE_NAME = <procedure> ,
           MAX_QUEUE_READERS = max_readers , 
           EXECUTE AS { SELF | 'user_name' | OWNER } 
            ) ]
    ]
     [ ON { filegroup | [ DEFAULT ] } ]
[ ; ]

<object> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        queue_name
} 

<procedure> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        stored_procedure_name
} 

Argumentos

• database_name(objeto)
  É o nome do banco de dados no qual a nova fila é criada. O database_name deve especificar o nome de um banco de dados existente. Quando o database_name não é fornecido, a fila é criada no banco de dados atual.

• schema_name (objeto)
  É o nome do esquema ao qual a nova fila pertence. O esquema considera como padrão o esquema padrão para o usuário que executa a instrução. Se a instrução CREATE QUEUE for executada por um membro da função de servidor fixa sysadmin ou por um membro das funções de banco de dados fixas db_dbowner ou db_ddladmin no banco de dados especificado por database_name, o schema_name poderá especificar um esquema diferente do que está associado ao logon da conexão atual. Caso contrário, o schema_name deverá ser o esquema padrão do usuário que executa a instrução.

• queue_name
  É o nome da fila a ser criada. Esse nome deve satisfazer as diretrizes para identificadores do SQL Server.

• STATUS (Fila)
  Especifica se a fila está disponível (ON) ou indisponível (OFF). Quando a fila estiver indisponível, nenhuma mensagem pode ser adicionada à fila ou removida dela. Você pode criar a fila em um estado indisponível para evitar que as mensagens cheguem à fila até que a fila seja tornada disponível com uma instrução ALTER QUEUE. Se esta cláusula for omitida, o padrão será ON e a fila estará disponível.

• RETENTION
  Especifica a configuração de retenção para a fila. Se RETENTION = ON, todas as mensagens enviadas ou recebidas em conversações que usem essa fila serão retidas na fila até que as conversações tenham terminado. Isso lhe permite reter mensagens para propósitos de auditoria ou executar transações de compensação se um erro acontecer. Se essa cláusula não for especificada, a configuração de retenção considerará OFF como padrão.

  Observação
  Definindo RETENÇÃO = ON pode diminuir o desempenho. Essa configuração só deveria ser usada se for requerida para o aplicativo. Para obter mais informações, consulte Retenção de mensagem.

• ACTIVATION
  Especifica informações sobre qual procedimento armazenado que você tem de começar a processar mensagens nesta fila.

• STATUS (Ativação)
  Especifica se o Service Broker inicia o procedimento armazenado. Quando o STATUS = ON, a fila começa o procedimento armazenado especificado com PROCEDURE_NAME quando o número de procedimentos atualmente sendo executados for menos que MAX_QUEUE_READERS e quando as mensagens chegarem à fila mais rápido do que os procedimentos armazenados recebam as mensagens. Quando o STATUS = OFF, a fila não inicia o procedimento armazenado. Se essa cláusula não for especificada, o padrão será ON.

• PROCEDURE_NAME = <procedimento>
  Especifica o nome do procedimento armazenado para começar a processar as mensagens nessa fila. Esse valor deve ser um identificador do SQL Server. Para obter mais informações, consulte Compreendendo quando ocorre a ativação.

• database_name(procedimento)
  É o nome do banco de dados que contém o procedimento armazenado.

• schema_name(procedimento)
  É o nome do esquema que contém o procedimento armazenado.

• procedure_name
  É o nome do procedimento armazenado.

• MAX_QUEUE_READERS **=**max_readers
  Especifica o número máximo de instâncias do procedimento armazenado de ativação que a fila inicia ao mesmo tempo. O valor de max_readers deve ser um número entre 0 e 32767.

• EXECUTE AS
  Especifica o banco de dados da conta do usuário SQL Server sob o qual o procedimento armazenado de ativação é executado. O SQL Server deve ser capaz de verificar as permissões para esse usuário na hora que a fila iniciar o procedimento armazenado. Para um usuário de domínio, o servidor deverá estar conectado ao domínio quando o procedimento armazenado for iniciado ou a ativação falhará. Para um usuário do SQL Server, o servidor sempre pode verificar as permissões.

• SELF
  Especifica que o procedimento armazenado é executado como o usuário atual. (O principal do banco de dados que executa esta instrução CREATE QUEUE.)

• 'user_name'
  É o nome do usuário que o procedimento armazenado usa para ser executado. O parâmetro user_name deve ser um usuário SQL Server válido especificado como um identificador SQL Server. O usuário atual que ter permissão IMPERSONATE para o user_name especificado.

• OWNER
  Especifica que o procedimento armazenado é executado como o proprietário da fila.

• ON filegroup | [DEFAULT]
  Especifica o grupo de arquivos do SQL Server no qual criar esta fila. Você pode usar o parâmetro filegroup para identificar um grupo de arquivos, ou usar o identificador DEFAULT para usar o grupo de arquivos padrão para o banco de dados do Agente de Serviços. No contexto desta cláusula, DEFAULT não é uma palavra-chave e deve ser delimitado como um identificador. Quando nenhum grupo de arquivos for especificado, a fila usará o grupo de arquivos padrão para o banco de dados.

Comentários

Uma fila pode ser o destino de uma instrução SELECT. Entretanto, os conteúdos de uma fila só podem ser modificados usando instruções que operam em conversações do Service Broker, tais como SEND, RECEIVE e END CONVERSATION. Uma fila não pode ser o destino de uma instrução INSERT, UPDATE, DELETE ou TRUNCATE.

Uma fila pode não ser um objeto temporário. Portanto, nomes de fila que iniciam com # não são válidos.

Criando uma fila em um estado inativo lhe permite ter a infra-estrutura pronta para um serviço antes de permitir que as mensagens sejam recebidas na fila.

O Service Broker não parará os procedimentos armazenados de ativação quando não houver nenhuma mensagem na fila. Um procedimento armazenado de ativação deveria sair quando nenhuma mensagem estiver disponível na fila por um período de tempo curto.

As permissões para um procedimento armazenado de ativação são verificadas quando o Service Broker iniciar o procedimento armazenado, não quando a fila for criada. A instrução CREATE QUEUE não verifica que o usuário especificado na cláusula EXECUTE AS tem permissão para executar o procedimento armazenado especificado na cláusula PROCEDURE NAME.

Quando uma fila estiver indisponível, o Service Broker segurará as mensagens para serviços que usem a fila na fila de transmissão para o banco de dados. A exibição do catálogo sys.transmission_queue fornece uma exibição da fila de transmissão.

Uma fila é um objeto possuído por esquema. As filas aparecem na exibição do catálogo sys.objects.

A tabela seguinte lista as colunas em uma fila.

Nome da coluna	Tipo de dados	Descrição
status	tinyint	Status da mensagem. Uma instrução RECEIVE retorna todas as mensagens que têm um status de 1. Se a retenção de mensagens estiver ativada, o status será definido como 0. Se a retenção de mensagens estiver desativada, a mensagem será excluída da fila. As mensagens na fila podem conter um dos seguintes valores: 0=Mensagem recebida retida 1= Pronta para receber 2=Ainda não concluída 3=Mensagem enviada retida
prioridade	tinyint	O nível de prioridade atribuído a esta mensagem.
queuing_order	bigint	Número da ordem da mensagem na fila.
conversation_group_id	uniqueidentifier	O identificador do grupo de conversação a que pertence essa mensagem.
conversation_handle	uniqueidentifier	Tratamento para a conversação da qual esta mensagem faz parte.
message_sequence_number	bigint	Número de seqüência da mensagem na conversação.
service_name	nvarchar(512)	O nome do serviço a que se destina a conversação.
service_id	int	Identificador de objeto SQL Server do serviço para o qual a conversação é destinada.
service_contract_name	nvarchar(256)	O nome do contrato que a conversação segue.
service_contract_id	int	Identificador de objeto SQL Server do contrato que a conversação segue.
message_type_name	nvarchar(256)	O nome do tipo de mensagem a que descreve a mensagem.
message_type_id	int	Identificador de objeto SQL Server do tipo de mensagem que descreve a mensagem.
validation	nchar(2)	Validação usada para a mensagem. E=Vazio N = Nenhum X= XML
message_body	varbinary(MAX)	O conteúdo da mensagem.
message_id	uniqueidentifier	Identificador exclusivo para a mensagem.

Permissões

Permissão para criar uma fila usa os membros da função de banco de dados fixa db_ddladmin ou db_owner e a função de servidor fixa sysadmin.

A permissão para alterar uma rota assume como padrão o proprietário da rota, os membros das funções de banco de dados fixas db_ddladmin ou db_owner e os membros da função de servidor fixa sysadmin.

A permissão RECEIVE para uma fila que tem como padrão o proprietário da fila, os membros da função de banco de dados fixa db_owner e os membros da função de servidor fixa sysadmin.

Exemplos

A. Criando uma fila sem parâmetros

O exemplo seguinte cria uma fila que está disponível para receber mensagens. Nenhum procedimento armazenado de ativação é especificado para a fila.

CREATE QUEUE ExpenseQueue ;

B. Criando uma fila indisponível

O exemplo seguinte cria uma fila que está indisponível para receber mensagens. Nenhum procedimento armazenado de ativação é especificado para a fila.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF ;

C. Criando uma fila e especificando informações de ativação interna

O exemplo seguinte cria uma fila que está disponível para receber mensagens. A fila inicia o procedimento armazenado expense_procedure quando uma mensagem entrar na fila. O procedimento armazenado executa como o usuário ExpenseUser. A fila inicia um máximo de 5 instâncias do procedimento armazenado.

CREATE QUEUE ExpenseQueue
    WITH STATUS=ON,
    ACTIVATION (
        PROCEDURE_NAME = expense_procedure,
        MAX_QUEUE_READERS = 5,
        EXECUTE AS 'ExpenseUser' ) ;

D. Criando uma fila em um grupo de arquivos específico

O exemplo a seguir cria uma fila no grupo de arquivos ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup ;

E. Criando uma fila com vários parâmetros

O exemplo a seguir cria uma fila no grupo de arquivos DEFAULT. A fila está indisponível. As mensagens são retidas na fila até que a conversação a que elas pertençam termine. Quando a fila for deixada disponível por ALTER QUEUE, a fila inicia o procedimento armazenado AdventureWorks.dbo.expense_procedure para processar as mensagens. O procedimento armazenado executa como o usuário que executou a instrução CREATE QUEUE. A fila inicia um máximo de 10 instâncias do procedimento armazenado.

CREATE QUEUE ExpenseQueue
    WITH STATUS = OFF,
      RETENTION = ON,
      ACTIVATION (
          PROCEDURE_NAME = AdventureWorks.dbo.expense_procedure,
          MAX_QUEUE_READERS = 10,
          EXECUTE AS SELF )
    ON [DEFAULT] ;

Consulte também

Referência

ALTER QUEUE (Transact-SQL)

CREATE SERVICE (Transact-SQL)

DROP QUEUE (Transact-SQL)

RECEIVE (Transact-SQL)

EVENTDATA (Transact-SQL)

Conceitos

Filas

Criando aplicativos com o Service Broker

Ativação do Service Broker

Contexto de ativação interna

Tutoriais do Service Broker