Compartir a través de

RAISERROR (Transact-SQL)

  • Artículo

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 RAISERROR instrucción 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 para SQL Server, Azure SQL Database y Azure SQL Managed Instance:

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 deben ser mayores que 50000. Cuando no se especifica msg_id , RAISERROR genera un mensaje de error con un número de error de 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 2048 o más caracteres, solo se muestran los primeros 2044; Se agrega un botón de puntos suspensivos para indicar que el mensaje se trunca. Los parámetros de sustitución consumen más caracteres de los que se muestran en la salida debido al comportamiento interno del almacenamiento. Por ejemplo, el parámetro de sustitución de %d con un valor asignado de 2 genera realmente un carácter en la cadena de mensaje, pero también ocupa internamente tres caracteres adicionales de almacenamiento. Este requisito de almacenamiento reduce el número de caracteres disponibles para la salida del mensaje.

Cuando se especifica msg_str , RAISERROR genera un mensaje de error con un número de error de 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 Anteponer el valor del argumento con un signo más (+) o menos (-) 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 0 aparecen 0 y el signo menos (-), se omite.
# (número) 0x prefijo para el tipo hexadecimal de x o X Cuando se usa con el oformato , xo X , la marca de signo de número (#) da como prefacio cualquier valor distinto de cero con 0, 0xo 0X, respectivamente. Cuando d, io u están precedidos por la marca de signo de número (#), se omite la marca .
' ' (en blanco) Relleno con espacios Coloca delante del valor de salida espacios en blanco si el valor tiene signo y es positivo. Este relleno se omite cuando se incluye con la marca 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.

Un asterisco (*) significa que el ancho se especifica mediante el argumento asociado en la lista de argumentos, que debe ser 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.

Un asterisco (*) significa que el argumento asociado especifica la precisión en la lista de argumentos, que debe ser un valor entero.

{h | l} type

Se usa con tipos dde caracteres , i, o, xs, Xo uy crea valores shortint (h) o longint (l).

Especificación de tipo Representa
d o i Entero con signo
o Octal sin signo
s Cadena
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. Las especificaciones de tipo usadas en printf no se admiten RAISERROR cuando Transact-SQL no tiene un tipo de datos similar al tipo de datos de C asociado. Por ejemplo, la %p especificación de punteros no se admite porque RAISERROR Transact-SQL no tiene un tipo de datos de puntero.

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

@local_variable

Variable de cualquier tipo de datos de caracteres válido que contenga una cadena con el mismo formato 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 comprendidos entre 19 y 25, se requiere la WITH LOG opción . Los niveles de gravedad inferiores a 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 se deben usar valores 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 cero o más parámetros de sustitución, pero el número total de parámetros de sustitución no puede superar los 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 Registra el error en el registro de errores y el registro de aplicaciones de la instancia de SQL Server Motor de base de datos. Los errores guardados en el registro de errores tienen un límite máximo de 440 bytes. Solo un miembro del rol fijo de servidor sysadmin o un usuario con ALTER TRACE permisos puede especificar WITH LOG.

Se aplica a: SQL Server
NOWAIT Envía inmediatamente los mensajes al cliente.

Se aplica a: SQL Server, Azure SQL Database y Azure SQL Managed Instance.
SETERROR Establece los valores @@ERROR y ERROR_NUMBER en msg_id o 50000, independientemente del nivel de gravedad.

Se aplica a: SQL Server, Azure SQL Database y Azure SQL Managed Instance.

Comentarios

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 RAISERROR se ejecuta con una gravedad de 11 o superior en un TRY bloque, transfiere el control al bloque asociado CATCH . 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 se establece 0 en de forma predeterminada para los mensajes con una gravedad de 1 a 10.

Cuando msg_id especifica un mensaje definido por el usuario disponible en la sys.messages vista de catálogo, RAISERROR procesa el mensaje de la columna de texto con las mismas reglas que se aplican al texto de un mensaje definido por el usuario especificado mediante msg_str. El texto del mensaje definido por el usuario puede contener especificaciones de conversión y RAISERROR asigna valores de argumento 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 usar como alternativa a PRINT devolver mensajes a las aplicaciones que llaman. RAISERROR admite la sustitución de caracteres similar a la funcionalidad de la printf función en la biblioteca estándar de C, mientras que la instrucción Transact-SQL PRINT no. La PRINT instrucción no se ve afectada por TRY bloques, mientras que una RAISERROR ejecución con una gravedad de 11 a 19 en un bloque TRY transfiere el control al bloque asociado CATCH . 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

Cualquier usuario puede especificar un nivel de gravedad comprendido entre 0 y 18. Los niveles de gravedad comprendidos entre 19 y 25 solo pueden especificarse por los miembros del rol fijo de servidor sysadmin o los usuarios con ALTER TRACE permisos.

Ejemplos

A Devolver información de error de 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 podría generar errores con el estado 0, se recomienda comprobar el estado de error devuelto por ERROR_STATE antes de pasarlo como un valor al parámetro state 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. Creación de un mensaje ad hoc en sys.messages

En el ejemplo siguiente se muestra cómo generar un mensaje almacenado en la vista de sys.messages catálogo. El mensaje se agregó a la vista de sys.messages catálogo mediante el procedimiento almacenado del sp_addmessage sistema como número 50005de mensaje .

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. Usar una variable local para proporcionar 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

Contenido relacionado