1.0 Overview

The schedule module provides a convenient interface to the OS' native
schedule mechanism.  Other modules may create scheduled items and they
will run at the specified time and interval without having to work with
these services directly.


2.0 Expectations

It is expected that this module will undergo some enhancements in the
future, specifically:

	- Run jobs as a specific user

	- Perform CCE actions on a schedule (e.g. toggle an attribute).
	  In general, doing things other than running a program or script.

	- Wait until the actual start time before running a job (see
	  Limitations, below).

	- Pass a standard argument to the action to identify the schedule
	  object that executed it.


3.0 Schedules

The following abstract sets are involved in scheduling an action:

	o Schedule	See section 3.1
	o Timer		See section 3.2

The Schedule specifies an action that should be run once at a 
specific time or at set intervals after a specific time has passed. 
The Timer monitors the current time and executes the action 
when the specified time has arrived.


3.1 Schedule

A Schedule defines the first time and repetition interval at which an
action should be performed.  The attributes associated with a schedule are:

	Attribute	Description
	--------------  --------------------------------------------------
	Name		An arbitrary name that may be used to identify the
			scheduled item.

			Values: Any string.

	Enabled		Whether the schedule is active or not.

			Values: True or False.

	Start Time	The time at which an action should be performed.
			The basis for both the first time and the interval
			at which a repeated action is performed.

			Values:  UTC time in seconds.
			Time since 00:00:00 UTC, January 1, 1970.

	Repeat Interval The frequency at which an action should be performed.

			Values: None, Minute, Quarter-hourly, Hourly,
			Quarter-daily, Daily, Weekly, and Monthly.

	Action		The command to run.

			Values: String
			The string must have the format

				path/file arguments
	
			The path and executable must be the first word in
			the action; the file  must exist and be executable.
			

The events that effect a schedule are:

	Event		Description
	--------------  --------------------------------------------------
	Create		Add a new schedule to CCE.

			Parameters: All attributes of a schedule

	Modify		Change the attributes of a schedule.  All schedule
			attributes may be modified.

			Parameters: Changed attributes

	Delete		Remove a scheduled action from CCE

			Parameters:  None


3.1.1 Create Event

When a Schedule is created, the parameters are checked to ensure that they
have valid values.  If the Schedule is enabled, the repeat interval is
examined and the Schedule is added to the Timer (see below for start time
conversion).


3.1.2 Modify Event

When a Schedule is modified, the changed parameters are first checked for
validity.  If the Schedule exists in the Timer, it is removed and the
Schedule attributes updated.

After the Schedule attributes are updated, the new set is checked to determine
if the Schedule should be added to the Timer again.


3.1.3 Delete Event

When a Schedule is deleted, it is removed from the Timer, if necessary.


3.2 Timer

The Timer performs actions at a specific time using the OS-specific facility
for this purpose.

Attributes associated with the Timer:

	Attribute	Description
	--------------  --------------------------------------------------
	Filename	The file used by the OS native scheduler to perform
			the action.

			Values: Valid path and file characters.
			Filenames are generated randomly and uniquely. 

	Minute		The minute(s) at which an action should be performed.

			Values:  0-59, *. '*' indicates every minute.

	Hour		The hour(s) at which an action should be performed.

			Values: 0-23, *. '*' indicates every hour.

	Day of Month	The day(s) of the month when and action should be
			performed.

			Values: 1-31, *. '*' indicates every day.  

			Day values above 28 may be skipped, if the month
			does not have those days.  While not considered,
			the following reference may be used to determine
			which months will possibly miss a scheduled day:

			January		1-31
			February	1-28 (29 on leap years)
			March		1-31
			April		1-30
			May		1-31
			June		1-30
			July		1-31
			August		1-31
			September	1-30
			October		1-31
			November	1-30
			December	1-31

	Month		The month(s) at which an action should be performed.

			Values: 1-12, *.  '*' indicates every month.  Months
			are:

			January		1
			February	2
			March		3
			April		4
			May		5
			June		6
			July		7
			August		8
			September	9
			October		10
			November	11
			December	12


	Day of Week	The day(s) of the week an action should be performed.

			Values: 0-7, '*'. '*' indicates every day.  Values
			are converted to days as follows:

			Sunday		0
			Monday		1
			Tuesday		2
			Wednesday	3
			Thursday	4
			Friday		5
			Saturday	6
			Sunday		7


Events that effect the Timer:

	Action		Description
	--------------  --------------------------------------------------
	Add		Adds a Schedule to perform an action, either once
			or on a periodic basis.

			Parameters:  Schedule Start Time, Repeat Interval,
			Action.

	Delete		Removes a Schedule so that it will not be performed
			in the future.

			Parameters:  Schedule Start Time, Repeat Interval

	Run		An action is performed.

			Parameters: Schedule Action

3.2.1  Add Event

When a Schedule is added to the Timer, the Schedule start time and repeat
interval are examined to determine if the action is enabled and what the
repeat interval should be.  Enabled actions are added to the Timer for
execution using the start time conversion listed in section 3.2.4.


3.2.2  Delete Event

When a Schedule is removed from the Timer, the OS will stop performing the
action defined in the Schedule.


3.2.3  Run Event

When the start time for an action arrives, the Timer executes the action
as if it were a command line.  Output from the action is discarded.

If an event is long-running, it may occur that the previous event is still
executing when the next scheduled time arrives.  The action will not be
started again until the previous run has completed; actions which contain
infinite loops will only run once.


3.2.4  How Schedule Start Times and Repeat Intervals are Interpreted

	Start and repeat times converted to Timer Attributes:

	Repeat                        Day of         Day of
	Interval        Minute  Hour  Month   Month  Week
	--------        ------  ----  ------  -----  ------
	Minute            *      *      *       *      *
	Quarter-Hourly   MM(1)   *      *       *      *
	Hourly           MM      *      *       *      *
	Quarter-Daily    MM(2)  HH(3)   *       *      *
	Daily            MM     HH      *       *      *
	Weekly           MM     HH      *       *      DD(4)
	Monthly          MM     HH      DD(5)   *      *

	(1)  A list of minutes, starting with the minute specified in the
	schedule start time:  MM, MM+15, MM+30, MM+45.  Values above the
	valid range for the minute attribute will be normalized to the
	range and the list sorted.

	(2)  The minute from the schedule start time.

	(3)  A list of hours, starting with the hour specified in the
	schedule start time:  HH, HH+6, HH+12, HH+18.  Values above the
	valid range for the hour attribute will be normalized to the
	range and the list sorted.

	(4)  The day of the week specified in the schedule start time.

	(5)  The day of the month specified in the schedule start time.

	
4.0 Limitations

While the schedule takes a start time, only part of it is currently used.
Instead of waiting for the absolute start time, the action is scheduled
to run at the next repeat interval based on the start time; the year part
of the start time is also not used.

Actions that repeat are scheduled for the next occurance of the interval
without regard to the absolute start time; if the next interval occurs
before the start time, the action will still be performed.

In the future, having a piece of middleware that ensures the start time
has passed before executing the action would ensure that the absolute
start time is used.

