nodeTest

The scheduler for SIAM is a very flexible scheduler that is similar in many respects to the Unix cron utility. Using a terse syntax, it facilitates scheduling tasks at a set of fixed, absolute times or periodically at a specified rate.

Schedules are described in text files using a cron-like syntax. Each schedule consists of a number of entries, delimited by newlines; each entry contains 12 fields, described in the table below. A description of the entry syntax follows.

Field	Description	Allowed Values	Comments
type	Type of schedule entry (relative or absolute)	r a	case insensitive
second	Seconds mask	* 0-59
minute	Minutes mask	* 0-59
hour	Hours mask	* 0-23
day	Days modulus	* integer	Modulus portion used for relative schedules only. Mask portion must be *.
day of week	Weekday mask	* 0-7 sun,mon,tue,wed thu,fri,sat
month	Months mask	* 0-11 jan,feb,mar,apr,may,jun jul,aug,sep,oct,nov,dec
day of year	Day of year mask	* 0-365
time zone	Compute time in this time zone (to operate during local daylight hours, for example)	GMT[± n]
max cycles	Stop execution after max cycles	* integer
job	Name of job file	string	path relative to schedulePath, set in scheduler.cfg

Types of Schedules

There are two types of schedules: relative and absolute. Absolute schedules are analogous to crontab entries; they represent a set of specific times at which to perform some task. An absolute schedule would be used, for example, to schedule a task to run Monday,Wednesday, and Saturday at 12:00 and 18:00, or at quarter past the hour, every hour between 0600 and 13:00.

Relative schedules are used to schedule a task for execution at an arbitrarily long fixed period. Relative schedules can be masked to operate only during certain times. A relative schedule would be used to schedule a task to execute every 47 minutes, or every 2 days, 3 hours, and 20 minutes, but only june-august during daylight hours. Relative schedules may be shifted by some delay to align (or avoid alignment) with other tasks, or to execute their initial cycle at a specific time.

The key difference between absolute and relative schedules is that absolute schedules execute at a specific set of times that are not necessarily periodic and will be the same regardless of when they begin, but relative schedules are strictly periodic, and their execution times are determined relative to the time they begin.

Entry Syntax

The schedule specification consists of 11 fields describing the set of execution times plus the job to execute, all separated by whitespace. In general, each field consists of a mask followed by a modulus, of the form

The modulus is always a number; the mask consists of a list of comma-delimited ranges of numbers or names, for example:

3,5,11-22,7
thu-sun,tue
mar,may-aug

An asterisk (*) may be used as a mask to represent the range "first-last".

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclu-
sive. For example, 8-11 for an "hours" entry specifies execution at hours 8, 9, 10 and 11.

Lists are allowed. A list is a set of numbers and/or ranges separated by commas. Examples: ``1,2,5,9'', ``0-4,8-12''.

The mask and modulus are interpreted differently for relative and absolute schedules:

The modulus values can be used in conjunction with ranges to skip certain values in each range. For absolute schedules, fol lowing a range with "/n" indicates that only every nth value of the range is included in the mask. For example, "0-23/2" can be used in the hours field to specify command execution every other hour (the alternative in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps are also permitted after an asterisk, so if you want to say "every two hours'', just use "*/2".

For relative schedules, the modules is used to compute the execution period. The mask portion is used to mask off certain execution times. For example,

r * */3 13-23/2...

indicates that execution should occur every two hours and 3 minutes, but only between the hours of 1 p.m. and 11 p.m.. By contrast, the same entry for an absolute schedule would indicate every third minute of every odd hour between 1 p.m. and 11 p.m. : "13:00,13:03...13:57,15:00,15:03...15:57,17:00...."

Names can also be used for the "month" and "day of week" fields. Use the first three letters of the partic-
ular day or month (case insensitive). Ranges or lists of names are allowed.

# Run dummyInstrumentJob every 10 seconds between 50 past and 10 past the minute
r 50-10/10 * * * * * * * GMT * dummyInstrument.job

# Run garmin25HVSGPS at 0,15,30,45 past the hour, every other hour between midnight and 6 a.m. and
# between noon and 6 p.m. (GMT-8 time zone), mon-fri
# Stop after 300 cycles
a 0 0,15,30,45 0-6,12-18/2 * mon-fri * * * GMT-8 300 garmin25HVSGPS.job

For convenience, schedule entries (jobs) may be grouped together in a single schedule file. The schedule file is analogous to a crontab. Entire schedules may be loaded and unloaded into the scheduler using the addSchedule and removeSchedule utilities (like crontab <file> and crontab -r, respectively). The use syntax is

By default, attempts to install a schedule with the same name as an existing schedule will fail; the "o" option will force the existing schedule to be overwritten.

Another utility, showSchedule, displays a list of all currently loaded schedules and the status of each job. The use syntax is

The showSchedule utility lists each schedule and job, including an index which may be used to modify the job using the other scheduler utilities.

Additional job control is provided through the addScheduleEntry and removeScheduleEntry utilities. As their names suggest, they facilitate adding or removing individual entries (jobs) in a schedule. The use syntax is

A schedule entry (job) may be suspended using suspendScheduleEntry. Suspension only causes the job to be ignored at each execution time. The scheduler continues to maintain the timers associated with the job, and there is no effect on any services invoked by the job. A call to resumeScheduleEntry restores operation; relative schedules do not shift as a result of suspension. The use syntax is

< There needs to be a facility for shifting execution of relative schedules >
< There may be a need for a utility to change individual schedule parameters >
< Obvious candidate for a GUI >

siam/utils/system.sch	Sample default schedule file
siam/properties/scheduler.cfg	Scheduler properties
siam/utils/*.job	Sample Job Files
siam/utils/addSchedule	Load a schedule
siam/utils/removeSchedule	Unload a schedule
siam/utils/addScheduleEntry	Add/Overwrite a job
siam/utils/removeScheduleEntry	Remove a job
siam/utils/suspendScheduleEntry	Suspend a job
siam/utils/resumeScheduleEntry	Resume a job
siam/utils/showSchedule	Show schedule status