FORMATMESSAGE (Transact-SQL)

van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceSQL-database in Microsoft Fabric

Bouwt een bericht op van een bestaand bericht in sys.messages of van een opgeleverde string. De functionaliteit van FORMATMESSAGE lijkt op die van de RAISERROR-instructie. RAISERROR print het bericht echter direct af, terwijl FORMATMESSAGE het geformatteerde bericht teruggeeft voor verdere verwerking.

Transact-SQL syntaxis-conventies

Syntaxis

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

Arguments

msg_number
Is de ID van het bericht opgeslagen in sys.messages. Als msg_number = 13000 is <, of als het bericht niet bestaat in sys.messages, wordt NULL teruggegeven.

msg_string
Van toepassing op: SQL Server (SQL Server 2016 (13.x) tot en met de huidige versie).

Is een string omsloten in enkele aanhalingstekens en met tijdelijke parameterwaarde-placeholders. Het foutbericht kan maximaal 2.047 tekens bevatten. Als het bericht 2.048 of meer tekens bevat, worden alleen de eerste 2.044 weergegeven en wordt een ellips toegevoegd om aan te geven dat het bericht is afgekapt. Let op dat substitutieparameters meer tekens verbruiken dan de output laat zien vanwege het interne geheugengedrag. Voor informatie over de structuur van een berichtstring en het gebruik van parameters in de string, zie de beschrijving van het msg_str-argument in RAISERROR (Transact-SQL).

@msg_variable
Van toepassing op: SQL Server (SQL Server 2016 (13.x) tot en met de huidige versie).

Is een nvarchar- of varchar-variabele die een string bevat die voldoet aan de criteria voor msg_string hierboven.

param_value
Is een parameterwaarde voor gebruik in het bericht. Kan meer dan één parameterwaarde zijn. De waarden moeten worden gespecificeerd in de volgorde waarin de plaatshoudervariabelen in het bericht voorkomen. Het maximale aantal waarden is 20.

Retourtypen

nvarchar

Opmerkingen

Net als de RAISERROR-instructie bewerkt FORMATMESSAGE het bericht door de opgegeven parameterwaarden te vervangen door tijdelijke variabelen in het bericht. Voor meer informatie over de toegestane plaatsvervangers in foutmeldingen en het bewerkingsproces, zie RAISERROR (Transact-SQL).

FORMATMESSAGE zoekt het bericht op in de huidige taal van de gebruiker. Voor systeemberichten (msg_number<=50000), als er geen gelokaliseerde versie van het bericht is, wordt de OS-taalversie gebruikt. Voor gebruikersberichten (msg_number>50000), als er geen gelokaliseerde versie van het bericht is, wordt de Engelse versie gebruikt.

Voor gelokaliseerde berichten moeten de meegeleverde parameterwaarden overeenkomen met de parameter-placeholders in de Amerikaanse Engelse versie. Dat wil zeggen, parameter 1 in de gelokaliseerde versie moet overeenkomen met parameter 1 in de Amerikaanse Engelse versie, parameter 2 moet overeenkomen met parameter 2, enzovoort.

Voorbeelden

Eén. Voorbeeld met een berichtnummer

Het volgende voorbeeld gebruikt een replicatiebericht 20009 opgeslagen in sys.messages als: "Het artikel '%s' kon niet worden toegevoegd aan de publicatie '%s'." FORMATMESSAGE vervangt de waarden First Variable en Second Variable voor de parameter-placeholders. De resulterende string, "Het artikel 'First Variable' could not be added to the publication 'Second Variable'.", wordt opgeslagen in de lokale variabele @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. Voorbeeld met een berichtstring

Van toepassing op: SQL Server (SQL Server 2016 (13.x) tot en met de huidige versie).

Het volgende voorbeeld neemt een string als invoer.

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

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

C. Aanvullende voorbeelden van berichtstring-opmaak

De volgende voorbeelden tonen verschillende opmaakopties.

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

Zie ook

RAISERROR (Transact-SQL)
GOOI (Transact-SQL)
sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL)
TEKST.SAMENV (Transact-SQL)
CONCAT_WS (Transact-SQL)
CITAATNAAM (Transact-SQL)
VERVANG (Transact-SQL)
ACHTERUIT (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
SPULLEN (Transact-SQL)
VERTALEN (Transact-SQL)
Systeemfuncties (Transact-SQL)