# Appendix B

| # Time Expression Specifications

> This appendix describes time format with which complex time intervals can be specified in the agent.

> It covers the following topics:

- Notation--page 581
- Time Expression Specification--page 582

## Notation

> When specifying values for the time specification, white space is not usually important. However, an exception to this rule is that spaces are not allowed in numbers (that is, 4.5 not 4. 5) or in time (10:03 not 10: 03). In addition, upper or lower case is not important.

> The exact specification for the time format is described in the next section. Below are some general comments about the notation used.

- Any string enclosed by "" represents a literal string that must be used.
- DIGIT represent any single numeric value from 0 to 9.
- The notation `N*' before any value can be interpreted as N or more items of that value, where N is 1 or more. For example 2*DIGIT specifies 2 or more DIGIT values.
- To specify 0 or more values, precede the item with `*'. For example *DIGIT represents 0 or more DIGIT values.
- To specify an exact number of items, precede the item with the number of values required. For example 1DIGIT represents exactly one DIGIT value.
- The `|' denotes a logical "or" condition. For example 1DIGIT | 2DIGIT represents a value that can have one or two DIGIT values.
- Any item enclosed in [] is optional. For example [ time ] indicates that the time value may or may not be specified.

## Time Expression Specification

> When specifying an interval using the time specification, the following syntax is used (the refreshInterval command is used as an example):

>     "refreshInterval" = timex_spec
>     timex_spec = empty_string
>                  | simple_exp *( ("&&" | "||") simple_exp )

>     empty_string = ""
>     simple_exp = absolute
>                  | cyclic
>                  | comparison
>                  | cron
>                  | variable_subsitution

> The time specification can be set to an empty_string ("") or can be composed of 1 or more simple_exp items connected together using logical "and" and "or" operators. Using the empty_string specification is equivalent to specifying second = * (see below). The logical operators "and" and "or" are represented by the C && and || operators, respectively. The precedence of the logical operators is the same as in C. In addition, bracketing is also allowed.

> The different types of simple_exp are describe in the following sections:

### Absolute Time Expression Specification

> The absolute format allows the specification of a single instance in time. The syntax is:

> CODE EXAMPLE B-1 Absolute Time Expression Specification

>     absolute = "epoch(" 1*DIGIT ")"
>                | month_of_year "/" day_of_month "/" ( yr | year ) [ time ]
>                | month day_of_month [","] year [ time ]
>     month_of_year = <1*DIGIT value from 1 to 12>
>     day_of_month = <1*DIGIT value from 1 to 31>

>     month = "jan" | "feb" | "mar" | "apr" | "may" | "jun" | "jul" | "aug" |
>             "sep" | "oct" | "nov" | "dec" | "january" | "february" | "march"
>             | "april" | "june" | "july" | "august" | "september" | "october"
>             | "november" | "december"

>     yr = 2DIGIT
>     year = <4DIGIT value from 1970 to 2038>

>     time = (hour12 ":" minute [":" second] time_suffix )
>            | (hour24 ":" minute [":" second])

>     hour12 = <1*DIGIT value from 1 to 12>
>     hour24 = <1*DIGIT value from 0 to 23>
>     minute = <2DIGIT value from 00 to 59>
>     second = <2DIGIT value from 00 to 59>
>     time_suffix = "am" | "pm"

> The first form specifies the number of seconds from Jan 1, 1970 12:00am GMT. This is provided for UNIX programmers. The second and third forms, allow an optional time specification. If this is not specified, then the time used will be midnight of date specified. Examples of the absolute specification are:

>     refreshInterval = Jan 3, 1996 10:03:23 pm
>     refreshInterval = Jan 3 1996 10:03:23 pm
>     refreshInterval = 01/03/96 10pm
>     refreshInterval = epoch(234324324)

> Cyclic Time Specification

> The cyclic specification allows the specifications of periodic events. The period can be seconds, minutes, hours, days, or weeks in length. The syntax is:

> CODE EXAMPLE B-2 Syntax for Cyclic Specification

>     cyclic = "cycle(" rel_time ")"

>     rel_time = FLOAT [ rel_units ]
>     rel_units =  unit_week | unit_day | unit_hour | unit_min | unit_sec

>     unit_week = "w" | "wk" | "wks" | "week" | "weeks"
>     unit_day = "d" | "day" | "days"
>     unit_hour = "h" | "hr" | "hrs" | "hour" | "hours"
>     unit_min = "m" | "min" | "minute" | "minutes"
>     unit_sec = "s" | "sec" | "secs" | "second" | "seconds"

>     FLOAT = (1*DIGIT "." *DIGIT)
>             | (*DIGIT "." 1*DIGIT)
>             | *DIGIT

> If the rel_uints are not supplied, then seconds are assumed. If the entire time specification is a in cyclic format, the cycle()can be dropped. For example, both of the following examples are valid:

>     refreshInterval = cycle( 5 h )
>     refreshInterval = 5 h

> Comparison Time Specification

> The comparison specification can be used to specific conditions on variables that must be true. The syntax is:

> CODE EXAMPLE B-3 Syntax for Comparison Specification

>     comparison = ["!"] variable op value

>     variable = "day_of_week"
>                | "week_of_year"
>                | "day_of_year"
>                | "second"
>                | "minute"
>                | "hour"
>                | "day_of_month"
>                | "week_of_month"
>                | "month"
>                | "year"
>                | "date"
>                | "time"

>     op = "<"
>          | "<="
>          | "="
>          | "=="
>          | ">"
>          | ">="
>          | "!="

>     value = "*"
>             | value_item *[ "," value_item ]
>     value_item = value_basic
>                  | value-basic "-" value_basic
>     value_basic = *DIGIT
>                   | day_of_week
>                   | day
>                   | week_of_year
>                   | day_of_year
>                   | second
>                   | minute
>                   | hour
>                   | day_of_month
>                   | year
>                   | absolute
>                   | time

> The optional (!) in front of the variable can be interpreted as a "not" logical operator. When (*) is specified for value any value is valid for that variable and that all values will be considered when finding the next beat. For example minute=* says that the object will be true all the time and will beat once at the start of every minute.

> Only certain types of value_basic can be used in with certain variables (see the example below). In addition only certain types of value_basic can be specified in a range in value_item.The value_basic types that cannot be specified in a range are: hour, hour24, minute, second, and time.In addition, ranges can only be used when the "=" op is used. For example, `day_of_month < 2-15,25` is invalid and
> `day_of_month = 2-15,25` is valid.

> The ranges for value_basic types written maximum to minimum will get translated to minimum to maximum. For example, day_of_month=25-5, will be treated the same as day_of_month = 25-31,1-5.

> Internally, a precision is kept for each value so that seconds will be not lost when specifying ranges. For example, time<8:05am && time>=8:05am will cover the entire day. Without the precision, there would be a 59-second period that would not be covered (8:04:01am-8:04:59am).

> Each of the variable and associated value items is described below.

>     "day_of_week"
>     value = day_of_week | day
>     day_of_week = <1DIGIT value from 0 to 7>
>     day = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun"
>           | "monday" | "tuesday" | "wednesday" | "thursday" | "friday"
>           | "saturday"  "sunday"

- Monday corresponds to a numeric value of 1.
- Sunday can have a numeric value of 0 or 7.
- Saturday has a numeric value of 6.
- The words sun or sunday correspond to the numeric value 0, not 7.

> Do not use <, <=, >=, or > with `day_of_week`, since Sunday can be 0 or 7. For example, `day_of_week <= 7` means the entire week (0-7) whereas `day_of_week<=0 or day_of_week<=Sun` means Sunday only.

> Use two end points. For example, use `day_of_week=wed-sun` or `day_of_week>=wed && day_of_week<=Sun` so that the start and end days are clear.

>     "week_of_year"
>     value = week_of_year
>     week_of_year = <1*DIGIT value from 1 to 53>

- A value of 1 is the first week in the year where there are four days of the week in that year (monday is considered the beginning of a week).
- A value of 0 is defined to be the 1, 2 or 3 days that may lie in that year but come before week 1.
- A value of 53 may occur under certain conditions. For example, if the first day of the year falls on a thursday and the year is a leap year.

      "day_of_year"
      value = day_of_year
      day_of_year = <1*DIGIT value from 1 to 366>
      "second"
      value = second
      "minute"
      value = minute
      "hour"
      value = hour
      hour = ( hour12 time_suffix ) | hour24
      midnight is 0 or 12am
      noon is 12 or 12pm
      "day_of_month"
      value = day_of_month
      day_of_month = <1*DIGIT value from 1 to 31>
      "week_of_month"
      value = week_of_month
      week_of_month = <1DIGIT value from 1 to 5>

- `week_of_month` represents the number of times that day of the week has occurred in the month.
- Used to represent things like the first sunday in July `week_of_month==1 && day_of_week==sun && month==july`

      "month"
      value = month_of_year | month
      "year"
      value = year
      "date"
      value = absolute
      "time"
      value = time

  Cron Time Specification

> The cron specification allows UNIX cron style inputs. The syntax is:

>     cron = "cron(" minute hour day_of_month month day_of_week ")"

> The five entries correspond to the usual minute, hour, day of month, month, day of week values respectively. These values can include ranges as in the comparison specification. If the entire time specification is a cron specification, then the "cron()" can be dropped. For example both of the following specifications are valid:

>     refreshInterval = cron(5 * * * *)
>     refreshInterval = 5 * * * *

> Variable Substitution Specification

> The time specification also allows variable substitution. All variables will be de-referenced from the `base-timex-d.x` file. The notation for referencing variables is:

>     variable_subsitution = "$" <character string>

> For example, the variable xmas can be specified in the `base-timex-d.x` file:

>     xmas = "day_of_month = 25 && month = dec"

> This variable can then be used in specifying an interval:

>     refreshInterval = "!($xmas) && cycle(5s) || ($xmas) && cycle(1hr)"

> This example indicates that on Christmas, specify a cycle interval with a period of one hour. Otherwise, cycle with a period of 5 seconds.

Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.