sp_add_jobstep (Transact-SQL)

Article
12/15/2008

Mis à jour : 14 avril 2006

Ajoute une étape (opération) à un travail.

Syntaxe

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' } ]

Arguments

[ @job_id =] job_id
Numéro d'identification du travail auquel l'étape doit être ajoutée. job_id est de type uniqueidentifier et sa valeur par défaut est NULL.

[ @job_name =] 'job_name'
Nom du travail auquel l'étape doit être ajoutée. L'argument job_name est de type sysname, avec NULL comme valeur par défaut.

Remarque :

Vous devez définir la valeur de job_id ou de job_name, mais pas les deux valeurs à la fois.

Remarque :
Vous devez définir la valeur de job_id ou de job_name, mais pas les deux valeurs à la fois.

[ @step_id =] step_id
Numéro d'identification de la séquence de l'étape de travail. Les numéros d'identification d'étape commencent à 1 et sont incrémentés sans intervalle. Si une étape est insérée dans une séquence existante, les numéros de cette séquence sont ajustés automatiquement. Une valeur est affectée si l'argument step_id n'est pas spécifié. L'argument step_idest de type int, avec NULL comme valeur par défaut.

[ @step_name =] 'step_name'
Nom de l'étape. L'argument step_nameest de type sysname, sans valeur par défaut.

[ @subsystem =] 'subsystem'
Sous-système utilisé par le service Microsoft SQL Server Agent pour exécuter command. subsystemest de type nvarchar(40) et peut prendre l'une des valeurs suivantes :

Valeur	Description
'ACTIVESCRIPTING'	Script actif
'CMDEXEC'	Commande du système d'exécution ou programme exécutable
'DISTRIBUTION'	Travail de l'Agent de distribution de réplication
'SNAPSHOT'	Travail de l'Agent de capture instantanée de réplication
'LOGREADER'	Travail de l'Agent de lecture du journal de réplications
'MERGE'	Travail de l'Agent de fusion de réplication
'QueueReader'	Travail de l'Agent de lecture de file d'attente de réplication
'ANALYSISQUERY'	Requête Analysis Services (MDX, DMX).
'ANALYSISCOMMAND'	Commande Analysis Services (XMLA).
'Dts'	Exécution du package Integration Services
'TSQL' (valeur par défaut)	Instruction Transact-SQL

[ @command= ] 'command'
Commandes qui doivent être exécutées par le service SQLServerAgent via subsystem. command est de type nvarchar(max) et a pour valeur par défaut NULL. SQL Server Agent effectue une substitution de jetons qui offre la même souplesse que les variables lorsque vous écrivez des logiciels.

Important :
Dans SQL Server 2005 Service Pack 1, la syntaxe des étapes de travail de SQL Server Agent n'est plus la même. Par conséquent, une macro d'échappement doit désormais accompagner tous les jetons utilisés dans les étapes de travail, afin que celles-ci n'échouent pas. En outre, la syntaxe SQL Server 2000, qui utilisait des crochets pour appeler les jetons d'étape de travail de SQL Server Agent (par exemple, « `[DATE]` ») a également changé. Vous devez désormais mettre les noms de jeton entre parenthèses et placer un signe dollar (`$`) au début de la syntaxe du jeton. Exemple : `$(ESCAPE_`macro name`(DATE))`

Important :

Dans SQL Server 2005 Service Pack 1, la syntaxe des étapes de travail de SQL Server Agent n'est plus la même. Par conséquent, une macro d'échappement doit désormais accompagner tous les jetons utilisés dans les étapes de travail, afin que celles-ci n'échouent pas. En outre, la syntaxe SQL Server 2000, qui utilisait des crochets pour appeler les jetons d'étape de travail de SQL Server Agent (par exemple, « [DATE] ») a également changé. Vous devez désormais mettre les noms de jeton entre parenthèses et placer un signe dollar ($) au début de la syntaxe du jeton. Exemple : $(ESCAPE_macro name(DATE))

Pour plus d'informations sur ces jetons et sur la mise à jour des étapes de travail afin d'utiliser la nouvelle syntaxe des jetons, consultez Utilisation de jetons dans les étapes d'un travail.

Remarque relative à la sécurité :
Tout utilisateur Windows qui dispose des autorisations d'écriture dans le journal d'événements Windows peut accéder aux étapes de travail activées par les alertes WMI ou par les alertes de SQL Server Agent. Pour remédier à ce problème lié à la sécurité, les jetons de l'Agent SQL Server qui sont utilisables dans les travaux activés par les alertes sont désactivés par défaut. Ces jetons sont : A-DBN, A-SVR, A-ERR, A-SEV, A-MSG et WMI(property). Si vous devez utiliser ces jetons, assurez-vous d'abord que seuls les membres des groupes de sécurité Windows approuvés, comme le groupe Administrateurs, disposent des autorisations d'écriture pour le journal d'événements de l'ordinateur sur lequel SQL Server réside. Ensuite, affichez l'Explorateur d'objets, cliquez avec le bouton droit sur SQL Server Agent, puis sélectionnez Propriétés et dans la page Système d'alerte qui s'affiche, sélectionnez Remplacer les jetons pour toutes les réponses de travaux aux alertes pour activer ces jetons.

Tout utilisateur Windows qui dispose des autorisations d'écriture dans le journal d'événements Windows peut accéder aux étapes de travail activées par les alertes WMI ou par les alertes de SQL Server Agent. Pour remédier à ce problème lié à la sécurité, les jetons de l'Agent SQL Server qui sont utilisables dans les travaux activés par les alertes sont désactivés par défaut. Ces jetons sont : A-DBN, A-SVR, A-ERR, A-SEV, A-MSG et WMI(property). Si vous devez utiliser ces jetons, assurez-vous d'abord que seuls les membres des groupes de sécurité Windows approuvés, comme le groupe Administrateurs, disposent des autorisations d'écriture pour le journal d'événements de l'ordinateur sur lequel SQL Server réside. Ensuite, affichez l'Explorateur d'objets, cliquez avec le bouton droit sur SQL Server Agent, puis sélectionnez Propriétés et dans la page Système d'alerte qui s'affiche, sélectionnez Remplacer les jetons pour toutes les réponses de travaux aux alertes pour activer ces jetons.

[ @additional_parameters= ] 'parameters'
Indiqué à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. parameters est de type ntext, avec NULL comme valeur par défaut.

[ @cmdexec_success_code = ] code
Valeur retournée par une commande du sous-système CmdExec pour indiquer que l'argument command a été exécuté avec succès. codeest de type int, avec 0 comme valeur par défaut.

[ @on_success_action= ] success_action
Action à exécuter si l'étape réussit. L'argument success_actionest de type tinyint et peut prendre l'une des valeurs suivantes.

Valeur Description (action)

1 (valeur par défaut)

Sortie avec succès

2

Sortie avec échec

3

Passez à l'étape suivante

4

Passer à l'étape on_success_step_id

Valeur	Description (action)
1 (valeur par défaut)	Sortie avec succès
2	Sortie avec échec
3	Passez à l'étape suivante
4	Passer à l'étape on_success_step_id

[ @on_success_step_id = ] success_step_id
ID de l'étape du travail à exécuter si l'étape réussit et que success_actiona la valeur 4. success_step_idest de type int, avec 0 comme valeur par défaut.

[ @on_fail_action= ] fail_action
Action à exécuter si l'étape échoue. L'argument fail_actionest de type tinyint et peut prendre l'une des valeurs suivantes.

Valeur Description (action)

1

Sortie avec succès

2 (valeur par défaut)

Sortie avec échec

3

Passer à l'étape suivante

4

Passer à l'étape on_fail_step_id

Valeur	Description (action)
1	Sortie avec succès
2 (valeur par défaut)	Sortie avec échec
3	Passer à l'étape suivante
4	Passer à l'étape on_fail_step_id

[ @on_fail_step_id= ] fail_step_id
ID de l'étape du travail à exécuter si l'étape échoue et que fail_actiona la valeur 4. fail_step_idest de type int, avec 0 comme valeur par défaut.

[ @server =] 'server'
Indiqué à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. serverest de type nvarchar(30), avec NULL comme valeur par défaut.

[ @database_name= ] 'database'
Nom de la base de données dans laquelle exécuter une étape Transact-SQL. L'argument databaseest de type sysname, avec NULL comme valeur par défaut. Dans ce cas, c'est la base de données master qui est utilisée. Pour une étape de travail ActiveX, database correspond au nom du langage de script utilisé par l'étape.

[ @database_user_name= ] 'user'
Nom du compte d'utilisateur à utiliser lors de l'exécution d'une étape Transact-SQL. L'argument user est de type sysname, avec NULL comme valeur par défaut. Lorsque la valeur de user est NULL, l'étape est exécutée dans le contexte de l'utilisateur propriétaire du travail dans database.

[ @retry_attempts= ] retry_attempts
Nombre de tentatives à effectuer si l'étape échoue. L'argument retry_attemptsest de type int, avec 0 comme valeur par défaut qui signifie qu'aucune tentative de reprise n'est effectuée.

[ @retry_interval= ] retry_interval
Nombre de minutes s'écoulant entre chaque tentative de reprise. L'argument retry_intervalest de type int, avec 0 comme valeur par défaut qui signifie que l'intervalle est de 0 minute.

[ @os_run_priority = ] run_priority
Indiqué à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie.

[ @output_file_name= ] 'file_name'
Nom du fichier dans lequel est sauvegardé le résultat de l'étape. L'argument file_nameest de type nvarchar(200), avec NULL comme valeur par défaut. Cet argument peut inclure un ou plusieurs jetons répertoriés sous command. Cet argument est valide uniquement avec les commandes fonctionnant dans les sous-systèmes Transact-SQL ou CmdExec.

[ @flags= ] flags
Option contrôlant le comportement. L'argument flags est de type int et peut prendre l'une des valeurs suivantes :

Valeur	Description
0 (valeur par défaut)	Écrasement du fichier de sortie
2	Ajout au fichier de sortie
4	Écriture de la sortie de l'étape d'un travail Transact-SQL dans l'historique des étapes.
8	Écriture du journal dans la table (remplace l'historique existant)
16	Écriture du journal dans la table (s'ajoute à l'historique existant)

[ @proxy_id = ] proxy_id
Numéro d'identification du proxy sous lequel s'exécute l'étape de travail. proxy_id est de type int, avec NULL comme valeur par défaut. Si aucune valeur proxy_id, proxy_name et user_name n'est spécifiée, l'étape du travail s'exécute sous le compte de service de l'Agent SQL Server.

[ @proxy_name= ] 'proxy_name'
Nom du proxy sous lequel l'étape d'un travail s'exécute. L'argument proxy_name est de type sysname, avec NULL comme valeur par défaut. Si aucune valeur proxy_id, proxy_name et user_name n'est spécifiée, l'étape du travail s'exécute sous le compte de service de l'Agent SQL Server.

Jeux de résultats

Aucun

Notes

La procédure sp_add_jobstep doit être exécutée à partir de la base de données msdb.

SQL Server Management Studio est un outil simple, basé sur une interface graphique, qui permet de gérer les travaux. Son utilisation est recommandée pour créer et gérer l'infrastructure des travaux.

Une étape de travail doit spécifier un proxy, sauf si le créateur de l'étape est membre du rôle de sécurité fixe sysadmin.

Un proxy est identifié par l'argument proxy_name ou proxy_id.

Autorisations

Seuls les membres du rôle de serveur fixe sysadmin peuvent exécuter cette procédure stockée. Les autres utilisateurs doivent disposer de l'un des rôles de base de données fixes SQL Server Agent suivants dans la base de données msdb.

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

Pour en savoir plus sur les autorisations de ces rôles, consultez Rôles de base de données fixes de l'Agent SQL Server.

Le créateur de l'étape de travail doit disposer des droits d'accès au proxy pour cette étape. Les membres du rôle de serveur fixe sysadmin disposent des droits d'accès à tous les serveurs proxy. Pour les autres utilisateurs, les droits d'accès à un proxy doivent être octroyés explicitement.

Valeurs des codes renvoyés

0 (succès) ou 1 (échec)

Exemple

L'exemple suivant montre la création de l'étape d'un travail permettant de modifier l'accès à une base de données appelée AdventureWorks et de lui affecter le mode d'accès en lecture seule. En outre, cet exemple indique 5 tentatives de reprises, chacune d'elles étant exécutée toutes les 5 minutes.

Remarque :
Cet exemple part du principe que le travail `Weekly Sales Data Backup` existe déjà.

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

Voir aussi

Historique des modifications

Version	Historique
14 avril 2006	Nouveau contenu : Insertion de la remarque Important sur la modification de la syntaxe des jetons SQL Server Agent dans SQL Server 2005 Service Pack 1. Contenu modifié : Suppression des descriptions de l'ancienne syntaxe des jetons SQL Server Agent.

14 avril 2006

Nouveau contenu :

Insertion de la remarque Important sur la modification de la syntaxe des jetons SQL Server Agent dans SQL Server 2005 Service Pack 1.

Contenu modifié :

Suppression des descriptions de l'ancienne syntaxe des jetons SQL Server Agent.