sp_add_jobstep (Transact-SQL)

Articolo
12/15/2008

Data aggiornamento: 14 aprile 2006

Aggiunge un passaggio (operazione) a un processo.

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 Microsoft SQL Server Agent per eseguire command. subsystemè di tipo nvarchar(40). I possibili valori sono i seguenti.

Valore	Descrizione
'ACTIVESCRIPTING'	Script ActiveX
'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
'TSQL' (predefinito)	Istruzione Transact-SQL

[ @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))`

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

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 protezione:
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 protezione, 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(proprietà). Se si desidera utilizzare questi token, verificare innanzitutto che solo i membri di gruppi di protezione 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 protezione, 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(proprietà). Se si desidera utilizzare questi token, verificare innanzitutto che solo i membri di gruppi di protezione 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'
Identificazione a solo scopo informativo. Supporto non fornito. 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'
Identificazione a solo scopo informativo. Supporto non fornito. Non è garantita la compatibilità con le versioni future. server è di tipo nvarchar(30) e il 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. 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.

[ @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
Identificazione a solo scopo informativo. Supporto non fornito. Non è garantita la compatibilità con le versioni future.

[ @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 Transact-SQL o CmdExec.

[ @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

[ @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 del 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.

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 del server 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.

Valori restituiti

0 (esito positivo) o 1 (esito negativo)

Esempi

Nell'esempio seguente viene creato un passaggio di processo che modifica l'accesso al database impostando la modalità sola lettura per il database AdventureWorks. 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'exec sp_dboption ''sales'', ''read only'', ''true''', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO

Vedere anche

Cronologia modifiche

Versione	Cronologia
14 aprile 2006	Nuovo contenuto: Aggiunta della nota Importante relativa alla modifica della sintassi dei token di SQL Server Agent in SQL Server 2005 Service Pack 1. Contenuto modificato: Rimozione delle descrizioni della precedente sintassi dei token di SQL Server Agent.

14 aprile 2006

Nuovo contenuto:

Aggiunta della nota Importante relativa alla modifica della sintassi dei token di SQL Server Agent in SQL Server 2005 Service Pack 1.

Contenuto modificato:

Rimozione delle descrizioni della precedente sintassi dei token di SQL Server Agent.

Condividi tramite