sp_add_jobstep (Transact-SQL)

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

Conventions de syntaxe Transact-SQL

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.

  Notes

  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 Agent SQL Server pour exécuter command. subsystem est de type nvarchar(40) et peut prendre l'une des valeurs suivantes :

  Valeur	Description
  'ACTIVESCRIPTING'	Script actif Important Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.
  '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 d'instantané 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
  'PowerShell'	script PowerShell
  '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. L'Agent SQL Server 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))

  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 Agent SQL Server, 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'
  Identifié à 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

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

• [ @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'
  Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie. server est 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 database est 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. Les noms placés entre crochets ([ ]) ne sont pas autorisés. 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. L'Agent SQL Server inclut ce paramètre uniquement si le propriétaire du travail est un sysadmin SQL Server. Dans ce cas, l'étape Transact-SQL donnée est exécutée dans le contexte du nom d'utilisateur SQL Server spécifié. Si le propriétaire du travail n'est pas un sysadmin SQL Server, l'étape Transact-SQL est toujours exécutée dans le contexte de la connexion qui possède ce travail et le paramètre @database_user_name est ignoré.

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

• [ @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. Ce paramètre est valide uniquement avec les commandes s'exécutant dans les sous-systèmes Transact-SQL, CmdExec, PowerShell, Integration Services ou Analysis Services.

• [ @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)
  32	Écriture de toute la sortie dans l'historique de travail
  64	Création d'un événement Windows à utiliser comme signal pour l'étape de travail Cmd à abandonner

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

Valeurs des codes renvoyés

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

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.

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

Notes

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

Voir aussi

Référence

sp_add_job (Transact-SQL)

sp_add_schedule (Transact-SQL)

sp_delete_jobstep (Transact-SQL)

sp_help_job (Transact-SQL)

sp_help_jobstep (Transact-SQL)

sp_update_jobstep (Transact-SQL)

Procédures stockées système (Transact-SQL)

Concepts

Affichage et modification des travaux