Использование маркеров в шагах задания

Агент SQL Server позволяет применять маркеры в сценариях шагов заданий на языке Transact-SQL. Применение маркеров при написании шагов заданий обеспечивает такую же гибкость, какую дают переменные при написании программ. После добавления маркера в сценарий шага задания агент SQL Server замещает маркер во время выполнения, до того как шаг задания выполняется подсистемой Transact-SQL

Важно!

Начиная с SQL Server 2005 с пакетом обновления 1 (SP1), синтаксис маркера шага задания агента SQL Server был изменен. В результате управляющий макрос должен сопровождать все маркеры, используемые в шагах заданий, иначе произойдет сбой в шагах заданий. Использование управляющих макросов и обновление шагов заданий агента SQL Server, в которых используются маркеры, описывается в разделах «Основные сведения об использовании маркеров», «Макросы и маркеры агента SQL Server» и «Обновление шагов заданий для использования маркеров». Кроме того, также изменился синтаксис SQL Server 2000, при котором для обнаружения маркеров шагов заданий SQL Server (например «[DATE]») использовались квадратные скобки. Теперь имена маркеров необходимо заключать в круглые скобки и в начале записи маркера добавлять знак доллара ($). Например: $(ESCAPE_имя макроса(DATE))

Основные сведения об использовании маркеров

Примечание по безопасности

Все пользователи Windows с разрешением на запись в журнал событий Windows могут получить доступ к шагам заданий, которые активируются предупреждениями агента SQL Server или предупреждениями инструментария WMI. Чтобы избежать этого нарушения безопасности, SQL Server маркеры агента, которые могут использоваться в заданиях, активированных предупреждениями, по умолчанию отключены. Такими маркерами являются A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property). Если необходимо использовать эти маркеры, убедитесь, что только члены доверенных групп безопасности Windows, таких как группа «Администраторы», обладают разрешением на работу с журналом событий компьютера, на котором находится SQL Server. Затем, чтобы включить эти маркеры, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойства и на странице Система предупреждений выберите Заменять маркеры всех ответов заданий на предупреждения.

Замена маркеров агента SQL Server проста и эффективна: Агент SQL Server заменяет маркер точной символьной строкой. Все маркеры обрабатываются с учетом регистра. Шаги заданий должны это учитывать для учетной записи и правильно заключать в кавычки применяемые маркеры или преобразовывать замещающие строки к верному типу данных.

Например, чтобы напечатать имя базы данных в шаге задания, можно использовать следующую инструкцию:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

В этом примере макрос ESCAPE_SQUOTE добавляется с маркером A-DBN. Во время выполнения маркер A-DBN будет замещен соответствующим именем базы данных. Управляющий макрос экранирует все одиночные кавычки, которые случайно передаются в строку замещения маркера. Агент SQL Server заместит символ одиночной кавычки двумя символами одиночной кавычки в конечной строке.

Например, если замещающая маркер строка AdventureWorks'SELECT @@VERSION --, то команда, выполняемая агентом SQL Server имеет вид:

PRINT N'Current database name is AdventureWorks''SELECT @@VERSION --' ;

В этом случае добавленная инструкция SELECT @@VERSION не выполняется. Вместо этого, дополнительный символ одинарной кавычки заставляет сервер анализировать передаваемую инструкцию как строку. Если замещающая маркер строка не содержит одинарных кавычек, то никакие символы не экранируются, и шаг задания, содержащий маркер, выполняется как планировалось.

Чтобы отладить использование маркеров в шагах заданий, используйте инструкции вывода на печать, такие как PRINT N'$(ESCAPE_SQUOTE(SQLDIR))' и сохраняйте выходные данные шага задания в файл или таблицу. Используйте страницу Дополнительно диалогового окна Свойства шага задания для указания выходного файла или таблицы для шага задания.

Маркеры и макросы агента SQL Server

В следующей таблице перечислены и описаны маркеры и макросы, которые поддерживает агент SQL Server.

Маркеры агента SQL Server

Маркер	Описание
(A-DBN)	Имя базы данных. Если задание запускается в результате предупреждения, то имя базы данных автоматически замещает в шаге задания этот маркер.
(A-SVR)	Имя сервера. Если задание запускается в результате предупреждения, то имя сервера автоматически замещает в шаге задания этот маркер.
(A-ERR)	Номер ошибки. Если задание запускается в результате предупреждения, то номер ошибки автоматически замещает в шаге задания этот маркер.
(A-SEV)	Серьезность ошибки. Если задание запускается в результате предупреждения, то степень серьезности ошибки автоматически замещает в шаге задания этот маркер.
(A-MSG)	Текст сообщения. Если задание запускается в результате предупреждения, то текст сообщения автоматически замещает в шаге задания этот маркер.
(DATE)	Текущая дата (в формате ГГГГММДД).
(INST)	Имя экземпляра. Для экземпляра по умолчанию этот маркер будет иметь значение экземпляра по умолчанию: MSSQLSERVER.
(JOBID)	Идентификатор задания.
(MACH)	Имя компьютера.
(MSSA)	Имя главной службы SQLServerAgent.
(OSCMD)	Префикс для программы, используемой для запуска шагов задания CmdExec.
(SQLDIR)	Каталог, в котором установлен SQL Server. Значение по умолчанию — «C:\Program Files\Microsoft SQL Server\MSSQL».
(STEPCT)	Количество выполнений этого шага (кроме повторных попыток). Может применяться командой шага для принудительного прекращения цикла из нескольких шагов.
(STEPID)	Идентификатор шага.
(SRVR)	Имя компьютера, на котором работает SQL Server. В случае именованного экземпляра SQL Server имя компьютера включается в имя экземпляра.
(TIME)	Текущее время (в формате ЧЧММСС).
(STRTTM)	Время запуска задания (в формате ЧЧММСС).
(STRTDT)	Дата запуска задания (в формате ГГГГММДД).
(WMI(property))	Для заданий, запускаемых в ответ на предупреждение инструментария WMI, значение свойства указывается параметром property. Например, маркер $(WMI(DatabaseName)) предоставляет значение для свойства DatabaseName в событии инструментария WMI, которое вызвало предупреждение.

Экранирующие макросы агента SQL Server

Экранирующие макросы	Описание
$(ESCAPE_SQUOTE(token_name))	Экранирует символы одинарных кавычек (') в строке замещения маркера. Замещает символ одинарной кавычки двумя символами одинарной кавычки.
$(ESCAPE_DQUOTE(token_name))	Экранирует символы двойных кавычек (") в строке замещения маркера. Замещает символ двойных кавычек двумя символами двойных кавычек.
$(ESCAPE_RBRACKET(token_name))	Экранирует символы правой квадратной скобки (]) в строке замещения маркера. Замещает один символ правой квадратной скобки двумя символами правой квадратной скобки.
$(ESCAPE_NONE(token_name))	Замещает маркер, не экранируя никакие символы строки. Этот макрос предоставлен для поддержки обратной совместимости в окружениях, где строки замещения маркера ожидаются только от надежных пользователей. Дополнительные сведения см. в подразделе «Обновление шагов заданий для использования маркеров» далее в этом разделе.

Обновление шагов заданий для использования маркеров

Начиная с версии SQL Server 2005 с пакетом обновления 1 (SP1), шаги заданий, содержащие маркеры без экранирующих макросов, завершаются сбоем и возвращают сообщение об ошибке; это сообщение указывает на то, что шаг задания содержит маркеры, обновление которых при помощи макроса необходимо перед тем, как задание можно будет выполнить.

Сценарий см. в статье базы знаний Microsoft 915845: SQL Server Agent Job Steps That Use Tokens Fail in SQL Server 2005 Service Pack 1. С помощью этого сценария можно обновить все шаги задания, использующие токены с макросом ESCAPE_NONE. После применения этого сценария рекомендуется как можно скорее просмотреть шаги заданий, в которых используются маркеры, и заменить макрос ESCAPE_NONE экранирующим макросом, который соответствует контексту шага задания.

Следующая таблица показывает, каким образом замена маркеров обрабатывается агентом SQL Server. Чтобы включить или отключить замену маркеров предупреждений, щелкните правой кнопкой мыши элемент Агент SQL Server в обозревателе объектов, выберите пункт меню Свойства и на странице Система предупреждений установите или снимите флажок Заменить маркеры всех ответов заданий на предупреждения.

Синтаксис маркера	Предупреждение о замене маркеров включено	Предупреждение о замене маркеров отключено
Управляющие макросы используются	Все маркеры в заданиях заменяются успешно.	Маркеры, активированные предупреждениями, не заменяются. К этим маркерам относятся A-DBN, A-SVR, A-ERR, A-SEV, A-MSG и WMI(property). Другие статические маркеры заменяются успешно.
Управляющие макросы не используются	Все задания, содержащие маркеры, завершаются сбоем.	Все задания, содержащие маркеры, завершаются сбоем.

Примеры обновления синтаксиса маркеров

А. Использование маркеров в невложенных строках

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

PRINT N'Current database name is $(A-DBN)' ;

После выполнения обновляющего сценария макрос ESCAPE_NONE добавляется перед маркером A-DBN. Так как для отделения строки печати используются одинарные кавычки, необходимо обновить шаг задания, добавив макрос ESCAPE_SQUOTE следующим образом:

PRINT N'Current database name is $(ESCAPE_SQUOTE(A-DBN))' ;

Б. Использование маркеров во вложенных строках

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

Например, рассмотрим следующий шаг задания, в котором используется маркер A-MSG и который не был обновлен с помощью управляющего макроса:

PRINT N'Print ''$(A-MSG)''' ;

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

DECLARE @msgString nvarchar(max)

SET @msgString = '$(ESCAPE_SQUOTE(A-MSG))'

SET @msgString = QUOTENAME(@msgString,'''')

PRINT N'Print ' + @msgString ;

Имейте в виду, что функция QUOTENAME устанавливает символ кавычки.

В. Использование маркеров с макросом ESCAPE_NONE

Следующий пример является частью сценария, который извлекает job_id из таблицы sysjobs и использует маркер JOBID, чтобы заполнить переменную @JobID, которая была объявлена как бинарный тип данных ранее в сценарии. Имейте в виду, что с маркером JOBID используется макрос ESCAPE_NONE, так как для бинарного типа данных разделители не требуются. После выполнения сценария обновления не нужно обновлять этот шаг задания.

SELECT * FROM msdb.dbo.sysjobs

WHERE @JobID = CONVERT(uniqueidentifier, $(ESCAPE_NONE(JOBID))) ;

См. также

Справочник

sp_add_jobstep (Transact-SQL)