RECEIVE (Transact-SQL)

  • Articolo

Recupera uno o più messaggi da una coda. A seconda del periodo di memorizzazione impostato per la coda, questa istruzione rimuove il messaggio dalla coda o aggiorna lo stato del messaggio nella coda.

Sintassi

[ 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
}

Argomenti

  • WAITFOR
    Specifica che l'istruzione RECEIVE deve rimanere in attesa dell'arrivo di un messaggio nella coda, se non sono presenti messaggi.
  • TOP( n )
    Specifica il numero massimo di messaggi da restituire. Se questa clausola viene omessa, vengono restituiti tutti i messaggi corrispondenti ai criteri dell'istruzione.
  • *
    Specifica che il set dei risultati contiene tutte le colonne nella coda.
  • column_name
    Nome di una colonna da includere nel set dei risultati.
  • expression
    Nome di colonna, costante, funzione o qualsiasi combinazione di nomi di colonna, costanti e funzioni concatenati da uno o più operatori.
  • column_alias
    Nome alternativo per sostituire il nome di colonna nel set dei risultati.
  • FROM
    Specifica la coda contenente i messaggi da recuperare.
  • database_name
    Nome del database contenente la coda da cui ricevere i messaggi. Se non si specifica database_name, viene utilizzato per impostazione predefinita il database corrente.
  • schema_name
    Nome dello schema proprietario della coda da cui ricevere i messaggi. Se non si specifica schema_name, viene utilizzato per impostazione predefinita lo schema predefinito dell'utente corrente.
  • queue_name
    Nome della coda da cui ricevere i messaggi.
  • INTO table_variable
    Specifica la tabella in cui inserire le colonne dai messaggi ricevuti.
  • WHERE
    Specifica la conversazione o il gruppo di conversazioni per i messaggi ricevuti. Se la clausola viene omessa, vengono restituiti i messaggi dal successivo gruppo di conversazioni disponibile.
  • conversation_handle = conversation_handle
    Specifica la conversazione per i messaggi ricevuti. Il valore conversation_handle specificato deve essere di tipo uniqueidentifer o di un tipo convertibile in uniqueidentifier.
  • conversation_group_id = conversation_group_id
    Specifica il gruppo di conversazioni per i messaggi ricevuti. Il valore conversation_group_id specificato deve essere di tipo uniqueidentifier o di un tipo convertibile in uniqueidentifier.
  • TIMEOUT timeout
    Specifica l'intervallo di tempo, in millisecondi, per cui l'istruzione deve rimanere in attesa di un messaggio. È possibile utilizzare questa clausola solo insieme alla clausola WAITFOR. Se non si specifica questa clausola o il timeout è -1, il tempo di attesa è illimitato. Alla scadenza del timeout, l'istruzione RECEIVE restituisce un set dei risultati vuoto.

Osservazioni

ms186963.note(it-it,SQL.90).gifImportante:
Se l'istruzione RECEIVE non è la prima istruzione in un batch o in una stored procedure, l'istruzione precedente deve terminare con un punto e virgola (;), ovvero il carattere di terminazione delle istruzioni per Transact-SQL.

L'istruzione RECEIVE legge i messaggi da una coda e restituisce un set dei risultati. Il set dei risultati restituito è composto da zero o più righe, ognuna contenente un singolo messaggio. Se non si utilizza la clausola INTO e il parametro column_specifier non assegna valori a variabili locali, l'istruzione restituisce un set dei risultati al programma chiamante.

L'istruzione RECEIVE rimuove i messaggi ricevuti dalla coda a meno che per la coda non sia specificato un periodo di memorizzazione dei messaggi. Se l'impostazione di RETENTION per la coda è ON, l'istruzione RECEIVE aggiorna la colonna status impostando il valore 1 e lascia i messaggi nella coda. Se viene eseguito il rollback di una transazione che contiene un'istruzione RECEIVE, viene eseguito il rollback anche di tutte le modifiche apportate alla coda nell'ambito della transazione, con conseguente ripristino dei messaggi nella coda.

Tutti i messaggi restituiti da un'istruzione RECEIVE appartengono allo stesso gruppo di conversazioni. L'istruzione RECEIVE blocca il gruppo di conversazioni per i messaggi restituiti fino al completamento della transazione che contiene l'istruzione. Il set dei risultati restituito da un'istruzione RECEIVE viene ordinato in modo implicito. Per una determinata conversazione, l'istruzione RECEIVE restituisce i messaggi con status1 in ordine crescente di message_sequence_number.

Nella clausola WHERE dell'istruzione RECEIVE è possibile includere solo condizioni di ricerca che utilizzano i parametri conversation_handle o conversation_group_id. Nella condizione di ricerca non è consentito inserire nessun'altra colonna della coda. I parametri conversation_handle o conversation_group_id possono non essere un'espressione. Se si omette la clausola WHERE, l'istruzione RECEIVE restituisce i messaggi dal successivo gruppo di conversazioni disponibile, indipendentemente da eventuali blocchi mantenuti attivi dalla connessione corrente su altri gruppi di conversazioni. Se nella clausola WHERE non si specifica un conversation_handle, l'istruzione RECEIVE restituisce i messaggi dal gruppo di conversazioni indipendentemente dalla conversazione a cui appartiene ogni messaggio. Se l'handle di conversazione o l'identificatore del gruppo di conversazioni specificato nella clausola WHERE non esiste oppure non è associato alla coda specificata, l'istruzione RECEIVE restituisce un errore.

Se lo stato della coda specificata nell'istruzione RECEIVE è impostato su OFF, l'istruzione viene interrotta con un errore Transact-SQL.

Se si specifica la clausola WAITFOR, l'istruzione rimane in attesa per il periodo di timeout specificato oppure fino a quando non è disponibile un set dei risultati. Se la coda viene eliminata o lo stato della coda viene impostato su OFF mentre l'istruzione è in attesa, l'istruzione restituisce immediatamente un errore. Se l'istruzione RECEIVE specifica un gruppo di conversazioni o un handle di conversazione e il servizio per tale conversazione viene eliminato o spostato in un'altra coda, l'istruzione RECEIVE segnala un errore Transact-SQL.

RECEIVE non è un'istruzione valida in una funzione definita dall'utente.

Nella tabella seguente vengono elencate le colonne di una coda.

Nome colonna Tipo di dati Descrizione

status

tinyint

Stato del messaggio. Per i messaggi restituiti dal comando RECEIVE, lo stato è sempre 0. I messaggi nella coda possono contenere uno dei valori seguenti:

0=Pronto1=Messaggio ricevuto2=Non ancora completo3=Messaggio inviato memorizzato

priority

tinyint

0. Identificazione a solo scopo informativo. Supporto non fornito. Non è garantita la compatibilità con le versioni future..

queuing_order

bigint

Numero progressivo del messaggio nella coda.

conversation_group_id

uniqueidentifier

Identificatore del gruppo di conversazioni a cui appartiene il messaggio.

conversation_handle

uniqueidentifier

Handle della conversazione di cui fa parte il messaggio.

message_sequence_number

bigint

Numero di sequenza del messaggio nella conversazione.

service_name

nvarchar(512)

Nome del servizio a cui è destinata la conversazione.

service_id

int

Identificatore di oggetto di SQL Server del servizio a cui è destinata la conversazione.

service_contract_name

nvarchar(256)

Nome del contratto rispettato dalla conversazione.

service_contract_id

int

Identificatore di oggetto di SQL Server del contratto rispettato dalla conversazione.

message_type_name

nvarchar(256)

Nome del tipo di messaggio che descrive il messaggio.

message_type_id

int

Identificatore di oggetto di SQL Server del tipo di messaggio che descrive il messaggio.

validation

nchar(2)

Convalida utilizzata per il messaggio.

E=Messaggio vuotoN=Nessuna convalidaX=XML

message_body

varbinary(MAX)

Contenuto del messaggio.

Autorizzazioni

Per ricevere un messaggio, l'utente corrente deve disporre dell'autorizzazione RECEIVE per la coda.

Esempi

A. Ricezione di tutte le colonne di tutti i messaggi in un gruppo di conversazioni

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. L'istruzione restituisce i messaggi in forma di set dei risultati.

RECEIVE * FROM ExpenseQueue ;

B. Ricezione delle colonne specificate per tutti i messaggi in un gruppo di conversazioni

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. L'istruzione restituisce i messaggi in forma di set dei risultati contenente le colonne conversation_handle, message_type_name e message_body.

RECEIVE conversation_handle, message_type_name, message_body
FROM ExpenseQueue ;

C. Ricezione del primo messaggio disponibile nella coda

Nell'esempio seguente, l'istruzione è impostata per la ricezione del primo messaggio disponibile dalla coda ExpenseQueue in forma di set dei risultati.

RECEIVE TOP (1) * FROM ExpenseQueue ;

D. Ricezione di tutti i messaggi per una conversazione specificata

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per la conversazione specificata dalla coda ExpenseQueue in forma di set dei risultati.

DECLARE @conversation_handle UNIQUEIDENTIFIER ;

SET @conversation_handle = <retrieve conversation from database> ;

RECEIVE *
FROM ExpenseQueue
WHERE conversation_handle = @conversation_handle ;

E. Ricezione dei messaggi per un gruppo di conversazioni specificato

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il gruppo di conversazioni specificato dalla coda ExpenseQueue in forma di set dei risultati.

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. Ricezione in una variabile di tabella

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il gruppo di conversazioni specificato dalla coda ExpenseQueue in una variabile di tabella.

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. Ricezione dei messaggi e attesa illimitata

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. L'istruzione attende fino a quando non diventa disponibile almeno un messaggio e quindi restituisce un set dei risultati contenente tutte le colonne del messaggio.

WAITFOR (
    RECEIVE *
    FROM ExpenseQueue) ;

H. Ricezione dei messaggi e attesa per un intervallo di tempo specificato

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. L'istruzione attende 60 secondi o fino a quando non diventa disponibile almeno un messaggio, a seconda dell'evento che viene generato per primo. L'istruzione restituisce un set dei risultati contenente tutte le colonne del messaggio se è disponibile almeno un messaggio. In caso contrario, l'istruzione restituisce un set dei risultati vuoto.

WAITFOR (
    RECEIVE *
    FROM ExpenseQueue ),
TIMEOUT 60000 ;

I. Ricezione dei messaggi con modifica del tipo di una colonna

Nell'esempio seguente, l'istruzione è impostata per la ricezione di tutti i messaggi disponibili per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. Se il tipo di messaggio indica che il messaggio contiene un documento XML, l'istruzione converte il corpo del messaggio in XML.

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. Ricezione di un messaggio con estrazione dei dati dal corpo del messaggio e recupero dello stato della conversazione

Nell'esempio seguente, l'istruzione è impostata per la ricezione del successivo messaggio disponibile per il successivo gruppo di conversazioni disponibile dalla coda ExpenseQueue. Se il messaggio è di tipo //Adventure-Works.com/Expenses/SubmitExpense, l'istruzione estrae l'ID del dipendente e un elenco di elementi dal corpo del messaggio. L'istruzione recupera inoltre lo stato della conversazione dalla tabella ConversationState.

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 ;

Vedere anche

Riferimento

BEGIN DIALOG CONVERSATION (Transact-SQL)
BEGIN CONVERSATION TIMER (Transact-SQL)
END CONVERSATION (Transact-SQL)
SEND (Transact-SQL)
CREATE QUEUE (Transact-SQL)
ALTER QUEUE (Transact-SQL)
DROP QUEUE (Transact-SQL)

Altre risorse

Esercitazioni su Service Broker
Conversation Group Locks
Architettura delle conversazioni

Guida in linea e informazioni

Assistenza su SQL Server 2005