FORMATMESSAGE (Transact-SQL)FORMATMESSAGE (Transact-SQL)

SE APLICA A: síSQL Server síAzure SQL Database noAzure SQL Data Warehouse noAlmacenamiento de datos paralelos APPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Genera un mensaje a partir de un mensaje existente en sys.messages o de una cadena proporcionada.Constructs a message from an existing message in sys.messages or from a provided string. La funcionalidad de FORMATMESSAGE es similar a la de la instrucción RAISERROR.The functionality of FORMATMESSAGE resembles that of the RAISERROR statement. Sin embargo, RAISERROR imprime el mensaje inmediatamente, mientras que FORMATMESSAGE devuelve el mensaje formateado para que se pueda seguir procesando.However, RAISERROR prints the message immediately, while FORMATMESSAGE returns the formatted message for further processing.

Icono de vínculo de tema Convenciones de sintaxis de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxisSyntax

FORMATMESSAGE ( { msg_number  | ' msg_string ' } , [ param_value [ ,...n ] ] )  

ArgumentosArguments

msg_numbermsg_number
Es el identificador del mensaje almacenado en sys.messages.Is the ID of the message stored in sys.messages. Si msg_number es <= 13000 o si el mensaje no existe en sys.messages, se devuelve NULL.If msg_number is <= 13000, or if the message does not exist in sys.messages, NULL is returned.

msg_stringmsg_string
Se aplica a: SQL ServerSQL Server (desde SQL Server 2016 (13.x)SQL Server 2016 (13.x) hasta la versión actual).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

Es una cadena entre comillas simples que contiene marcadores de posición de valor de parámetro.Is a string enclosed in single quotes and containing parameter value placeholders. El mensaje de error puede tener 2.047 caracteres como máximo.The error message can have a maximum of 2,047 characters. 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.If the message contains 2,048 or more characters, only the first 2,044 are displayed and an ellipsis is added to indicate that the message has been truncated. 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.Note that substitution parameters consume more characters than the output shows because of internal storage behavior. 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).For information about the structure of a message string and the use of parameters in the string, see the description of the msg_str argument in RAISERROR (Transact-SQL).

param_valueparam_value
Valor de parámetro que se utiliza en el mensaje.Is a parameter value for use in the message. Puede ser más de un valor.Can be more than one parameter value. Los valores se deben especificar en el orden en el que las variables de marcador de posición aparezcan en el mensaje.The values must be specified in the order in which the placeholder variables appear in the message. El número máximo de valores es 20.The maximum number of values is 20.

Tipos devueltosReturn Types

nvarcharnvarchar

NotasRemarks

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.Like the RAISERROR statement, FORMATMESSAGE edits the message by substituting the supplied parameter values for placeholder variables in the message. 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).For more information about the placeholders allowed in error messages and the editing process, see RAISERROR (Transact-SQL).

FORMATMESSAGE busca el mensaje en el idioma actual del usuario.FORMATMESSAGE looks up the message in the current language of the user. Si no hay una versión del mensaje en otro idioma, se utiliza la versión en inglés.If there is no localized version of the message, the U.S. English version is used.

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.For localized messages, the supplied parameter values must correspond to the parameter placeholders in the U.S. English version. 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.That is, parameter 1 in the localized version must correspond to parameter 1 in the U.S. English version, parameter 2 must correspond to parameter 2, and so on.

EjemplosExamples

A.A. Ejemplo con un número de mensajeExample with a message number

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.The following example uses a replication message 20009 stored in sys.messages as, "The article '%s' could not be added to the publication '%s'." FORMATMESSAGE substitutes the values First Variable and Second Variable for the parameter placeholders. 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.The resulting string, "The article 'First Variable' could not be added to the publication 'Second Variable'.", is stored in the local variable @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.B. Ejemplo con una cadena de mensajeExample with a message string

Se aplica a: SQL ServerSQL Server (desde SQL Server 2016 (13.x)SQL Server 2016 (13.x) hasta la versión actual).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

En el siguiente ejemplo se toma una cadena como entrada.The following example takes a string as an input.

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.Returns: This is the first variable and this is the second variable.

C.C. Más ejemplos de formato de cadena de mensajeAdditional message string formatting examples

En los siguientes ejemplos se muestran distintas opciones de formato.The following examples show a variety of formatting options.

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énSee Also

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