sp_add_jobstep (Transact-SQL)

Aktualisiert: 14. April 2006

Fügt einem Auftrag einen Schritt (eine Operation) hinzu.

Syntax

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

Argumente

• [ @job_id = ] job_id
  Die ID des Auftrags, dem der Schritt hinzugefügt werden soll. job_id ist vom Datentyp uniqueidentifier und hat den Standardwert NULL.

• [ @job_name = ] 'job_name'
  Der Name des Auftrags, dem der Schritt hinzugefügt werden soll. job_name ist vom Datentyp sysname und hat den Standardwert NULL.

  Hinweis:
  Es muss entweder job_id oder job_name angegeben werden, aber beide Angaben sind nicht möglich.

• [ @step_id = ] step_id
  Die Sequenz-ID des Auftragsschrittes. Schritt-IDs beginnen mit 1 und werden lückenlos erhöht. Wenn ein Schritt in eine vorhandene Sequenz eingefügt wird, werden die Sequenznummern automatisch angepasst. Wenn step_id nicht angegeben wird, wird ein Wert bereitgestellt. step_idist vom Datentyp int; der Standardwert ist NULL.

• [ @step_name = ] 'step_name'
  Der Name des Auftragschritts. step_nameist vom Datentyp sysname; es gibt keinen Standardwert.

• [ @subsystem = ] 'subsystem'
  Das vom Microsoft SQL Server-Agent zum Ausführen von command verwendete Subsystem. subsystemist vom Datentyp nvarchar(40). Folgende Werte sind möglich.

  Wert	Beschreibung
  'ACTIVESCRIPTING'	Active Script
  'CMDEXEC'	Betriebssystembefehl oder ausführbares Programm
  'DISTRIBUTION'	Auftrag des Replikationsverteilungs-Agents
  'SNAPSHOT'	Auftrag des Replikationssnapshot-Agents
  'LOGREADER'	Auftrag des Replikationsprotokolllese-Agents
  'MERGE'	Auftrag des Replikationsmerge-Agents
  'QueueReader'	Warteschlangenlese-Agent-Auftrag der Replikation
  'ANALYSISQUERY'	Analysis Services-Abfrage (MDX, DMX)
  'ANALYSISCOMMAND'	Analysis Services-Befehl (XMLA)
  'Dts'	Integration Services-Paketausführung
  'TSQL' (Standardwert)	Transact-SQL-Anweisung

• [ @command= ] 'command'
  Die vom SQLServerAgent-Dienst über subsystem auszuführenden Befehle. command ist vom Datentyp nvarchar(max) und hat den Standardwert NULL. Vom SQL Server-Agent wird eine Tokenersetzung bereitgestellt, die Ihnen beim Schreiben von Softwareprogrammen dieselbe Flexibilität wie Variablen bietet.

  Wichtig:

  In SQL Server 2005 Service Pack 1 wurde die Syntax von Token für Auftragsschritte des SQL Server-Agents geändert. Daher muss jetzt zu allen in Auftragsschritten verwendeten Token ein Escapemakro vorhanden sein, ansonsten tritt bei diesen Auftragsschritten ein Fehler auf. Darüber hinaus wurde die Syntax aus SQL Server 2000, in der Token für Auftragsschritte des SQL Server-Agents (beispielsweise "[DATE]") mit eckigen Klammern ausgezeichnet wurden, ebenfalls geändert. Jetzt müssen Sie Tokennamen in runde Klammern einschließen und ein Dollarzeichen ($) an den Anfang der Tokensyntax setzen. Beispiel: $(ESCAPE_macro name(DATE))

  Weitere Informationen zu diesen Token und zum Aktualisieren der Auftragsschritte auf die neue Tokensyntax finden Sie unter Verwenden von Token in Auftragsschritten.

  Sicherheitshinweis:

  Jeder Windows-Benutzer mit Schreibberechtigungen für das Windows-Ereignisprotokoll kann auf Auftragsschritte zugreifen, die durch SQL Server-Agent-Warnungen oder WMI-Warnungen aktiviert werden. Um dieses Sicherheitsrisiko zu vermeiden, sind SQL Server-Agenttoken, die in durch Warnungen aktivierten Aufträgen verwendet werden können, standardmäßig deaktiviert. Dabei handelt es sich um folgende Token: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG und WMI(property). Wenn Sie diese Token verwenden müssen, stellen Sie zuvor sicher, dass ausschließlich Mitglieder von vertrauenswürdigen Windows-Sicherheitsgruppen, wie der Administratorengruppe, über Schreibberechtigungen für das Ereignisprotokoll des Computers verfügen, auf dem SQL Server ausgeführt wird. Klicken Sie dann zum Aktivieren dieser Token im Objekt-Explorer mit der rechten Maustaste auf SQL Server-Agent, wählen Sie Eigenschaften aus, und wählen Sie anschließend auf der Seite Warnungssystem die Option Token für alle Auftragsantworten auf Warnungen ersetzen aus.

• [ @additional_parameters= ] 'parameters'
  Nur für Informationszwecke identifiziert. Nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt. parameters ist ein Wert vom Datentyp ntext. Der Standardwert ist NULL.

• [ @cmdexec_success_code = ] code
  Der von einem CmdExec-Subsystembefehl zurückgegebene Wert, der anzeigt, dass command erfolgreich ausgeführt wurde. code ist vom Datentyp int und hat den Standardwert 0.

• [ @on_success_action= ] success_action
  Die Aktion, die ausgeführt werden soll, wenn der Schritt erfolgreich ausgeführt wurde. success_action ist vom Datentyp tinyint. Die folgenden Werte sind möglich:

  Wert	Beschreibung (Aktion)
  1 (Standardwert)	Beenden mit Erfolg
  2	Beenden mit Fehler
  3	Zum nächsten Schritt wechseln
  4	Gehe zu Schritt on_success_step_id

• [ @on_success_step_id = ] success_step_id
  Die ID des Auftragsschrittes, der ausgeführt werden soll, wenn der Schritt erfolgreich ausgeführt wurde und success_action gleich 4 ist. success_step_id ist vom Datentyp int und hat den Standardwert 0.

• [ @on_fail_action= ] fail_action
  Die Aktion, die ausgeführt werden soll, wenn der Schritt fehlschlägt. fail_action ist vom Datentyp tinyint. Die folgenden Werte sind möglich:

  Wert	Beschreibung (Aktion)
  1	Beenden mit Erfolg
  2 (Standardwert)	Beenden mit Fehler
  3	Zum nächsten Schritt wechseln
  4	Gehe zu Schritt on_fail_step_id

• [ @on_fail_step_id= ] fail_step_id
  Die ID des Auftragsschrittes, der ausgeführt werden soll, wenn der Schritt fehlschlägt und fail_action gleich 4 ist. fail_step_id ist vom Datentyp int und hat den Standardwert 0.

• [ @server =] 'server'
  Nur für Informationszwecke identifiziert. Nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt. server ist ein Wert vom Datentyp nvarchar(30). Der Standardwert ist NULL.

• [ @database_name= ] 'database'
  Der Name der Datenbank, in der ein Transact-SQL-Schritt ausgeführt werden soll. database ist vom Datentyp sysname und hat den Standardwert NULL, womit die master-Datenbank verwendet wird. Für einen ActiveX-Auftragsschritt gibt database den Namen der vom Schritt verwendeten Skriptsprache an.

• [ @database_user_name= ] 'user'
  Der Name des Benutzerkontos, das beim Ausführen eines Transact-SQL-Schrittes verwendet werden soll. user ist vom Datentyp sysname; der Standardwert ist NULL. Wenn user gleich NULL ist, wird der Schritt im Benutzerkontext des Auftragsbesitzers von database ausgeführt.

• [ @retry_attempts= ] retry_attempts
  Die Anzahl der Wiederholungsversuche für den Fall, dass dieser Schritt fehlschlägt. retry_attempts ist vom Datentyp int und hat den Standardwert 0, der anzeigt, dass keine Wiederholungsversuche ausgeführt werden.

• [ @retry_interval= ] retry_interval
  Der Zeitraum in Minuten zwischen zwei Wiederholungsversuchen. retry_interval ist vom Datentyp int und hat den Standardwert 0, der ein Intervall von 0 Minuten angibt.

• [ @os_run_priority = ] run_priority
  Nur für Informationszwecke identifiziert. Nicht unterstützt. Zukünftige Kompatibilität wird nicht sichergestellt.

• [ @output_file_name= ] 'file_name'
  Der Name der Datei, in der die Ausgabe dieses Schrittes gespeichert wird. file_name ist vom Datentyp nvarchar(200) und hat den Standardwert NULL. file_name kann ein oder mehrere der unter command aufgeführten Token enthalten. Dieser Parameter ist nur mit Befehlen gültig, die im Transact-SQL- oder CmdExec-Subsystem ausgeführt werden.

• [ @flags= ] flags
  Eine Option, die das Verhalten steuert. flags ist vom Datentyp int. Die folgenden Werte sind möglich:

  Wert	Beschreibung
  0 (Standardwert)	Ausgabedatei überschreiben
  2	An Ausgabedatei anfügen
  4	Ausgabe des Transact-SQL-Auftragsschrittes in Schrittverlauf schreiben
  8	Protokoll in Tabelle schreiben (vorhandenen Verlauf überschreiben)
  16	Protokoll in Tabelle schreiben (an vorhandenen Verlauf anfügen)

• [ @proxy_id = ] proxy_id
  Die ID des Proxys, als der der Auftragsschritt ausgeführt wird. proxy_id ist vom Datentyp int und hat den Standardwert NULL. Wenn proxy_id, proxy_name und user_name nicht angegeben werden, wird der Auftragsschritt als Dienstkonto für den SQL Server-Agent ausgeführt.

• [ @proxy_name = ] 'proxy_name'
  Der Name des Proxys, als der der Auftragsschritt ausgeführt wird. proxy_name ist vom Datentyp sysname und hat den Standardwert NULL. Wenn proxy_id, proxy_name und user_name nicht angegeben werden, wird der Auftragsschritt als Dienstkonto für den SQL Server-Agent ausgeführt.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Resultsets

Keine

Hinweise

sp_add_jobstep muss von der msdb-Datenbank aus ausgeführt werden.

Mit SQL Server Management Studio lassen sich Aufträge auf einfache Weise mit einer grafischen Oberfläche verwalten. Dies ist die empfohlene Vorgehensweise zum Erstellen und Verwalten der Auftragsinfrastruktur.

Für einen Auftragsschritt muss ein Proxy angegeben werden, es sei denn, der Ersteller des Auftragsschrittes ist ein Mitglied der festen Sicherheitsrolle sysadmin.

Ein Proxy muss mithilfe von proxy_name oder proxy_id identifiziert werden.

Berechtigungen

Standardmäßig können nur Mitglieder der festen Serverrolle sysadmin diese gespeicherte Prozedur ausführen. Anderen Benutzern muss eine der folgenden festen Datenbankrollen des SQL Server-Agents in der msdb-Datenbank zugewiesen werden:

• SQLAgentUserRole
• SQLAgentReaderRole
• SQLAgentOperatorRole

Weitere Informationen zu den Berechtigungen dieser Rollen finden Sie unter Feste Datenbankrollen des SQL Server-Agents.

Der Ersteller des Auftragsschrittes muss Zugriff auf den für den Auftragsschritt verwendeten Proxy haben. Mitglieder der festen Serverrolle sysadmin haben Zugriff auf alle Proxys. Anderen Benutzern muss der Zugriff auf einen Proxy explizit erteilt werden.

Beispiele

Im folgenden Beispiel wird ein Auftragsschritt erstellt, der für die AdventureWorks-Datenbank den Schreibschutz aktiviert. Zudem werden in diesem Beispiel 5 Wiederholungsversuche festgelegt, wobei jede Wiederholung nach einer Wartezeit von 5 Minuten auftritt.

Hinweis:
Bei diesem Beispiel wird vorausgesetzt, dass der Auftrag Weekly Sales Data Backup bereits vorhanden ist.

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

Siehe auch

Verweis

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)
Gespeicherte Systemprozeduren (Transact-SQL)

Andere Ressourcen

Anzeigen und Ändern von Aufträgen

Hilfe und Informationen

Informationsquellen für SQL Server 2005

Änderungsverlauf

Version	Verlauf
14. April 2006	Neuer Inhalt: Ein wichtiger Hinweis zur Änderung der Syntax von Token des SQL Server-Agents in SQL Server 2005 Service Pack 1 wurde hinzugefügt. Geänderter Inhalt: Beschreibungen der alten Syntax von Token des SQL Server-Agents wurden entfernt.