Utilizzo di RAISERROR

L'istruzione RAISERROR consente di restituire messaggi alle applicazioni che utilizzano lo stesso formato di un errore di sistema o un messaggio di avviso generato da Motore di database di SQL Server.

RAISERROR consente di restituire gli elementi seguenti:

• Un messaggio di errore definito dall'utente, creato tramite la stored procedure di sistema sp_addmessage. Si tratta di messaggi con un numero di messaggio maggiore di 50000 che possono essere visualizzati nella vista del catalogo sys.messages.

• Stringhe di messaggio specificate nell'istruzione RAISERROR.

L'istruzione RAISERROR consente inoltre di eseguire le operazioni seguenti:

• Assegnare un numero di errore, un livello di gravità e uno stato specifici.

• Richiedere che l'errore venga registrato nel log degli errori di Motore di database e nel registro applicazioni di Microsoft.

• Sostituire i valori degli argomenti nel testo del messaggio, analogamente alla funzione printf_s del linguaggio C.

Le istruzioni RAISERROR e PRINT possono essere utilizzate entrambe per restituire messaggi informativi o di avviso a un'applicazione. Il testo del messaggio restituito da RAISERROR può essere creato utilizzando la funzionalità di sostituzione della stringa simile alla funzione printf della libreria standard C, mentre PRINT può restituire solo una stringa di caratteri o un'espressione di caratteri. Un'istruzione RAISERROR con livello di gravità compreso tra 11 a 19 eseguita nel blocco TRY di un costrutto TRY…CATCH provoca il trasferimento del controllo al blocco CATCH associato. Specificare un livello di gravità minore o uguale a 10 per restituire messaggi tramite RAISERROR senza richiamare un blocco CATCH. L'istruzione PRINT non provoca il trasferimento del controllo a un blocco CATCH.

Se l'istruzione RAISERROR viene utilizzata insieme al parametro msg_id di un messaggio definito dall'utente in sys.messages, l'ID di messaggio msg_id viene restituito come numero di errore o codice di errore nativo di SQL Server. Se RAISERROR viene utilizzata insieme al parametro msg_str invece che al parametro msg_id, il numero di errore o il numero di errore nativo di SQL Server restituito è 50000.

Se si utilizza REISERROR per restituire un messaggio di errore definito dall'utente, specificare un numero di stato diverso per ogni istruzione RAISERROR che fa riferimento all'errore, in modo da semplificare le operazioni di diagnostica degli errori.

Utilizzare RAISERROR per eseguire le operazioni seguenti:

• Risolvere problemi relativi al codice Transact-SQL.

• Verificare i valori dei dati.

• Restituire messaggi contenenti testo variabile.

• Provocare il passaggio dell'esecuzione da un blocco TRY al blocco CATCH associato.

• Restituire informazioni sull'errore dal blocco CATCH al batch o all'applicazione che ha eseguito la chiamata.

Nell'esempio seguente vengono sostituiti i valori delle funzioni DB_ID() e DB_NAME() in un messaggio restituito all'applicazione:

DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR
    (N'The current database ID is:%d, the database name is: %s.',
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Nell'esempio seguente vengono fornite le stesse informazioni tramite un messaggio definito dall'utente:

EXECUTE sp_dropmessage 50005;
GO
EXECUTE sp_addmessage 50005, -- Message id number.
    10, -- Severity.
    N'The current database ID is: %d, the database name is: %s.';
GO
DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR (50005,
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Nell'esempio di codice seguente viene illustrato come utilizzare l'istruzione RAISERROR all'interno di un blocco TRY per impostare il passaggio dell'esecuzione al blocco CATCH associato. Viene inoltre illustrato come utilizzare l'istruzione RAISERROR per restituire le informazioni sull'errore che ha richiamato 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;