A calendar is a set of rules that defines on what days a job may run. The rules that make up a calendar are specified in the configuration file and the calendars themselves are associated with a Family in the Family file.

Calendar names should contain only the characters shown below:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-

Let's start with the configuration file. You can have zero or more calendars in the configuration file. Each calendar may be associated with zero or more Families. A calendar consists of one or more rules. All rules belonging to a calendar are consulted in order to determine whether or not the Family should run today. The rules are consulted in the order in which they are specified in the configuration file. Rules may contradict each other. A rule may not conclusively determine whether or not the Family should run today. The last rule that determines whether or not a Family should run today will override any earlier rules. Rules are case insensitive.

Let's see some examples. First, let's see how a Family file specifies a calendar:

Example 1 - One day only

       +-------------------------------------------------------
    01 |start => '00:00', tz => 'GMT', calendar => 'NY2010'
    02 |
       | ...

You can see here that instead of the `days => '...'`, we have `calendar => 'NY2010'`. This tells the system that this family will rely on the calendar named 'NY2010.' This calendar is defined in its own file. The file name should be the same as the calendar name. The directory in which the file exists is specified by the calendar_dir option:

       +-------------------------------------------------------
       | ...
       | calendar_dir = "/foo/bar/calendars"
       | ...

The file /foo/bar/calendars/NY2010 looks like this (the # symbols and anything after them are comments, just like in the configuration file):

       +-------------------------------------------------------
    01 | # NY2010
    02 | + 2010/01/01  # Only valid on New Years Day, 2010
       +-------------------------------------------------------

This calendar only has one rule. It is "+ 2010/01/01". The '+' in the rule says that if the date specified in this rule matches, then the Family must run on that day. The '+' is optional. This calendar will allow the Family that uses it to run on Jan 1, 2010, and on no other day. Dates in rules should be in the YYYY/MM/DD format.

Example 2 - One month only

What if we want a job to run on every day in November 2010? You can use a rule like this:

    # Nov2010

     2010/11/*

The '*' in the DD part of the date is like a wildcard. It means that the DD part of the rule will match any number. In other words, if today's date is November DD, 2010, then this rule will match, for all values of DD. Note that the '+' is missing here. That's ok. It's optional, and if missing, the system will assume that you meant to put in a '+'.

Example 3 - Rejecting days

If, on the other hand, you wanted this Families that use this calendar to run on all days in 2010 except all of November, you would use the '-' sign:

    # All_But_Nov2010

     + 2010/*/*
     - 2010/11/*

The first line matches all days in 2010. The MM and DD parts are both wildcards. The optional plus tells the system that if the date matches this pattern, it should count as a valid run date. The next line, on the other, hand adds an exception to this rule: If the date falls within November 2010, the date should not be a valid run date - note the '-' sign that tells the system to exclude this date.

Example 4 - Daily Calendar

To specify a daily calendar, use this:

    # Daily

    */*/*

Of course, you don't have to name the calendar 'Daily.' You can name it whatever you want. Using this calendar is equivalent to having `days=>'Mon,Tue,Wed,Thu,Fri,Sat,Sun'` in the Family file.

Example 5 - Specifying days of the week

You can also specify rules that specify days of the week with a qualifier. For example, to run a job on the first Monday of every month in 2009, you should use a rule like this:

    # FirstMon09

    + first Mon 2009/*

A couple of points to mention here: First, the '+' is optional here as well. Second, the date part of the rule only has the year and the month (in YYYY/MM format). When you use a qualifier like 'first,' it makes no sense to say things like 'The first Monday of the 1st of every month.'

The word 'first' in line 2 above is called a qualifier. Valid qualifiers are:

- first
- second
- third
- fourth
- fifth
- last
- second last
- third last
- fourth last
- every

The qualifiers 'first last,', 'last last' and 'every last' also work in version 1.25, but they may stop working in a future version, so don't get into the habit of using those qualifiers.

Unlike the 'days' specifier in the family file, the days of the week in calendar rules may be spelled out. Only the first 3 characters are significant.

Calendar Recipes

The following 'recipes' show you some useful calendar rules:

    # ############################################################
    # Run every day
    #
    + */*/*

    # ############################################################
    # Run on weekdays only
    #
    */*/*
    - every Saturday */*
    - every Sunday */*

    # You could also replace the 3 lines above
    # with 5 '+' lines, one for each weekday.

    # ############################################################
    # 'Thanksgiving Day' observed in the U.S.
    #
    fourth Thursday */11

    # ############################################################
    # 'Thanksgiving Day' observed in Canada
    #
    second Monday */10

    # ############################################################
    # 'Memorial Day' observed in the U.S.
    #
    last Monday */5

    # ############################################################
    # The day Daylight Saving Time starts in the U.S.
    #
    second Sun */03  # this rule is valid for dates
                     # after 2007, but not earlier

    # ############################################################
    # The day Daylight Saving Time ends in the U.S.
    #
    first Sun */11   # this rule is valid for dates
                     # after 2007, but not earlier

    # ############################################################
    # The day Daylight Saving Time starts in Europe
    #
    last Sun */03    # tested for 2009

    # ############################################################
    # The day Daylight Saving Time ends in Europe
    #
    last Sun */10    # tested for 2009