FORMATMESSAGE (Transact-SQL)

Artículo
04/26/2023

Se aplica a:SQL Server Azure SQL Database Azure SQL Managed Instance

Genera un mensaje a partir de un mensaje existente en sys.messages o de una cadena proporcionada. La funcionalidad de FORMATMESSAGE es similar a la de la instrucción RAISERROR. Sin embargo, RAISERROR imprime el mensaje inmediatamente, mientras que FORMATMESSAGE devuelve el mensaje formateado para que se pueda seguir procesando.

Convenciones de sintaxis de Transact-SQL

Sintaxis

FORMATMESSAGE ( { msg_number  | ' msg_string ' | @msg_variable} , [ param_value [ ,...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_number
Es el identificador del mensaje almacenado en sys.messages. Si msg_number es <= 13000 o si el mensaje no existe en sys.messages, se devuelve NULL.

msg_string
Se aplica a: SQL Server (desde SQL Server 2016 (13.x) hasta la versión actual).

Es una cadena entre comillas simples que contiene marcadores de posición de valor de parámetro. 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. Para más información sobre la estructura de una cadena de mensaje y el uso de parámetros en la cadena, vea la descripción del argumento msg_str en RAISERROR (Transact-SQL).

@msg_variable
Se aplica a: SQL Server (desde SQL Server 2016 (13.x) hasta la versión actual).

Es una variable nvarchar o varchar que contiene una cadena que cumple con los criterios de msg_string anteriores.

param_value
Valor de parámetro que se utiliza en el mensaje. Puede ser más de un valor. Los valores se deben especificar en el orden en el que las variables de marcador de posición aparezcan en el mensaje. El número máximo de valores es 20.

Tipos de valor devuelto

nvarchar

Observaciones

Al igual que la instrucción RAISERROR, FORMATMESSAGE modifica el mensaje sustituyendo los valores de los parámetros suministrados por variables de marcador de posición del mensaje. Para más información sobre los marcadores de posición permitidos en los mensajes de error y el proceso de edición, vea RAISERROR (Transact-SQL).

FORMATMESSAGE busca el mensaje en el idioma actual del usuario. En el caso de los mensajes del sistema (msg_number<=50000), si no hay ninguna versión localizada del mensaje, se usa la versión del idioma del sistema operativo. Para los mensajes del usuario (msg_number>50000), si no hay ninguna versión localizada del mensaje, se usa la versión en inglés.

En los mensajes en otros idiomas, los valores de los parámetros suministrados deben corresponder a los marcadores de posición de los parámetros de la Versión en inglés. Es decir, el parámetro 1 de la versión en otros idiomas debe corresponder al parámetro 1 de la versión en inglés, el parámetro 2 debe corresponder al parámetro 2, etc.

Ejemplos

A. Ejemplo con un número de mensaje

En el siguiente ejemplo se usa un mensaje de replicación 20009 almacenado en sys.messages como "No se pudo agregar el artículo '%s' a la publicación '%s'". FORMATMESSAGE sustituye los valores First Variable y Second Variable por los marcadores de posición de los parámetros. La cadena resultante, "No se pudo agregar el artículo 'First Variable' a la publicación 'Second Variable'", se almacena en la variable local @var1.

SELECT text FROM sys.messages WHERE message_id = 20009 AND language_id = 1033;  
DECLARE @var1 VARCHAR(200);   
SELECT @var1 = FORMATMESSAGE(20009, 'First Variable', 'Second Variable');   
SELECT @var1;

B. Ejemplo con una cadena de mensaje

Se aplica a: SQL Server (desde SQL Server 2016 (13.x) hasta la versión actual).

En el siguiente ejemplo se toma una cadena como entrada.

SELECT FORMATMESSAGE('This is the %s and this is the %s.', 'first variable', 'second variable') AS Result;

Devuelve: This is the first variable and this is the second variable.

C. Más ejemplos de formato de cadena de mensaje

En los siguientes ejemplos se muestran distintas opciones de formato.

SELECT FORMATMESSAGE('Signed int %i, %d %i, %d, %+i, %+d, %+i, %+d', 5, -5, 50, -50, -11, -11, 11, 11);
SELECT FORMATMESSAGE('Signed int with up to 3 leading zeros %03i', 5);  
SELECT FORMATMESSAGE('Signed int with up to 20 leading zeros %020i', 5);  
SELECT FORMATMESSAGE('Signed int with leading zero 0 %020i', -55);  
SELECT FORMATMESSAGE('Bigint %I64d', 3000000000);
SELECT FORMATMESSAGE('Unsigned int %u, %u', 50, -50);  
SELECT FORMATMESSAGE('Unsigned octal %o, %o', 50, -50);  
SELECT FORMATMESSAGE('Unsigned hexadecimal %x, %X, %X, %X, %x', 11, 11, -11, 50, -50);  
SELECT FORMATMESSAGE('Unsigned octal with prefix: %#o, %#o', 50, -50);  
SELECT FORMATMESSAGE('Unsigned hexadecimal with prefix: %#x, %#X, %#X, %X, %x', 11, 11, -11, 50, -50);  
SELECT FORMATMESSAGE('Hello %s!', 'TEST');  
SELECT FORMATMESSAGE('Hello %20s!', 'TEST');  
SELECT FORMATMESSAGE('Hello %-20s!', 'TEST');

Consulte también

RAISERROR (Transact-SQL)
THROW (Transact-SQL)
sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL)
CONCAT (Transact-SQL)
CONCAT_WS (Transact-SQL)
QUOTENAME (Transact-SQL)
REPLACE (Transact-SQL)
REVERSE (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
STUFF (Transact-SQL)
TRANSLATE (Transact-SQL)
Funciones del sistema (Transact-SQL)