Usar RAISERROR

RAISERROR se usa para devolver mensajes a las aplicaciones con el mismo formato que un error del sistema o un mensaje de advertencia generado por SQL Server Database Engine (Motor de base de datos de SQL Server).

RAISERROR puede devolver:

• Un mensaje de error definido por el usuario creado mediante el procedimiento almacenado del sistema sp_addmessage. Hay mensajes con un número de mensaje superior a 50000 que se pueden ver en la vista de catálogo sys.messages.

• Una cadena de mensaje especificada en la instrucción RAISERROR.

RAISERROR también puede:

• Asignar un número de error, gravedad y estado específicos.

• Solicitar que el error se guarde en el registro de errores de Database Engine (Motor de base de datos) y en el registro de aplicación de Microsoft Windows.

• Sustituir valores de argumento en el texto del mensaje, de forma parecida a como lo hace la función printf_s del lenguaje C.

Tanto RAISERROR como PRINT se pueden usar para devolver mensajes de información o advertencia a una aplicación. El texto del mensaje devuelto por RAISERROR se puede generar con una funcionalidad de sustitución de cadenas similar a la función printf_s de la biblioteca estándar de C, mientras que PRINT sólo puede devolver una cadena de caracteres o una expresión de caracteres. Una gravedad de RAISERROR entre 11 y 19 ejecutada en el bloque TRY de una construcción TRY…CATCH provoca que se transfiera el control al bloque CATCH asociado. Especifique una gravedad de 10 o inferior para devolver mensajes mediante RAISERROR sin invocar un bloque CATCH. PRINT no transfiere el control a un bloque CATCH.

Cuando RAISERROR se usa con el msg_id de un mensaje definido por el usuario en sys.messages, msg_id se devuelve como el número de error de SQL Server o el código nativo del error. Cuando RAISERROR se usa con una msg_str en lugar de un msg_id, el número de error y el número nativo del error de SQL Server devuelto es 50000.

Cuando use RAISERROR para devolver un mensaje de error definido por el usuario, use un número de estado distinto en cada RAISERROR que haga referencia al error. Esto puede ayudar a diagnosticar los errores cuando se generan.

Use RAISERROR para:

• Ayudar a solucionar problemas del código Transact-SQL.

• Comprobar los valores de los datos.

• Devolver mensajes que contengan texto variable.

• Provocar que la ejecución salte de un bloque TRY al bloque CATCH asociado.

• Devolver información de error desde el bloque CATCH al lote o aplicación que realiza la llamada.

En el siguiente ejemplo se sustituyen los valores de las funciones DB_ID() y DB_NAME() de un mensaje devuelto a la aplicación:

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

En este ejemplo se proporciona la misma información con un mensaje definido por el usuario.

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

En el siguiente ejemplo de código se muestra cómo usar RAISERROR dentro de un bloque TRY para provocar que la ejecución salte al bloque CATCH asociado. También se muestra cómo usar RAISERROR para devolver información acerca del error que invocó un bloque 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;