RAISERROR (Transact-SQL)

Artículo
05/23/2023

Se aplica a:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)Punto de conexión de análisis SQL en Microsoft Fabric Almacenamiento en Microsoft Fabric

Nota:

La instrucción RAISERROR no respeta SET XACT_ABORT. Las aplicaciones nuevas deben usar THROW en lugar de RAISERROR.

Genera un mensaje de error e inicia el procesamiento de errores de la sesión. RAISERROR puede hacer referencia a un mensaje definido por el usuario almacenado en la vista de catálogo sys.messages, o bien puede generar un mensaje dinámicamente. El mensaje se devuelve como un mensaje de error de servidor a la aplicación que realiza la llamada o a un bloque CATCH de una construcción TRY...CATCH asociado. Las nuevas aplicaciones deben usar THROW en su lugar.

Convenciones de sintaxis de Transact-SQL

Sintaxis

Sintaxis de SQL Server y Azure SQL Database:

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

Sintaxis para Azure Synapse Analytics y Almacenamiento de datos en paralelo:

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

Nota:

Para ver la sintaxis de Transact-SQL para SQL Server 2014 (12.x) y versiones anteriores, consulte Versiones anteriores de la documentación.

Argumentos

msg_id

Un número de mensaje de error definido por el usuario almacenado en la vista de catálogo sys.messages utilizando sp_addmessage. Los números de error para los mensajes de error definidos por el usuario deberían ser mayores que 50000. Si no se especifica msg_id, RAISERROR genera un mensaje de error con el número de error 50000.

msg_str

Es un mensaje definido por el usuario con un formato similar al de la función printf de la biblioteca estándar de C. El mensaje de error puede tener 2.047 caracteres como máximo. Si el mensaje contiene más de 2.048 caracteres, solamente aparecerán los 2.044 primeros y se agregarán puntos suspensivos para indicar que el mensaje se ha truncado. Tenga en cuenta que los parámetros de sustitución utilizan más caracteres de lo que muestra la salida debido al comportamiento del almacenamiento interno. Por ejemplo, el parámetro de sustitución de %d con el valor 2 asignado genera en realidad un carácter en la cadena del mensaje, pero internamente ocupa tres caracteres adicionales de almacenamiento. Este requisito de almacenamiento reduce el número de caracteres disponibles para la salida del mensaje.

Si se especifica msg_str, RAISERROR genera un mensaje de error con el número de error 50000.

msg_str es una cadena de caracteres que incluye especificaciones de conversión opcionales. Cada especificación de conversión define cómo se aplica formato a un valor de la lista de argumentos y cómo se coloca en un campo en la posición indicada en la especificación de conversión de msg_str. Las especificaciones de conversión tienen el formato siguiente:

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

Los parámetros que se pueden usar en msg_str son:

flag

Es un código que determina el espaciado y la alineación del valor sustituido.

Código	Prefijo o justificación	Descripción
- (menos)	Justificado a la izquierda	Justifica a la izquierda el valor del argumento en el ancho de campo dado.
+ (más)	Prefijo de signo	Coloca el signo más (+) o menos (-) delante del valor del argumento, si el valor es de un tipo con signo.
0 (cero)	Relleno con ceros	Coloca ceros iniciales en la salida hasta alcanzar el ancho mínimo. Cuando aparecen 0 y el signo menos (-), el 0 no se tiene en cuenta.
# (número)	Prefijo 0x del tipo hexadecimal de x o X	Cuando se utiliza con el formato o, x o X, la marca del signo de número (#) se coloca delante de los valores distintos de cero con 0, 0x o 0X, respectivamente. Cuando d, i, o u llevan delante la marca del signo de número (#), se omite la marca.
' ' (espacio en blanco)	Relleno con espacios	Coloca delante del valor de salida espacios en blanco si el valor tiene signo y es positivo. Se omite cuando se incluye con la marca del signo más (+).

width

Un entero que define el ancho mínimo del campo en el que se coloca el valor del argumento. Si la longitud del valor del argumento es igual o mayor que width, el valor se imprime sin relleno. Si el valor es menor que width, se rellena hasta obtener la longitud especificada en width.

El asterisco (*) significa que el ancho se especifica mediante el argumento asociado de la lista de argumentos, que debe tener un valor entero.

precisión

Es el número máximo de caracteres del valor del argumento para valores de cadena. Por ejemplo, si una cadena tiene cinco caracteres y la precisión es 3, solo se utilizan los tres primeros caracteres del valor de cadena.

Para los valores enteros, precision es el número mínimo de dígitos impresos.

El asterisco (*) significa que la precisión se especifica mediante el argumento asociado de la lista de argumentos, que debe tener un valor entero.

{h | l} type

Se usa con los tipos de caracteres d, i, o, s, x, X o u, y crea valores shortint (h) o longint (l).

Especificación de tipo	Representa
d o i	Entero con signo
o	Octal sin signo
s	String
u	Entero sin signo
x o X	Hexadecimal sin signo

Estas especificaciones de tipo se basan en las definidas originalmente para la función printf de la biblioteca estándar de C. Las especificaciones de tipo usadas en las cadenas de mensajes RAISERROR se asignan a tipos de datos de Transact-SQL, mientras que las especificaciones usadas en printf se asignan a tipos de datos del lenguaje C. RAISERROR no admite las especificaciones de tipo usadas en printf cuando Transact-SQL no tiene un tipo de datos similar al tipo de datos de C asociado. Por ejemplo, RAISERROR no admite la especificación %p para punteros porque Transact-SQL no tiene un tipo de datos de puntero.

Para convertir un valor al tipo de datos Transact-SQL bigint, especifique %I64d.

@local_variable

Es una variable de un tipo de datos de caracteres válido que contiene una cadena formateada de la misma forma que msg_str. local_variable debe ser char o varchar, o bien se debe poder convertir implícitamente a estos tipos de datos.

severity

El nivel de gravedad definido por el usuario asociado a este mensaje. Cuando se utiliza msg_id para generar un mensaje definido por el usuario creado mediante sp_addmessage, la gravedad especificada en RAISERROR invalida la gravedad especificada en sp_addmessage.

Para los niveles de gravedad del 19 al 25, se necesita la opción WITH LOG. Los niveles de gravedad menores que 0 se interpretan como 0. Los niveles de gravedad mayores que 25 se interpretan como 25.

Precaución

Los niveles de gravedad del 20 al 25 se consideran muy negativos. Si se encuentra un nivel de gravedad de este tipo, la conexión de cliente termina tras recibir el mensaje, y el error se incluye en el registro de errores y en el registro de la aplicación.

Puede especificar -1 para devolver el valor de gravedad asociado al error como se muestra en el ejemplo siguiente.

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

El conjunto de resultados es el siguiente:

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

state

Un entero entre 0 y 255. Los valores negativos son 1 de forma predeterminada. No deben usarsevalores mayores que 255.

Si se genera el mismo error definido por el usuario en varias ubicaciones, el uso de un único número de estado para cada ubicación puede ayudar a averiguar qué sección del código está generando los errores.

argument

Los parámetros usados en la sustitución de las variables definidas en msg_str o el mensaje correspondiente a msg_id. Puede haber 0 o más parámetros de sustitución, pero el número total no puede superar 20. Cada parámetro de sustitución puede ser una variable local o cualquiera de estos tipos de datos: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary o varbinary. No se admiten otros tipos de datos.

Opción

Es una opción personalizada del error y puede tener uno de los valores de la tabla siguiente.

Valor	Descripción
`LOG`	Guarda el error en el registro de errores y en el registro de aplicación de la instancia del Motor de base de datos de Microsoft SQL Server. Los errores guardados en el registro de errores tienen un límite máximo de 440 bytes. Solo los miembros del rol fijo de servidor sysadmin o los usuarios con permisos ALTER TRACE pueden especificar WITH LOG. Se aplica a: SQL Server
`NOWAIT`	Envía inmediatamente los mensajes al cliente. Se aplica a: SQL Server, SQL Database
`SETERROR`	Establece los valores `@@ERROR` y `ERROR_NUMBER` en msg_id o 50000, independientemente del nivel de gravedad. Se aplica a: SQL Server, SQL Database

Observaciones

Los errores generados por RAISERROR funcionan igual que los generados por el código del Motor de base de datos. Los valores especificados por RAISERROR se notifican mediante las funciones de sistema ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE y @@ERROR. Cuando se ejecuta RAISERROR con un nivel de gravedad 11 o superior en un bloque TRY, transfiere el control al bloque CATCH asociado. El error se devuelve al autor de la llamada si RAISERROR se ejecuta:

Fuera del ámbito de cualquier bloque TRY.
Con un nivel de gravedad de 10 o inferior en un bloque TRY.
Con un nivel de gravedad 20 o superior que finaliza la conexión con la base de datos.

Los bloques CATCH pueden utilizar RAISERROR para volver a iniciar el error que ha invocado el bloque CATCH mediante funciones del sistema como ERROR_NUMBER y ERROR_MESSAGE con el fin de recuperar la información del error original. @@ERROR está establecido de forma predeterminada en 0 para los mensajes con una gravedad de 1 a 10.

Cuando msg_id especifica un mensaje definido por el usuario disponible en la vista de catálogo sys.messages, RAISERROR procesa el mensaje de la columna de texto usando las mismas reglas que se aplican al texto de un mensaje definido por el usuario especificado con msg_str. El texto del mensaje definido por el usuario puede contener especificaciones de conversión. En ese caso, RAISERROR asignará los valores de los argumentos a las especificaciones de conversión. Utilice sp_addmessage para agregar los mensajes de error definidos por el usuario y sp_dropmessage para eliminarlos.

RAISERROR se puede utilizar como alternativa a PRINT para devolver mensajes a las aplicaciones que realizan llamadas. RAISERROR admite la sustitución de caracteres similar a la de la función printf de la biblioteca estándar de C, pero la instrucción PRINT de Transact-SQL no la admite. La instrucción PRINT no se ve afectada por los bloques TRY, mientras que, si RAISERROR se ejecuta con un nivel de gravedad de 11 a 19 en un bloque TRY, se transfiere el control al bloque CATCH asociado. Especifique un nivel de gravedad de 10 o inferior para que RAISERROR devuelva un mensaje desde un bloque TRY sin invocar al bloque CATCH.

Normalmente, los argumentos reemplazan las especificaciones de conversión secuencialmente: el primer argumento reemplaza la primera especificación de conversión, el segundo argumento reemplaza la segunda especificación de conversión, y así sucesivamente. Por ejemplo, en la siguiente instrucción RAISERROR, el primer argumento N'number' reemplaza la primera especificación de conversión %s y el segundo argumento 5 reemplaza la segunda especificación de conversión %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

Si se especifica un asterisco (*) para el ancho o la precisión de una especificación de conversión, el valor que se utilizará para el ancho o la precisión se especifica como un valor de argumento entero. En este caso, una especificación de conversión puede utilizar hasta tres argumentos, uno para el valor de ancho, uno para el valor de precisión y uno para el valor de sustitución.

Por ejemplo, las dos instrucciones RAISERROR siguientes devuelven la misma cadena. Una especifica los valores de ancho y precisión en la lista de argumentos y la otra en la especificación de conversión.

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

Permisos

Todos los usuarios pueden especificar los niveles de gravedad del 0 al 18. Solo los miembros del rol fijo de servidor sysadmin o los usuarios con permisos ALTER TRACE pueden especificar los niveles de gravedad del 19 al 25.

Ejemplos

A. Devolver información de error desde un bloque CATCH

En el siguiente ejemplo de código se muestra cómo utilizar RAISERROR dentro de un bloque TRY para provocar que la ejecución salte al bloque CATCH asociado. También se muestra cómo utilizar RAISERROR para devolver información acerca del error que invocó al bloque CATCH.

Nota

RAISERROR solo genera errores con un estado comprendido entre 1 y 127. Dado que el Motor de base de datos puede generar errores con un estado 0, se recomienda comprobar el estado del error que devuelve ERROR_STATE antes de pasarlo como un valor al parámetro de estado de 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. Crear un mensaje ad hoc en sys.messages

En el siguiente ejemplo se indica cómo mostrar un mensaje almacenado en la vista de catálogo sys.messages. El mensaje se agregó a la vista de catálogo sys.messages por medio del procedimiento almacenado del sistema sp_addmessage con el número de mensaje 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. Utilizar una variable local para suministrar el texto del mensaje

En el siguiente ejemplo de código se muestra cómo utilizar una variable local para suministrar el texto del mensaje para una instrucción 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