FORMATMESSAGE (Transact-SQL)

A következőkre vonatkozik:SQL ServerAzure SQL DatabaseFelügyelt Azure SQL-példánySQL-adatbázis a Microsoft Fabricben

Üzenetet épít egy meglévő üzenetből a sys.messages-ben vagy egy megadott stringből. A FORMATMESSAGE funkcionalitása hasonlít a RAISERROR utasításéva. Azonban a RAISERROR azonnal kinyomtatja az üzenetet, míg a FORMATMESSAGE visszaadja a formázott üzenetet további feldolgozásra.

Transact-SQL szintaxis konvenciók

Szemantika

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

Arguments

msg_number
Az üzenet azonosítója, amelyet a sys.messages adatbázisban tárolnak. Ha msg_number<= 13000, vagy ha az üzenet nem létezik a sys.messages-ben, akkor a NULL visszatér.

msg_string
Érvényes: SQL Server (SQL Server 2016 (13.x)-től a jelenlegi verzióig).

Egy string, amely egyetlen idézőjelben van bezárva, és paraméterérték-helykitöltőket tartalmaz. A hibaüzenet legfeljebb 2 047 karakterből állhat. Ha az üzenet 2 048 vagy annál több karaktert tartalmaz, csak az első 2 044 jelenik meg, és egy ellipszist adnak hozzá, hogy jelezze, hogy az üzenet lerövidült. Fontos megjegyezni, hogy a helyettesítési paraméterek több karaktert fogyasztanak, mint amennyit a kimenet mutat a belső tárolási viselkedés miatt. Az üzenetlánc szerkezetéről és a láncsorban lévő paraméterek használatáról információért lásd a msg_str argumentum leírását a RAISERROR (Transact-SQL) között.

@msg_variable
Érvényes: SQL Server (SQL Server 2016 (13.x)-től a jelenlegi verzióig).

Egy nvarchar vagy varchar változó, amely tartalmaz egy stringet, amely megfelel a fent említett msg_string kritériumainak.

param_value
Egy paraméterérték, amelyet az üzenetben használnak. Több paraméterérték is lehet. Az értékeket abban a sorrendben kell megadni, ahogyan a helykitöltő változók megjelennek az üzenetben. A maximális értékszám 20.

Visszatérési típusok

nvarchar

Megjegyzések

A RAISERROR utasításhoz hasonlóan a FORMATMESSAGE is úgy szerkeszti az üzenetet, hogy a megadott paraméterértékeket helyettesíti az üzenetben lévő helymeghatározó változókkal. További információért a hibaüzenetekben engedélyezett helykitöltőkről és a szerkesztési folyamatról lásd: RAISERROR (Transact-SQL).

A FORMATMESSAGE a felhasználó aktuális nyelvén keresi az üzenetet. Rendszerüzenetek esetén (msg_number<=50000), ha nincs lokalizált verzió az üzenetnek, az operációs rendszer nyelvi változatát használják. Felhasználói üzeneteknél (msg_number>50000), ha nincs lokalizált verzió az üzenetnek, az angol változatot használják.

Lokalizált üzeneteknél a megadott paraméterértékeknek egyezniük kell az amerikai angol verzióban szereplő paraméter helykitöltőivel. Vagyis a lokalizált verzióban az 1-es paraméternek felelnie kell az amerikai angol verzió 1-es paraméterének, a 2-es paraméternek a 2-es paraméternek, és így tovább.

Példák

A. Példa üzenetszámmal

A következő példa egy sys.messages formátumban tárolt replikációs üzenetet 20009 használ, hogy "A cikk '%s'nem volt hozzáadható a '%s' kiadványhoz." A FORMATMESSAGE helyettesíti az értékeket First Variable és Second Variable a paraméter helykitöltőit. A kapott string, "Az 'Első változó' cikk nem lehetett hozzáadni a 'Második változó' című publikációhoz.", a helyi változóban @var1van tárolva.

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. Példa üzenetlánccal

Érvényes: SQL Server (SQL Server 2016 (13.x)-től a jelenlegi verzióig).

A következő példa egy stringet vesz bemenetként.

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

Visszatér: This is the first variable and this is the second variable.

C. További üzenet-string formázási példák

Az alábbi példák különféle formázási lehetőségeket mutatnak.

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

Lásd még:

RAISERROR (Transact-SQL)
DOBÁS (Transact-SQL)
sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL)
CONCAT (Transact-SQL)
CONCAT_WS (Transact-SQL)
QUOTENAME (Transact-SQL)
CSERE (Transact-SQL)
FORDÍTOTT (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
STUFF (Transact-SQL)
FORDÍTSA (Transact-SQL)
Rendszerfunkciók (Transact-SQL)