RAISERROR (Transact-SQL)

  • Articolo

Si applica a:SQL Server database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics AnalyticsPlatform System (PDW)SQL analytics endpoint in Microsoft FabricWarehouse in Microsoft Fabric

Nota

L'istruzione RAISERROR non rispetta SET XACT_ABORT. Le nuove applicazioni dovrebbero usare THROW anziché RAISERROR.

Consente di generare un messaggio di errore e di inizializzare l'elaborazione dell'errore per la sessione. RAISERROR può fare riferimento a un messaggio definito dall'utente archiviato nella vista del catalogo sys.messages oppure compilare un messaggio in modo dinamico. Il messaggio viene restituito come messaggio di errore del server all'applicazione chiamante o a un blocco CATCH associato di un costrutto TRY...CATCH. Per le nuove applicazioni è invece necessario usare THROW.

Convenzioni di sintassi Transact-SQL

Sintassi

Sintassi per SQL Server e database SQL di Azure:

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

Sintassi per Azure Synapse Analytics e Parallel Data Warehouse:

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

Nota

Per visualizzare la sintassi Transact-SQL per SQL Server 2014 (12.x) e versioni precedenti, vedere la documentazione delle versioni precedenti.

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 non si specifica msg_id, RAISERROR genera un messaggio di errore numero 50000.

msg_str

Messaggio definito dall'utente con formattazione simile alla funzione printf nella libreria standard 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 pari a 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 numero 50000.

msg_str è una stringa di caratteri con specifiche di conversione incorporate facoltative. Ogni specifica di conversione definisce la modalità con cui 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 che possono essere usati nell'argomento msg_str sono i seguenti:

flag

Codice che determina la spaziatura e la giustificazione del valore sostituito.

Codice Prefisso o allineamento Descrizione
- (sottrazione) Allineamento a sinistra Allinea a sinistra il valore dell'argomento entro la larghezza dei campi specificata.
+ (addizione) 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 intero che definisce la larghezza minima del campo in cui 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 intero.

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 interi, 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 intero.

{h | l} type

Viene usato 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 Intero con segno
o Ottale senza segno
s Stringa
u Intero senza segno
x o X Valori esadecimali senza segno

Queste specifiche del tipo si basano su quelle originariamente definite per la funzione printf nella libreria standard C. Le specifiche del tipo usate nelle stringhe di messaggio di RAISERROR sono associate ai tipi di dati Transact-SQL, mentre le specifiche usate in printf sono associate ai tipi di dati del linguaggio C. Le specifiche del tipo usate 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é Transact-SQL non ha un tipo di dati puntatore.

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

@local_variable

Variabile di qualsiasi tipo di dati carattere valido contenente una stringa con la stessa formattazione di msg_str. @local_variable deve essere di tipo char o varchar oppure deve supportare la conversione implicita in questi tipi di dati.

severity

Livello di gravità definito dall'utente associato al messaggio. Se si usa 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 19 a 25 richiedono l'opzione WITH LOG. I livelli di gravità inferiori a 0 vengono interpretati come 0. I livelli di gravità superiori a 25 vengono interpretati come 25.

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.

È possibile specificare -1 per restituire il valore di gravità associato all'errore come illustrato nell'esempio seguente.

RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');

Questo è il set di risultati.

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

state

Valore intero compreso tra 0 e 255. I valori negativi vengono impostati per impostazione predefinita su 1. I valori maggiori di 255 non devono essere usati.

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 usati nella sostituzione delle variabili definite in msg_str oppure nel 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 o uno di questi tipi di dati: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary o varbinary. Non sono supportati altri tipi di dati.

opzione

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 del motore di database di Microsoft SQL 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 hanno l'autorizzazione ALTER TRACE possono specificare WITH LOG.

Si applica a: SQL Server
NOWAIT Invia i messaggi direttamente al client.

Si applica a: SQL Server, database SQL
SETERROR Imposta i valori di @@ERROR e ERROR_NUMBER su msg_id o 50000, indipendentemente dal livello di gravità.

Si applica a: SQL Server, database SQL

Osservazioni:

Gli errori generati da RAISERROR hanno le stesse caratteristiche degli errori generati dal codice del motore di database. I valori specificati da RAISERROR vengono segnalati 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 usare 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 viene impostato su 0 per i messaggi con una gravità da 1 a 10.

Se msg_id specifica un messaggio definito dall'utente disponibile nella vista del catalogo sys.messages, RAISERROR elabora il messaggio dalla colonna di testo usando 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. Usare sp_addmessage per aggiungere messaggi di errore definiti dall'utente e sp_dropmessage per eliminarli.

RAISERROR può essere usato in alternativa a PRINT per restituire i messaggi alle applicazioni di chiamata. RAISERROR supporta la sostituzione dei caratteri in modo analogo alla funzione printf nella libreria C standard, al contrario dell'istruzione PRINT di Transact-SQL. 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 usare 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 usare per la larghezza o la precisione viene specificato come valore intero 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

Autorizzazioni

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 hanno l'autorizzazione ALTER TRACE.

Esempi

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

Nell'esempio di codice seguente viene illustrato come utilizzare RAISERROR all'interno di un blocco TRY per definire il passaggio dell'esecuzione al blocco CATCH associato. Viene inoltre illustrato come utilizzare RAISERROR per restituire le informazioni sull'errore che ha richiamato il blocco CATCH.

Nota

RAISERROR genera esclusivamente errori con stato compreso tra 1 e 127. Poiché il motore di database può generare errori con stato 0, è consigliabile verificare lo stato dell'errore restituito da ERROR_STATE prima di passarlo come valore al parametro di stato di RAISERROR.

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

Nell'esempio seguente viene illustrato come generare un messaggio archiviato nella vista del catalogo sys.messages. Il messaggio è stato aggiunto alla vista del catalogo sys.messages tramite la stored procedure di sistema sp_addmessage come numero di messaggio 50005.

EXEC 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
EXEC sp_dropmessage @msgnum = 50005;
GO

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

Nell'esempio di codice seguente viene illustrato l'utilizzo di una variabile locale per definire il testo del messaggio per un'istruzione RAISERROR.

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

Vedi anche