JobStep Object (SQL-DMO)

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

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-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 desired 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 desired 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.

Methods

Properties