How to Execute and Monitor an Agent Job Using T-SQL in SQL Server 2005/2008


How to Execute and Monitor an Agent Job Using T-SQL in SQL Server 2005/2008

by Brian Bickell

In SQL Server 2005 and 2008 it’s possible to start an agent job with T-SQL syntax. This is frequently useful. For example, you may have a job that you’d like to have an outside application invoke. Jobs can also be used to execute SSIS packages. Using T-SQL to execute a job that runs an SSIS package is a way to provide an application access to an SSIS package.

One potential hangup with running agent jobs from a stored procedure is that control is returned immediately to the SQL that runs the job. Most of the time, it would be useful to know when the job has finished. Perhaps you’re calling an SSIS package from a web page and you’d like to update the UI when the package has been completed.

I’ll show you how to determine the status of a job that has been invoked, and return upon completion.

First, some background.

Running An Agent Job With T-SQL

The syntax to execute an agent job is as follows:

EXEC MSDB.dbo.sp_start_job @Job_Name = 'JobName'

This will execute the job specified in the @Job_Name parameter of the sp_start_job function. This works as long as the account running the command has permissions to run agent jobs. If you run this, you’ll notice that the command returns immediately, proceeding to the next line in the batch. This is no good for most uses.

One way of waiting to return until the job has finished is to drop into a tight loop until the job has completed.

Checking The Status Of An Agent Job In T-SQL

Our plan requires us to be able to check the status of an agent job with T-SQL syntax. We can accomplish this with the following syntax:

EXEC MSDB.dbo.sp_help_job @job_name = 'JobName', @job_aspect = 'JOB'

This will return a record set containing information about our job. The most interesting piece of information for us is the current execution status. When the job is idle sp_help_job will return a value of 4 for the current execution status. If you’re interested in what the other values mean, you can dig through the definition of MSDB.dbo.sp_help_job, which will in turn send you digging through MSDB.dbo.sp_get_composite_job_info.

The Wait Loop

Now that we know how to invoke our agent job, and check its status we can start putting it all together.

Our procedure will be something like this:

Call Agent Job
While Execution Status 4
Poll Execution Status

Or, in actual T-SQL:

SET @JobStatus = 0
EXEC MSDB.dbo.sp_start_job @Job_Name = 'JobName'
SELECT @JobStatus = current_execution_status FROM OPENROWSET('SQLNCLI', 'Server=localhost;Trusted_Connection=yes;',
'EXEC MSDB.dbo.sp_help_job @job_name = ''JobName'', @job_aspect = ''JOB'' ')
WHILE @JobStatus 4
SELECT @JobStatus = current_execution_status FROM OPENROWSET('SQLNCLI', 'Server=localhost;Trusted_Connection=yes;',
'EXEC MSDB.dbo.sp_help_job @job_name = ''JobName'', @job_aspect = ''JOB'' ')

Getting the job status from the sp_help_job stored procedure requires us to encapsulate it in an OPENROWSET to provide a rowset we can select from. There are other ways to do this, if you’re averse to using OPENROWSET. I’ll leave them up to you.

The Final Version

Running the query above, you’ll notice that it seems to bounce out of the WHILE loop way too quickly. In fact the WHILE loop doesn’t even make one iteration. When a job is invoked by sp_start_job the current_execution_status in sp_help_job is not updated instantaneous. It’s updated very quickly, but it’s possible for your initial query setting @JobStatus to get the ‘4′ (Idle) value immediately after you’ve kicked the job off. The only way I’ve seen to get around this is to add a WAITFOR command with the DELAY argument in between sp_start_job and the initial sp_help_job check. We can also add a WAITFOR DELAY in the wait loop to prevent the loop from becoming too inefficient. You can tune the WAITFOR value depending on what your job is doing.

SET @JobStatus = 0     
EXEC MSDB.dbo.sp_start_job @Job_Name = 'JobName'
WAITFOR DELAY '00:00:01'
SELECT @JobStatus = current_execution_status  FROM OPENROWSET('SQLNCLI', 'Server=localhost;Trusted_Connection=yes;',  
'EXEC MSDB.dbo.sp_help_job @job_name = ''JobName'', @job_aspect = ''JOB'' ')
 WHILE @JobStatus  4
	WAITFOR DELAY '00:00:03'
	SELECT @JobStatus = current_execution_status  FROM OPENROWSET('SQLNCLI', 'Server=localhost;Trusted_Connection=yes;',  
'EXEC MSDB.dbo.sp_help_job @job_name = ''JobName'', @job_aspect = ''JOB'' ')

There are still more improvements that could be made. Perhaps you would like to determine what the other current_execution_status codes are and do something when one of them is detected. One suggestion I’d make is to add a timeout value to the WHILE loop to prevent it from waiting indefinitely if something unexpected happens.
I’ll leave that exercise to the reader.


More About the Author

Brian Bickell

Global Data Practice Director
Introducing the Snowflake Data Cloud: How We Got Here Five years ago, in the distant past that still included large, boozy, in-person technology conferences, I met two guys from an upstart ...
InterWorks’ Influential Role at the KeyBanc Capital Markets Emerging Technology Summit Two weeks ago, KeyBanc Capital Markets and the Mosaic network held their 15th Annual Emerging Technology Summit in San Francisco, ...

See more from this author →

Subscribe to our newsletter

  • I understand that InterWorks will use the data provided for the purpose of communication and the administration my request. InterWorks will never disclose or sell any personal data except where required to do so by law. Finally, I understand that future communications related topics and events may be sent from InterWorks, but I can opt-out at any time.
  • This field is for validation purposes and should be left unchanged.

InterWorks uses cookies to allow us to better understand how the site is used. By continuing to use this site, you consent to this policy. Review Policy OK


Interworks GmbH
Ratinger Straße 9
40213 Düsseldorf
Geschäftsführer: Mel Stephenson

Telefon: +49 (0)211 5408 5301

Amtsgericht Düsseldorf HRB 79752
UstldNr: DE 313 353 072