FORMATMESSAGE (Transact-SQL)

Articolo
10/16/2024

Si applica a: SQL Server Database SQL di Azure Istanza gestita di SQL di Azure

Crea un messaggio in base a un messaggio esistente di sys.messages o a una stringa specificata. La funzionalità di FORMATMESSAGE è simile a quella dell'istruzione RAISERROR. Tuttavia, mentre RAISERROR stampa il messaggio immediatamente, FORMATMESSAGE restituisce il messaggio modificato per ulteriori elaborazioni.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

msg_number
ID del messaggio archiviato in sys.messages. Se msg_number è <= 13000 o se il messaggio non esiste in sys.messages, viene restituito NULL.

msg_string
Si applica a: SQL Server ( SQL Server 2016 (13.x) fino alla versione corrente).

È una stringa racchiusa tra virgolette singole contenente segnaposto per il valore del parametro. Il messaggio di errore può contenere un massimo di 2.047 caratteri. Se contiene più di 2.048 caratteri, vengono visualizzati solo i primi 2.044 e vengono aggiunti tre punti a indicare che il messaggio è stato troncato. I parametri di sostituzione utilizzano un maggior numero di caratteri rispetto a quanto viene visualizzato nell'output a causa della gestione dell'archiviazione interna. Per informazioni sulla struttura di una stringa di messaggio e sull'uso di parametri nella stringa, vedere la descrizione dell'argomento msg_str in RAISERROR (Transact-SQL).

@msg_variable
Si applica a: SQL Server ( SQL Server 2016 (13.x) fino alla versione corrente).

È una variabile nvarchar o varchar che contiene una stringa conforme ai criteri per l'argomento msg_string precedente.

param_value
Valore del parametro da utilizzare nel messaggio. È possibile specificare più di un valore di parametro. È necessario specificare i valori nell'ordine in cui le variabili di segnaposto sono elencate nel messaggio. Il numero di valori massimo consentito è 20.

Tipi restituiti

nvarchar

Osservazioni:

In modo analogo all'istruzione RAISERROR, l'istruzione FORMATMESSAGE modifica il messaggio mediante la sostituzione delle variabili di segnaposto con i valori di parametro specificati. Per altre informazioni sui segnaposto consentiti nei messaggi di errore e sul processo di modifica, vedere RAISERROR (Transact-SQL).

L'istruzione FORMATMESSAGE esegue la ricerca del messaggio nella lingua corrente dell'utente. Per i messaggi di sistema (msg_number<=50000), se non è disponibile una versione localizzata del messaggio, viene usata la versione della lingua del sistema operativo. Per i messaggi utente (msg_number>50000), se non è disponibile una versione localizzata del messaggio, viene usata la versione inglese.

Per i messaggi localizzati, i parametri specificati devono corrispondere ai segnaposti del parametro nella versione inglese (Stati Uniti), ovvero il parametro 1 nella versione localizzata deve corrispondere al parametro 1 nella versione inglese (Stati Uniti), il parametro 2 deve corrispondere al parametro 2 e così via.

Esempi

R. Esempio con un numero di messaggio

Nell'esempio seguente viene utilizzato un messaggio 20009 di replica archiviato in sys.messages come "Impossibile aggiungere l'articolo '%s' alla pubblicazione '%s'". FORMATMESSAGE sostituisce i valori First Variable e Second Variable per i segnaposto dei parametri. La stringa risultante, "Impossibile aggiungere l'articolo 'First Variable' alla pubblicazione 'Second Variable'", viene archiviata nella variabile locale @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. Esempio con una stringa di messaggio

Si applica a: SQL Server ( SQL Server 2016 (13.x) fino alla versione corrente).

Nell'esempio seguente viene accettata come input una stringa.

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

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

C. Esempi aggiuntivi di formattazione della stringa di messaggio

Gli esempi seguenti visualizzano una vasta gamma di opzioni di formattazione.

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

Vedi anche

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)
Funzioni di sistema (Transact-SQL)

Condividi tramite