Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Defining Schedule Specifications

Defining Schedule Specifications

The default scheduling for business hosts is for them to run whenever the production is running. However, a finer control is possible. Not only can you enable and disable business hosts, but the Production Configuration page also provides a Schedule setting for each business host. This is an optional command string that schedules the item to be stopped and started at specific times and on specific days of the week, month, or year. When it is time to start, if the item is enabled, the scheduler starts it; when it is time to stop, if the item is running, the scheduler stops it.

The Schedule Spec Editor page (Ensemble > Configure > Schedule Specs) aids you in creating a string to use in this configuration setting. Once you create a schedule string and give it a name, you can use this string as a value for the Schedule configuration setting.

Schedule Specifications

The Schedule string is a comma-separated list of event specifications. Each event specification has the following format:

action:YYYY-MM-DDThh:mm:ss

Where each item in the event specification, from left to right, has the described values:

Item Possible Values
action START or STOP indicates the desired action
: Required separator
YYYY-MM-DD Either:
  • YYYY is the year as 4 numerals
  • MM is the month as 2 numerals
  • DD is the day of the month as 2 numerals
  • Any of these fields may be the single character * (asterisk) indicating all years, all months, or all days
Or:
  • YYYY is the word WEEK
  • MM is the specific occurrence of the day of the week (indicated by DD) in the month (01 = first occurrence of the specific day of the week in the month, 02 = second occurrence in the month, etc.)
  • DD is a specific day of the week (00 = Sunday, 01 = Monday, etc.)
  • MM may be * for all occurrences and DD may be * for all days
Once a field is specified as *, all fields to the left of it are also assumed to be *. Thus, if the DD value is *, the MM value is treated as * even if it has a specific numeric value. Similarly, if MM is *, YYYY is treated as *.
T Required separator
hh:mm:ss Hour, minute, and second
, Use the comma separator only if there is another event specification after the current one. Do not use it at the end of the Schedule string.

If you set a schedule specification to be deployable, then the specification can be included when you export the production. When you are exporting the production, select Deployable Settings and select the Ens.Util.Schedule setting.

See the Ens.ScheduleHandler entry in the Class Reference for more information.

The following sections provide examples, details on Daylight Saving Time considerations, and the intended use and limitations of the setting.

Examples

If your schedule contains recurring events, the Schedule setting requires both START and STOP actions. If your schedule setting is an absolute one time event, then you need only use the appropriate single START or STOP action. In most cases, Schedule strings should contain both a START and a STOP action.

Some examples of Schedule strings follow:

  • Start the business host every day at 8 a.m. and stop it every day at 5 p.m.

    START:*-*-*T08:00:00,STOP:*-*-*T17:00:00
    
  • Stop every year on January 2 at 7 a.m. and start again on January 3 at 7 a.m.

    STOP:*-01–02T07:00:00,START:*-01-03T07:00:00
    
  • Start every month on the second day of the month at 8 a.m. and stop every month on the tenth day of the month at 8:30 p.m.

    START:*-*-02T08:00:00,STOP:*-*-10T20:30:00
    
  • Stop every Sunday at 10 a.m. and start every Monday at 8:30 a.m.

    STOP:WEEK-*-00T10:00:00,START:WEEK-*-01T08:30:00
    
  • Start every third Tuesday at 9 a.m. and stop every third Friday at 4 p.m.

    START:WEEK-03-02T09:00:00,STOP:WEEK-03-05T16:00:00
    
  • Stop on December 31, 2010 just before midnight.

    STOP:2010-12-31T23:59:59
    
  • Start on January 3, 2011 at 6:45 a.m.

    START:2011-01-03T06:45:00
    
  • The following two strings are equivalent: Start every day at 2 a.m.

    START:*-*-*T02:00:00
    START:WEEK-*-*T02:00:00
    

Scheduling and Daylight Saving Time

When daylight saving time (DST) begins, clocks skip an hour that day, usually from 2:00 a.m. to 3:00 a.m. Any item you have scheduled that falls into that nonexisting hour takes place at the beginning (which is also the end) of that hour. For example, on the day DST begins, an event scheduled to take place at 2:15 a.m. takes place at 2:00 a.m. (which is also 3:00 a.m.).

When DST ends, an hour of the day repeats, usually from 1:00 a.m. to 2:00 a.m. Any item you have scheduled that falls in that repeated hour takes place only once. Whether the event takes place on the first occurrence of the scheduled time or the second occurrence in the repeated hour depends on the operating system, but it only takes place once. For example, on a Windows system on the day DST ends, an event scheduled to take place at 1:15 a.m. takes place at the second occurrence of 1:15 a.m.

Intended Use and Limitations

The Schedule setting starts and stops production business hosts according to a schedule; it is not a task scheduler. The schedule string defines a square wave in time declaring during what time intervals the item should be running, in between which it should be not be running. Ensemble cannot prevent scheduled transitions from being interrupted or superseded by other production events.

The scheduler wakes up periodically (it sets its own alarm clock for when any scheduled item next expects a transition) and attempts to start or stop any items that are not currently in the expected state according to their schedule strings. It runs the UpdateProduction() method of the Ens.ScheduleHandler class and checks what event it needs to schedule next.

There are two general classes of things that can prevent transitions from taking place as the schedule string indicates:

  • The scheduler might be unable to cause the intended state change; that is, the UpdateProduction() method fails to affect the relevant items.

    For example, an item could be in a Read timeout or some other busy state that lasts longer than the Update timeout. Another example is a business host the scheduler starts cannot be stopped by the scheduler if the item is in the middle of a synchronous call. The business host must wait for a response to the call before the scheduler stops it.

  • The scheduler might not be able to wake up at the intended time. Examples of conditions that could cause this: the CPU is busy, a queue builds up of the alarm clock messages for the scheduler, the scheduler is itself disabled or crashed, the production is down, etc. The scheduler is not guaranteed to wake up during any particular interval, and when it does wake up it only looks at the intended state for the current moment, not at any history of when it should have woken up.

Use of the schedule setting is not intended or designed as an event signaling device. It is intended to accommodate planned outages and scheduled intervals of activity or inactivity. If you have events that you must trigger at a particular time or as soon as possible thereafter, Ensemble provides better alternatives:

  • You can configure your business service to use an inbound adapter with the implemented OnTask() method where you call the business service. Ensemble provides classes for many types of inbound adapters. See the Ens.InboundAdapter entry in the Class Reference and the books in the Ensemble Adapter Guides set for details.

  • If you do not want to use an adapter, you can call the business service programmatically and schedule it to run using the Task Scheduler Wizard page (/csp/sys/op/UtilSysTaskHome.csp) in the Management Portal. To access the Task Scheduler Wizard page, select System Operation > Task Manager > New Task. This gives you finer control in situations such as the system being down at 1:00 a.m.

    The recommended approach is to configure the business service with Pool Size = 0 and then use the Task Manager to launch a task that calls CreateBusinessService() on it and invokes ProcessInput() on the resulting service instance object. The advantage of calling a business service this way is that you call it at the time you want and it runs only once. If Ensemble happens to be down at that time, your task can register an error. See the following sections for details:

Feedback