• 项目

sp_update_jobstep (Transact-SQL)

更改执行自动活动的作业中某一步骤的设置。

主题链接图标Transact-SQL 语法约定

语法

sp_update_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 =] success_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_id 或 job_name，但不能两个都指定。

  • [ @job_name =] 'job_name'
    步骤所属的作业的名称。job_name的数据类型为 sysname，默认值为 NULL。必须指定 job_id 或 job_name，但不能两个都指定。

  • [ @step_id =] step_id
    要修改的作业步骤的标识号。不能更改该标识号。step_id的数据类型为 int，无默认值。

  • [ @step_name =] 'step_name'
    步骤的新名称。step_name的数据类型为 sysname，默认值为 NULL。

  • [ @subsystem =] 'subsystem'
    Microsoft SQL Server 代理执行 command 所使用的子系统。subsystem 的数据类型为 nvarchar(40)，默认值为 NULL。

  • [ @command =] 'command'
    通过 subsystem 执行的命令。command 的数据类型为 nvarchar(max)，默认值为 NULL。

  • [ @additional_parameters =] 'parameters'
    标识为仅供参考。 不提供支持。 不保证以后的兼容性。

  • [ @cmdexec_success_code =] success_code
    CmdExec 子系统命令返回的值，用以指示 command 已成功执行。success_code 的数据类型为 int，默认值为 NULL。

  • [ @on_success_action =] success_action
    步骤成功后要执行的操作。success_action 的数据类型为 tinyint，默认值为 NULL，可以是下列值之一：

    值

    说明（操作）

    1

    成功后退出。

    2

    失败后退出。

    3

    转到下一步。

    4

    转到步骤 success_step_id。

  • [ @on_success_step_id =] success_step_id
    当该步骤成功且 success_action 为 4 时，该作业中要执行的步骤的标识号。success_step_id 的数据类型为 int，默认值为 NULL。

  • [ @on_fail_action =] fail_action
    步骤失败后要执行的操作。fail_action 的数据类型为 tinyint，默认值为 NULL，可以是下列值之一：

    值

    说明（操作）

    1

    成功后退出。

    2

    失败后退出。

    3

    转到下一步。

    4

    转到步骤 fail_step_id。

  • [ @on_fail_step_id =] fail_step_id
    当该步骤失败且 fail_action 为 4 时，该作业中要执行的步骤的标识号。fail_step_id 的数据类型为 int，默认值为 NULL。

  • [ @server =] 'server'
    标识为仅供参考。 不提供支持。 不保证以后的兼容性。server 的数据类型为 nvarchar(128)，默认值为 NULL。

  • [ @database_name =] 'database'
    要在其中执行 Transact-SQL 步骤的数据库的名称。database 的数据类型为 sysname。不允许用方括号 ([ ]) 将名称括起来。默认值为 NULL。

  • [ @database_user_name =] 'user'
    执行 Transact-SQL 步骤时要使用的用户帐户的名称。user的数据类型为 sysname，默认值为 NULL。

  • [ @retry_attempts =] retry_attempts
    该步骤失败时要进行的重试次数。retry_attempts的数据类型为 int，默认值为 NULL。

  • [ @retry_interval =] retry_interval
    两次重试的间隔时间（分钟）。retry_interval 的数据类型为 int，默认值为 NULL。

  • [ @os_run_priority =] run_priority
    标识为仅供参考。 不提供支持。 不保证以后的兼容性。

  • [ @output_file_name =] 'file_name'
    保存该步骤的输出的文件名。file_name 的数据类型为 nvarchar(200)，默认值为 NULL。此参数只对于 Transact-SQL 或 CmdExec 子系统中运行的命令有效。

    若要将 output_file_name 重新设置回 NULL，必须将 output_file_name 设置为空字符串 (' ') 或空白字符串，但不能使用 CHAR(32) 函数。例如，按如下所示将此参数设置为空字符串：

    @output_file_name = ' '

  • [ @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 代理的服务帐户运行。

返回代码值

0（成功）或 1（失败）

注释

sp_update_jobstep 必须从 msdb 数据库中运行。

更新作业步骤将增加作业的版本号。

权限

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

  • SQLAgentUserRole

  • SQLAgentReaderRole

  • SQLAgentOperatorRole

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

只有 sysadmin 的成员才可以更新其他用户拥有的作业步骤。

如果作业步骤需要访问代理，则该作业步骤的创建者必须拥有对该作业步骤的代理的访问权限。除 Transact-SQL 之外的所有子系统都需要一个代理帐户。sysadmin 的成员可以访问所有代理，并可以将 SQL Server 代理服务帐户用于该代理。

示例

下面的示例更改 Weekly Sales Data Backup 作业的第一步的重试次数。在运行此示例后，重试次数将为 10。

USE msdb ;
GO

EXEC dbo.sp_update_jobstep
    @job_name = N'Weekly Sales Data Backup',
    @step_id = 1,
    @retry_attempts = 10 ;
GO