Articolo
03/31/2012

sp_add_jobstep (Transact-SQL)

Aggiunge un passaggio (operazione) a un processo.

Icona di collegamento a un argomento Convenzioni della sintassi Transact-SQL

Sintassi

        sp_add_jobstep [ @job_id = ] job_id | [ @job_name= ] 'job_name' 
     [ , [ @step_id = ] step_id ] 
     { , [ @step_name = ] 'step_name' } 
     [ , [ @subsystem = ] 'subsystem' ] 
     [ , [ @command = ] 'command' ] 
     [ , [ @additional_parameters = ] 'parameters' ] 
          [ , [ @cmdexec_success_code = ] code ] 
     [ , [ @on_success_action = ] success_action ] 
          [ , [ @on_success_step_id = ] success_step_id ] 
          [ , [ @on_fail_action = ] fail_action ] 
          [ , [ @on_fail_step_id = ] fail_step_id ] 
     [ , [ @server = ] 'server' ] 
     [ , [ @database_name = ] 'database' ] 
     [ , [ @database_user_name = ] 'user' ] 
     [ , [ @retry_attempts = ] retry_attempts ] 
     [ , [ @retry_interval = ] retry_interval ] 
     [ , [ @os_run_priority = ] run_priority ] 
     [ , [ @output_file_name = ] 'file_name' ] 
     [ , [ @flags = ] flags ] 
     [ , { [ @proxy_id = ] proxy_id 
         | [ @proxy_name = ] 'proxy_name' } ]

Argomenti

[ @job_id = ] job_id
Numero di identificazione del processo a cui si desidera aggiungere un passaggio. job_id è di tipo uniqueidentifier e il valore predefinito è NULL.
[ @job_name = ] 'job_name'
Nome del processo a cui si desidera aggiungere il passaggio. job_name è di tipo sysname e il valore predefinito è NULL.

Nota

È necessario specificare l'argomento job_id oppure l'argomento job_name ma non è possibile specificarli entrambi.
[ @step_id = ] step_id
Numero di identificazione sequenziale per il passaggio del processo. I numeri di identificazione dei passaggi iniziano da 1 e aumentano in modo sequenziale. Se viene inserito un passaggio nella sequenza esistente, i numeri di sequenza vengono automaticamente adeguati. Se step_id viene omesso, viene assegnato un valore dal sistema. step_idè di tipo int e il valore predefinito è NULL.
[ @step_name = ] 'step_name'
Nome del passaggio. step_name è di tipo sysname e non prevede alcun valore predefinito.

[ @subsystem = ] 'subsystem'
Il sottosistema utilizzato dal servizio SQL Server Agent per eseguire command. subsystem è di tipo nvarchar(40). I possibili valori sono i seguenti.

Valore	Descrizione
'ACTIVESCRIPTING'	Script ActiveX Importante Questa caratteristica verrà rimossa a partire da una delle prossime versioni di Microsoft SQL Server. Evitare di utilizzare questa caratteristica in un nuovo progetto di sviluppo e prevedere interventi di modifica nelle applicazioni in cui è attualmente implementata.
'CMDEXEC'	Comando del sistema operativo o programma eseguibile
'DISTRIBUTION'	Processo di Agente distribuzione repliche
'SNAPSHOT'	Processo di Agente snapshot repliche
'LOGREADER'	Processo di Agente lettura log repliche
'MERGE'	Processo di Agente merge repliche
'QueueReader'	Processo di Agente lettura coda repliche
'ANALYSISQUERY'	Query di Analysis Services (MDX, DMX).
'ANALYSISCOMMAND'	Comando di Analysis Services (XMLA).
'Dts'	Esecuzione di un pacchetto Integration Services
'PowerShell'	Script di PowerShell
'TSQL' (predefinito)	Transact-SQL - istruzione

[ @command= ] 'command'
Comandi che devono essere eseguiti dal servizio SQLServerAgent tramite subsystem. command è di tipo nvarchar(max) e il valore predefinito è NULL. SQL Server Agent consente di eseguire la sostituzione dei token, che garantisce la stessa flessibilità assicurata dalle variabili durante la scrittura dei programmi software.

Importante
In SQL Server 2005 Service Pack 1 sono state apportate modifiche alla sintassi dei token dei passaggi di processo di SQL Server Agent. Sarà pertanto necessario includere una macro di escape in tutti i token utilizzati nei passaggi del processo. In caso contrario i passaggi del processo avranno esito negativo. È stata inoltre modificata la sintassi di SQL Server 2000, in cui vengono utilizzate parentesi quadre per chiamare i token dei passaggi di processo di SQL Server Agent, ad esempio "[DATE]". È ora necessario racchiudere tra parentesi i nomi dei token e inserire il simbolo di dollaro ($) all'inizio della sintassi del token, come illustrato di seguito: $(ESCAPE_nome macro(DATE))

In SQL Server 2005 Service Pack 1 sono state apportate modifiche alla sintassi dei token dei passaggi di processo di SQL Server Agent. Sarà pertanto necessario includere una macro di escape in tutti i token utilizzati nei passaggi del processo. In caso contrario i passaggi del processo avranno esito negativo. È stata inoltre modificata la sintassi di SQL Server 2000, in cui vengono utilizzate parentesi quadre per chiamare i token dei passaggi di processo di SQL Server Agent, ad esempio "[DATE]". È ora necessario racchiudere tra parentesi i nomi dei token e inserire il simbolo di dollaro ($) all'inizio della sintassi del token, come illustrato di seguito:

$(ESCAPE_nome macro(DATE))

Per ulteriori informazioni su questi token e sull'aggiornamento dei passaggi di processo per l'utilizzo della nuova sintassi dei token, vedere Utilizzo dei token nei passaggi dei processi.

Nota sulla sicurezza
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 Server Agent o di WMI. Per evitare questo rischio per la sicurezza, per impostazione predefinita i token di SQL Server Agent utilizzabili nei processi attivati dagli avvisi sono disabilitati. I token interessati sono: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property). 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 Server. Per abilitare questi token, è quindi necessario fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietà e quindi selezionare Sostituisci token per tutte le risposte del processo ad avvisi nella pagina Sistema avvisi.

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 Server Agent o di WMI. Per evitare questo rischio per la sicurezza, per impostazione predefinita i token di SQL Server Agent utilizzabili nei processi attivati dagli avvisi sono disabilitati. I token interessati sono: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG e WMI(property).

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 Server. Per abilitare questi token, è quindi necessario fare clic con il pulsante destro del mouse su SQL Server Agent in Esplora oggetti, scegliere Proprietà e quindi selezionare Sostituisci token per tutte le risposte del processo ad avvisi nella pagina Sistema avvisi.

[ @additional_parameters= ] 'parameters'
Identificato solo a scopo informativo. Non supportato. Non è garantita la compatibilità con le versioni future. parameters è di tipo ntext e il valore predefinito è NULL.
[ @cmdexec_success_code = ] code
Il valore restituito da un comando del sottosistema CmdExec per indicare che command è stato eseguito senza errori. codeè di tipo int e il valore predefinito è 0.

[ @on_success_action= ] success_action
Azione da eseguire se il passaggio ha esito positivo. success_actionè di tipo tinyint. I possibili valori sono i seguenti.

Valore	Descrizione (azione)
1 (predefinito)	Uscita in caso di esito positivo
2	Uscita in caso di esito negativo
3	Esecuzione del passaggio successivo
4	Esecuzione del passaggio on_success_step_id

[ @on_success_step_id = ] success_step_id
ID del passaggio del processo da eseguire se il passaggio ha esito positivo e success_actionè uguale a 4. success_step_idè di tipo int e il valore predefinito è 0.

[ @on_fail_action= ] fail_action
Azione da eseguire se il passaggio ha esito negativo. fail_actionè di tipo tinyint. I possibili valori sono i seguenti.

Valore	Descrizione (azione)
1	Uscita in caso di esito positivo
2 (predefinito)	Uscita in caso di esito negativo
3	Esecuzione del passaggio successivo
4	Esecuzione del passaggio on_fail_step_id

[ @on_fail_step_id= ] fail_step_id
ID del passaggio del processo da eseguire se il passaggio ha esito negativo e fail_actionè uguale a 4. fail_step_idè di tipo int e il valore predefinito è 0.
[ @server =] 'server'
Identificato solo a scopo informativo. Non supportato. Non è garantita la compatibilità con le versioni future. server è nvarchar(30), con valore predefinito NULL.
[ @database_name = ] 'database'
Nome del database in cui eseguire un passaggio Transact-SQL. database è di tipo sysname e il valore predefinito è NULL. Se è NULL, viene utilizzato il database master. I nomi inclusi tra parentesi quadre ([ ]) non sono ammessi. Per un passaggio di un processo ActiveX, database è il nome del linguaggio di scripting utilizzato dal passaggio.
[ @database_user_name= ] 'user'
Nome dell'account utente da utilizzare quando viene eseguito un passaggio Transact-SQL. user è di tipo sysname e il valore predefinito è NULL. Quando user è NULL, il passaggio viene eseguito nel contesto utente del proprietario del processo in database. SQL Server Agent includerà questo parametro solo se il proprietario del processo è un sysadmin di SQL Server. In tal caso il passaggio del processo Transact-SQL specificato sarà eseguito nel contesto del nome utente di SQL Server specificato. Se il proprietario del processo non è un sysadmin di SQL Server, il passaggio di Transact-SQL sarà eseguito sempre nel contesto dell'accesso proprietario del processo e il parametro @database_user_name sarà ignorato.
[ @retry_attempts= ] retry_attempts
Numero di tentativi da eseguire se il passaggio ha esito negativo. retry_attempts è di tipo int e il valore predefinito è 0, che indica nessun tentativo.
[ @retry_interval= ] retry_interval
Numero di minuti che devono trascorrere tra i tentativi. retry_intervalè di tipo int e il valore predefinito è 0, che indica un intervallo di 0 minuti.
[ @os_run_priority = ] run_priority
Riservato.
[ @output_file_name= ] 'file_name'
Nome del file in cui salvare l'output del passaggio. file_nameè di tipo nvarchar(200) e il valore predefinito è NULL. file_namepuò includere uno o più token elencati per command. Questo parametro è valido solo con i comandi eseguiti nei sottosistemi di Transact-SQL, CmdExec, PowerShell, Integration Services o Analysis Services .

[ @flags= ] flags
Opzione che controlla il funzionamento. flags è di tipo int. I possibili valori sono i seguenti.

Valore	Descrizione
0 (predefinito)	Il file di output viene sovrascritto
2	L'output viene aggiunto alla fine del file di output
4	L'output del passaggio del processo Transact-SQL viene scritto nella cronologia dei passaggi
8	Il log viene scritto nella tabella. La cronologia esistente viene sovrascritta.
16	Il log viene scritto nella tabella in aggiunta alla cronologia esistente
32	Tutto l'output viene scritto nella cronologia processi
64	Creare un evento Windows da utilizzare come segnale per l'interruzione dell'oggetto JobStep Cmd

[ @proxy_id = ] proxy_id
ID del proxy con il cui account viene eseguito il passaggio del processo. proxy_id è di tipo int e il valore predefinito è NULL. Se proxy_id, proxy_name e user_name vengono omessi, il passaggio del processo viene eseguito con l'account di servizio per SQL Server Agent.
[ @proxy_name = ] 'proxy_name'
Nome del proxy con il cui account viene eseguito il passaggio del processo. proxy_name è di tipo sysname e il valore predefinito è NULL. Se proxy_id, proxy_name e user_name vengono omessi, il passaggio del processo viene eseguito con l'account del servizio per SQL Server Agent.

Valori restituiti

0 (esito positivo) o 1 (esito negativo)

Set di risultati

Nessuno

Osservazioni

La procedura sp_add_jobstep deve essere eseguita dal database msdb.

SQL Server Management Studio include un semplice strumento grafico per la gestione dei processi ed è lo strumento consigliato per la creazione e gestione dell'infrastruttura dei processi.

È necessario che un passaggio di un processo specifichi un proxy, a meno che l'autore del passaggio del processo non sia membro del ruolo predefinito di sicurezza sysadmin.

Un proxy può essere identificato da proxy_name o proxy_id.

Autorizzazioni

Per impostazione predefinita, questa stored procedure può essere eseguita dai membri del ruolo predefinito del server sysadmin. Gli altri utenti devono appartenere a uno dei seguenti ruoli predefiniti del database di SQL Server Agent nel database msdb:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Per informazioni sulle autorizzazioni di questi ruoli, vedere Ruoli di database predefiniti di SQL Server Agent.

L'autore del passaggio del processo deve avere accesso al proxy per il passaggio del processo. I membri del ruolo predefinito del server sysadmin hanno accesso a tutti i proxy. Per quanto riguarda gli altri utenti, è necessario concedere esplicitamente l'accesso a un proxy.

Esempi

Nell'esempio seguente viene creato un passaggio di processo che modifica l'accesso al database impostando la modalità sola lettura per il database Sales. In questo esempio, inoltre, vengono specificati 5 tentativi, con un intervallo di 5 minuti tra ognuno.

Nota

In questo esempio si presuppone che il processo Weekly Sales Data Backup esista già.

USE msdb;
GO
EXEC sp_add_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_name = N'Set database to read only',
    @subsystem = N'TSQL',
    @command = N'ALTER DATABASE SALES SET READ_ONLY', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO