RAISERROR (Transact-SQL)

Sintassi

RAISERROR ( { msg_id | msg_str | @local_variable }
    { ,severity ,state }
    [ ,argument [ ,...n ] ] )
    [ WITH option [ ,...n ] ]

Argomenti

• msg_id
  Numero del messaggio di errore definito dall'utente archiviato nella vista del catalogo sys.messages tramite sp_addmessage. I numeri di errore per i messaggi di errore definiti dall'utente devono essere maggiori di 50000. Se msg_id viene omesso, RAISERROR genera un messaggio di errore con numero di errore pari a 50000.

• msg_str
  Messaggio definito dall'utente con formattazione simile alla funzione printf nella libreria standard del C. Il messaggio di errore può contenere un massimo di 2.047 caratteri. Se contiene più di 2.048 caratteri, vengono visualizzati solo i primi 2.044 e vengono aggiunti tre punti a indicare che il messaggio è stato troncato. I parametri di sostituzione utilizzano un maggior numero di caratteri rispetto a quanto viene visualizzato nell'output a causa della gestione dell'archiviazione interna. Ad esempio, il parametro di sostituzione %d con un valore assegnato di 2 genera effettivamente un carattere nella stringa del messaggio, ma internamente occupa fino a tre caratteri aggiuntivi dell'archivio. Questo requisito a livello di archiviazione riduce il numero di caratteri disponibili per l'output del messaggio.

  Se si specifica msg_str, RAISERROR genera un messaggio di errore con numero di errore pari a 50000.

  msg_str è una stringa di caratteri con specifiche di conversione incorporate facoltative. Ogni specifica di conversione definisce come un valore nell'elenco di argomenti viene formattato e inserito in un campo in corrispondenza della posizione della specifica di conversione definita in msg_str. Le specifiche di conversione sono caratterizzate dal formato seguente:

  % [[flag] [width] [. precision] [{h | l}]] type

  I parametri utilizzabili nell'argomento msg_str sono i seguenti:

• flag

  Codice che determina la spaziatura e l'allineamento del valore sostituito.

  Codice	Prefisso o allineamento	Descrizione
  - (meno)	Allineamento a sinistra	Allinea a sinistra il valore dell'argomento entro la larghezza dei campi specificata.
  + (più)	Segno (prefisso)	Inserisce il segno più (+) o meno (–) all'inizio del valore dell'argomento se il valore è di tipo con segno.
  0 (zero)	Riempimento con zeri	Inserisce nell'output il numero necessario di zero fino al raggiungimento della larghezza minima. Se sono stati specificati 0 e il segno meno (-), 0 viene ignorato.
  # (simbolo di cancelletto)	Prefisso 0x per tipi esadecimali di x o di X	Quando viene utilizzato con il formato o, x o X, il simbolo di cancelletto (#) inserisce rispettivamente i caratteri 0, 0x o 0X all'inizio di qualsiasi valore diverso da zero. Il simbolo di cancelletto (#) viene ignorato se utilizzato come prefisso di d, i oppure u.
  ' ' (spazio)	Riempimento con spazi	Inserisce spazi vuoti all'inizio di un valore con segno positivo. Viene ignorato quando è specificato con il segno più (+).

• width

  Valore integer che definisce la larghezza minima del campo nel quale viene inserito il valore dell'argomento. Se la lunghezza del valore dell'argomento è maggiore o uguale a width, il valore viene stampato senza alcun riempimento. Se invece è minore di width, al valore vengono aggiunti caratteri fino a raggiungere la lunghezza specificata in width.

  Un asterisco (*) indica che la larghezza viene specificata dall'argomento associato nell'elenco di argomenti, che deve essere un valore integer.

• precision

  Numero massimo di caratteri recuperati dal valore dell'argomento per i valori stringa. Se, ad esempio, una stringa include cinque carattere e la precisione è stata impostata su 3, vengono utilizzati solo i primi tre caratteri del valore stringa.

  Per i valori integer precision definisce il numero minimo di cifre stampate.

  Un asterisco (*) indica che la precisione viene specificata dall'argomento associato nell'elenco di argomenti, che deve essere un valore integer.

• {h | l} type

  Viene utilizzato con tipi d, i, o, s, x, X, u e consente di creare valori shortint (h) o longint (l).

  Specifica del tipo	Rappresenta
  d o i	Valori integer con segno
  o	Ottale senza segno
  s	Stringa
  u	Valori integer senza segno
  x o X	Valori esadecimali senza segno

  [!NOTA]

  Queste specifiche del tipo si basano su quelle originariamente definite per la funzione printf nella libreria standard C. Le specifiche del tipo utilizzate nelle stringhe di messaggio di RAISERROR sono associate ai tipi di dati Transact-SQL, mentre le specifiche utilizzate in printf sono associate ai tipi di dati del linguaggio C. Le specifiche del tipo utilizzate in printf non sono supportate da RAISERROR se Transact-SQL non dispone di un tipo di dati simile al tipo di dati C associato. Ad esempio, la specifica %p per i puntatori non è supportata in RAISERROR perché in Transact-SQL non è disponibile un tipo di dati puntatore.

  [!NOTA]

  Per convertire un valore nel tipo di dati bigint di Transact-SQL, specificare %I64d.

• **@**local_variable
  Variabile di qualsiasi tipo di dati character valido contenente una stringa con la stessa formattazione di msg_str. **@**local_variable deve essere di tipo char o varchar oppure di un tipo che possa essere convertito in questi tipi di dati.

• severity
  Livello di gravità definito dall'utente associato al messaggio. In caso di utilizzo di msg_id per generare un messaggio definito dall'utente creato tramite sp_addmessage, la gravità specificata in RAISERROR ha la priorità sulla gravità specificata in sp_addmessage.

  I livelli di gravità da 0 a 18 possono essere specificati da qualsiasi utente, mentre i livelli di gravità da 19 a 25 possono essere specificati solo dai membri del ruolo predefinito del server sysadmin oppure dagli utenti che dispongono dell'autorizzazione ALTER TRACE. I livelli di gravità da 19 a 25 richiedono l'opzione WITH LOG.

  Attenzione
  I livelli di gravità da 20 a 25 sono considerati irreversibili. Se viene rilevato un livello di gravità irreversibile, la connessione del client viene interrotta dopo la ricezione del messaggio e l'errore viene registrato nel log degli errori e nel registro applicazioni.

  [!NOTA]

  I livelli di gravità minori di 0 vengono interpretati come 0, mentre quelli maggiori di 25 vengono interpretati come 25.

• state
  Valore integer compreso tra 0 e 255. Valori negativi o maggiori di 255 generano un errore.

  Se in più posizioni viene generato lo stesso errore definito dall'utente, lo stesso numero di stato univoco per ogni posizione può semplificare l'individuazione della sezione di codice in cui si sono verificati gli errori.

• argument
  Parametri utilizzati nella sostituzione delle variabili definite in msg_str oppure messaggio corrispondente a msg_id. Possono essere presenti 0 o più parametri di sostituzione, ma il numero complessivo di tali parametri non può essere maggiore di 20. Ogni parametro di sostituzione può essere una variabile locale di uno dei tipi di dati tinyint, smallint, int, char, varchar, nchar, nvarchar, binary o varbinary. Non sono supportati altri tipi di dati.

• option
  Opzione personalizzata per l'errore. Può essere uno dei valori riportati nella tabella seguente.

  Valore	Descrizione
  LOG	Registra l'errore nel log degli errori e nel registro applicazioni per l'istanza di Motore di database di MicrosoftSQL Server. Gli errori registrati nel log degli errori non possono superare i 440 byte. Solo i membri del ruolo predefinito del server sysadmin oppure gli utenti che dispongono dell'autorizzazione ALTER TRACE possono specificare WITH LOG.
  NOWAIT	Invia i messaggi direttamente al client.
  SETERROR	Imposta i valori di @@ERROR e ERROR_NUMBER su msg_id o 50000, indipendentemente dal livello di gravità.

Osservazioni

Gli errori generati da RAISERROR hanno le stesse caratteristiche degli errori generati dal codice di Motore di database. I valori specificati da RAISERROR sono restituiti dalle funzioni di sistema ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE e @@ERROR. Se si esegue RAISERROR con un livello di gravità maggiore o uguale a 11 in un blocco TRY, il controllo viene trasferito al blocco CATCH associato. L'errore viene restituito al chiamante se RAISERROR viene eseguito:

• All'esterno dell'ambito di qualsiasi blocco TRY.

• Con una gravità minore o uguale a 10 in un blocco TRY.

• Con una gravità maggiore o uguale a 20; in questo caso la connessione al database viene terminata.

I blocchi CATCH possono utilizzare RAISERROR per generare nuovamente l'errore che ha richiamato il blocco CATCH mediante l'utilizzo di funzioni di sistema quali ERROR_NUMBER e ERROR_MESSAGE per recuperare le informazioni sull'errore di origine. Per impostazione predefinita, @@ERROR è impostato su 0 per i messaggi con livello di gravità compreso tra 1 e 10. Per ulteriori informazioni, vedere Utilizzo di TRY...CATCH in Transact-SQL.

Se msg_id specifica un messaggio definito dall'utente disponibile nella vista del catalogo sys.messages, RAISERROR elabora il messaggio dalla colonna di testo utilizzando le stesse regole applicate al testo di un messaggio definito dall'utente specificato tramite msg_str. Il testo del messaggio definito dall'utente può contenere specifiche di conversione; RAISERROR eseguirà il mapping dei valori degli argomenti in base a tali specifiche di conversione. Utilizzare le stored procedure sp_addmessage e sp_dropmessage rispettivamente per aggiungere ed eliminare i messaggi di errore definiti dall'utente.

RAISERROR può essere utilizzato in alternativa a PRINT per restituire i messaggi alle applicazioni di chiamata. RAISERROR supporta la sostituzione dei caratteri in modo analogo alla funzionalità printf nella libreria standard del C, al contrario dell'istruzione Transact-SQL PRINT. L'istruzione PRINT non è interessata dai blocchi TRY, mentre un'istruzione RAISERROR eseguita con un livello di gravità da 11 a 19 in un blocco TRY trasferisce il controllo al blocco CATCH associato. Specificare un livello di gravità minore o uguale a 10 per utilizzare RAISERROR per restituire un messaggio da un blocco TRY senza richiamare il blocco CATCH.

In genere gli argomenti successivi sostituiscono le specifiche di conversione successive, ovvero il primo argomento sostituisce la prima specifica di conversione, il secondo argomento sostituisce la seconda specifica di conversione e così via. Nell'istruzione RAISERROR seguente, ad esempio, il primo argomento N'number' sostituisce la prima specifica di conversione %s; mentre il secondo argomento 5 sostituisce la seconda specifica di conversione %d.

RAISERROR (N'This is message %s %d.', -- Message text.
           10, -- Severity,
           1, -- State,
           N'number', -- First argument.
           5); -- Second argument.
-- The message text returned is: This is message number 5.
GO

Se per la larghezza o la precisione di una specifica di conversione viene specificato un asterisco (*), il valore da utilizzare per la larghezza o la precisione viene specificato come valore integer dell'argomento. In questo caso, una specifica di conversione può utilizzare fino a tre argomenti, ovvero uno per la larghezza, uno per la precisione e uno per il valore di sostituzione.

Entrambe le istruzioni RAISERROR seguenti, ad esempio, restituiscono la stessa stringa. In una vengono inseriti i valori di larghezza e di precisione nell'elenco degli argomenti, mentre nell'altra tali valori vengono definiti nella specifica di conversione.

RAISERROR (N'<<%*.*s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           7, -- First argument used for width.
           3, -- Second argument used for precision.
           N'abcde'); -- Third argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
RAISERROR (N'<<%7.3s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

Esempi

A. Restituzione delle informazioni sull'errore da un blocco CATCH

BEGIN TRY
    -- RAISERROR with severity 11-19 will cause execution to 
    -- jump to the CATCH block.
    RAISERROR ('Error raised in TRY block.', -- Message text.
               16, -- Severity.
               1 -- State.
               );
END TRY
BEGIN CATCH
    DECLARE @ErrorMessage NVARCHAR(4000);
    DECLARE @ErrorSeverity INT;
    DECLARE @ErrorState INT;

    SELECT 
        @ErrorMessage = ERROR_MESSAGE(),
        @ErrorSeverity = ERROR_SEVERITY(),
        @ErrorState = ERROR_STATE();

    -- Use RAISERROR inside the CATCH block to return error
    -- information about the original error that caused
    -- execution to jump to the CATCH block.
    RAISERROR (@ErrorMessage, -- Message text.
               @ErrorSeverity, -- Severity.
               @ErrorState -- State.
               );
END CATCH;

B. Creazione di un messaggio ad hoc in sys.messages

sp_addmessage @msgnum = 50005,
              @severity = 10,
              @msgtext = N'<<%7.3s>>';
GO
RAISERROR (50005, -- Message id.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
sp_dropmessage @msgnum = 50005;
GO

C. Utilizzo di una variabile locale per fornire il testo del messaggio

DECLARE @StringVariable NVARCHAR(50);
SET @StringVariable = N'<<%7.3s>>';

RAISERROR (@StringVariable, -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

Vedere anche

Riferimento

Concetti