Verwenden von „sqlcmd“ mit Skriptvariablensqlcmd - Use with Scripting Variables

GILT FÜR: JaSQL Server JaAzure SQL-Datenbank JaAzure Synapse Analytics (SQL DW) JaParallel Data Warehouse APPLIES TO: YesSQL Server YesAzure SQL Database YesAzure Synapse Analytics (SQL DW) YesParallel Data Warehouse

Variablen, die in Skripts verwendet werden, werden als Skriptvariablen bezeichnet.Variables that are used in scripts are called scripting variables. Durch Skriptvariablen wird ein Skript aktiviert, das in verschiedenen Szenarien verwendet wird.Scripting variables enable one script to be used in multiple scenarios. Wenn Sie beispielsweise ein einzelnes Skript auf mehreren Servern ausführen möchten, anstatt das Skript für jeden Server zu ändern, können Sie eine Skriptvariable für den Servernamen verwenden.For example, if you want to run one script against multiple servers, instead of modifying the script for each server, you can use a scripting variable for the server name. Durch das Ändern des Servernamens für die Skriptvariable kann das gleiche Skript auf verschiedenen Servern ausgeführt werden.By changing the server name supplied to the scripting variable, the same script can be executed on different servers.

Skriptvariablen können explizit mithilfe des Befehls setvar oder implizit mithilfe der Option sqlcmd -v definiert werden.Scripting variables can be defined explicitly by using the setvar command, or implicitly by using the sqlcmd -v option.

Dieses Thema enthält auch Beispiele zum Definieren von Umgebungsvariablen an der Eingabeaufforderung von „Cmd.exe“ mithilfe von SET.This topic also includes examples defining environmental variables at the Cmd.exe command prompt by using SET.

Festlegen von Skriptvariablen mithilfe des setvar-BefehlsSetting Scripting Variables by Using the setvar Command

Der Befehl setvar wird zum Definieren von Skriptvariablen verwendet.The setvar command is used to define scripting variables. Mithilfe des Befehls setvar definierte Variablen werden intern gespeichert.Variables that are defined by using the setvar command are stored internally. Skriptvariablen dürfen nicht mit Umgebungsvariablen verwechselt werden, die mithilfe von SETan der Eingabeaufforderung definiert werden.Scripting variables should not be confused with environment variables that are defined at the command prompt by using SET. Wenn ein Skript auf eine Variable verweist, die keine Umgebungsvariable ist oder nicht mithilfe von setvardefiniert wurde, wird eine Fehlermeldung zurückgegeben und die Ausführung des Skripts unterbrochen.If a script references a variable that is not an environment variable or is not defined by using setvar, an error message is returned and the execution of the script will stop. Weitere Informationen finden Sie unter der Option -b im Hilfsprogramm sqlcmd.For more information, see the -b option in sqlcmd Utility.

Rangfolge der Variablen (vom niedrigsten bis zum höchsten Rang)Variable Precedence (Low to High)

Wenn mehrere Variablentypen denselben Namen aufweisen, wird die Variable mit der höchsten Rangfolge verwendet.If more than one type of variable has the same name, the variable with the highest precedence is used.

  1. Umgebungsvariablen auf SystemebeneSystem level environmental variables

  2. Umgebungsvariablen auf BenutzerebeneUser level environmental variables

  3. Die vor dem Starten vonSET X=Yan der Eingabeaufforderung festgelegte Befehlsshell ( SET X=Y)Command shell (SET X=Y) set at command prompt before starting sqlcmd

  4. sqlcmd -v X=Ysqlcmd -v X=Y

  5. :Setvar X Y:Setvar X Y

Hinweis

Öffnen Sie die Systemsteuerung, klicken Sie auf Systemund anschließend auf die Registerkarte Erweitert , um die Umgebungsvariablen anzuzeigen.To view the environmental variables, in Control Panel, open System, and then click the Advanced tab.

Implizites Festlegen von SkriptvariablenImplicitly Setting Scripting Variables

Wenn Sie sqlcmd mit einer Option starten, die eine verknüpfte sqlcmd -Variable aufweist, wird die sqlcmd -Variable implizit auf den Wert festgelegt, der mithilfe der Option angegeben wurde.When you start sqlcmd with an option that has a related sqlcmd variable, the sqlcmd variable is set implicitly to the value that is specified by using the option. Im folgenden Beispiel beginnt sqlcmd mit der Option -l .In the following example, sqlcmd is started with the -l option. Dadurch wird implizit die SQLLOGINTIMEOUT-Variable festgelegt.This implicitly sets the SQLLOGINTIMEOUT variable.

c:\> sqlcmd -l 60

Sie können auch die Option -v verwenden, um eine Skriptvariable festzulegen, die in einem Skript vorhanden ist.You can also use the -v option to set a scripting variable that exists in a script. Im folgenden Skript (der Dateiname lautet testscript.sql) wird ColumnName als Skriptvariable verwendet.In the following script (the file name is testscript.sql), ColumnName is a scripting variable.

USE AdventureWorks2012;

SELECT x.$(ColumnName)
FROM Person.Person x
WHERE x.BusinessEntityID < 5;

Sie können daraufhin den Namen der Spalte angeben, die mithilfe der Option -v zurückgegeben werden soll:You can then specify the name of the column that you want returned by using the -v option:

sqlcmd -v ColumnName ="FirstName" -i c:\testscript.sql

Ändern Sie den Wert der ColumnName -Skriptvariablen, um eine andere Spalte mithilfe desselben Skripts zurückzugeben.To return a different column by using the same script, change the value of the ColumnName scripting variable.

sqlcmd -v ColumnName ="LastName" -i c:\testscript.sql

Richtlinien für Namen und Werte von SkriptvariablenGuidelines for Scripting Variable Names and Values

Die folgenden Richtlinien sollten bei der Benennung von Skriptvariablen berücksichtigt werden:Consider the following guidelines when you name scripting variables:

  • Variablennamen dürfen keine Leerzeichen oder Anführungszeichen enthalten.Variable names must not contain white space characters or quotation marks.

  • Variablennamen dürfen nicht die gleiche Form wie Variablenausdrücke (beispielsweise $(var) ) aufweisen.Variable names must not have the same form as a variable expression, such as $(var).

  • Bei Skriptvariablen wird nicht zwischen Groß- und Kleinschreibung unterschieden.Scripting variables are case-insensitive

    Hinweis

    Wenn einer sqlcmd -Umgebungsvariablen kein Wert zugewiesen wird, wird die Variable entfernt.If no value is assigned to a sqlcmd environment variable, the variable is removed. Bei Verwendung von :setvar VarName ohne Wert wird die Variable gelöscht.Using :setvar VarName without a value clears the variable.

Die folgenden Richtlinien sollten beim Angeben von Werten für Skriptvariablen berücksichtigt werden:Consider the following guidelines when you specify values for scripting variables:

  • Variablenwerte, die mit setvar oder mit der Option -v definiert werden, müssen in Anführungszeichen eingeschlossen werden, sofern im Zeichenfolgenwert Leerzeichen enthalten sind.Variable values that are defined by using setvar or the -v option must be enclosed by quotation marks if the string value contains spaces.

  • Wenn Anführungszeichen Bestandteil des Variablenwerts sind, müssen sie mit Escapezeichen versehen werden.If quotation marks are part of the variable value, they must be escaped. Beispiel: :setvar MyVar "spac""e".For example: :setvar MyVar "spac""e".

Richtlinien für Cmd.exe SET-Variablennamen und -werteGuidelines for Cmd.exe SET Variable Values and Names

Mithilfe von SET definierte Variablen sind Teil der Cmd.exe-Umgebung, und es kann mit sqlcmdauf sie verwiesen werden.Variables that are defined by using SET are part of the Cmd.exe environment and can be referenced by sqlcmd. Berücksichtigen Sie die folgenden Richtlinien:Consider the following guidelines:

  • Variablennamen dürfen keine Leerzeichen oder Anführungszeichen enthalten.Variable names must not contain white space characters or quotation marks.

  • Variablenwerte dürfen Leerzeichen oder Anführungszeichen enthalten.Variable values may contain spaces or quotation marks.

sqlcmd-Skriptvariablensqlcmd Scripting Variables

Mithilfe von sqlcmd definierte Variablen werden als Skriptvariablen bezeichnet.Variables that are defined by sqlcmd are known as scripting variables. In der folgenden Tabelle sind die sqlcmd -Skriptvariablen aufgelistet.The following table lists sqlcmd scripting variables.

VariableVariable Zugehörige OptionRelated option R/WR/W StandardDefault
SQLCMDUSER*SQLCMDUSER* -U-U RR """"
SQLCMDPASSWORD*SQLCMDPASSWORD* -P-P -- """"
SQLCMDSERVER*SQLCMDSERVER* -S-S RR "DefaultLocalInstance""DefaultLocalInstance"
SQLCMDWORKSTATIONSQLCMDWORKSTATION -H-H RR "ComputerName""ComputerName"
SQLCMDDBNAMESQLCMDDBNAME -d-d RR """"
SQLCMDLOGINTIMEOUTSQLCMDLOGINTIMEOUT -l-l R/WR/W "8" (Sekunden)"8" (seconds)
SQLCMDSTATTIMEOUTSQLCMDSTATTIMEOUT -t-t R/WR/W "0" = unbegrenzt warten"0" = wait indefinitely
SQLCMDHEADERSSQLCMDHEADERS -H-h R/WR/W "0""0"
SQLCMDCOLSEPSQLCMDCOLSEP -S-s R/WR/W „ “" "
SQLCMDCOLWIDTHSQLCMDCOLWIDTH -w-w R/WR/W "0""0"
SQLCMDPACKETSIZESQLCMDPACKETSIZE -a-a RR "4096""4096"
SQLCMDERRORLEVELSQLCMDERRORLEVEL -M-m R/WR/W "0""0"
SQLCMDMAXVARTYPEWIDTHSQLCMDMAXVARTYPEWIDTH -y-y R/WR/W "256""256"
SQLCMDMAXFIXEDTYPEWIDTHSQLCMDMAXFIXEDTYPEWIDTH -y-Y R/WR/W "0" = unbegrenzt"0" = unlimited
SQLCMDEDITORSQLCMDEDITOR R/WR/W "edit.com""edit.com"
SQLCMDINISQLCMDINI RR """"

SQLCMDUSER, SQLCMDPASSWORD und SQLCMDSERVER werden festgelegt, wenn :Connect verwendet wird.SQLCMDUSER, SQLCMDPASSWORD and SQLCMDSERVER are set when :Connect is used.

Durch R wird angezeigt, dass der Wert nur einmal während der Programminitialisierung festgelegt werden kann.R indicates the value can only be set one time during program initialization.

Durch R/W wird angezeigt, dass der Wert mithilfe des Befehls setvar zurückgesetzt werden kann. Für nachfolgende Befehle wird der neue Wert verwendet.R/W indicates that the value can be reset by using the setvar command and subsequent commands will use the new value.

BeispieleExamples

A.A. Verwenden des setvar-Befehls in einem SkriptUsing the setvar command in a script

Viele sqlcmd -Optionen können in einem Skript mithilfe des Befehls setvar gesteuert werden.Many sqlcmd options can be controlled in a script by using the setvar command. Im folgenden Beispiel wird das Skript test.sql erstellt, in dem die Variable SQLCMDLOGINTIMEOUT auf 60 Sekunden festgelegt ist. Eine weitere Skriptvariable ( server) wird auf testserverfestgelegt.In the following example, the script test.sql is created in which the SQLCMDLOGINTIMEOUT variable is set to 60 seconds and another scripting variable, server, is set to testserver. Der folgende Code befindet sich in test.sql.The following code is in test.sql.

:setvar SQLCMDLOGINTIMEOUT 60
:setvar server "testserver"
:connect $(server) -l $(SQLCMDLOGINTIMEOUT)

USE AdventureWorks2012;

SELECT FirstName, LastName
FROM Person.Person;

Das Skript wird anschließend mit „sqlcmd“ aufgerufen:The script is then called by using sqlcmd:

sqlcmd -i c:\test.sql

B.B. Interaktives Verwenden des setvar-BefehlsUsing the setvar command interactively

Im folgenden Beispiel wird veranschaulicht, wie eine Skriptvariable mithilfe des setvar -Befehls interaktiv festgelegt wird.The following example shows how to set a scripting variable interactively by using the setvar command.

sqlcmd
:setvar  MYDATABASE AdventureWorks2012
USE $(MYDATABASE);
GO

Hier ist das Resultset.Here is the result set.

Changed database context to 'AdventureWorks2012'
1>

C.C. Verwenden von Eingabeaufforderung-Umgebungsvariablen innerhalb von "sqlcmd"Using command prompt environment variables within sqlcmd

are Im folgenden Beispiel werden vier Umgebungsvariablen festgelegt und dann von sqlcmdaufgerufen.In the following example, four environment variables are set and then called from sqlcmd.

C:\>SET tablename=Person.Person
C:\>SET col1=FirstName
C:\>SET col2=LastName
C:\>SET title=Ms.
C:\>sqlcmd -d AdventureWorks2012
1> SELECT TOP 5 $(col1) + ' ' + $(col2) AS Name
2> FROM $(tablename)
3> WHERE Title ='$(title)'
4> GO

D:D. Verwenden von Umgebungsvariablen auf Benutzerebene in "sqlcmd"Using user-level environment variables within sqlcmd

Im folgenden Beispiel wird die %Temp% -Umgebungsvariable auf Benutzerebene an der Eingabeaufforderung festgelegt und an die sqlcmd -Eingabedatei übergeben.In the following example the user-level environmental variable %Temp% is set at the command prompt and passed to the sqlcmd input file. Zum Abrufen der Umgebungsvariable auf Benutzerebene doppelklicken Sie unter Systemsteuerungauf System.To obtain the user-level environment variable, in Control Panel, double-click System. Klicken Sie auf die Registerkarte Erweitert , und klicken Sie dann auf Umgebungsvariablen.Click the Advance tab, and then click Environment Variables.

In der Eingabedatei c:\testscript.txtist der folgende Code enthalten:The following code is in the input file c:\testscript.txt:

:OUT $(MyTempDirectory)
USE AdventureWorks2012;

SELECT FirstName
FROM AdventureWorks2012.Person.Person
WHERE BusinessEntityID` `< 5;

Der folgende Code wird an der Eingabeaufforderung eingegeben:This following code is entered at the command prompt:

C:\ >SET MyTempDirectory=%Temp%\output.txt
C:\ >sqlcmd -i C:\testscript.txt

Das folgende Ergebnis wird an die Ausgabedatei „C:\Dokumente und Einstellungen\<Benutzer>\Lokale Einstellungen\Temp\output.txt“ gesendet.The following result is sent to the output file C:\Documents and Settings\<user>\Local Settings\Temp\output.txt.

Changed database context to 'AdventureWorks2012'.
FirstName
--------------------------------------------------
Gustavo
Catherine
Kim
Humberto

(4 rows affected)

E.E. Verwenden eines StartskriptsUsing a startup script

Beim Starten von sqlcmd wird ein sqlcmd -Startskript ausgeführt.A sqlcmd startup script is executed when sqlcmd is started. Im folgenden Beispiel wird die Umgebungsvariable SQLCMDINIfestgelegt.The following example sets the environment variable SQLCMDINI. Dies ist der Inhalt von init.sql.This is the contents of init.sql.

SET NOCOUNT ON
GO

DECLARE @nt_username nvarchar(128)
SET @nt_username = (SELECT rtrim(convert(nvarchar(128), nt_username))
FROM sys.dm_exec_sessions WHERE spid = @@SPID)
SELECT  @nt_username + ' is connected to ' +
rtrim(CONVERT(nvarchar(20), SERVERPROPERTY('servername'))) +
' (' +`  
rtrim(CONVERT(nvarchar(20), SERVERPROPERTY('productversion'))) +
')'
:setvar SQLCMDMAXFIXEDTYPEWIDTH 100
SET NOCOUNT OFF
GO

:setvar SQLCMDMAXFIXEDTYPEWIDTH

Damit wird die Datei init.sql beim Starten von sqlcmd aufgerufen.This calls the init.sql file when sqlcmd is started.

c:\> SET sqlcmdini=c:\init.sql
>1 Sqlcmd

Dies ist die Ausgabe.This is the output.

>1 < user > is connected to < server > (9.00.2047.00)

Hinweis

Mit der Option -X wird die Startskriptfunktion deaktiviert.The -X option disables the startup script feature.

F.F. VariablenerweiterungVariable expansion

Im folgenden Beispiel wird die Verwendung von Daten in Form einer sqlcmd -Variablen veranschaulicht.The following example shows working with data in the form of a sqlcmd variable.

USE AdventureWorks2012;
CREATE TABLE AdventureWorks2012.dbo.VariableTest
(
Col1 nvarchar(50)
);
GO

Fügen Sie eine Zeile in Col1 von dbo.VariableTest ein, in der der Wert $(tablename)enthalten ist.Insert one row into Col1 of dbo.VariableTest that contains the value $(tablename).

INSERT INTO AdventureWorks2012.dbo.VariableTest(Col1)
VALUES('$(tablename)');
GO

Wenn keine Variable auf einen Wert gleich sqlcmd festgelegt ist, wird die Zeile an der $(tablename)-Eingabeaufforderung mit folgenden Anweisungen zurückgegeben:At the sqlcmd prompt, when no variable is set equal to $(tablename), the following statements return the row.

C:\> sqlcmd
>1 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(tablename)';
>2 GO
>3 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(tablename)';
>4 GO

Hier ist das Resultset.Here is the result set.

>1 Col1
>2 ------------------
>3 $(tablename)
>4
>5 (1 rows affected)

Es wird angenommen, dass die Variable MyVar auf $(tablename)festgelegt ist.Given the variable MyVar is set to $(tablename).

>6 :setvar MyVar $(tablename)

Die Zeile wird mit diesen Anweisungen zurückgegeben. Außerdem wird die Meldung "Die 'tablename'-Skriptvariable ist nicht definiert." zurückgegeben.These statements return the row and also return the message "'tablename' scripting variable not defined."

>6 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(tablename)';
>7 GO

>1 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(tablename)';
>2 GO

Die Zeile wird mit diesen Anweisungen zurückgegeben.These statements return the row.

>1 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = '$(MyVar)';
>2 GO
>1 SELECT Col1 FROM dbo.VariableTest WHERE Col1 = N'$(MyVar)';
>2 GO

Weitere InformationenSee Also

Verwenden des Hilfsprogramms „sqlcmd“ Use the sqlcmd Utility
sqlcmd (Hilfsprogramm) sqlcmd Utility
Referenz zum Eingabeaufforderungs-Hilfsprogramm (Datenbank-Engine)Command Prompt Utility Reference (Database Engine)