CREATE QUEUE (Transact-SQL)

Crea una nueva cola en una base de datos. Las colas almacenan mensajes. Cuando llega un mensaje para un servicio, Service Broker lo coloca en la cola asociada a ese servicio.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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)
  Es el nombre de la base de datos en que se crea la nueva cola. database_name debe especificar el nombre de una base de datos existente. Si no se proporciona database_name, la cola se crea en la base de datos actual.

• schema_name (objeto)
  Nombre del esquema al que pertenece la nueva cola. El valor predeterminado del esquema es el esquema predeterminado del usuario que ejecuta la instrucción. Si un miembro de la función fija de servidor sysadmin o un miembro de las funciones de base de datos fija db_dbowner o db_ddladmin ejecuta la instrucción CREATE QUEUE en la base de datos que especifica database_name, schema_name puede especificar un esquema diferente al asociado con el inicio de sesión de la conexión actual. De no ser así, el valor de schema_name debe ser el esquema predeterminado del usuario que ejecuta la instrucción.

• queue_name
  Nombre de la cola que se va a crear. Este nombre debe cumplir las directrices de los identificadores de SQL Server.

• STATUS (cola)
  Especifica si la cola está disponible (ON) o no (OFF). Cuando la cola no está disponible, no pueden agregarse mensajes a ella ni tampoco quitarse. Puede crear la cola en un estado de no disponibilidad para impedir que lleguen mensajes a ésta hasta que la cola esté disponible mediante una instrucción ALTER QUEUE. Si se pasa por alto esta cláusula, el valor predeterminado es ON y la cola estará disponible.

• RETENTION
  Especifica la configuración de retención para la cola. Si RETENTION = ON, todos los mensajes enviados o recibidos relativos a conversaciones que utilizan esta cola se retendrán en ella hasta que finalicen las conversaciones. Esto permite retener mensajes con fines de auditoría o para realizar transacciones de compensación si se produce un error. Si no se especifica esta cláusula, el valor predeterminado de retención es OFF.

  [!NOTA]

  El rendimiento puede disminuir si se establece RETENTION en ON. Utilice este valor sólo si lo requiere la aplicación. Para obtener más información, vea Retención de mensajes.

• ACTIVATION
  Especifica información sobre qué procedimiento almacenado es necesario iniciar para procesar los mensajes de esta cola.

• STATUS (activación)
  Especifica si Service Broker inicia el procedimiento almacenado. Si STATUS = ON, la cola inicia el procedimiento almacenado especificado con PROCEDURE_NAME cuando el número de procedimientos que se ejecutan actualmente es menor que MAX_QUEUE_READERS y cuando los mensajes llegan a la cola antes de que los procedimientos almacenados reciban mensajes. Si STATUS = OFF, la cola no inicia el procedimiento almacenado. Si no se especifica esta cláusula, el valor predeterminado es ON.

• PROCEDURE_NAME = <procedure>
  Especifica el nombre del procedimiento almacenado que es necesario iniciar para procesar mensajes en esta cola. Este valor debe ser un identificador de SQL Server. Para obtener más información, vea Entender cuándo se produce la activación.

• database_name(procedure)
  Nombre de la base de datos que contiene el procedimiento almacenado.

• schema_name(procedure)
  Es el nombre del esquema que contiene el procedimiento almacenado.

• procedure_name
  Nombre del procedimiento almacenado.

• MAX_QUEUE_READERS **=**max_readers
  Especifica el número máximo de instancias del procedimiento almacenado de activación que la cola inicia al mismo tiempo. El valor de max_readers debe ser un número comprendido entre 0 y 32767.

• EXECUTE AS
  Especifica la cuenta de usuario de base de datos de SQL Server en la que se ejecuta el procedimiento almacenado de activación. SQL Server debe poder comprobar los permisos de este usuario en el momento en que la cola inicia el procedimiento almacenado. En el caso de un usuario de dominio, el servidor debe estar conectado al dominio cuando se inicie el procedimiento o se producirá un error en la activación. En usuarios de SQL Server, el servidor siempre puede comprobar los permisos.

• SELF
  Especifica que el procedimiento almacenado se ejecuta como el usuario actual. Es la entidad de seguridad de base de datos que ejecuta esta instrucción CREATE QUEUE.

• 'user_name'
  Es el nombre del usuario con el que se ejecuta el procedimiento almacenado. El parámetro user_name debe ser un usuario de SQL Server válido especificado como identificador de SQL Server. El usuario actual debe tener el permiso IMPERSONATE para el valor de user_name especificado.

• OWNER
  Especifica que el procedimiento almacenado se ejecuta como el propietario de la cola.

• ON filegroup | [DEFAULT]
  Especifica el grupo de archivos de SQL Server en que se va a crear esta cola. Puede utilizar el parámetro filegroup para identificar un grupo de archivos, o utilizar el identificador DEFAULT para usar el grupo de archivos predeterminado de la base de datos de Service Broker. En el contexto de esta cláusula, DEFAULT no es una palabra clave y debe delimitarse como un identificador. Si no se especifica ningún grupo de archivos, la cola utiliza el grupo de archivos predeterminado de la base de datos.

Notas

Una cola puede ser el destino de una instrucción SELECT. No obstante, el contenido de una cola sólo puede modificarse mediante instrucciones que funcionan en conversaciones de Service Broker, como SEND, RECEIVE y END CONVERSATION. Una cola no puede ser el destino de una instrucción INSERT, UPDATE, DELETE o TRUNCATE.

Una cola no puede ser un objeto temporal. Por lo tanto, los nombres de cola que empiecen por # no son válidos.

Si crea una cola en estado inactivo, puede obtener la infraestructura de un servicio antes de permitir que los mensajes se reciban en la cola.

Service Broker no detiene los procedimientos almacenados de activación si no hay ningún mensaje en la cola. Un procedimiento almacenado de activación debe finalizar cuando no haya ningún mensaje disponible en la cola durante un breve período de tiempo.

Los permisos para el procedimiento almacenado de activación se comprueban cuando Service Broker inicia el procedimiento almacenado, no cuando se crea la cola. La instrucción CREATE QUEUE no comprueba que el usuario especificado en la cláusula EXECUTE AS tenga permiso para ejecutar el procedimiento almacenado especificado en la cláusula PROCEDURE NAME.

Cuando una cola no está disponible, Service Broker retiene los mensajes para los servicios que utilizan la cola en la cola de transmisión para la base de datos. La vista de catálogo sys.transmission_queue proporciona una vista de la cola de transmisión.

Una cola es un objeto propiedad de un esquema. Las colas aparecen en la vista de catálogo sys.objects.

La siguiente tabla contiene las columnas de una cola.

Nombre de columna	Tipo de datos	Descripción
status	tinyint	Estado del mensaje. La instrucción RECEIVE devuelve todos los mensajes que tienen 1 como estado. Si la retención de los mensajes está activada, el estado se establece en 0. Si está desactivada, el mensaje se elimina de la cola. Los mensajes de la cola pueden contener uno de los valores siguientes: 0=Mensaje recibido retenido 1=Listo para recibir 2=Sin completar 3=Mensaje enviado retenido
priority	tinyint	Nivel de prioridad asignado a este mensaje.
queuing_order	bigint	Número de orden del mensaje en la cola.
conversation_group_id	uniqueidentifier	Identificador para el grupo de conversación al que pertenece este mensaje.
conversation_handle	uniqueidentifier	Identificador para la conversación de la que forma parte este mensaje.
message_sequence_number	bigint	Número de secuencia del mensaje en la conversación.
service_name	nvarchar(512)	Nombre del servicio al que se destina la conversación.
service_id	int	Identificador de objeto de SQL Server del servicio al que se destina la conversación.
service_contract_name	nvarchar(256)	Nombre del contrato por el que se rige la conversación.
service_contract_id	int	Identificador de objeto de SQL Server del contrato por el que se rige la conversación.
message_type_name	nvarchar(256)	Nombre del tipo de mensaje que describe el mensaje.
message_type_id	int	Identificador de objeto de SQL Server del tipo de mensaje que describe el mensaje.
validation	nchar(2)	Validación utilizada para el mensaje. E=Vacío N=Ninguno X=XML
message_body	varbinary(MAX)	Contenido del mensaje.
message_id	uniqueidentifier	Identificador único para el mensaje.

Permisos

Tienen permiso para crear una cola los miembros de las funciones fijas de la base de datos db_ddladmin o db_owner y la función fija del servidor sysadmin.

De forma predeterminada, tienen permiso REFERENCES en una cola el propietario de ésta, los miembros de las funciones fijas de la base de datos db_ddladmin o db_owner y los miembros de la función fija del servidor sysadmin.

De forma predeterminada, tienen permiso RECEIVE en una cola el propietario de ésta, los miembros de la función de base de datos fija db_owner y los miembros de la función fija de servidor sysadmin.

Ejemplos

A. Crear una cola sin parámetros

En el siguiente ejemplo se crea una cola que está disponible para recibir mensajes. No se especifica ningún procedimiento almacenado de activación para la cola.

CREATE QUEUE ExpenseQueue ;

B. Crear una cola no disponible

En el siguiente ejemplo se crea una cola que no está disponible para recibir mensajes. No se especifica ningún procedimiento almacenado de activación para la cola.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF ;

C. Crear una cola y especificar información de activación interna

En el siguiente ejemplo se crea una cola que está disponible para recibir mensajes. La cola inicia el procedimiento almacenado expense_procedure cuando un mensaje entra en la cola. El procedimiento almacenado se ejecuta como el usuario ExpenseUser. La cola inicia un máximo de 5 instancias del procedimiento almacenado.

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

D. Crear una cola en un grupo de archivos específico

En el siguiente ejemplo se crea una cola en el grupo de archivos ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup ;

E. Crear una cola con varios parámetros

En el siguiente ejemplo se crea una cola en el grupo de archivos DEFAULT. La cola no está disponible. Los mensajes se retienen en la cola hasta que finaliza la conversación a la que pertenecen. Cuando la cola pasa a estar disponible mediante ALTER QUEUE, la cola inicia el procedimiento almacenado AdventureWorks.dbo.expense_procedure para procesar los mensajes. El procedimiento almacenado se ejecuta como el usuario que ejecutó la instrucción CREATE QUEUE. La cola inicia un máximo de 10 instancias del procedimiento almacenado.

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

Vea también

Referencia

ALTER QUEUE (Transact-SQL)

CREATE SERVICE (Transact-SQL)

DROP QUEUE (Transact-SQL)

RECEIVE (Transact-SQL)

EVENTDATA (Transact-SQL)

Conceptos

Colas

Generar aplicaciones con Service Broker

Activación de Service Broker

Contexto de activación interna

Tutoriales de Service Broker