sp_add_jobstep (Transact-SQL)

已更新： 2006 年 4 月 14 日

在作业中添加一个步骤（操作）。

语法

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' } ]

参数

[ @job_id = ] job_id

要添加步骤的作业的标识号。job_id 的数据类型为 uniqueidentifier，默认值为 NULL。

[ @job_name = ] 'job_name'

要添加步骤的作业的名称。job_name 的数据类型为 sysname，默认值为 NULL。

注意：
必须指定 job_id 或 job_name，但不能两个都指定。

[ @step_id = ] step_id

作业步骤的序列标识号。步骤标识号从 1 开始，并无间断递增。如果在现有序列中插入一个步骤，则将自动调整序列号。如果不指定 step_id，则将提供一个值。step_id 的数据类型为 int，默认值为 NULL。

[ @step_name = ] 'step_name'

步骤的名称。step_name 的数据类型为 sysname，无默认值。

[ @subsystem = ] 'subsystem'

Microsoft SQL Server 代理服务用于执行 command 的子系统。subsystem 的数据类型为 nvarchar(40)，可以是下列值之一：

值	说明
'ACTIVESCRIPTING'	活动脚本
'CMDEXEC'	操作系统命令或可执行程序
'DISTRIBUTION'	复制分发代理作业
'SNAPSHOT'	复制快照代理作业
'LOGREADER'	复制日志读取器代理作业
'MERGE'	复制合并代理作业
'QueueReader'	复制队列读取器代理作业
'ANALYSISQUERY'	Analysis Services 查询 (MDX、DMX)。
'ANALYSISCOMMAND'	Analysis Services 命令 (XMLA)。
'Dts'	Integration Services 包执行
'TSQL'（默认）	Transact-SQL 语句

[ @command = ] 'command'

SQLServerAgent 服务通过 subsystem 执行的命令。command 的数据类型为 nvarchar(max)，默认值为 NULL。SQL Server 代理提供令牌替换，在编写软件程序时，它可提供与变量相同的灵活性。

重要事项：
在 SQL Server 2005 Service Pack 1 中，SQL Server 代理作业步骤的标记语法已发生更改。因此，作业步骤中使用的所有令牌现在必须附带转义宏，否则，这些作业步骤将失败。此外，使用方括号调用 SQL Server 2000 代理作业步骤标记的 SQL Server 语法（例如，“`[DATE]`”）也已发生更改。现在，必须用括号将令牌名称括起来，并在令牌语法的开头加上美元符号 (`$`)。例如： `$(ESCAPE_`宏名称`(DATE))`

重要事项：

在 SQL Server 2005 Service Pack 1 中，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 安全组（如 Administrators 组）成员才对安装 SQL Server 的计算机的事件日志具有写入权限。然后在对象资源管理器中右键单击“SQL Server 代理”，选择“属性”，并在“警报系统”页上选择“为警报的所有作业响应替换令牌”以启用这些令牌。

安全说明：

对 Windows 事件日志具有写入权限的任何 Windows 用户都可以访问由 SQL Server 代理警报或 WMI 警报激活的作业步骤。为了确保安全，默认情况下，可在警报激活的作业中使用的 SQL Server 代理令牌处于禁用状态。这些令牌是：A-DBN、A-SVR、A-ERR、A-SEV、A-MSG 和 WMI(property)。

如果您需要使用这些令牌，请首先确保只有可信任的 Windows 安全组（如 Administrators 组）成员才对安装 SQL Server 的计算机的事件日志具有写入权限。然后在对象资源管理器中右键单击“SQL Server 代理”，选择“属性”，并在“警报系统”页上选择“为警报的所有作业响应替换令牌”以启用这些令牌。

[ @additional_parameters = ] 'parameters'

保留。parameters 的数据类型为 ntext，默认值为 NULL。

[ @cmdexec_success_code = ] code

CmdExec 子系统命令返回的值，用于指示 command 已成功执行。code 的数据类型为 int，默认值为 0。

[ @on_success_action = ] success_action

步骤成功时执行的操作。success_action 的数据类型为 tinyint，可以是下列值之一：

值	说明（操作）
1（默认值）	成功后退出
2	失败后退出
3	转到下一步
4	转到步骤 on_success_step_id。

[ @on_success_step_id = ] success_step_id

步骤成功并且 success_action 的值为 4 时，该作业中要执行的步骤的 ID。success_step_id 的数据类型为 int，默认值为 0。

[ @on_fail_action = ] fail_action

步骤失败时执行的操作。fail_action 的数据类型为 tinyint，可以是下列值之一：

值	说明（操作）
1	成功后退出
2（默认值）	失败后退出
3	转到下一步
4	转到步骤 on_fail_step_id。

[ @on_fail_step_id = ] fail_step_id

步骤失败并且 fail_action 的值为 4 时，该作业中要执行的步骤的 ID。fail_step_id 的数据类型为 int，默认值为 0。

[ @server =] 'server'

保留。server 的数据类型为 nvarchar(30)，默认值为 NULL。

[ @database_name = ] 'database'

在其中执行 Transact-SQL 步骤的数据库的名称。database 的数据类型为 sysname，默认值为 NULL，此时将使用 master 数据库。对于 ActiveX 作业步骤，database 是该步骤使用的脚本语言的名称。

[ @database_user_name = ] 'user'

执行 Transact-SQL 步骤时要使用的用户帐户的名称。user 的数据类型为 sysname，默认值为 NULL。如果 user 为 NULL，则该步骤将在 database 中的作业所有者用户上下文中运行。

[ @retry_attempts = ] retry_attempts

该步骤失败时的重试次数。retry_attempts 的数据类型为 int，默认值为 0，指示不重试。

[ @retry_interval = ] retry_interval

两次重试之间的间隔时间（分钟）。retry_interval 的数据类型为 int，默认值为 0，指示重试间隔为 0 分钟。

[ @os_run_priority = ] run_priority

保留。

[ @output_file_name = ] 'file_name'

用于保存该步骤输出的文件的名称。file_name 的数据类型为 nvarchar(200)，默认值为 NULL。file_name 可包含 command 下列出的一个或多个令牌。该参数仅对在 Transact-SQL 或 CmdExec 子系统上运行的命令有效。

[ @flags = ] flags

控制行为的选项。flags 的数据类型为 int，可以是下列值之一：

值	说明
0（默认值）	覆盖输出文件
2	追加到输出文件
4	将 Transact-SQL 作业步骤输出写入步骤历史记录
8	将日志写入表（覆盖现有的历史记录）
16	将日志写入表中（追加到现有历史记录）

[ @proxy_id = ] proxy_id

作业步骤作为代理运行时，代理的 ID 号。proxy_id 的数据类型为 int，默认值为 NULL。如果未指定 proxy_id、proxy_name 和 user_name，则作业步骤将作为 SQL Server 代理的服务帐户运行。

[ @proxy_name = ] 'proxy_name'

作业步骤作为代理运行时，代理的名称。proxy_name 的数据类型为 sysname，默认值为 NULL。如果未指定 proxy_id、proxy_name 和 user_name，则作业步骤将作为 SQL Server 代理的服务帐户运行。

备注

必须从 msdb 数据库运行 sp_add_jobstep。

SQL Server Management Studio 为管理作业提供了一种图形化的简便方法，建议使用此方法来创建和管理作业基础结构。

除非作业步骤的创建者是 sysadmin 固定安全角色的成员，否则作业步骤必须指定一个代理。

代理可通过 proxy_name 或 proxy_id 标识。

返回代码值

0（成功）或 1（失败）

结果集

无

权限

默认情况下，只有 sysadmin 固定服务器角色的成员才可以执行此存储过程。其他用户必须被授予 msdb 数据库中下列 SQL Server 代理固定数据库角色的权限之一：

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

有关这些角色的权限的详细信息，请参阅 SQL Server 代理固定数据库角色。

作业步骤的创建者必须有权访问作业步骤的代理。sysadmin 固定服务器角色的成员可以访问所有代理。其他用户必须经过显式授予才能访问代理。

示例

以下示例可创建一个作业步骤，将 AdventureWorks 数据库的访问权限更改为只读。此外，此示例还指定了 5 次重试，每次重试之间的间隔为 5 分钟。

注意：
此示例假定已经存在 `Weekly Sales Data Backup` 作业。

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'exec sp_dboption ''sales'', ''read only'', ''true''', 
    @retry_attempts = 5,
    @retry_interval = 5 ;
GO