Previous Next Contents Generated Index Home


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

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.


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"

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>

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.




Previous Next Contents Generated Index Home

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