Utilizzo dei token nei passaggi dei processiUse Tokens in Job Steps

SQL ServerSQL Server Agent consente di usare token negli script per passaggi di processi Transact-SQLTransact-SQL . Agent allows you to use tokens in Transact-SQLTransact-SQL job step scripts. L'utilizzo di token quando si scrivono passaggi di processo offre la stessa flessibilità assicurata dalle variabili quando si scrivono programmi software.Using tokens when you write your job steps gives you the same flexibility that variables provide when you write software programs. Dopo aver inserito un token nello script di un passaggio di processo, SQL ServerSQL Server Agent sostituisce il token in fase di esecuzione, prima che il passaggio di processo venga eseguito dal sottosistema Transact-SQLTransact-SQL .After you insert a token in a job step script, SQL ServerSQL Server Agent replaces the token at run time, before the job step is executed by the Transact-SQLTransact-SQL subsystem.

Importante

In SQL Server 2005SQL Server 2005 Service Pack 1 la sintassi del token dei passaggi del processo di SQL ServerSQL Server Agent è stata modificata.Starting with SQL Server 2005SQL Server 2005 Service Pack 1, the SQL ServerSQL Server Agent job step token syntax changed. Di conseguenza, è necessario inserire una macro di escape con tutti i token utilizzati nei passaggi di processo. In caso contrario, questi passaggi avranno esito negativo.As a result, an escape macro must now accompany all tokens used in job steps, or else those job steps will fail. L'utilizzo delle macro di escape e l'aggiornamento dei passaggi di processo di SQL ServerSQL Server Agent che utilizzano token sono illustrati nelle sezioni "Informazioni sull'utilizzo dei token", "Token e macro di SQL ServerSQL Server Agent" e "Aggiornamento dei passaggi di processo per l'utilizzo di macro" riportate di seguito.Using escape macros and updating your SQL ServerSQL Server Agent job steps that use tokens are described in the following sections, "Understanding Using Tokens," " SQL ServerSQL Server Agent Tokens and Macros," and "Updating Job Steps to Use Macros." È inoltre cambiata la sintassi di SQL Server 2000SQL Server 2000 che prevedeva l'utilizzo delle parentesi quadre per chiamare i token dei passaggi di processo di SQL ServerSQL Server Agent, ad esempio "[DATE]".In addition, the SQL Server 2000SQL Server 2000 syntax, which used square brackets to call out SQL ServerSQL Server Agent job step tokens (for example, "[DATE]") has also changed. È ora necessario racchiudere tra parentesi i nomi dei token e inserire il simbolo di dollaro ($) all'inizio della sintassi del token,You must now enclose token names in parentheses and place a dollar sign ($) at the beginning of the token syntax. Esempio:For example:

$(ESCAPE_macro name(DATE))$(ESCAPE_macro name(DATE))

Informazioni sull'utilizzo dei tokenUnderstanding Using Tokens

Importante

Qualsiasi utente di Windows con autorizzazioni di scrittura per il registro eventi di Windows è in grado di accedere ai passaggi di processo attivati dagli avvisi di SQL ServerSQL Server Agent o di WMI.Any Windows user with write permissions on the Windows Event Log can access job steps that are activated by SQL ServerSQL Server Agent alerts or WMI alerts. Per evitare rischi per la sicurezza, i token di SQL ServerSQL Server Agent che possono essere utilizzati in processi attivati dagli avvisi sono disabilitati per impostazione predefinita.To avoid this security risk, SQL ServerSQL Server Agent tokens that can be used in jobs activated by alerts are disabled by default. I token interessati sono: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, e WMI(property).These tokens are: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG., and WMI(property). Si noti che in questa versione l'utilizzo dei token è esteso a tutti gli avvisi.Note that in this release, use of tokens is extended to all alerting.

Se si desidera utilizzare questi token, verificare innanzitutto che solo i membri di gruppi di sicurezza di Windows trusted, ad esempio il gruppo Administrators, dispongano delle autorizzazioni di scrittura per il registro eventi del computer in cui è installato SQL ServerSQL Server .If you need to use these tokens, first ensure that only members of trusted Windows security groups, such as the Administrators group, have write permissions on the Event Log of the computer where SQL ServerSQL Server resides. A questo punto, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietàe nella pagina Sistema avvisi selezionare Sostituisci token per tutte le risposte del processo ad avvisi per abilitare questi token.Then, right-click SQL Server Agent in Object Explorer, select Properties, and on the Alert System page, select Replace tokens for all job responses to alerts to enable these tokens.

SQL ServerSQL Server In SQL ServerSQL Server Agent i token vengono sostituiti da valori stringa letterali esatti con un'operazione semplice ed efficiente. Agent token replacement is simple and efficient: SQL ServerSQL Server Agent replaces an exact literal string value for the token. Tutti i token effettuano una distinzione tra maiuscole e minuscole.All tokens are case-sensitive. È necessario prendere in considerazione tale comportamento nei passaggi di processo e indicare correttamente i token da utilizzare oppure convertire la stringa di sostituzione nel tipo di dati corretto.Your job steps must take this into account and correctly quote the tokens you use or convert the replacement string to the correct data type.

Ad esempio, è possibile utilizzare l'istruzione seguente per inserire il nome del database in un passaggio di processo:For example, you might use the following statement to print the name of the database in a job step:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

In questo esempio la macro ESCAPE_SQUOTE viene inserita con il token A-DBN .In this example, the ESCAPE_SQUOTE macro is inserted with the A-DBN token. In fase di esecuzione il token A-DBN verrà sostituito con il nome del database appropriato.At run time, the A-DBN token will be replaced with the appropriate database name. Tramite la macro di escape è possibile utilizzare caratteri di escape per eventuali virgolette singole inavvertitamente passate nella stringa di sostituzione del token.The escape macro escapes any single quotation marks that may be inadvertently passed in the token replacement string. SQL ServerSQL Server In Agent una virgoletta singola verrà sostituita con due virgolette singole nella stringa finale. Agent will replace one single quotation mark with two single quotation marks in the final string.

Se ad esempio la stringa passata per sostituire il token è AdventureWorks2012'SELECT @@VERSION --, il comando eseguito dal passaggio di processo di SQL ServerSQL Server Agent sarà il seguente:For example, if the string passed to replace the token is AdventureWorks2012'SELECT @@VERSION --, the command executed by the SQL ServerSQL Server Agent job step will be:

PRINT N'Current database name is AdventureWorks2012''SELECT @@VERSION --' ;

In questo caso, l'istruzione inserita SELECT @@VERSIONnon verrà eseguita.In this case, the inserted statement, SELECT @@VERSION, does not execute. Al contrario, la virgoletta singola aggiuntiva indurrà il server ad analizzare l'istruzione inserita come stringa.Instead, the extra single quotation mark causes the server to parse the inserted statement as a string. Se la stringa di sostituzione del token non contiene una virgoletta singola, per nessun carattere verranno utilizzati caratteri di escape e il passaggio di processo contenente il token verrà eseguito come previsto.If the token replacement string does not contain a single quotation mark, no characters are escaped and the job step containing the token executes as intended.

Per eseguire il debug dell'utilizzo dei token nei passaggi di processo, utilizzare istruzioni PRINT come PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' e salvare l'output del passaggio di processo in un file o in una tabella.To debug token usage in your job steps, use print statements such as PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' and save job step output to a file or table. Usare la pagina Avanzate della finestra di dialogo Proprietà passaggio processo per specificare un file o una tabella per l'output del passaggio di processo.Use the Advanced page of the Job Step Properties dialog box to specify a job step output file or table.

Token e macro di SQL Server AgentSQL Server Agent Tokens and Macros

Nelle tabelle seguenti vengono elencati e illustrati i token e le macro supportati da SQL ServerSQL Server Agent.The following tables list and describe the tokens and macros that SQL ServerSQL Server Agent supports.

Token di SQL Server AgentSQL Server Agent Tokens

TokenToken DescriptionDescription
(A-DBN)(A-DBN) Nome del database.Database name. Se il processo viene eseguito da un avviso, il valore del nome del database sostituisce automaticamente il token nel passaggio di processo.If the job is run by an alert, the database name value automatically replaces this token in the job step.
(A-SVR)(A-SVR) Nome del server.Server name. Se il processo viene eseguito da un avviso, il valore del nome del server sostituisce automaticamente il token nel passaggio di processo.If the job is run by an alert, the server name value automatically replaces this token in the job step.
(A-ERR)(A-ERR) Numero di errore.Error number. Se il processo viene eseguito da un avviso, il valore del numero di errore sostituisce automaticamente il token nel passaggio di processo.If the job is run by an alert, the error number value automatically replaces this token in the job step.
(A-SEV)(A-SEV) Gravità dell'errore.Error severity. Se il processo viene eseguito da un avviso, il valore della gravità dell'errore sostituisce automaticamente il token nel passaggio di processo.If the job is run by an alert, the error severity value automatically replaces this token in the job step.
(A-MSG)(A-MSG) Testo del messaggio.Message text. Se il processo viene eseguito da un avviso, il valore del testo del messaggio sostituisce automaticamente il token nel passaggio di processo.If the job is run by an alert, the message text value automatically replaces this token in the job step.
(JOBNAME)(JOBNAME) Nome del processo.The name of the job.
(STEPNAME)(STEPNAME) Nome del passaggio.The name of the step.
(DATE)(DATE) Data corrente nel formato AAAAMMGG.Current date (in YYYYMMDD format).
(INST)(INST) Nome dell'istanza.Instance name. Il nome di un'istanza predefinita di questo token sarà MSSQLSERVER.For a default instance, this token will have the default instance name: MSSQLSERVER.
(JOBID)(JOBID) ID del processo.Job ID.
(MACH)(MACH) Nome del computer.Computer name.
(MSSA)(MSSA) Nome del servizio SQLServerAgent master.Master SQLServerAgent service name.
(OSCMD)(OSCMD) Prefisso per il programma usato per l'esecuzione dei passaggi di processo CmdExec .Prefix for the program used to run CmdExec job steps.
(SQLDIR)(SQLDIR) Directory in cui è installato SQL ServerSQL Server .The directory in which SQL ServerSQL Server is installed. Per impostazione predefinita corrisponde a C:\Programmi\Microsoft SQL Server\MSSQL.By default, this value is C:\Program Files\Microsoft SQL Server\MSSQL.
(SQLLOGDIR)(SQLLOGDIR) Token di sostituzione per il percorso della cartella del log degli errori di SQL Server, ad esempio $(ESCAPE_SQUOTE(SQLLOGDIR)).Replacement token for the SQL Server error log folder path – for example, $(ESCAPE_SQUOTE(SQLLOGDIR)).
(STEPCT)(STEPCT) Numero di esecuzioni del passaggio, escluse le esecuzioni non completate.A count of the number of times this step has executed (excluding retries). Può essere utilizzato dal comando del passaggio per imporre l'interruzione di un ciclo a più passaggi.Can be used by the step command to force termination of a multistep loop.
(STEPID)(STEPID) ID del passaggio.Step ID.
(SRVR)(SRVR) Nome del computer che esegue SQL ServerSQL Server.Name of the computer running SQL ServerSQL Server. Se l'istanza di SQL ServerSQL Server è un'istanza denominata, questo token include il nome dell'istanza.If the SQL ServerSQL Server instance is a named instance, this includes the instance name.
(TIME)(TIME) Ora corrente nel formato HHMMSS.Current time (in HHMMSS format).
(STRTTM)(STRTTM) Ora nel formato HHMMSS in cui è stata avviata l'esecuzione del processo.The time (in HHMMSS format) that the job began executing.
(STRTDT)(STRTDT) Data nel formato AAAAMMGG in cui è stata avviata l'esecuzione del processo.The date (in YYYYMMDD format) that the job began executing.
(WMI (property))(WMI(property)) Per i processi eseguiti in risposta ad avvisi WMI, indica il valore della proprietà specificata da property.For jobs that run in response to WMI alerts, the value of the property specified by property. Ad esempio, $(WMI(DatabaseName)) specifica il valore della proprietà DatabaseName per l'evento WMI che ha provocato l'esecuzione dell'avviso.For example, $(WMI(DatabaseName)) provides the value of the DatabaseName property for the WMI event that caused the alert to run.

Macro di escape di SQL Server AgentSQL Server Agent Escape Macros

Macro di escapeEscape Macros DescriptionDescription
$(ESCAPE_SQUOTE(nome_token))$(ESCAPE_SQUOTE(token_name)) Utilizza caratteri di escape per virgolette singole (') nella stringa di sostituzione del token.Escapes single quotation marks (') in the token replacement string. Sostituisce una virgoletta singola con due virgolette singole.Replaces one single quotation mark with two single quotation marks.
$(ESCAPE_DQUOTE(nome_token))$(ESCAPE_DQUOTE(token_name)) Utilizza caratteri di escape per virgolette doppie (") nella stringa di sostituzione del token.Escapes double quotation marks (") in the token replacement string. Sostituisce una virgoletta doppia con due virgolette doppie.Replaces one double quotation mark with two double quotation marks.
$(ESCAPE_RBRACKET(nome_token))$(ESCAPE_RBRACKET(token_name)) Utilizza caratteri di escape per parentesi chiuse (]) nella stringa di sostituzione del token.Escapes right brackets (]) in the token replacement string. Sostituisce una parentesi chiusa con due parentesi chiuse.Replaces one right bracket with two right brackets.
$(ESCAPE_NONE(nome_token))$(ESCAPE_NONE(token_name)) Sostituisce il token senza utilizzare caratteri di escape per i caratteri della stringa.Replaces token without escaping any characters in the string. Questa macro viene utilizzata per assicurare la compatibilità con le versioni precedenti in ambienti in cui si presuppone che le stringhe di sostituzione dei token provengano esclusivamente da utenti trusted.This macro is provided to support backward compatibility in environments where token replacement strings are only expected from trusted users. Per ulteriori informazioni, vedere "Aggiornamento dei passaggi di processo per l'utilizzo di macro" più avanti in questo argomento.For more information, see "Updating Job Steps to Use Macros," later in this topic.

Aggiornamento dei passaggi di processo per l'utilizzo di macroUpdating Job Steps to Use Macros

In SQL Server 2005SQL Server 2005 Service Pack 1, i passaggi di processo che contengono token senza macro di escape avranno esito negativo e restituiranno un messaggio di errore in cui è indicato che il passaggio di processo contiene uno o più token che devono essere aggiornati con una macro prima che il processo possa essere eseguito.Beginning with SQL Server 2005SQL Server 2005 Service Pack 1, job steps that contain tokens without escape macros will fail and return an error message indicating the job step contains one or more tokens that must be updated with a macro before the job can run.

Nell'articolo 915845 della MicrosoftMicrosoft Knowledge Base: I processi di SQL Server Agent che usano token hanno esito negativo in SQL Server 2005 Service Pack 1viene specificato uno script che può essere usato per aggiornare tutti i passaggi di processo che usano token con la macro ESCAPE_NONE .A script is provided with MicrosoftMicrosoft Knowledge Base article 915845: SQL Server Agent Job Steps That Use Tokens Fail in SQL Server 2005 Service Pack 1.You can use this script to update all of your job steps that use tokens with the ESCAPE_NONE macro. Dopo aver usato questo script, è consigliabile esaminare al più presto i passaggi di processo che usano token e sostituire la macro ESCAPE_NONE con una macro di escape appropriata per il contesto del passaggio di processo.After using this script, we recommend that you review your job steps that use tokens as soon as possible, and replace the ESCAPE_NONE macro with an escape macro that is appropriate for the job step context.

Nella tabella seguente viene indicata la modalità di gestione della sostituzione del token in SQL ServerSQL Server Agente.The following table describes how token replacement is handled by SQL ServerSQL Server Agent. Per attivare o disattivare la sostituzione dei token relativi agli avvisi, fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietàe selezionare o deselezionare la casella di controllo Sostituisci token per tutte le risposte del processo ad avvisi nella pagina Sistema avvisi .To turn alert token replacement on or off, right-click SQL Server Agent in Object Explorer, select Properties, and on the Alert System page, select or clear the Replace tokens for all job responses to alerts check box.

Sintassi dei tokenToken syntax Sostituzione dei token relativi agli avvisi attivataAlert token replacement on Sostituzione dei token relativi agli avvisi disattivataAlert token replacement off
La macro ESCAPE è stata utilizzataESCAPE macro used Tutti i token presenti nei processi sono stati sostituiti correttamente.All tokens in jobs are successfully replaced. I token attivati da avvisi non vengono sostituiti.Tokens activated by alerts are not replaced. I token interessati sono A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, e WMI(property).These tokens are A-DBN, A-SVR, A-ERR, A-SEV, A-MSG, and WMI(property). Altri token statici sono stati sostituiti correttamente.Other static tokens are replaced successfully.
La macro ESCAPE non è stata utilizzataNo ESCAPE macro used Tutti i processi contenenti token hanno esito negativo.Any jobs containing tokens fail. Tutti i processi contenenti token hanno esito negativo.Any jobs containing tokens fail.

Esempi di aggiornamento della sintassi dei tokenToken Syntax Update Examples

A.A. Utilizzo di token in stringhe non nidificateUsing tokens in non-nested strings

Nell'esempio seguente viene illustrato come aggiornare uno script semplice non nidificato con la macro di escape appropriata.The following example shows how to update a simple non-nested script with the appropriate escape macro. Prima di eseguire lo script di aggiornamento, lo script del passaggio di processo seguente utilizza un token per inserire il nome del database appropriato:Before running the update script, the following job step script uses a job step token to print the appropriate database name:

PRINT N'Current database name is $(A-DBN)' ;

Dopo aver eseguito lo script di aggiornamento, una macro ESCAPE_NONE viene inserita prima del token A-DBN .After running the update script, an ESCAPE_NONE macro is inserted before the A-DBN token. Poiché le virgolette singole vengono utilizzate per delimitare la stringa di stampa, è necessario aggiornare il passaggio di processo inserendo la macro ESCAPE_SQUOTE nel modo seguente:Because single quotation marks are used to delimit the print string, you must update the job step by inserting the ESCAPE_SQUOTE macro as follows:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

B.B. Utilizzo di token in stringhe nidificateUsing tokens in nested strings

Negli script dei passaggi di processo in cui i token vengono utilizzati in istruzioni o stringhe nidificate, è necessario riscrivere le istruzioni nidificate come più istruzioni prima di inserire le macro di escape appropriate.In job step scripts where tokens are used in nested strings or statements, the nested statements should be rewritten as multiple statements before inserting the appropriate escape macros.

Si consideri, ad esempio, il passaggio di processo seguente che non è stato aggiornato con una macro di escape e nel quale viene utilizzato il token A-MSG :For example, consider the following job step, which uses the A-MSG token and has not been updated with an escape macro:

PRINT N'Print ''$(A-MSG)''' ;

Dopo aver eseguito lo script di aggiornamento, una macro ESCAPE_NONE viene inserita con il token.After running the update script, an ESCAPE_NONE macro is inserted with the token. In questo caso, tuttavia, è necessario riscrivere lo script senza utilizzare la nidificazione nel modo seguente e inserire la macro ESCAPE_SQUOTE per utilizzare correttamente caratteri di escape per i delimitatori che potrebbero essere passati nella stringa di sostituzione del token:However, in this case, you would have to rewrite the script without using nesting as follows and insert the ESCAPE_SQUOTE macro to properly escape delimiters that may be passed in the token replacement string:

DECLARE @msgString nvarchar(max)  
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))'  
SET @msgString = QUOTENAME(@msgString,'''')  
PRINT N'Print ' + @msgString ;

Si noti inoltre che in questo esempio la funzione QUOTENAME imposta il carattere utilizzato per le virgolette.Note also in this example that the QUOTENAME function sets the quote character.

C.C. Utilizzo di token con la macro ESCAPE_NONEUsing tokens with the ESCAPE_NONE macro

L'esempio seguente fa parte di uno script in cui job_id viene recuperato dalla tabella sysjobs e in cui il token JOBID viene utilizzato per popolare la variabile @JobID dichiarata in precedenza nello script come tipo di dati binario.The following example is part of a script that retrieves the job_id from the sysjobs table and uses the JOBID token to populate the @JobID variable, which was declared earlier in the script as a binary data type. Poiché non è necessario alcun delimitatore per i tipi di dati binari, la macro ESCAPE_NONE viene utilizzata con il token JOBID .Note that because no delimiters are required for binary data types, the ESCAPE_NONE macro is used with the JOBID token. Non è necessario aggiornare questo passaggio di processo dopo aver eseguito lo script di aggiornamento.You would not need to update this job step after running the update script.

SELECT * FROM msdb.dbo.sysjobs  
WHERE @JobID = CONVERT(uniqueidentifier, $(ESCAPE_NONE(JOBID))) ;

Vedere ancheSee Also

Implementazione di processiImplement Jobs
Gestire passaggi di processoManage Job Steps