sp_add_schedule (Transact-SQL)

Article
12/03/2008

Creates a schedule that can be used by any number of jobs.

Syntax

sp_add_schedule [ @schedule_name = ] 'schedule_name' 
    [ , [ @enabled = ] enabled ]
    [ , [ @freq_type = ] freq_type ]
    [ , [ @freq_interval = ] freq_interval ] 
    [ , [ @freq_subday_type = ] freq_subday_type ] 
    [ , [ @freq_subday_interval = ] freq_subday_interval ] 
    [ , [ @freq_relative_interval = ] freq_relative_interval ] 
    [ , [ @freq_recurrence_factor = ] freq_recurrence_factor ] 
    [ , [ @active_start_date = ] active_start_date ] 
    [ , [ @active_end_date = ] active_end_date ] 
    [ , [ @active_start_time = ] active_start_time ] 
    [ , [ @active_end_time = ] active_end_time ] 
    [ , [ @owner_login_name = ] 'owner_login_name' ]
    [ , [ @schedule_uid = ] schedule_uid OUTPUT ]
    [ , [ @schedule_id = ] schedule_id OUTPUT ]
    [ , [ @originating_server = ] server_name ] /* internal */

Arguments

[ @schedule_name = ] 'schedule_name'
The name of the schedule. schedule_nameis sysname, with no default.

[ @enabled = ] enabled
Indicates the current status of the schedule. enabledis tinyint, with a default of 1 (enabled). If 0, the schedule is not enabled. When the schedule is not enabled, no jobs will run on this schedule.

[ @freq_type = ] freq_type
A value indicating when a job is to be executed. freq_typeis int, with a default of 0, and can be one of these values.

Value Description

1

Once

4

Daily

8

Weekly

16

Monthly

32

Monthly, relative to freq_interval

64

Run when SQLServerAgent service starts

128

Run when the computer is idle

Value	Description
1	Once
4	Daily
8	Weekly
16	Monthly
32	Monthly, relative to freq_interval
64	Run when SQLServerAgent service starts
128	Run when the computer is idle

[ @freq_interval = ] freq_interval
The days that a job is executed. freq_interval is int, with a default of 1, and depends on the value of freq_type.

Value of freq_type	Effect on freq_interval
1 (once)	freq_interval is unused.
4 (daily)	Every freq_interval days.
8 (weekly)	freq_interval is one or more of the following (combined with an OR logical operator): 1 = Sunday 2 = Monday 4 = Tuesday 8 = Wednesday 16 = Thursday 32 = Friday 64 = Saturday
16 (monthly)	On the freq_interval day of the month.
32 (monthly relative)	freq_interval is one of the following: 1 = Sunday 2 = Monday 3 = Tuesday 4 = Wednesday 5 = Thursday 6 = Friday 7 = Saturday 8 = Day 9 = Weekday 10 = Weekend day
64 (when SQLServerAgent service starts)	freq_interval is unused.
128	freq_interval is unused.

[ @freq_subday_type = ] freq_subday_type
Specifies the units for freq_subday_interval. freq_subday_typeis int, with a default of 0, and can be one of these values.

Value Description (unit)

0x1

At the specified time

0x4

Minutes

0x8

Hours

Value	Description (unit)
0x1	At the specified time
0x4	Minutes
0x8	Hours

[ @freq_subday_interval = ] freq_subday_interval
The number of freq_subday_type periods to occur between each execution of a job. freq_subday_intervalis int, with a default of 0. freq_subday_interval is ignored in those cases where freq_subday_type is equal to 1.

[ @freq_relative_interval = ] freq_relative_interval
A job's occurrence of freq_interval in each month, if freq_type is 32 (monthly relative). freq_relative_intervalis int, with a default of 0, and can be one of these values. freq_relative_interval is ignored in those cases where freq_type is not equal to 32.

Value Description (unit)

1

First

2

Second

4

Third

8

Fourth

16

Last

Value	Description (unit)
1	First
2	Second
4	Third
8	Fourth
16	Last

[ @freq_recurrence_factor = ] freq_recurrence_factor
The number of weeks or months between the scheduled execution of a job. freq_recurrence_factor is used only if freq_type is 8, 16, or 32. freq_recurrence_factoris int, with a default of 0.

[ @active_start_date = ] active_start_date
The date on which execution of a job can begin. active_start_dateis int, with a default of NULL, which indicates today's date. The date is formatted as YYYYMMDD. If active_start_date is not NULL, the date must be greater than or equal to 19900101. After you create the schedule, review the start date and confirm that it is the correct date. For more information, see the section "Scheduling Start Date" in Creating Schedules.

[ @active_end_date = ] active_end_date
The date on which execution of a job can stop. active_end_dateis int, with a default of 99991231, which indicates December 31, 9999. Formatted as YYYYMMDD.

[ @active_start_time = ] active_start_time
The time on any day between active_start_date and active_end_date to begin execution of a job. active_start_timeis int, with a default of 000000, which indicates 12:00:00 A.M. on a 24-hour clock, and must be entered using the form HHMMSS.

[ @active_end_time = ] active_end_time
The time on any day between active_start_date and active_end_date to end execution of a job. active_end_timeis int, with a default of 235959, which indicates 11:59:59 P.M. on a 24-hour clock, and must be entered using the form HHMMSS.

[ @owner_login_name= ] 'owner_login_name'
The name of the server principal that owns the schedule. owner_login_name is sysname, with a default of NULL, which indicates that the schedule is owned by the creator.

[ @schedule_uid= ] schedule_uidOUTPUT
A unique identifier for the schedule. schedule_uid is a variable of type uniqueidentifier.

[ @schedule_id= ] schedule_idOUTPUT
An identifier for the schedule. schedule_id is a variable of type int.

[ @originating_server= ] server_name
Identified for informational purposes only. Not supported. Future compatibility is not guaranteed.

Return Code Values

0 (success) or 1 (failure)

Result Sets

None

Remarks

SQL Server Management Studio provides an easy, graphical way to manage jobs, and is the recommended way to create and manage the job infrastructure.

Permissions

By default, members of the sysadmin fixed server role can execute this stored procedure. Other users must be granted one of the following SQL Server Agent fixed database roles in the msdb database:

SQLAgentUserRole
SQLAgentReaderRole
SQLAgentOperatorRole

For details about the permissions of these roles, see SQL Server Agent Fixed Database Roles.

Examples

A. Creating a schedule

The following example creates a schedule named RunOnce. The schedule runs one time, at 23:30 on the day that the schedule is created.

USE msdb ;
GO

EXEC dbo.sp_add_schedule
    @schedule_name = N'RunOnce',
    @freq_type = 1,
    @active_start_time = 233000 ;

GO

B. Creating a schedule, attaching the schedule to multiple jobs

The following example creates a schedule named NightlyJobs. Jobs that use this schedule execute every day when the time on the server is 01:00. The example attaches the schedule to the job BackupDatabase and the job RunReports.

Note

This example assumes that the job BackupDatabase and the job RunReports already exist.

USE msdb ;
GO

EXEC sp_add_schedule
    @schedule_name = N'NightlyJobs' ,
    @freq_type = 4,
    @freq_interval = 1,
    @active_start_time = 010000 ;
GO


EXEC sp_attach_schedule
   @job_name = N'BackupDatabase',
   @schedule_name = N'NightlyJobs' ;
GO

EXEC sp_attach_schedule
   @job_name = N'RunReports',
   @schedule_name = N'NightlyJobs' ;
GO

Change History

Release	History
17 November 2008	Changed content: Added information about @ active_start_date.
12 December 2006	Changed content: Added clarification to the descriptions of @freq_subday_interval and @freq_relative_interval.
17 July 2006	Changed content: Removed the Seconds option from @freq_subday_type. This option is not supported.
14 April 2006	Changed content: Corrected default value of @freq_interval from 0 to 1.

Share via

sp_add_schedule (Transact-SQL)

Syntax

Arguments

Return Code Values

Result Sets

Remarks

Permissions

Examples

See Also

Reference

Help and Information

Change History

Additional resources