ALTER QUEUE (Transact-SQL)

Cambia las propiedades de una cola.

Convenciones de sintaxis de Transact-SQL

Sintaxis

ALTER 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 } ]
       |  DROP }
          ) ] 
[ ; ]

<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 que contiene la cola que se va a cambiar. Si no se proporciona database_name, el valor predeterminado es la base de datos actual.

• schema_name (object)
  Nombre del esquema al que pertenece la nueva cola. Si no se proporciona schema_name, se utiliza el esquema predeterminado del usuario actual.

• queue_name
  Es el nombre de la cola que se va a cambiar.

• 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.

• 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.

  [!NOTA]

  El rendimiento puede disminuir si se establece RETENTION en ON. Esta configuración sólo debe utilizarse si es necesario satisfacer el acuerdo de nivel de servicio para la aplicación.

• ACTIVATION
  Especifica información acerca del procedimiento almacenado que se activa para procesar mensajes que llegan a esta cola.

• STATUS (activación)
  Especifica si una cola 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.

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

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

• schema_name (procedimiento)
  Nombre del esquema que tiene la propiedad del procedimiento almacenado.

• stored_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 simultáneamente. El valor de max_readers debe ser un número comprendido entre 0 y 32767.

• EXECUTE AS
  Especifica la cuenta de usuario de la 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. Para un usuario de dominio de Windows, SQL Server debe estar conectado al dominio y debe poder validar los permisos del usuario especificado cuando se active el procedimiento o la activación genere un error. 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 ALTER QUEUE.

• 'user_name'
  Es el nombre de usuario con el que se ejecuta el procedimiento almacenado. user_name debe ser un usuario válido de SQL Server especificado como un 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.

• DROP
  Elimina toda la información de activación asociada a la cola.

Notas

Cuando una cola que tiene especificado un procedimiento almacenado de activación contiene mensajes, al cambiar el estado de activación de OFF a ON, se activa inmediatamente el procedimiento almacenado de activación. Cambiar el estado de activación de ON a OFF impide que el broker active instancias del procedimiento almacenado, pero las instancias que están en ejecución no se detienen.

Modificar una cola para agregar un procedimiento almacenado de activación no afecta al estado de activación de la cola. Modificar el procedimiento almacenado de activación de la cola no afecta a las instancias del procedimiento almacenado de activación que se estén ejecutando en el momento actual.

Service Broker comprueba el número máximo de lectores de cola como parte del proceso de activación. Por tanto, si se modifica una cola para aumentar el número máximo de lectores de cola, Service Broker iniciará inmediatamente más instancias del procedimiento almacenado de activación. Modificar una cola para reducir el número máximo de lectores de cola no afecta a las instancias del procedimiento almacenado de activación que se estén ejecutando en el momento actual. No obstante, Service Broker no inicia ninguna nueva instancia del procedimiento almacenado hasta que el número de instancias del procedimiento almacenado de activación sea inferior al número máximo configurado. Para obtener una descripción más detallada del proceso de activación, vea Entender cuándo se produce la activación.

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.

Si las instrucciones RECEIVE o GET CONVERSATION GROUP especifican una cola que no está disponible, generarán un error de Transact-SQL.

Permisos

De forma predeterminada, se concede permiso para modificar una cola al propietario de la cola, a los miembros de las funciones fijas de base de datos db_ddladmin o db_owner y a los miembros de la función fija de servidor sysadmin.

Ejemplos

A. Hacer que una cola no esté disponible

En el ejemplo siguiente se hace que la cola de ExpenseQueue no esté disponible para recibir mensajes.

ALTER QUEUE ExpenseQueue WITH STATUS = OFF ;

B. Cambiar el procedimiento almacenado de activación

En el siguiente ejemplo se muestra cómo cambiar el procedimiento almacenado iniciado por la cola. El procedimiento almacenado se ejecuta como el usuario que ejecutó la instrucción ALTER QUEUE.

ALTER QUEUE ExpenseQueue
    WITH ACTIVATION (
        PROCEDURE_NAME = new_stored_proc,
        EXECUTE AS SELF) ;

C. Cambiar el número de lectores de cola

En el ejemplo siguiente se establece en 7 el número máximo de instancias de procedimiento almacenado que inicia Service Broker para esta cola.

ALTER QUEUE ExpenseQueue WITH ACTIVATION (MAX_QUEUE_READERS = 7) ;

D. Cambiar el procedimiento almacenado de activación y la cuenta EXECUTE AS

En el ejemplo siguiente se cambia el procedimiento almacenado iniciado por Service Broker. El procedimiento almacenado se ejecuta con el usuario SecurityAccount.

ALTER QUEUE ExpenseQueue
    WITH ACTIVATION (
        PROCEDURE_NAME = AdventureWorks.dbo.new_stored_proc ,
        EXECUTE AS 'SecurityAccount') ;

E. Configurar la cola para retener mensajes

En el siguiente ejemplo se muestra cómo configurar la cola para retener mensajes. La cola retiene todos los mensajes enviados a o desde los servicios que utilizan la cola hasta que la conversación que contiene el mensaje finaliza.

ALTER QUEUE ExpenseQueue WITH RETENTION = ON ;

F. Quitar la activación de una cola

En el siguiente ejemplo se muestra cómo quitar toda la información de activación de la cola.

ALTER QUEUE ExpenseQueue WITH ACTIVATION (DROP) ;

Vea también

Referencia

CREATE QUEUE (Transact-SQL)

DROP QUEUE (Transact-SQL)

EVENTDATA (Transact-SQL)

Conceptos

Colas

Activación de Service Broker

Contexto de activación interna