RECEIVE (Transact-SQL)

Sintaxis

[ WAITFOR ( ]
    RECEIVE [ TOP ( n ) ] 
        <column_specifier> [ ,...n ]
        FROM <queue>
        [ INTO table_variable ]
        [ WHERE {  conversation_handle = conversation_handle
                 | conversation_group_id = conversation_group_id } ]
[ ) ] [ , TIMEOUT timeout ]
[ ; ]

<column_specifier> ::=
{    * 
  |  { column_name | [ ] expression } [ [ AS ] column_alias ]
  |  column_alias = expression 
}     [ ,...n ] 

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

Argumentos

• WAITFOR
  Especifica que la instrucción RECEIVE espera a que llegue un mensaje a la cola en caso de no haber ningún mensaje.

• TOP( n )
  Especifica el número máximo de mensajes que se van a devolver. Si no se especifica esta cláusula, se devuelven todos los mensajes que cumplen los criterios de la instrucción.

• *
  Especifica que el conjunto de resultados contiene todas las columnas de la cola.

• column_name
  Nombre de la columna que se va a incluir en el conjunto de resultados.

• expression
  Nombre de columna, constante, función o combinación de nombres de columnas, constantes y funciones conectados mediante un operador.

• column_alias
  Nombre alternativo para reemplazar el nombre de la columna en el conjunto de resultados.

• FROM
  Especifica la cola que contiene los mensajes que se van a recuperar.

• database_name
  Nombre de la base de datos que contiene la cola desde la que se van a recibir los mensajes. Si no se proporciona database name, el valor predeterminado es la base de datos actual.

• schema_name
  Nombre del esquema al que pertenece la cola desde la que se van a recibir los mensajes. Si no se proporciona schema name, se utiliza el esquema predeterminado del usuario actual.

• queue_name
  Nombre de la cola desde la que se reciben los mensajes.

• INTO table_variable
  Especifica la variable de tabla en la que RECEIVE coloca los mensajes. La variable de tabla debe tener el mismo número de columnas que los mensajes. El tipo de datos de cada columna en la variable de tabla debe ser implícitamente convertible al tipo de datos de la columna correspondiente en los mensajes. Si no se especifica INTO, los mensajes se devuelven como un conjunto de resultados.

• WHERE
  Especifica la conversación o grupo de conversación para los mensajes recibidos. Si se omite, se devuelven los mensajes del siguiente grupo de conversación disponible.

• conversation_handle = conversation_handle
  Especifica la conversación para los mensajes recibidos. El valor de conversation handle proporcionado debe ser un uniqueidentifier o un tipo convertible en uniqueidentifier.

• conversation_group_id = conversation_group_id
  Especifica el grupo de conversación para los mensajes recibidos. El valor de conversation group ID that is proporcionado debe ser un uniqueidentifier o un tipo convertible en uniqueidentifier.

• TIMEOUT timeout
  Especifica el tiempo, en milisegundos, durante el que la instrucción espera un mensaje. Esta cláusula sólo se puede utilizar con la cláusula WAITFOR. Si no se especifica esta cláusula o el tiempo de espera es -1, el tiempo de espera es ilimitado. Si se agota el tiempo de espera, RECEIVE devuelve un conjunto de resultados vacío.

Comentarios

Importante
Si la instrucción RECEIVE no es la primera instrucción de un lote o de un procedimiento almacenado, la instrucción anterior deberá finalizar con un punto y coma (;).

La instrucción RECEIVE lee los mensajes de una cola y devuelve un conjunto de resultados. El conjunto de resultados consta de cero o más filas, cada una de las cuales contiene un mensaje. Si no se utiliza la cláusula INTO y column_specifier no asigna valores a las variables locales, la instrucción devuelve un conjunto de resultados al programa que realiza la llamada.

Los mensajes devueltos por la instrucción RECEIVE pueden ser de distintos tipos de mensaje. Las aplicaciones pueden usar la columna message_type_name para enrutar cada mensaje al código que administra el tipo de mensaje asociado. Hay dos clases de tipos de mensaje:

• Tipos de mensaje definidos por la aplicación que se crearon utilizando la instrucción CREATE MESSAGE TYPE. El contrato de Service Broker que se especifica para la conversación define el conjunto de tipos de mensaje definidos por la aplicación que se admiten en una conversación.

• Mensajes de sistema de Service Broker que devuelven información de estado o error. Para obtener más información, vea mensajes del sistema de Broker.

La instrucción RECEIVE quita los mensajes recibidos de la cola a menos que la cola especifique la retención de mensajes. Si el valor RETENTION para la cola está activado, la instrucción RECEIVE actualiza la columna status a 0 y deja los mensajes en la cola. Si se revierte una transacción que contiene la instrucción RECEIVE, también se revierten todos los cambios de la cola de la transacción y se devuelven los mensajes a la cola.

Todos los mensajes devueltos por una instrucción RECEIVE pertenecen al mismo grupo de conversación. La instrucción RECEIVE bloquea el grupo de conversación para los mensajes devueltos hasta que se termina la transacción que contiene la instrucción. Una instrucción RECEIVE devuelve mensajes que tienen un estado de 1. El conjunto de resultados devuelto por la instrucción RECEIVE se ordena de forma implícita:

• Si los mensajes de varias conversaciones cumplen las condiciones de la cláusula WHERE, la instrucción RECEIVE devuelve todos los mensajes de una conversación antes de devolver los mensajes para otras conversaciones. Las conversaciones se procesan en orden de nivel de prioridad descendente.

• Para una conversación determinada, la instrucción RECEIVE devuelve los mensajes en orden message_sequence_number ascendente.

La cláusula WHERE de la instrucción RECEIVE sólo puede contener una condición de búsqueda que use conversation_handle o conversation_group_id. La condición de búsqueda no puede contener una o más columnas de las demás columnas de la cola. conversation_handle o conversation_group_id no pueden ser una expresión. El conjunto de mensajes que se devuelve depende de las condiciones que se especifican en la cláusula WHERE:

• Si se especifica conversation_handle, RECEIVE devuelve todos los mensajes de la conversación especificada que están disponibles en la cola.

• Si se especifica conversation_group_id, RECEIVE devuelve todos los mensajes que están disponibles en la cola de cualquier conversación que forme parte del grupo de conversación especificado.

• Si no hay ninguna cláusula WHERE, RECEIVE determina qué grupo de conversación:

  • Tiene uno o más mensajes en la cola.

  • No ha sido bloqueado por otra instrucción RECEIVE.

  • Tiene el nivel de prioridad más alto de todos los grupos de conversación que cumplen estos criterios.

  A continuación, RECEIVE devuelve todos los mensajes disponibles en la cola de cualquier conversación que forme parte del grupo de conversación seleccionado.

Si el identificador de conversación o el identificador del grupo de conversación especificado en la cláusula WHERE no existe o no está asociado a la cola especificada, la instrucción RECEIVE devuelve un error.

Si la cola especificada en la instrucción RECEIVE tiene el estado de cola establecido en OFF, la instrucción genera un error de Transact-SQL.

Si se especifica la cláusula WAITFOR, la instrucción espera a que se agote el tiempo de espera especificado o hasta que haya un conjunto de resultados disponible. Si se quita la cola o su estado se establece en OFF mientras la instrucción está esperando, dicha instrucción devuelve un error de inmediato. Si la instrucción RECEIVE especifica un grupo de conversación o un identificador de conversación y se quita o se mueve el servicio para dicha conversación a otra cola, la instrucción RECEIVE notifica de un error de Transact-SQL.

RECEIVE no tiene validez en una función definida por el usuario.

La instrucción RECEIVE no tiene ninguna prevención de colapso de la prioridad. Si una instrucción RECEIVE única bloquea un grupo de conversación y recupera muchos mensajes de conversaciones de prioridad baja, no se podrá recibir ningún mensaje de las conversaciones de prioridad alta del grupo. Para evitar esto, cuando recupere mensajes de conversaciones de prioridad baja, utilice la cláusula TOP para limitar el número de mensajes recuperados por cada instrucción RECEIVE.

Poner las columnas en una cola

La siguiente tabla enumera las columnas que contiene una cola:

Permisos

Para recibir un mensaje, el usuario actual debe tener el permiso RECEIVE en la cola.

Ejemplos

A. Recibir todas las columnas para todos los mensajes en un grupo de conversación

RECEIVE * FROM ExpenseQueue ;

B. Recibir las columnas especificadas para todos los mensajes en un grupo de conversación

RECEIVE conversation_handle, message_type_name, message_body
FROM ExpenseQueue ;

C. Recibir el primer mensaje disponible en la cola

RECEIVE TOP (1) * FROM ExpenseQueue ;

D. Recibir todos los mensajes para una conversación especificada

DECLARE @conversation_handle UNIQUEIDENTIFIER ;

SET @conversation_handle = <retrieve conversation from database> ;

RECEIVE *
FROM ExpenseQueue
WHERE conversation_handle = @conversation_handle ;

E. Recibir mensajes para un grupo de conversación especificado

DECLARE @conversation_group_id UNIQUEIDENTIFIER ;

SET @conversation_group_id = 
    <retrieve conversation group ID from database> ;

RECEIVE *
FROM ExpenseQueue
WHERE conversation_group_id = @conversation_group_id ;

F. Recibir en una variable de tabla

DECLARE @conversation_group_id UNIQUEIDENTIFIER ;

DECLARE @procTable TABLE(
     service_instance_id UNIQUEIDENTIFIER,
     handle UNIQUEIDENTIFIER,
     message_sequence_number BIGINT,
     service_name NVARCHAR(512),
     service_contract_name NVARCHAR(256),
     message_type_name NVARCHAR(256),
     validation NCHAR,
     message_body VARBINARY(MAX)) ;

SET @conversation_group_id = <retrieve conversation group ID from database> ;

RECEIVE TOP (1)
    conversation_group_id,
    conversation_handle,
    message_sequence_number,
    service_name,
    service_contract_name,
    message_type_name,
    validation,
    message_body
FROM ExpenseQueue
INTO @procTable
WHERE conversation_group_id = @conversation_group_id ;

G. Recibir mensajes y esperar indefinidamente

WAITFOR (
    RECEIVE *
    FROM ExpenseQueue) ;

H. Recibir mensajes y esperar durante un intervalo especificado

WAITFOR (
    RECEIVE *
    FROM ExpenseQueue ),
TIMEOUT 60000 ;

I. Recibir mensajes y modificar el tipo de columna

WAITFOR (
    RECEIVE message_type_name,
        CASE
            WHEN validation = 'X' THEN CAST(message_body as XML)
            ELSE NULL
         END AS message_body 
         FROM ExpenseQueue ),
TIMEOUT 60000 ;

J. Recibir un mensaje, extraer los datos del cuerpo del mensaje y recuperar el estado de la conversación

WAITFOR(
    RECEIVE 
    TOP(1)
      message_type_name,
      COALESCE(
           (SELECT TOP(1) ConversationState
            FROM CurrentConversations AS cc
            WHERE cc.ConversationHandle = conversation_handle),
           'NEW')
      AS ConversationState,
      COALESCE(
          (SELECT TOP(1) ErrorCount
           FROM CurrentConversations AS cc
           WHERE cc.ConversationHandle = conversation_handle), 
           0)
      AS ConversationErrors,
      CASE WHEN message_type_name = N'//Adventure-Works.com/Expenses/SubmitExpense'
          THEN CAST(message_body AS XML).value(
                'declare namespace rpt = "http://Adventure-Works.com/schemas/expenseReport"
                   (/rpt:ExpenseReport/rpt:EmployeeID)[1]', 'nvarchar(20)')
         ELSE NULL
      END AS EmployeeID,
      CASE WHEN message_type_name = N'//Adventure-Works.com/Expenses/SubmitExpense'
          THEN CAST(message_body AS XML).query(
                'declare namespace rpt = "http://Adventure-Works.com/schemas/expenseReport" 
                     /rpt:ExpenseReport/rpt:ItemDetail')
          ELSE NULL
      END AS ItemList
    FROM ExpenseQueue 
), TIMEOUT 60000 ;

Vea también

Referencia

Conceptos