sp_addmessage (Transact-SQL)

Almacena un nuevo mensaje de error definido por el usuario en una instancia del Motor de base de datos de SQL Server. Los mensajes almacenados mediante sp_addmessage se pueden ver con la vista de catálogo sys.messages.

Se aplica a: SQL Server (SQL Server 2008 a través de la versión actual).

Convenciones de sintaxis de Transact-SQL

Sintaxis

sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg' 
     [ , [ @lang= ] 'language' ] 
     [ , [ @with_log= ] { 'TRUE' | 'FALSE' } ] 
     [ , [ @replace= ] 'replace' ] 

Argumentos

• [ @msgnum= ] msg_id
  Es el identificador del mensaje de error. msg_id es de tipo int y su valor predeterminado es NULL. msg_id para los mensajes de error definidos por el usuario puede ser un entero entre 50.001 y 2.147.483.647. La combinación de msg_id y language debe ser única; se devuelve un error si el identificador ya existe para el idioma especificado.

• [ @severity = ]severity
  Es el nivel de gravedad del error. severity es de tipo smallint y su valor predeterminado es NULL. Los niveles válidos son de 1 a 25. Para obtener más información sobre los niveles de gravedad, vea Niveles de gravedad de error del motor de base de datos.

• [ @msgtext = ] 'msg'
  Es el texto del mensaje de error. msg es de tipo nvarchar(255) y su valor predeterminado es NULL.

• [ @lang = ] 'language'
  Es el idioma de este mensaje. language es de tipo sysname y su valor predeterminado es NULL. Puesto que pueden instalarse varios idiomas en el mismo servidor, language especifica el idioma en el que está escrito cada mensaje. Cuando se omite language, se utiliza el idioma predeterminado de la sesión.

• [ @with_log = ] { 'TRUE' | 'FALSE' }
  Especifica si el mensaje debe escribirse en el registro de aplicación Windows cuando se produzca. @with_log es de tipo varchar(5) y su valor predeterminado es FALSE. Si es TRUE, el error siempre se escribe en el registro de aplicación Windows. Si es FALSE, el error no siempre se escribe en el registro de aplicación Windows, pero se puede escribir, dependiendo de cómo se haya producido el error. Solo los miembros del rol de servidor sysadmin pueden usar esta opción.

  Nota

  Si se escribe un mensaje en el registro de aplicación Windows, también se escribe en el archivo de registro de errores del Motor de base de datos.

• [ @replace = ] 'replace'
  Si se especifica como la cadena replace, los mensajes de error existentes se sobrescriben con el texto y el nivel de gravedad de los mensajes nuevos. replace es de tipo varchar(7) y su valor predeterminado es NULL. Esta opción se debe especificar si msg_id ya existe. Si se sustituye un mensaje en inglés de EE.UU., se sustituirá el nivel de gravedad para todos los mensajes de todos los demás idiomas que tengan el mismo msg_id.

Valores de código de retorno

0 (correcto) o 1 (error)

Conjuntos de resultados

Ninguno

Comentarios

Para las versiones no inglesas de SQL Server, la versión en inglés de EE.UU. de un mensaje deberá existir para que pueda agregarse el mensaje en otro idioma. La gravedad de las dos versiones del mensaje debe coincidir.

Para traducir mensajes que contienen parámetros, utilice los números de parámetro que corresponden a los parámetros del mensaje original. Inserte un signo de exclamación (!) detrás de cada número de parámetro.

Mensaje original	Mensaje traducido
‘Parámetro 1 del mensaje original: %s, parámetro 2: %d'	‘Parámetro 1 del mensaje traducido: %1!, parámetro 2: %2!'

Debido a las diferencias sintácticas que existen entre los idiomas, puede que los números de los parámetros del mensaje traducido no aparezcan en la misma secuencia que en el mensaje original.

Permisos

Debe pertenecer a los roles fijos de servidor sysadmin y serveradmin.

Ejemplos

A.Definir un mensaje personalizado

En el ejemplo siguiente se agrega un mensaje personalizado a sys.messages.

USE master;
GO
EXEC sp_addmessage 50001, 16, 
   N'Percentage expects a value between 20 and 100. 
   Please reexecute with a more appropriate value.';
GO

B.Agregar un mensaje en dos idiomas

En el ejemplo siguiente se agrega primero un mensaje en inglés de EE.UU. y luego se agrega el mismo mensaje en francés.

USE master;
GO
EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'The item named %s already exists in %s.', 
   @lang = 'us_english';

EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'L''élément nommé %1! existe déjà dans %2!', 
   @lang = 'French';
GO

C.Cambiar el orden de los parámetros

En el ejemplo siguiente se agrega primero un mensaje en inglés de EE.UU. y luego se agrega un mensaje traducido con el orden de los parámetros cambiado.

USE master;
GO

EXEC sp_addmessage 
    @msgnum = 60000, 
    @severity = 16,
    @msgtext = 
        N'This is a test message with one numeric
        parameter (%d), one string parameter (%s), 
        and another string parameter (%s).',
    @lang = 'us_english';

EXEC sp_addmessage 
    @msgnum = 60000, 
    @severity = 16,
    @msgtext = 
        -- In the localized version of the message,
        -- the parameter order has changed. The 
        -- string parameters are first and second
        -- place in the message, and the numeric 
        -- parameter is third place.
        N'Dies ist eine Testmeldung mit einem 
        Zeichenfolgenparameter (%3!),
        einem weiteren Zeichenfolgenparameter (%2!), 
        und einem numerischen Parameter (%1!).',
    @lang = 'German';
GO  

-- Changing the session language to use the U.S. English
-- version of the error message.
SET LANGUAGE us_english;
GO

RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state,
GO                                       -- parameters.

-- Changing the session language to use the German
-- version of the error message.
SET LANGUAGE German;
GO

RAISERROR(60000,1,1,15,'param1','param2'); -- error, severity, state, 
GO                                       -- parameters.

Vea también

Referencia

RAISERROR (Transact-SQL)

sp_altermessage (Transact-SQL)

sp_dropmessage (Transact-SQL)

Procedimientos almacenados del sistema (Transact-SQL)