The scheduler for SIAM is a very flexible scheduler that is similar in many respects to the Unix cron utility. Schedules may be used to specify scheduled tasks at a set of absolute dates/times or periodically at a specified rate.

Instrument services may use one or more named schedules; by default, each has a single default sampling schedule called "default".

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.

Schedule Specifier Syntax

The schedule specification consists of 11 fields describing the set of execution times, 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:

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, following 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 modulus is used to compute the execution period. The mask portion is used to mask off certain execution times. For example,

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 particular day or month (case insensitive). Ranges or lists of names are allowed.

The last field (to the end of the line) specifies the job file to be run (Note: the use of the job field is deprecated; it may be included, and will be displayed by toString(), but is not functional).

Examples

Run a job every 10 seconds between 50 past and 10 past the minute

Run job 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

Utilities

A number of utilities are provided (under siam/utils/) to manipulate schedules:

• addSchedule
• setSchedule
• removeSchedule
• showSchedule
• suspendSchedule
• resumeSchedule

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 *.
month	Months mask	* 0-7 jan,feb,mar,apr,may,jun, jul,aug,sep,oct,nov
day of week	Weekday mask	* 0-7 sun,mon,tue,wed thu,fri,sat
day of month	Month Day mask	* 0-31
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

Scheduler Utilities

There are a number of utilities for using SIAM scheduler:

• addSchedule
• setSchedule
• removeSchedule
• showSchedule
• suspendSchedule
• resumeSchedule

The following table describes the utilities and their use. The options are described in greater detail in a separate table below.

Name	Use Syntax	Description
showSchedule	showSchedule <nodeURL> [<port> [<scheduleName>] [<lookAheadSec>]]...	Display the current state of specified schedule(s). If no port or schedule is specified, all schedules on the given nodeURL will be displayed. The information displayed includes the names of all schedules, making this a good place to start. All instrument services have a schedule named Default which implements their default sampling schedule..
addSchedule	addSchedule <nodeURL> <port> <scheduleName> <scheduleSpecifier> [o]	Adds a schedule for the specified device (port). If the device does not recognize scheduleName, the schedule will not be added. If the overwrite option ("o") is specified, the schedule (if scheduleName is valid) will be overwritten if it already exists. If the overwrite option is not specified (and scheduleName is valid), addSchedule will return a message indicating that the schedule already exists and will not modify the schedule.
setSchedule	setSchedule <nodeURL> <port> <scheduleName> <scheduleSpecifier>	Same as addSchedule; the overwrite option is implicitly asserted
removeSchedule	removeSchedule <nodeURL> <port> <scheduleName>	Removes the specified schedule
suspendSchedule	suspendSchedule <nodeURL> <port> <scheduleName>	Suspends the action for the specified schedule. This may be useful for temporarily disabling a device without interrupting its schedule. The schedule continues to run, but exits immediately instead of performing its scheduled task.
resumeSchedule	resumeSchedule <nodeURL> <port> <scheduleName>	Informs a suspended task to resume normal operation
synch	synch <nodeURL> <port> <scheduleName> [<delay ms>]	Causes the specified schedule to execute after the specified delay (default delay is 0 ms). May be used to shift the relative starting times of relative schedules. Absolute schedules will execute after the specified delay, but are otherwise unaffected.

Options

Option	Description	Values
nodeURL	IP address or host name of SIAM node	e.g. 134.89.88.1, mooring.moos.mbari.org
portName	Name of instrument port (or alias) defined in siamPort.cfg	/dev/ttyS8, COM1, /dev/tty.KeySerial1
scheduleName	Named schedule to manipulate	"default", "darkCalSample", "backgroundSample", etc.
scheduleSpecifier	Schedule definition string using scheduleSpecifier syntax (see above). Simple periodic intervals may be specified simply as some number of seconds.	Simple (relative) schedule: once per hour (using simple scheduleSpecifier) setSchedule localhost /dev/tty.KeySerial1 default 3600 Simple (relative) schedule: once per hour (using full scheduleSpecifier) setSchedule localhost /dev/tty.KeySerial1 default "R */0 */0 */1 */0 * * * * GMT *" Absolute schedule: 06:30 and 18:30 GMT every M,W,F (although periodic with no end time, happens at a specific (absolute) time of day) setSchedule localhost /dev/tty.KeySerial1 default "A 0 30 6,18 * mon,wed,fri * * * GMT *" Absolute schedule: 0,15,30,45 past the hour every other hour between midnight and 6 a.m. and between noon and 6 p.m. mon-fri GMT-8 time zone Stop after 300 cycles setSchedule localhost /dev/tty.KeySerial1 default "a 0 0,15,30,45 0-6,12-18/2 * mon-fri * * * GMT-8 300"
o (overwrite)	option valid for addSchedule only When adding a schedule, overwrite the specified schedule if one of the same name already exists.	-
delay ms	option valid for synch only Delay for the specified number of milliseconds before beginning synch. Relative schedules will be referenced to the time of first execution following the delay.	-
lookAheadSec	Since absolute schedules may not occur at regular intervals, the Scheduler needs to bound its search for upcoming events. The lookAhead value indicates how far into the future (in seconds) to search for upcoming event times. When none is specified, the default value is used.	-

Example output: The showSchedule utility (used with no portName option specified) returns all schedules on a SIAM node:

					showSchedule system.node.mbari.org 
					
					
					Name: Default
					Owner: org.mbari.siam.foce.devices.elmo.ElmoThruster:1729 key=14
					Schedule: R */2 */0 */0 */0 * * * * GMT *
					Status: Executing	-
					
					Name: Default
					Owner: org.mbari.siam.foce.devices.digital.DigitalInputService:1738 key=4
					Schedule: R */10 */0 */0 */0 * * * * GMT *
					Status: Waiting	3284
					
					Name: Default
					Owner: org.mbari.siam.devices.seabird.sbe52mp.SBE52MP:1733 key=6
					Schedule: R */0 */1 */0 */0 * * * * GMT *
					Status: Executing	-
					
					Name: Default
					Owner: org.mbari.siam.foce.devices.analog.ScaledAnalog:1737 key=3
					Schedule: R */10 */0 */0 */0 * * * * GMT *
					Status: Executing	-
					
					...etc.
					

The showSchedule utility (used with portName option specified) returns all schedules associated with that port:

					showSchedule system.node.mbari.org EMonitor
					
					0 [main] ERROR org.mbari.siam.operations.utils.ShowSchedule  - ShowSchedule: lookAhead value undefined or invalid; using default (3600)
					
					Name: Default
					Owner: org.mbari.siam.foce.devices.analog.Sensoray518:1721 key=2
					Schedule: R */10 */0 */0 */0 * * * * GMT *
					Status: Waiting	7979
					

Note that an error is thrown, indicating that no lookAhead value is provided.
Since absolute schedules may not occur at regular intervals, the Scheduler needs to bound its search for upcoming events.
The lookAhead value indicates how far into the future to search for upcoming event times.
When none is specified, the default value is used.