RAISERROR (Transact-SQL)

Si applica a: SQL Server Database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics Piattaforma di strumenti analitici (PDW) Endpoint di analisi SQL in Microsoft Fabric Warehouse in Microsoft Fabric

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 relative alla sintassi Transact-SQL

Sintassi

Sintassi per SQL Server, database SQL di Azure e Istanza gestita di 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 ] ]

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. Quando non viene specificato msg_id, RAISERROR genera un messaggio di errore con un numero di errore .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 il messaggio contiene 2.048 o più caratteri, vengono visualizzati solo i primi 2.044; Viene aggiunto un puntino di sospensione per indicare che il messaggio viene troncato. I parametri di sostituzione utilizzano più caratteri rispetto all'output a causa del comportamento di archiviazione interno. Ad esempio, il parametro di sostituzione di %d con un valore assegnato di 2 produce effettivamente un carattere nella stringa del messaggio, ma occupa internamente anche tre caratteri aggiuntivi di archiviazione. Questo requisito a livello di archiviazione riduce il numero di caratteri disponibili per l'output del messaggio.

Quando si specifica msg_str, RAISERROR genera un messaggio di errore con un numero di errore .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.

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

Usato con i tipi di dcaratteri , soixXo ue crea valori shortint (h) o longint ().l

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 dei tipi usate in printf non sono supportate da RAISERROR quando Transact-SQL non ha un tipo di dati simile al tipo di dati C associato. Ad esempio, la %p specifica 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 Transact-SQL, specificare %I64d.

@local_variable

Variabile di qualsiasi tipo di dati di tipo carattere valido contenente una stringa formattata nello stesso modo 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.

Per i livelli di gravità da 19 a 25, è necessaria l'opzione WITH LOG . I livelli di gravità minori di 0 vengono interpretati come 0. I livelli di gravità superiori a 25 vengono interpretati come 25.

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

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

Il set di risultati è il seguente.

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. Non è consigliabile usare valori maggiori di 255.

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 zero o più parametri di sostituzione, ma il numero totale di parametri di sostituzione non può superare 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.

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. Quando RAISERROR viene eseguito con una gravità pari a 11 o superiore in un TRY blocco, trasferisce il controllo al blocco associato CATCH . 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. @@ERROR è impostato su 0 per impostazione predefinita per i messaggi con gravità da 1 a 10.

Quando msg_id specifica un messaggio definito dall'utente disponibile dalla sys.messages vista del catalogo, RAISERROR elabora il messaggio dalla colonna di testo usando le stesse regole applicate al testo di un messaggio definito dall'utente specificato utilizzando msg_str. Il testo del messaggio definito dall'utente può contenere specifiche di conversione e RAISERROR mappa i valori degli argomenti nelle specifiche di conversione. Usare sp_addmessage per aggiungere messaggi di errore definiti dall'utente e sp_dropmessage per eliminarli.

RAISERROR può essere usato come alternativa per PRINT restituire messaggi alle applicazioni chiamante. RAISERROR supporta la sostituzione di caratteri simile alla funzionalità della printf funzione nella libreria standard C, mentre l'istruzione Transact-SQL PRINT non lo fa. L'istruzione PRINT non è interessata dai TRY blocchi, mentre un'esecuzione RAISERROR con gravità da 11 a 19 in un blocco TRY trasferisce il controllo al blocco associato CATCH . 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

Qualsiasi utente può specificare un livello di gravità compreso tra 0 e 18. I livelli di gravità da 19 a 25 possono essere specificati solo dai membri del ruolo predefinito del server sysadmin o dagli utenti con ALTER TRACE autorizzazioni.

Esempi

R. Restituire 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.

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. Creare un messaggio ad hoc in sys.messages

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

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

Contenuto correlato

• Quali sono le funzioni del database SQL?
• DECLARE @local_variable (Transact-SQL)
• PRINT (Transact-SQL)
• sp_addmessage (Transact-SQL)
• sp_dropmessage (Transact-SQL)
• sys.messages (Transact-SQL)
• xp_logevent (Transact-SQL)
• @@ERROR (Transact-SQL)
• ERROR_LINE (Transact-SQL)
• ERROR_MESSAGE (Transact-SQL)
• ERROR_NUMBER (Transact-SQL)
• ERROR_PROCEDURE (Transact-SQL)
• ERROR_SEVERITY (Transact-SQL)
• ERROR_STATE (Transact-SQL)
• TRY...CATCH (Transact-SQL)