• Articolo

sp_add_jobstep (Transact-SQL)

Aggiunge un passaggio (operazione) a un processo.

Icona di collegamento a un argomentoConvenzioni 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

    Nota importanteImportante
    Questa caratteristica verrà rimossa a partire da una delle prossime versioni di Microsoft SQL Server. Evitare di utilizzare questa funzionalità 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.

    Nota importanteImportante

    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. È inoltre cambiata la sintassi di SQL Server 2000 che prevedeva l'utilizzo delle 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 protezioneNota 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(property).

    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'
    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.

  • [ @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 Transact-SQL, CmdExec, PowerShell, SQL Server Integration Services o SQL Server 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

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

Valori di codice 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 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.

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'ALTER DATABASE SALES SET READ_ONLY', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO