RAISERROR (Transact-SQL)

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 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 asociado de una construcción TRY…CATCH.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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

Argumentos

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

• msg_str
  Es un mensaje definido por el usuario con un formato similar al de la función printf de la biblioteca de C estándar. 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 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 utilizar en msg_str son:

• flag

  Es un código que determina el espaciado y la justificació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, el indicador 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 el indicador del signo de número (#), se omite el indicador.
  ' ' (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 el indicador del signo más (+).

• width

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

• precision

  Es el número máximo de caracteres del valor del argumento que se utilizan para valores de cadena. Por ejemplo, si una cadena tiene cinco caracteres y la precisión es 3, sólo 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 utiliza con los tipos de caracteres d, i, o, s, x, X, 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	Cadena
  u	Entero sin signo
  x o X	Hexadecimal sin signo

  Nota

  Estas especificaciones de tipo se basan en las definidas originalmente para la función printf de la biblioteca de C estándar. Las especificaciones de tipo utilizadas en las cadenas de mensajes RAISERROR se asignan a tipos de datos de Transact-SQL, mientras que las especificaciones utilizadas en printf se asignan a tipos de datos del lenguaje C. RAISERROR no admite las especificaciones de tipo utilizadas 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.

  Nota

  Para convertir un valor al tipo de datos Transact-SQLbigint, 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
  Es 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 reemplaza la gravedad especificada en sp_addmessage.

  Todos los usuarios pueden especificar los niveles de gravedad del 0 al 18. Sólo los miembros de la función fija de servidor sysadmin o los usuarios con permisos ALTER TRACE pueden especificar los niveles de gravedad del 19 al 25. Para los niveles de gravedad del 19 al 25, se necesita la opción WITH LOG.

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

  Nota

  Los niveles de gravedad inferiores a 0 se interpretan como 0 y los superiores a 25 se interpretan como 25.

• state
  Entero entre 0 y 255. Los valores negativos o mayores que 255 generan un error.

  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
  Son los parámetros utilizados 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.

• option
  Es una opción personalizada del error. 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. Sólo los miembros de la función fija de servidor sysadmin o los usuarios con permisos ALTER TRACE pueden especificar WITH LOG.
  NOWAIT	Envía inmediatamente los mensajes al cliente.
  SETERROR	Establece los valores @@ERROR y ERROR_NUMBER en msg_id o 50000, independientemente del nivel de gravedad.

Comentarios

Los errores generados por RAISERROR funcionan igual que los generados por el código del Motor de base de datos. Las funciones del sistema ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE y @@ERROR informan de los valores especificados por RAISERROR. 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 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 invocó el bloque CATCH mediante funciones del sistema como ERROR_NUMBER y ERROR_MESSAGE con el fin de recuperar la información del error original. De forma predeterminada, @@ERROR se establece en 0 para los mensajes con un nivel de gravedad de 1 a 10. Para obtener más información, vea Usar TRY...CATCH en Transact-SQL.

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 utilizando 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. En ese caso, RAISERROR asigna los valores de los argumentos a las especificaciones de conversión. Utilice sp_addmessage y sp_dropmessage para agregar y quitar, respectivamente, mensajes de error definidos por el usuario.

RAISERROR se puede utilizar como alternativa a PRINT para devolver mensajes a las aplicaciones que realizan llamadas. La sustitución de caracteres que RAISERROR admite es similar a la de la función printf de la biblioteca de C estándar, mientras que no sucede lo mismo con la instrucción PRINT de Transact-SQL. 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, transfiere el control al bloque CATCH asociado. Especifique un nivel de gravedad 10 o inferior para que RAISERROR devuelva un mensaje desde un bloque TRY sin invocar el 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

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 sólo genera errores con los estados 1 a 127. Motor de base de datos puede producir errores con el estado 0, por lo que se recomienda comprobar el estado de los errores que devuelve ERROR_STATE antes de pasarlo como 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 ejemplo siguiente 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 mediante el procedimiento almacenado del sistema sp_addmessage con el número de mensaje 50005.

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

Vea también

Referencia

DECLARE @local_variable (Transact-SQL)

Funciones integradas (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)

Conceptos

Usar RAISERROR

Usar @@ERROR

Usar TRY...CATCH en Transact-SQL