Artikel
09/24/2010

sp_add_jobstep (Transact-SQL)

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

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

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

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

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

Wert	Beschreibung
'ACTIVESCRIPTING'	Active Script Wichtig Diese Funktion wird in zukünftigen Versionen von Microsoft SQL Server nicht mehr bereitgestellt. Verwenden Sie diese Funktion beim Entwickeln neuer Anwendungen nicht, und planen Sie das Ändern von Anwendungen, in denen es zurzeit verwendet wird.
'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
'PowerShell'	PowerShell-Skript
'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))

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(Eigenschaft). 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.

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(Eigenschaft).

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 lautet 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 Auftragsschritts, 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 Auftragsschritts, 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. In diesem Fall wird die master-Datenbank verwendet. In eckige Klammern ([ ]) eingeschlossene Namen sind nicht zulässig. 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-Schritts 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
Reserviert.
[ @output_file_name= ] 'file_name'
Der Name der Datei, in der die Ausgabe dieses Schritts 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-, CmdExec, PowerShell-, SQL Server Integration Services- oder SQL Server Analysis Services-Subsystem ausgeführt werden.

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

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

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