JobStep Object

  • Article

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

The JobStep object exposes the attributes of a single SQL Server Agent executable job step.

SQL-DMO object model that shows the current object

Properties

AdditionalParameters Property

OnFailAction Property

CmdExecSuccessCode Property

OnFailStep Property

Command Property

OnSuccessAction Property

DatabaseName Property

OnSuccessStep Property

DatabaseUserName Property

OSRunPriority Property

Flags Property

OutputFileName Property

LastRunDate Property

RetryAttempts Property

LastRunDuration Property

RetryInterval Property

LastRunOutcome Property

Server Property

LastRunRetries Property

StepID Property

LastRunTime Property

SubSystem Property

Name Property

 

Methods

BeginAlter Method

Refresh Method

CancelAlter Method

Remove Method (Objects)

DoAlter Method

 

Remarks

SQL Server Agent jobs contain one or more execution units called steps. Each job step contains a textual command, type of execution that specifies command interpretation, and logic that determines the behavior of the job if the step succeeds or fails. For example, a job step may contain:

  • The command text:

    DBCC CHECKDB ('Northwind') WITH NO_INFOMSGS

  • A job step execution type of Transact-SQL.

  • An indication that the job should stop if the step fails.

With the JobStep object, you can:

  • Create a SQL Server Agent job step.
  • Remove a job step from a SQL Server Agent job.
  • Manage existing job steps by changing, for example, the command text or the actions taken on success or failure of the step.
  • Obtain details about the last attempted execution of the step.

The Name property of a JobStep object can contain up to 100 characters. The value of the Name property must be unique within a job.

After creation, the job step is appended to the list of steps in the SQL Server Agent job.

When creating job steps by using the JobStep object, the default logic for success or failure is that the job stops. SQL Distributed Management Objects (SQL-DMO) checks new steps to ensure that exit conditions are set correctly. When adding a series of steps to a job by using SQL-DMO, use the BeginAlter and DoAlter methods of the Job object to wrap the process so that step logic is checked for all steps added to the job.

To create a SQL Server Agent job step

  1. Create a JobStep object.

  2. Set the Name property.

  3. Set the StepID property.

  4. Set the Command property. The default execution type for a job step defined by a new JobStep object is Transact-SQL. If the command is an operating system executable or batch file, set the SubSystem property to CmdExec.

  5. Add the JobStep object to the JobSteps collection of a Job object that references an existing SQL Server Agent job.

To remove a SQL Server Agent job step

  1. Get the Job object from the Jobs collection of a connected JobServer object.

  2. Use the BeginAlter method of the Job object to mark the beginning of changes to the SQL Server Agent job.

  3. Get the JobStep object from the JobSteps collection of the Job object.

  4. Use the Remove method of the JobStep object to remove the step from the list of steps in the SQL Server Agent job.

  5. As appropriate, get JobStep objects that indicate the removed step in their logic. Adjust the OnFailStep and OnSuccessStep properties of those JobStep objects to correct their logic.

  6. Use the DoAlter method of the Job object to mark the end of changes, and then submit the changes to the server.