FORMATMESSAGE (Transact-SQL)

Artikel
04/26/2023

Gilt für:SQL Server Azure SQL-Datenbank Azure SQL Managed Instance

Erstellt eine Meldung aus einer vorhandenen Meldung in sys.messages oder über eine bereitgestellte Zeichenfolge. Die Funktionalität von FORMATMESSAGE ähnelt der RAISERROR-Anweisung. RAISERROR gibt die Meldung jedoch direkt aus, während FORMATMESSAGE die bearbeitete Meldung zur weiteren Verarbeitung zurückgibt.

Transact-SQL-Syntaxkonventionen

Syntax

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

Hinweis

Informationen zum Anzeigen der Transact-SQL-Syntax für SQL Server 2014 (12.x) und früher finden Sie unter Dokumentation zu früheren Versionen.

Argumente

msg_number
Die ID der in sys.messages gespeicherten Meldung. Falls msg_number<= 13.000 ist oder die Meldung in sys.messages nicht vorhanden ist, wird NULL zurückgegeben.

msg_string
Gilt für: SQL Server (SQL Server 2016 (13.x) bis zur aktuellen Version).

Eine Zeichenfolge in einfachen Anführungszeichen mit den Platzhaltern für die Parameterwerte. Die Fehlermeldung kann maximal 2.047 Zeichen enthalten. Wenn die Meldung mehr als 2.048 Zeichen enthält, werden nur die ersten 2.044 angezeigt und Auslassungspunkte angefügt, die anzeigen, dass die Meldung abgeschnitten wurde. Aufgrund des internen Speicherverhaltens beanspruchen Ersetzungsparameter mehr Zeichen als in der Ausgabe angezeigt werden. Weitere Informationen zur Struktur einer Nachrichtenzeichenfolge und zur Verwendung von Parametern in einer Zeichenfolge finden Sie in der Beschreibung des msg_str-Arguments und unter RAISERROR (Transact-SQL).

@msg_variable
Gilt für: SQL Server (SQL Server 2016 (13.x) bis zur aktuellen Version).

Eine nvarchar- oder varchar-Variable, die eine Zeichenfolge enthält, die den oben dargelegten Kriterien für msg_string genügt.

param_value
Ein Parameterwert, der in der Meldung verwendet wird. Hierbei kann es sich um mehrere Parameterwerte handeln. Die Werte müssen in der Reihenfolge angegeben werden, in der die Platzhaltervariablen in der Meldung vorkommen. Es können maximal 20 Werte angegeben werden.

Rückgabetypen

nvarchar

Bemerkungen

Wie bei der RAISERROR-Anweisung ersetzt FORMATMESSAGE die Platzhaltervariablen in der Meldung mit den angegebenen Parameterwerten. Weitere Informationen zu zulässigen Platzhaltern in Fehlermeldungen und zum Bearbeitungsprozess finden Sie unter RAISERROR (Transact-SQL).

FORMATMESSAGE sucht die Meldung in der aktuellen Sprache des Benutzers. Wenn für Systemmeldungen (msg_number<= 50.000) keine lokalisierte Version vorhanden ist, wird die Version in der Betriebssystemsprache verwendet. Wenn für Benutzermeldungen (msg_number> 50.000) keine lokalisierte Version vorhanden ist, wird die englische Version verwendet.

Für lokalisierte Meldungen müssen die angegebenen Parameterwerte den Parameterplatzhaltern in der Version für Englisch (USA) entsprechen. Das heißt, Parameter 1 in der lokalisierten Version muss Parameter 1 in der Version für Englisch (USA) entsprechen, Parameter 2 in der lokalisierten Version muss Parameter 2 in der Version für Englisch (USA) entsprechen usw.

Beispiele

A. Beispiel mit einer Meldungsnummer

Im folgenden Beispiel wird eine Replikationsmeldung mit dem Code 20009 verwendet, die mit folgendem Wortlaut in sys.messages gespeichert ist: "The article '%s' could not be added to the publication '%s'" (Der %s-Artikel konnte nicht zur %s-Veröffentlichung hinzugefügt werden.). In der FORMATMESSAGE-Anweisung werden für die Parameterplatzhalter die Werte First Variable und Second Variable eingesetzt. Die Ergebniszeichenfolge „The article 'First Variable' could not be added to the publication 'Second Variable'.“ („Der First Variable-Artikel konnte nicht zur Second Variable-Veröffentlichung hinzugefügt werden.“) wird in der lokalen Variablen @var1 gespeichert.

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. Beispiel mit einer Meldungszeichenfolge

Gilt für: SQL Server (SQL Server 2016 (13.x) bis zur aktuellen Version).

Im folgenden Beispiel wird eine Zeichenfolge als Eingabe akzeptiert.

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

Rückgabewert: This is the first variable and this is the second variable.

C. Zusätzliche Beispiele zur Formatierung von Meldungszeichenfolgen

Die folgenden Beispiele zeigen verschiedene Formatierungsoptionen.

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');

Weitere Informationen

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)
Systemfunktionen (Transact-SQL)