Программа sqlcmd

Изменения: 17 июля 2006 г.

Программа sqlcmd позволяет вводить инструкции Transact-SQL, системные процедуры и файлы сценариев в командную строку, в Редакторе запросов в режиме SQLCMD, в файл сценария или шаг задания операционной системы (Cmd.exe) задания агента SQL Server. Эта программа использует технологию OLE DB для выполнения пакетов Transact-SQL.

Важно!

Среда SQL Server Management Studio использует компонент Microsoft .NET Framework SqlClient для выполнения в обычном режиме и в Редакторе запросов в режиме SQLCMD. При вызове sqlcmd из командной строки программа использует поставщика OLE DB. Так как могут применяться различные параметры по умолчанию, выполнение одного и того же запроса в среде SQL Server Management Studio в режиме SQLCMD и в программе sqlcmd может проходить по-разному.

Синтаксис

sqlcmd 
[{ { -U login_id [ -P password ] } | –E trusted connection }] 
[ -z new password ] [ -Z new password and exit]
[ -S server_name [ \ instance_name ] ] [ -H wksta_name ] [ -d db_name ]
[ -l login time_out ] [ -A dedicated admin connection ] 
[ -i input_file ] [ -o output_file ]
[ -f < codepage > | i: < codepage > [ < , o: < codepage > ] ]
[ -u unicode output ] [ -r [ 0 | 1 ] msgs to stderr ] 
[ -R use client regional settings ]
[ -q "cmdline query" ] [ -Q "cmdline query" and exit ] 
[ -e echo input ] [ -t query time_out ] 
[ -I enable Quoted Identifiers ] 
[ -v var = "value"...] [ -x disable variable substitution ]
[ -h headers ][ -s col_separator ] [ -w column_width ] 
[ -W remove trailing spaces ]
[ -k [ 1 | 2 ] remove[replace] control characters ] 
[ -y display_width ] [-Y display_width ]
[ -b on error batch abort ] [ -V severitylevel ] [ -m error_level ] 
[ -a packet_size ][ -c cmd_end ] 
[ -L [ c ] list servers[clean output] ] 
[ -p [ 1 ] print statistics[colon format] ] 
[ -X [ 1 ] ] disable commands, startup script, enviroment variables [and exit] 
[ -? show syntax summary ]

Параметры командной строки

• Параметры, связанные с именем входа

• -Ulogin_id
  Идентификатор входа пользователя.

  Примечание.
  В целях обратной совместимости доступна переменная среды OSQLUSER. Переменная среды SQLCMDUSER имеет больший приоритет, чем OSQLUSER, то есть программы sqlcmd и osql могут применяться одновременно, не мешая друг другу. Это означает также, что существующие сценарии osql не перестанут работать.

  Если не указаны ни параметр -U, ни параметр -P, то программа sqlcmd пытается подключиться с помощью режима проверки подлинности Microsoft Windows. При этом используется учетная запись пользователя Windows, который запустил программу sqlcmd.

  Если параметры -U и -E (описаны ниже в этом разделе) указаны одновременно, выдается сообщение об ошибке. Если вслед за параметром -U указано более одного аргумента, выдается сообщение об ошибке и программа завершает свою работу.

• -Pпароль
  Пароль, заданный пользователем. Пароли учитывают регистр. Если указан параметр -U, а параметр -P отсутствует, и не установлена переменная среды SQLCMDPASSWORD, программа sqlcmd запрашивает пароль у пользователя. Если параметр -P указан в конце командной строки без указания пароля, то программа sqlcmd использует значение пароля по умолчанию (NULL).

  Примечание безопасности.
  Не используйте пустой пароль. Всегда выбирайте надежный пароль. Дополнительные сведения см. в разделе Надежные пароли.

  Запрос на ввод пароля выводится на консоль следующим образом: Password:

  Вводимые пользователем данные на экране не отображаются, то есть символы не выводятся и курсор остается на месте.

  Переменная среды SQLCMDPASSWORD позволяет задать значение пароля по умолчанию для текущего сеанса. Таким образом, нет необходимости указывать пароль в пакетных файлах.

  В следующем примере сначала устанавливается переменная SQLCMDPASSWORD в командной строке, а затем производится вызов программы sqlcmd. В командной строке введите:

  SET SQLCMDPASSWORD= p@a$$w0rd

  Примечание безопасности.
  Пароль будет отображаться на мониторе компьютера.

  В командной строке введите:

  sqlcmd

  Если обнаружено неправильное сочетание имени пользователя и пароля, поставщик OLE DB выдает сообщение об ошибке.

  Примечание.
  Переменная среды OSQLPASSWORD была сохранена в целях обратной совместимости. Переменная среды SQLCMDPASSWORD имеет больший приоритет, чем переменная среды OSQLPASSWORD. Это означает, что программы sqlcmd и osql могут использоваться одновременно, не мешая друг другу, и сценарии прежних версий не перестанут работать.

  Если параметр -P указан одновременно с параметром -E, выдается сообщение об ошибке.

  Если после параметра -P указано более одного аргумента, выдается сообщение об ошибке и программа завершает свою работу.

• -E trusted connection
  Использует для соединения с SQL Server вместо имени пользователя и пароля доверенное соединение. По умолчанию, если параметр -E не указан, программа sqlcmd использует доверенное соединение.

  Параметр -E не использует имя пользователя и пароль, указанные в переменных среды SQLCMDPASSWORD и др. Если параметр -E указан одновременно с параметром -U или -P, выдается сообщение об ошибке.

• -z new password
  Сменить пароль:

  sqlcmd -U someuser -P s0mep@ssword -z a_new_p@a$$w0rd

• -Z new password and exit
  Сменить пароль и выйти:

  sqlcmd -U someuser -P s0mep@ssword -Z a_new_p@a$$w0rd

• -Sserver_name [ **\**instance_name ]
  Указывает экземпляр SQL Server, к которому выполняется подключение. Устанавливает переменную сценария SQLCMDSERVER программы sqlcmd.

  Укажите сервер для подключения к экземпляру SQL Server по умолчанию на этом сервере. Укажите сервер[ **\**экземпляр], чтобы соединиться с именованным экземпляром SQL Server на этом сервере. Если сервер не указан, программа sqlcmd соединяется с экземпляром SQL Server по умолчанию на локальном компьютере. Этот параметр обязателен при запуске программы sqlcmd с удаленного компьютера в сети.

  Если значение сервер[ **\**экземпляр] при запуске программы sqlcmd не указано, SQL Server проверяет наличие переменной среды SQLCMDSERVER и, если она установлена, использует ее значение.

  Примечание.
  Переменная среды OSQLSERVER была сохранена в целях обратной совместимости. Переменная среды SQLCMDSERVER имеет больший приоритет, чем переменная среды OSQLSERVER. Это означает, что программы sqlcmd и osql могут применяться одновременно, не мешая друг другу, и сценарии прежних версий не перестанут работать.

• -Hимя_узла
  Имя рабочей станции. Этот параметр устанавливает переменную сценария SQLCMDWORKSTATION программы sqlcmd. Имя рабочей станции заносится в столбец host_name динамического административного представления sys.dm_exec_sessions или может быть возвращено хранимой процедурой sp_who. Если этот параметр не указан, используется текущее имя компьютера. Это имя может использоваться для идентификации сеансов работы программы sqlcmd.

• -dимя_используемой_БД
  Выдает инструкцию USE db_name при запуске программы sqlcmd. Этот параметр устанавливает переменную сценария SQLCMDDBNAME программы sqlcmd. Она задает начальную базу данных. По умолчанию свойство default-database имени входа. Если база данных не существует, то выдается сообщение об ошибке и программа sqlcmd завершает свою работу.

• -lвремя_ожидания_входа
  Задает время ожидания (в секундах) при подключении программы sqlcmd через поставщик OLE DB при попытке соединения с сервером. Этот параметр устанавливает переменную сценария SQLCMDLOGINTIMEOUT программы sqlcmd. По умолчанию для программы sqlcmd время ожидания составляет восемь секунд. Время ожидания должно быть числом от 0 до 65 534. Если указанное значение не является числом или не находится в этом диапазоне, программа sqlcmd выдаст сообщение об ошибке. Значение 0 задает неограниченное время ожидания.

• -A dedicated admin connection
  Входит на SQL Server посредством выделенного административного соединения. Этот вид соединения предназначен для устранения неполадок на сервере. Параметр будет работать только с теми серверами, которые поддерживают выделенные административные соединения. Если такое соединение недоступно, то программа sqlcmd выдает сообщение об ошибке и завершает свою работу. Дополнительные сведения о выделенных административных соединениях см. в разделе Использование выделенного административного подключения.

• Параметры ввода-вывода

• -i input_file[***,***input_file2...]
  Указывает файл, содержащий пакет инструкций или хранимых процедур SQL. Можно указать несколько файлов, которые будут считываться и обрабатываться в указанном порядке. Не разделяйте имена файлов пробелами. Программа sqlcmd сначала производит проверку наличия всех указанных файлов. Если хотя бы один из файлов не найден, то программа sqlcmd завершит работу. Параметры -i и -Q/-q являются взаимоисключающими.

  Примеры пути:

  -i C:\<имя_файла>

  -i \\<Сервер>\<ОбщаяПапка$>\<имя_файла>

  -i "C:\Некоторая папка\<имя файла>"

  Пути к файлам, содержащие пробелы, необходимо заключать в кавычки.

  Этот параметр можно указывать многократно: -i входной_файл-i входной_файл2

• -ooutput_file
  Указывает файл, в который направляется вывод программы sqlcmd.

  Если указан параметр -u, output_file сохраняется в Юникоде. Если имя файла недопустимо, выдается сообщение об ошибке и программа sqlcmd завершает работу. Одновременная запись нескольких процессов в один файл не поддерживается. В этом случае выводимые в файл данные будут неверны или повреждены. Дополнительные сведения о форматах файлов см. в разделе о параметре -f. Если этот файл не существует, он будет создан. Файл от предыдущего сеанса работы программы sqlcmd с тем же именем будет перезаписан. Указанный здесь файл не является файлом stdout. Если указан файл stdout, то этот файл не будет использоваться.

  Примеры пути:

  -o C:\<имя_файла>

  -o \\<Сервер>\<ОбщаяПапка$>\<имя_файла>

  -o "C:\Некоторая папка\<имя файла>"

  Пути к файлам, содержащие пробелы, необходимо заключать в кавычки.

• -f < codepage > кодовая_страница < codepage > > | i: < кодовая_страница>** [ <, o: < кодовая_страница**>** ] <** codepage > ]
  Задает входные и выходные кодовые страницы. Номер кодовой страницы — это числовое значение, которое определяет установленную кодовую страницу Windows. Дополнительные сведения см. в разделе Настройка параметров сортировки в программе установки.

  Правила преобразования кодовых страниц:

  • Если кодовая страница не задана, то программа sqlcmd использует текущую кодовую страницу как для входных, так и для выходных файлов. Если входной файл в Юникоде, то в этом случае преобразование не требуется.
  • Программа sqlcmd автоматически распознает входные файлы в Юникоде как с прямым, так и с обратным порядком следования байтов. Если задан параметр -u, то выходные данные всегда будут в Юникоде с прямым порядком следования байтов.
  • Если выходной файл не задан, то выходные данные будут иметь кодовую страницу консоли. Это обеспечивает правильное отображение данных на консоли.
  • Предполагается, что все входные файлы имеют одинаковую кодовую страницу. Входные файлы в Юникоде и не в Юникоде можно обрабатывать вместе.

  Чтобы проверить кодовую страницу Cmd.exe, введите в командной строке команду chcp.

• -u unicode output
  Указывает, что выходной_файл хранится в Юникоде вне зависимости от формата файла входной_файл.

• -r [ 0 | 1] msgs to stderr
  Перенаправляет вывод сообщений об ошибке на экран (stderr). Если параметр не указан или если указано значение 0, происходит перенаправление только сообщений об ошибках с уровнем серьезности 11 и выше. Если указать 1, то происходит перенаправление всех сообщений об ошибках (включая команду PRINT). Не имеет эффекта при использовании параметра -o. По умолчанию сообщения выдаются на stdout.

• -R use client regional settings
  Устанавливает использование поставщиком OLE DB SQL Server региональных настроек клиента при преобразовании данных денежного формата, формата даты и времени в символьные данные. По умолчанию используются региональные настройки сервера.

• Параметры выполнения запроса

• -q"запрос_ком.строки и выйти"
  При запуске программы sqlcmd выполняет запрос, но выход из программы по завершении его выполнения не производится. Могут быть выполнены несколько запросов, разделенные точкой с запятой. Заключайте запрос в кавычки, как показано в следующем примере.

  В командной строке введите:

  sqlcmd -d AdventureWorks -q "SELECT FirstName, LastName FROM Person.Contact WHERE LastName LIKE 'Whi%';"

  sqlcmd -d AdventureWorks -q "SELECT TOP 5 FirstName FROM Person.Contact;SELECT TOP 5 LastName FROM Person.Contact;"

  Важно!
  Не используйте в запросе признак конца GO.

  Если вместе с этим параметром указан параметр -b, программа sqlcmd завершит работу при возникновении ошибок. Параметр -b описан далее в этом разделе.

• **-Q"запрос_ком.строки"**и выйти
  При запуске программы sqlcmd выполняет запрос и немедленно завершает работу. Можно выполнить несколько запросов, разделив их точкой с запятой.

  Заключайте запрос в кавычки, как показано в следующем примере.

  В командной строке введите:

  sqlcmd -d AdventureWorks -Q "SELECT FirstName, LastName FROM Person.Contact WHERE LastName LIKE 'Whi%';"

  sqlcmd -d AdventureWorks -Q "SELECT TOP 5 FirstName FROM Person.Contact;SELECT TOP 5 LastName FROM Person.Contact;"

  Важно!
  Не используйте в запросе признак конца GO.

  Если вместе с этим параметром указан параметр -b, программа sqlcmd завершает работу при возникновении ошибки. Параметр -b описан далее в этом разделе.

• -e echo input
  Выдает входные сценарии на стандартное устройство вывода (stdout).

• -I enable Quoted Identifiers
  Устанавливает значение ON для параметра соединения SET QUOTED_IDENTIFIER. По умолчанию этот параметр имеет значение OFF. Дополнительные сведения см. в разделе SET QUOTED_IDENTIFIER (Transact-SQL).

• -tвремя_ожидания_запроса
  Задает число секунд времени ожидания команды (или инструкции SQL). Этот параметр устанавливает переменную сценария SQLCMDSTATTIMEOUT программы sqlcmd. Если значение время_ожидания_запроса не указывается, то команда имеет неограниченное время ожидания. Параметр время_ожидания_запроса должен иметь значение от 1 до 65 535. Если указанное значение не является числом или не находится в указанном диапазоне, программа sqlcmd выдает сообщение об ошибке.

  Примечание. Фактическое время ожидания может отличаться от указанного значения время_ожидания_запроса на несколько секунд.

• -vпеременная="значение"[ переменная="значение"...]
  Создает переменную сценария sqlcmd, которая может быть использована в сценарии sqlcmd. Если значение содержит пробелы, заключите его в кавычки. Можно определить несколько пар переменная="значение". Если в каком-либо из указанных значений обнаружена ошибка, программа sqlcmd выдает сообщение об этом и завершает работу.

  sqlcmd -v MyVar1=something MyVar2="some thing"

  sqlcmd -v MyVar1=something -v MyVar2="some thing"

• -x disable variable substitution
  Указывает, что программа sqlcmd не должна обрабатывать переменные сценария. Это может отказаться полезным в том случае, если в сценарии содержится много инструкций INSERT, которые могут содержать строки, имеющие тот же формат, что и обычные переменные, т.е. $(переменная).

• Параметры форматирования

• -hзаголовки
  Указывает количество строк для печати между заголовками столбцов. По умолчанию заголовки печатаются один раз для каждого набора результатов запроса. Этот параметр устанавливает переменную сценария SQLCMDHEADERS программы sqlcmd. Используйте значение -1 для отмены печати заголовков. Любое недопустимое значение приводит к тому, что программа sqlcmd выдает сообщение об ошибке и завершает свою работу.

• -sразделитель_столбцов
  Задает символ-разделитель столбцов. Значением по умолчанию является пробел. Этот параметр устанавливает переменную сценария SQLCMDCOLSEP программы sqlcmd. Чтобы использовать символы, имеющие специальное значение для операционной системы, такие как амперсанд (&) или точка с запятой (;), заключайте этот символ в кавычки ("). Разделитель столбцов может быть любым 8-разрядным символом.

• -wширина_экрана
  Задает ширину экрана для вывода. Этот параметр устанавливает переменную сценария SQLCMDCOLWIDTH программы sqlcmd. Ширина экрана должна быть числом в диапазоне от 8 до 65 536. Если указанное значение выходит за пределы диапазона, программа sqlcmd выдает сообщение об ошибке. Ширина по умолчанию составляет 80 символов. Когда строка вывода превышает указанную ширину столбца, вывод переносится на следующую строку.

• -W remove trailing spaces
  Этот параметр удаляет конечные пробелы в столбце. При подготовке данных для экспорта в другое приложение указывайте этот параметр вместе с параметром -s. Не может указываться одновременно с параметром -y или -Y.

• -k [ 1 | 2 ] remove[replace] control characters
  Удаляет из выходных данных все управляющие символы, такие как символы табуляции и символы новой строки. Это сохраняет формат столбцов при возврате данных. При указании значения 1 управляющие символы заменяются одиночным пробелом. Если указано значение 2, все последовательные управляющие символы заменяются одиночным пробелом.

• -yширина_для_переменных_типов
  Этот параметр устанавливает переменную сценария SQLCMDMAXVARTYPEWIDTH программы sqlcmd. По умолчанию 0 (не установлено). Ограничивает число символов, возвращаемых для типов данных переменной длины:

  • varchar(max)
  • nvarchar(max)
  • varbinary(max)
  • xml
  • Определяемые пользователем типы
  • text
  • ntext
  • image

  Примечание.
  Определяемые пользователем типы могут иметь фиксированную длину в зависимости от реализации. Если фиксированная длина определяемого пользователем типа короче, чем значение переменной ширина_экрана, то значение типа возвращается без изменений. Однако если длина превышает значение ширина_экрана, то производится усечение выходных данных.

  Если для параметра «ширина_экрана» указано значение 0, происходит усечение размера выходных данных до 1 МБ. Чтобы предотвратить усечение данных, можно воспользоваться командой :XML ON. Эта команда описана далее в этом разделе.

  Важно!
  Пользуйтесь параметром -y0 с особой осторожностью, поскольку при большом объеме возвращаемых данных это может значительно снизить производительность работы сервера и сети.

• -Yширина_для_фиксированных_типов
  Этот параметр устанавливает переменную сценария SQLCMDMAXFIXEDTYPEWIDTH программы sqlcmd. Значение по умолчанию — 256. Ограничивает число символов, возвращаемых для следующих типов данных:

  • char, где 1<n<8000;
  • nchar , где 1<n<4000;
  • varchar(n), где 1<n<8000;
  • nvarchar(n), где 1<n<4000;
  • varbinary(n), где 1<n<8000;
  • sql_variant

• Параметры отчета об ошибках

• -bзавершить_выполнение_командного_файла_при_ошибке
  Указывает, что при возникновении ошибки программа sqlcmd завершает работу и возвращает в DOS значение ERRORLEVEL. Значение, возвращаемое в переменную DOS ERRORLEVEL, равно 1, если сообщение об ошибке SQL Server имеет уровень серьезности выше 10. В противном случае возвращаемое значение равно 0. Если параметр -b был указан вместе с параметром -V, то программа sqlcmd не будет выдавать сообщение об ошибках, уровень серьезности которых ниже значения, заданного параметром -V. Пакетный файл командной строки может проверить значение ERRORLEVEL и выполнить соответствующую обработку ошибки. Программа sqlcmd не выдает сообщений об ошибках с уровнем серьезности 10 (информационные сообщения).

  Если сценарий программы sqlcmd содержит неправильный комментарий, синтаксическую ошибку или обнаружено отсутствие переменной сценария, то возвращается значение ERRORLEVEL, равное 1.

• -V severitylevel
  Задает минимальный уровень серьезности, при котором программа sqlcmd выдает сообщение. При возникновении в сценарии Transact-SQL ошибки уровень серьезности выдается только в том случае, если он больше или равен значению, заданному параметром -V. Если уровень серьезности меньше заданного уровня, выводится 0. По умолчанию уровень ошибки равен 0. Пакетный файл командной строки может проверить значение ERRORLEVEL и выполнить соответствующую обработку ошибки.

• -mуровень_сообщений_об_ошибках
  Настраивает отображение сообщений об ошибках. Номер сообщения, состояние и уровень ошибки отображаются для ошибок с уровнем серьезности выше заданного. Для ошибок с уровнем серьезности ниже заданного уровня данные не отображаются. Используйте значение -1, чтобы указать, что все заголовки должны возвращаться с сообщениями, даже с информационными. Если указывается значение -1, не ставьте пробел между параметром и значением (например, -m-1, а не -m-1).

  Этот параметр устанавливает переменную сценария SQLCMDERRORLEVEL программы sqlcmd, которая по умолчанию равна 0.

• Различные параметры

• -aразмер_пакета
  Запрашивает пакет другого размера. Этот параметр устанавливает переменную сценария SQLCMDPACKETSIZE программы sqlcmd. Параметр размер_пакета должен иметь значение в диапазоне от 512 до 32 767. Значение по умолчанию равно 4096. Увеличение размера пакета повышает производительность выполнения сценариев, содержащих большое количество инструкций SQL между командами GO. Можно запросить больший размер пакета. Однако в том случае, если запрос будет запрещен, программа sqlcmd использует размер пакета по умолчанию для сервера.

• -cконец_команды
  Задает признак конца пакета. По умолчанию команды завершаются и отправляются на SQL Server при вводе слова «GO» в отдельной строке. При сбросе признака конца пакета не используйте зарезервированные ключевые слова или символы Transact-SQL, которые имеют специальное значение для операционной системы, даже если перед ними присутствует символ обратной косой черты.

• -L [ c ] вывести_список_серверов[очистить_вывод]
  Выводит список локально настроенных серверов и имена серверов, осуществляющих передачу данных в сети. Этот параметр не может использоваться в сочетании с другими параметрами. В списке может быть перечислено не более 3 000 серверов. При усечении списка серверов в связи с нехваткой размера буфера выдается предупреждающее сообщение об этом.

  Примечание.
  Из-за особенностей сетевого широковещания программа sqlcmd не всегда своевременно получает ответ от всех серверов. Поэтому возвращаемый список серверов от вызова к вызову может различаться.

  Если указан дополнительный параметр «c», выводимые данные отображаются без строки заголовка «Серверы», а строка каждого сервера выводится без начальных пробелов. Это называется «чистым выводом». Чистый выход улучшает производительность обработки языков сценариев.

• -p [ 1 ] print statistics[colon format]
  Выводит на печать статистику производительности для каждого результирующего набора. Далее представлен пример формата для статистики производительности:

  Network packet size (bytes): n

  x xact[s]:

  Clock Time (ms.): total t1 avg t2 (t3 xacts per sec.)

  Где:

  x = Количество транзакций, обработанных SQL Server.

  t1 = Общее время обработки всех транзакций.

  t2 = Среднее время обработки одной транзакции.

  t3 = Среднее количество транзакций, обрабатываемых в секунду.

  Все значения времени приведены в миллисекундах.

  Если указывается необязательный параметр 1, статистика выводится в формате со столбцами, разделенными двоеточиями, и может быть легко импортирована в электронную таблицу или обработана сценарием.

  Если необязательный параметр имеет любое значение, кроме 1, то выводится сообщение об ошибке и программа sqlcmd завершает работу.

• -X [ 1 ] отключить_команды,сценарии_запуска,переменные_среды[и_выйти] [and exit]
  Отключает команды, которые могут поставить под угрозу безопасность системы при выполнении программы sqlcmd из пакетного файла. Отключенные команды по-прежнему распознаются: sqlcmd выдает предупреждающее сообщение и продолжает работу. Если необязательный параметр равен 1, программа sqlcmd выдает сообщение об ошибке и завершает работу. При использовании параметра -X происходит отключение следующих команд:

  • ED
  • **!!**command

  Указание параметра -X блокирует передачу переменных среды программе sqlcmd. Он также препятствует выполнению сценария запуска, указанного с помощью переменной сценария SQLCMDINI. Дополнительные сведения об использовании переменных сценария sqlcmd см. в разделе Использование программы sqlcmd с переменными сценария.

• -? show syntax summary
  Отображает сводку по синтаксису параметров программы sqlcmd.

Замечания

Параметры не обязательно должны указываться в том порядке, в котором они приведены в разделе описания синтаксиса.

Если возвращается несколько результатов, то программа sqlcmd выводит между результирующими наборами в пакете пустую строку. Кроме того, сообщение «обработано строк: <x>» не выдается, если оно не соответствует выполненной инструкции.

Для работы с программой sqlcmd в интерактивном режиме введите в командной строке sqlcmd, указав любой из параметров, описанных ранее в этом разделе. Дополнительные сведения см. в разделе Использование программы sqlcmd.

Примечание.
Параметры -L, -Q, -Z и -i после выполнения вызывают завершение программы.

Суммарная длина командной строки программы sqlcmd в командной среде (Cmd.exe), включая все аргументы и расширение переменных, определяется операционной системой для Cmd.exe и различна для разных операционных систем. Для Windows Server 2003 и Windows XP она равна 8191, для Windows 2000 и Windows NT4 — 2047.

Приоритет переменных (от низкого к высокому)

1. Переменные среды системного уровня.
2. Переменные среды пользовательского уровня.
3. Командная оболочка (SET X=Y) перед запуском программы sqlcmd выдает подсказку командной строки.
4. sqlcmd-v X=Y
5. :Setvar X Y

Примечание.
Чтобы просмотреть переменные среды, на панели управления откройте компонент Система и перейдите на вкладку Дополнительно.

Переменные сценария sqlcmd

Переменная	Связанный параметр	Чтение или запись	Значение
SQLCMDUSER	-U	Чтение	""
SQLCMDPASSWORD	-P	--	""
SQLCMDSERVER	-S	Чтение	"DefaultLocalInstance"
SQLCMDWORKSTATION	-H	Чтение	"ComputerName"
SQLCMDDBNAME	-d	Чтение	""
SQLCMDLOGINTIMEOUT	-l	Чтение и запись	"8" (секунд)
SQLCMDSTATTIMEOUT	-t	Чтение и запись	"0" = неограниченное время ожидания
SQLCMDHEADERS	-h	Чтение и запись	"0"
SQLCMDCOLSEP	-s	Чтение и запись	" "
SQLCMDCOLWIDTH	-w	Чтение и запись	"0"
SQLCMDPACKETSIZE	-a	Чтение	"4096"
SQLCMDERRORLEVEL	-m	Чтение и запись	0
SQLCMDMAXVARTYPEWIDTH	-y	Чтение и запись	"256"
SQLCMDMAXFIXEDTYPEWIDTH	-Y	Чтение и запись	"0" = неограниченное время ожидания
SQLCMDEDITOR		Чтение и запись	"edit.com"
SQLCMDINI		Чтение	""

Переменные SQLCMDUSER, SQLCMDPASSWORD и SQLCMDSERVER устанавливаются при использовании команды :Connect.

Пометка «Чтение» означает, что значение может быть задано только один раз в процессе инициализации программы.

Пометка «Чтение и запись» означает, что переменная может быть изменена командой setvar, и все последующие команды будут использовать новое значение.

Команды sqlcmd

В дополнение к инструкциям Transact-SQL в программе sqlcmd доступны также следующие команды:

GO [число]	:List
[:] RESET	:Error
[:] ED	:Out
[:] !!	:Perftrace
[:] QUIT	:Connect
[:] EXIT	:On Error
:r	:Help
:ServerList	:XML [ON | OFF]
:Setvar	:Listvar

При использовании команд программы sqlcmd следует учитывать следующие особенности.

• Все команды sqlcmd, за исключением GO, должны предваряться двоеточием (:).

  Важно!
  Для поддержки обратной совместимости с существующими сценариями osql некоторые команды будут распознаваться без двоеточия. На это указывают символы [:].

• Команды sqlcmd распознаются только в том случае, если они введены в начале строки.
• Во всех командах sqlcmd регистр символов не учитывается.
• Каждая команда должна находиться на отдельной строке. За командой не должна следовать инструкция Transact-SQL или другая команда.
• Команды выполняются немедленно. Они не помещаются в буфер выполнения, как инструкции .

• Команды изменения

• [:] ED
  Производит запуск текстового редактора. Этот редактор может использоваться для изменения текущего пакета Transact-SQL или последнего выполненного пакета. Для изменения последнего выполненного пакета необходимо ввести команду ED сразу после выполнения последнего пакета.

  Текстовый редактор определяется переменной среды SQLCMDEDITOR. Редактором по умолчанию является «Edit». Чтобы изменить редактор, установите переменную среды SQLCMDEDITOR. Например, чтобы установить в качестве редактора Блокнот (Майкрософт), в командной строке введите:

  SET SQLCMDEDITOR=notepad

• [:] RESET
  Очистка кэша инструкций.

• :List
  Вывод содержимого кэша инструкций.

• Переменные

• :Setvar <var> [ "value" ]
  Определяет переменные сценария sqlcmd. Переменные сценария имеют следующий формат: $(VARNAME).

  Имена переменных не зависят от регистра символов.

  Переменные сценария могут быть установлены следующими способами.

  • Неявно, с помощью параметра командной строки. Например, параметр -l устанавливает переменную сценария SQLCMDLOGINTIMEOUT программы sqlcmd.
  • Явным образом, с помощью команды :Setvar.
  • Путем установки переменной среды до запуска программы sqlcmd.

  Примечание.
  Параметр -X предотвращает передачу переменных среды программе sqlcmd.

  Если существует переменная среды, имеющая то же имя, что и переменная, определенная командой :Setvar, то больший приоритет имеет последняя.

  Имена переменных не должны содержать пробелы.

  Имена переменных не могут иметь тот же формат, что и выражение переменной: $(переменная).

  Если строковое значение переменной сценария содержит пробелы, то заключите значение в кавычки. Если значение для переменной сценария не указано, переменная сценария удаляется.

• :Listvar
  Список переменных сценария, заданных в настоящее время.

  Примечание.
  Отображаются только переменные, установленные программой sqlcmd и командой :Setvar.

• Команды вывода

• :Error **<filename>|STDERR|STDOUT
  Перенаправляет вывод всех сообщений об ошибках в файл, указываемый параметром имя_файла, в поток stderr или stdout. Команда Error может встречаться в сценарии несколько раз. По умолчанию вывод об ошибках направляется в STDERR.

  • file name
    Создает и открывает файл, который принимает выходные данные. Если файл уже существует, он будет усечен до 0 байт. Если файл недоступен по причине нехватки разрешений или по другим причинам, вывод перенаправляется не в него, а в последнее указанное назначение или в назначение по умолчанию.
  • STDERR
    Перенаправляет вывод сообщений об ошибках в поток stderr. Если было выполнено перенаправление, то адресат, которому был перенаправлен поток, получит выход ошибок.
  • STDOUT
    Перенаправляет выход ошибок в поток stdout. Если было выполнено перенаправление, то адресат, которому был перенаправлен поток, получит выход ошибок.

• :Out <имя_файла>| STDERR| STDOUT
  Создает и переадресовывает все результаты запроса в файл, указываемый параметром имя_файла, в stderr или в stdout. По умолчанию вывод направляется в stdout. Если файл уже существует, он будет усечен до 0 байт. Команда Out может встречаться в сценарии несколько раз.

• :Perftrace <имя_файла>| STDERR| STDOUT
  Создает и переадресовывает все данные трассировки производительности в файл, указываемый параметром имя_файла, в stderr или в stdout. По умолчанию вывод об отслеживании производительности направляется в stdout. Если файл уже существует, он будет усечен до 0 байт. Команда Perftrace может встречаться в сценарии несколько раз.

• Команды контроля выполнения

• :On Error[ exit | ignore]
  Установка действия, выполняемого при возникновении ошибки во время исполнения сценария или пакета.

  Если указан параметр exit, программа sqlcmd завершается с соответствующим кодом ошибки.

  Если указан параметр ignore, то ошибка пропускается и продолжается выполнение пакета или сценария. По умолчанию будет распечатано сообщение об ошибке.

• [:] QUIT
  Вызывает завершение работы программы sqlcmd.

• [:] EXIT[ (statement) ]
  Позволяет использовать результат выполнения инструкции SELECT в качестве возвращаемого значения программы sqlcmd. Первый столбец первой строки результатов преобразуется в 4-байтовое целое число (long). В MS-DOS младший байт передается родительскому процессу или уровню ошибки операционной системы. В Windows 2000 передается 4-байтовое целое число. Синтаксис:

  :EXIT(query)

  Например:

  :EXIT(SELECT @@ROWCOUNT)

  Также можно включить параметр EXIT в пакетный файл. Например, в командной строке введите:

  sqlcmd -Q "EXIT(SELECT COUNT(*) FROM '%1')"

  Программа sqlcmd отправляет на сервер все, что заключено в круглые скобки (). Если хранимая системная процедура выбирает набор и возвращает значение, то возвращается только выбранный набор. Инструкция EXIT ( ) с пустыми круглыми скобками выполняет все, что предшествует ей в пакете, а затем завершается, не возвращая значения.

  Если указан неверный запрос, программа sqlcmd завершит работу, не возвращая значения.

  Список форматов инструкции EXIT:

  • :EXIT

  Не выполняет пакет, немедленно завершает работу и не возвращает значения.

  • :EXIT( )

  Выполняет пакет, завершает выполнение и не возвращает значения.

  • :EXIT(query)

  Выполняет пакет, включая запрос, возвращает результаты запроса и завершает работу.

  Если в сценарии используется RAISERROR и возникает состояние 127, то программа sqlcmd завершает выполнение и возвращает клиенту идентификатор сообщения. Например:

  RAISERROR(50001, 10, 127)

  Эта ошибка приведет к завершению сценария sqlcmd, а клиенту будет возвращено сообщение с идентификатором 50001.

  Возвращаемые значения от -1 до -99 зарезервированы SQL Server. Программа sqlcmd дополнительно определяет следующие коды возврата:

  Возвращаемые значения	Описание
  -100	Перед выбором возвращаемого значения произошла ошибка.
  -101	При выборе возвращаемого значения не найдены строки.
  -102	При выборе возвращаемого значения произошла ошибка преобразования.

• GO [число]
  GO обозначает конец пакетного файла и исполнения любых кэшированных инструкций Transact-SQL. При задании значения для параметра число кэшируемые инструкции будут выполняться указанное число раз в виде единого пакета.

• Различные команды

• :r<имя_файла>
  Производит синтаксический анализ дополнительных инструкций Transact-SQL и команд программы sqlcmd в файле с именем <имя_файла>, загружая их в кэш инструкций.

  Если файл содержит инструкции , за которыми не следует GO, необходимо ввести GO в строку, следующую за :r.

  Примечание.
  Файл с именем <имя_файла> считывается относительно стартового каталога, в котором была запущена программа sqlcmd.

  Файл будет считан и выполнен после обнаружения признака конца пакета. Можно указывать несколько команд :r . В файле могут содержаться любые команды программы sqlcmd, в том числе признак конца пакета GO.

  Примечание.
  Число строк, отображаемых в интерактивном режиме, для каждой найденной команды :r будет увеличено на 1. Команда :r отображается в выводе команды list.

• :Serverlist
  Выводит список локально настроенных серверов и имена серверов, осуществляющих трансляцию данных в сети.

• :Connect сервер[**\**экземпляр] [-l время_ожидания] [-U пользователь [-P пароль]]
  Соединяется с экземпляром SQL Server. Также закрывает текущее соединение.

  Параметры времени ожидания:

  0	ждать бесконечно
  n>0	ждать в течение n секунд

  Переменная сценария SQLCMDSERVER отображает текущее активное соединение.

  Если не указан параметр время_ожидания, то берется значение переменной SQLCMDLOGINTIMEOUT по умолчанию.

  Если указано только пользователь (в виде параметра или в виде переменной среды), то у пользователя будет запрошен пароль. Однако этого не произойдет, если установлены переменные среды SQLCMDUSER или SQLCMDPASSWORD. Если ни параметры, ни переменные среды не введены, то для входа используется режим проверки подлинности Windows. Например, для подключения к экземпляру instance1 сервера SQL Server с именем myserver с использованием встроенной безопасности следует ввести следующую команду:

  :connect myserver\instance1

  Для подключения к экземпляру myserver по умолчанию с использованием переменных сценария следует ввести следующее выражение:

  :setvar myusername test

  :setvar myservername myserver

  :connect $(myservername) $(myusername)

• [:] !!< command>
  Исполнение команд операционной системы. Чтобы выполнить команду операционной системы, запустите строку, содержащую два восклицательных знака (!!) и далее команду операционной системы. Например:

  :!! Dir

  Примечание.
  Команда выполняется на компьютере, где работает программа sqlcmd.

• :XML [ON | OFF]
  Дополнительные сведения см. в подразделе «Формат выходных XML-данных» далее в этом разделе.

• :Help
  Выводит список команд программы sqlcmd вместе с кратким описанием каждой из них.

Имена файлов sqlcmd

Входные файлы sqlcmd могут быть указаны параметром -i или командой :r. Выходные файлы можно указать параметром -o или командами :Error, :Out и :Perftrace. При работе с этими файлами следует придерживаться следующих правил.

• Для команд :Error, :Out и :Perftrace должно быть указано отдельное <имя_файла>. Если используется одно и то же <имя_файла>, это может привести к смешиванию данных.
• Если входной файл, вызываемый из программы sqlcmd на локальном компьютере, расположен на удаленном сервере и путь к этому файлу содержит букву диска (например, :out c:\OutputFile.txt), то выходной файл будет создан на локальном компьютере, а не на удаленном сервере.
• Допустимы следующие пути: C:\<filename>, \\<Сервер>\<ОбщаяПапка$>\<имя_файла> и "C:\Некоторая папка\<имя_файла>". Если путь содержит пробелы, его необходимо заключить в кавычки.
• Каждый новый сеанс работы программы sqlcmd перезаписывает существующие файлы с теми же именами.

Информационные сообщения

Программа sqlcmd выводит все информационные сообщения, отправляемые сервером. В следующем примере после выполнения инструкций Transact-SQL выводится информационное сообщение.

Введите в командной строке:

sqlcmd

В командной строке программы sqlcmd введите следующее.

USE AdventureWorks;

GO

При нажатии клавиши ВВОД выводится следующее информационное сообщение: «Контекст базы данных изменен на "AdventureWorks"».

Формат вывода результатов выполнения запросов Transact-SQL

Сначала программа sqlcmd выводит заголовок, содержащий имена столбцов, перечисленных в списке выборки, которые разделяются символом, определенным в переменной SQLCMDCOLSEP. По умолчанию это пробел. Если имя столбца короче, чем ширина столбца, выходные данные дополняются пробелами до начала следующего столбца.

За этой строкой выводится строка-разделитель, которая представляет собой последовательность дефисов. Далее представлен пример вывода.

Запуск программы sqlcmd. В командной строке sqlcmd введите:

USE AdventureWorks;

SELECT TOP (2) Person.ContactID, FirstName, LastName

FROM Person.Contact;

GO

При нажатии клавиши ВВОД возвращается следующий результирующий набор:

ContactID FirstName LastName

----------- ------------ ----------

1 Syed Abbas

2 Catherine Abel

(2 row(s) affected)

Хотя столбец ContactID имеет ширину 4 символа, она была увеличена, чтобы вместить более длинное имя столбца. По умолчанию вывод заканчивается на 80 символе. Это может быть изменено с помощью параметра -w или путем установки переменной сценария SQLCMDCOLWIDTH.

Формат вывода XML

Выходные XML-данные, получаемые в результате выполнения предложения FOR XML, выводятся непрерывным потоком в неформатированном виде.

Если ожидается вывод XML-данных, воспользуйтесь следующей командой: :XML ON.

Примечание.
Сообщения об ошибках выводятся в обычном формате. Следует помнить, что сообщения об ошибках также выводятся в текстовый поток в формате XML. Если указать параметр :XML ON, программа sqlcmd не выводит информационные сообщения.

Чтобы отключить режим XML, введите следующую команду: :XML OFF.

Команда GO не должна указываться раньше команды XML OFF, поскольку последняя возвращает sqlcmd в режим вывода с построчным форматированием.

Не допускается смешивать XML-данные (потоковые) и данные набора строк. Если перед выполнением инструкции Transact-SQL, которая выводит потоки XML-данных, не была введена команда XML ON, то вывод будет искажен. Если была выполнена команда XML ON, то нельзя выполнить инструкции Transact-SQL, которые выводят обычные наборы строк.

Примечание.
Команда :XML не поддерживает инструкцию SET STATISTICS XML.

Рекомендации по использованию sqlcmd

Чтобы добиться максимальной безопасности и эффективности, придерживайтесь следующих правил.

• Используйте встроенную безопасность.
• В автоматизированных средах указывайте параметр -X.
• Обеспечьте защиту входных и выходных файлов при помощи соответствующих разрешений файловой системы NTFS.
• В целях повышения производительности выполняйте как можно больше работы в одном сеансе программы sqlcmd.
• Задайте значение времени ожидания для выполнения пакетов или запросов выше, чем ожидаемое время их выполнения.

См. также

Другие ресурсы

Использование программы sqlcmd
Использование программы sqlcmd с переменными сценария
Как подключиться к компоненту Database Engine при помощи sqlcmd.exe
Редактирование сценариев SQLCMD при помощи редактора запросов
Учебник по программе SQLCMD
Создание шагов задания
Как создать шаг задания CmdExec (среда SQL Server Management Studio)

Справка и поддержка

Получение помощи по SQL Server 2005