NAME Scheduler SYNOPSIS Utilities for scheduling data acquisition and system tasks DESCRIPTION Overview 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 *. 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 job Name of job file string path relative to schedulePath, set in scheduler.cfg Note: Use of the job field is deprecated; 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, all separated by whitespace. In general, each field consists of a mask followed by a modulus, of the form mask/modulus 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 modulus 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. 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 r 50-10/10 * * * * * * * GMT * # 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 a 0 0,15,30,45 0-6,12-18/2 * mon-fri * * * GMT-8 300 Interface A number of utilities are provided (under siam/utils/) to manipulate schedules: addSchedule setSchedule removeSchedule showSchedule suspendSchedule resumeSchedule The use syntax is Name Use Syntax Description showSchedule showSchedule <nodeURL> [<port> [<scheduleName>]]... 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> [overwrite] 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. ENVIRONMENT Currently the utilities are found in the CVS repository under siam/utils. The following files are relevant. siam/properties/scheduler.cfg Scheduler configuration siam/properties/siamPort.cfg Scheduler configuration siam/utils/addSchedule Add a schedule w/ optional overwrite siam/utils/setSchedule Load a schedule siam/utils/removeSchedule Unload a schedule siam/utils/suspendSchedule Suspend a schedule siam/utils/resumeSchedule Resume a schedule siam/utils/showSchedule Show schedule status The scheduler interface utilites require the bash shell SEE ALSO