CREATE QUEUE (Transact-SQL)

Artículo
12/15/2008

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

Icono de vínculo a temas 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)
Nombre de la base de datos en que se va a crear 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 (object)
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 fijas de base de datos db_dbowner o db_ddladmin ejecuta la instrucción CREATE QUEUE en la base de datos especificada por 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 que se especifique 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 se convierta en 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 hasta que las conversaciones finalicen. 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 Message Retention.

ACTIVATION
Especifica información sobre la activación del procedimiento almacenado para procesar mensajes en esta cola.

STATUS (activación)
Especifica si Service Broker activa o no 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 activa 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 se va a activar para procesar mensajes en esta cola. Este valor debe ser un identificador de SQL Server. Para obtener más información, vea Understanding When Activation Occurs.

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 activa el procedimiento almacenado. En el caso de un usuario de dominio, el servidor debe estar conectado al dominio cuando se active 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. Debe existir un procedimiento almacenado de activación cuando no hay 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 activa 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. Para los mensajes devueltos por el comando RECEIVE, el estado es siempre 1. Los mensajes de la cola pueden contener uno de los siguientes valores: 0=Mensaje recibido 1=Preparado 2=Sin completar 3=Mensaje enviado retenido
priority	tinyint	Reservado para uso futuro.
queuing_order	bigint	Número de orden de los mensajes 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

De forma predeterminada, tienen permiso para crear una cola los miembros de las funciones fijas de base de datos db_ddladmin o db_owner y la función fija de servidor sysadmin.

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

De forma predeterminada, tienen permiso RECEIVE en una cola el propietario de ésta, los miembros de la función fija de base de datos 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 activa 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

Compartir a través de