Verwenden von Token in Auftragsschritten
Der SQL Server-Agent ermöglicht die Verwendung von Token in Transact-SQL-Auftragsschrittskripts. Durch die Verwendung von Token verfügen Sie beim Schreiben von Auftragsschritten über dieselbe Flexibilität, die die Verwendung von Variablen beim Schreiben von Softwareprogrammen bietet. Die von Ihnen in ein Auftragsschrittskript eingefügten Token werden vom SQL Server-Agent zur Ausführungszeit ersetzt, bevor der Auftragsschritt vom Transact-SQL-Subsystem ausgeführt wird.
.gif "Wichtiger Hinweis") Wichtig |
|---|
Mit SQL Server 2005 Service Pack 1 wurde die Syntax der Token für die Arbeitsschritte des SQL Server-Agents geändert. Damit Auftragsschritte fehlerfrei ausgeführt werden können, müssen alle in Auftragsschritten verwendete Token von einem Escapemakro begleitet werden. Das Verwenden von Escapemakros und das Aktualisieren von SQL Server-Agent-Auftragsschritten, in denen Token verwendet werden, wird in den folgenden Abschnitten "Grundlegendes zum Verwenden von Token", "SQL Server-Agent-Token und -Makros" und "Aktualisieren von Auftragsschritten für die Verwendung von Makros" beschrieben. Außerdem wurde auch die SQL Server 2000-Syntax, in der zur Auszeichnung von SQL Server-Agent-Auftragsschritten eckige Klammern verwendet wurden (z. B. "[DATE]") 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)) |
Grundlegendes zum Verwenden von Token
.gif "Sicherheitshinweis") 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). Beachten Sie, dass in dieser Version die Verwendung von Token auf alle Warnungen ausgeweitet ist. 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, und wählen Sie anschließend auf der Seite Warnungssystem die Option Token für alle Auftragsantworten auf Warnungen ersetzen aus. |
Die Token für den SQL Server-Agent können einfach und effizient ersetzt werden: Der SQL Server-Agent ersetzt das Token durch ein genaues Zeichenfolgenliteral. Die Groß- und Kleinschreibung ist bei Token grundsätzlich zu beachten. Dies muss in den Auftragsschritten berücksichtigt werden, damit die verwendeten Token richtig angegeben werden oder die Ersatzzeichenfolge in den richtigen Datentyp konvertiert wird.
Mit der folgenden Anweisung können Sie z. B. den Namen der Datenbank in einem Auftragsschritt drucken:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
In diesem Beispiel wird das Makro ESCAPE_SQUOTE mit dem Token A-DBN eingefügt. Zur Laufzeit wird das Token A-DBN durch den entsprechenden Datenbanknamen ersetzt. Das Escapemakro umgeht alle einfachen Anführungszeichen, die möglicherweise unbeabsichtigt in der Zeichenfolge, durch die das Token ersetzt werden soll, übergeben werden. Der SQL Server-Agent ersetzt in der endgültigen Zeichenfolge jedes einfache Anführungszeichen durch zwei einfache Anführungszeichen.
Wenn beispielsweise als Ersatz für das Token die Zeichenfolge AdventureWorks2012'SELECT @@VERSION -- übergeben wird, wird im SQL Server-Agent-Auftragsschritt der folgende Befehl ausgeführt:
PRINT N'Current database name is AdventureWorks2012''SELECT @@VERSION --' ;
In diesem Fall wird die eingefügte Anweisung SELECT @@VERSION nicht ausgeführt. Stattdessen wird durch das überzählige einfache Anführungszeichen der Server veranlasst, die eingefügte Anweisung als Zeichenfolge zu analysieren. Wenn die Zeichenfolge, durch die das Token ersetzt werden soll, keine einfachen Anführungszeichen enthält, werden keine Zeichen umgangen, und der Auftragsschritt mit dem Token wird wie beabsichtigt ausgeführt.
Verwenden Sie zum Debuggen der Tokenverwendung in Auftragsschritten Druckanweisungen, wie z. B. PRINT N'$(ESCAPE_SQUOTE(SQLDIR))', und speichern Sie die Auftragsschrittausgabe in einer Datei oder Tabelle. Auf der Seite Erweitert des Dialogfelds Auftragsschritt-Eigenschaften können Sie eine Datei oder Tabelle für die Auftragsschrittausgabe angeben.
SQL Server-Agent-Token und -Makros
In der folgenden Tabelle sind die vom SQL Server-Agent unterstützten Token und Makros aufgelistet und beschrieben.
SQL Server-Agent-Token
Token |
Beschreibung |
|---|---|
(A-DBN) |
Datenbankname. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Datenbanknamens dieses Token im Auftragsschritt automatisch. |
(A-SVR) |
Servername. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Servernamens dieses Token im Auftragsschritt automatisch. |
(A-ERR) |
Die Fehlernummer. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert der Fehlernummer dieses Token im Auftragsschritt automatisch. |
(A-SEV) |
Fehlerschweregrad. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Fehlerschweregrads dieses Token im Auftragsschritt automatisch. |
(A-MSG) |
Meldungstext. Wenn der Auftrag durch eine Warnung ausgeführt wird, ersetzt der Wert des Meldungstexts dieses Token im Auftragsschritt automatisch. |
(DATE) |
Das aktuelle Datum (im Format YYYYMMDD). |
(INST) |
Der Instanzname. Für eine Standardinstanz erhält dieses Token den Standardinstanznamen: MSSQLSERVER. |
(JOBID) |
Auftrags-ID. |
(MACH) |
Computername. |
(MSSA) |
Name des Master-SQLServerAgent-Diensts. |
(OSCMD) |
Das Präfix des Programms, das zur Ausführung der CmdExec-Auftragsschritte verwendet wird. |
(SQLDIR) |
Verzeichnis, in dem SQL Server installiert ist. Der Standardwert lautet "C:\Programme\Microsoft SQL Server\MSSQL". |
(STEPCT) |
Die Angabe, wie oft dieser Schritt ausgeführt wurde (ohne Abbrüche). Mit diesem Token kann der Schrittbefehl den Abbruch einer aus mehreren Schritten bestehenden Schleife erzwingen. |
(STEPID) |
Schritt-ID. |
(SRVR) |
Name des Computers, auf dem SQL Server ausgeführt wird. Wenn es sich bei der SQL Server-Instanz um eine benannte Instanz handelt, ist auch der Name der Instanz angegeben. |
(TIME) |
Die aktuelle Zeit (im Format HHMMSS). |
(STRTTM) |
Uhrzeit (im Format HHMMSS), zu der die Ausführung des Auftrags begonnen hat. |
(STRTDT) |
Datum (im Format YYYYMMDD), an dem die Ausführung des Auftrags begonnen hat. |
(WMI (property))) |
Bei Aufträgen, die als Antwort auf WMI-Warnungen ausgeführt werden, ist dies der Wert der durch property angegebenen Eigenschaft. In $(WMI(DatabaseName)) ist beispielsweise der Wert der DatabaseName-Eigenschaft für das WMI-Ereignis angegeben, das die Ausführung der Warnung verursacht hat. |
SQL Server-Agent-Escapemakros
Escapemakros |
Beschreibung |
|---|---|
$(ESCAPE_SQUOTE(token_name)) |
Umgeht einfache Anführungszeichen (') in der Token-Ersetzungszeichenfolge. Ein einfaches Anführungszeichen wird durch zwei einfache Anführungszeichen ersetzt. |
$(ESCAPE_DQUOTE(token_name)) |
Umgeht doppelte Anführungszeichen (") in der Token-Ersetzungszeichenfolge. Ein doppeltes Anführungszeichen wird durch zwei doppelte Anführungszeichen ersetzt. |
$(ESCAPE_RBRACKET(token_name)) |
Umgeht rechte eckige Klammern (]) in der Token-Ersetzungszeichenfolge. Ersetzt jede rechte eckige Klammer durch zwei rechte eckige Klammern. |
$(ESCAPE_NONE(token_name)) |
Ersetzt Token, ohne irgendein Zeichen in der Zeichenfolge zu umgehen. Dieses Makro wird zur Unterstützung der Abwärtskompatibilität in Umgebungen bereitgestellt, in denen Token-Ersetzungszeichenfolgen nur von vertrauenswürdigen Benutzern erwartet werden. Weitere Informationen finden Sie weiter unten im Abschnitt zum Aktualisieren von Auftragsschritten für die Verwendung von Makros. |
Aktualisieren von Auftragsschritten für die Verwendung von Makros
Seit SQL Server 2005 Service Pack 1 können Auftragsschritte, die Token ohne Escapemakros enthalten, nicht ausgeführt werden. In diesen Fällen wird eine Fehlermeldung zurückgegeben, die darauf hinweist, dass der Auftragsschritt ein oder mehrere Token enthält, die mit einem Makro versehen werden müssen, bevor der Auftrag ausgeführt werden kann.
Im Microsoft Knowledge Base-Artikel 915845 zu SQL Server-Agent-Auftragsschritten mit Token, die in SQL Server 2005 Service Pack 1 nicht ausgeführt werden können, ist ein Skript enthalten, mit dem Sie alle Ihre Auftragsschritte, in denen Token verwendet werden, mit dem Makro ESCAPE_NONE aktualisieren können. Nach dem Verwenden dieses Skripts sollten Sie so bald wie möglich die Auftragsschritte, in denen Token verwendet werden, überprüfen und das ESCAPE_NONE-Makro durch ein für den Kontext des Auftragsschritts geeignetes Escapemakro ersetzen.
Die folgende Tabelle beschreibt, wie die symbolische Ersetzung von SQL Server-Agent behandelt wird. Um die Tokenersetzung durch Warnungen ein- oder auszuschalten, klicken Sie im Objekt-Explorer mit der rechten Maustaste auf SQL Server-Agent, wählen Sie Eigenschaften, und aktivieren bzw. deaktivieren Sie anschließend auf der Seite Warnungssystem das Kontrollkästchen Token für alle Auftragsantworten auf Warnungen ersetzen.
Tokensyntax |
Tokenersetzung durch Warnungen aktiviert |
Tokenersetzung durch Warnungen deaktiviert |
|---|---|---|
ESCAPE-Makro verwendet |
Alle Token in Auftragsschritten werden erfolgreich ersetzt. |
Durch Warnungen aktivierte Token werden nicht ersetzt. Dabei handelt es sich um folgende Token: A-DBN, A-SVR, A-ERR, A-SEV, A-MSG und WMI(property). Andere, statische Token werden erfolgreich ersetzt. |
Kein ESCAPE-Makro verwendet |
Alle Auftragsschritte mit Token werden nicht ausgeführt. |
Alle Auftragsschritte mit Token werden nicht ausgeführt. |
Beispiele für Updates der Tokensyntax
A.Verwenden von Token in nicht geschachtelten Zeichenfolgen
Im folgenden Beispiel wird gezeigt, wie Sie ein einfaches, nicht geschachteltes Skript mit dem entsprechenden Escapemakro aktualisieren. Vor dem Ausführen des Updateskripts verwendet das folgende Auftragsschrittskript ein Auftragsschritttoken, um den entsprechenden Datenbanknamen zu drucken:
PRINT N'Current database name is $(A-DBN)' ;
Nach dem Ausführen des Updateskripts wird vor dem A-DBN-Token ein ESCAPE_NONE-Makro eingefügt. Da die Druckzeichenfolge durch einfache Anführungszeichen begrenzt wird, müssen Sie den Auftragsschritt aktualisieren, indem Sie das ESCAPE_SQUOTE-Makro folgendermaßen einfügen:
PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;
B.Verwenden von Token in geschachtelten Zeichenfolgen
In Auftragsschritten, in denen Token in geschachtelten Zeichenfolgen oder Anweisungen verwendet werden, sollten die geschachtelten Anweisungen als Einzelanweisungen neu geschrieben werden, bevor die entsprechenden Escapemakros eingefügt werden.
Betrachten Sie z. B. den folgenden Auftragsschritt, der das Token A-MSG verwendet und nicht mit einem Escapemakro aktualisiert wurde:
PRINT N'Print ''$(A-MSG)''' ;
Nach dem Ausführen des Updateskripts wird mit dem Token ein ESCAPE_NONE-Makro eingefügt. In diesem Fall müssten Sie das Skript jedoch ohne Verwenden von Schachtelungen folgendermaßen neu schreiben und das ESCAPE_SQUOTE-Makro einfügen, damit die in der Token-Ersetzungszeichenfolge möglicherweise übergebenen Begrenzungszeichen richtig umgangen werden:
DECLARE @msgString nvarchar(max)
SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))'
SET @msgString = QUOTENAME(@msgString,'''')
PRINT N'Print ' + @msgString ;
Beachten Sie auch, dass in diesem Beispiel mit der Funktion QUOTENAME das Anführungszeichen festgelegt wird.
C.Verwenden von Token mit dem ESCAPE_NONE-Makro
Das folgende Beispiel ist Teil eines Skripts, mit dem die Auftrags-ID (job_id) aus der sysjobs-Tabelle abgerufen wird und mithilfe des JOBID-Tokens die zuvor im Skript als binärer Datentyp deklarierte @JobID-Variable aufgefüllt wird. Beachten Sie, dass mit dem JOBID-Token das ESCAPE_NONE-Makro verwendet wird, da für binäre Datentypen keine Begrenzungszeichen erforderlich sind. In diesem Fall muss der Auftragsschritt nach Ausführen des Updateskripts nicht aktualisiert werden.
SELECT * FROM msdb.dbo.sysjobs
WHERE @JobID = CONVERT(uniqueidentifier, $(ESCAPE_NONE(JOBID))) ;