Time Strings (Core Services)

A time string can contain a date, time, time zone information, and a relative interval. The string has two parts, each of which is optional: the date time part and the interval part. The date time part can be "Today" (or "T"), "Yesterday" (or "Y"), a weekday name, a month name, "*" (current time), a null reference, an Empty string, a number less than 32 (day of month), a four digit number greater than or equal 1970 (year), or a date and time specification in any format supported by the Microsoft .NET's System.DateTime.TryParse method. The SQL time string format of hh:mm:ss:fff (three fractional digits are required for this format) is also supported for the time portion of the date time part. A null reference or Empty string is equivalent to "*" and represents the current time.

"Today" and "Yesterday" are the beginning of the specified day at 0 hours local time. A weekday name (either full name or abbreviation) specifies the most current occurrence at 0 hours local time. For example if the current time is Tuesday, specifying a weekday of Wednesday would set the time to the beginning of the day six days ago. A month name (either full name or abbreviation) specifies the current day of the month at 0 hours local time. An absolute date and time specification can be enclosed in double or single quotes (" or ') in any format supported by Microsoft .NET's System.DateTime.TryParse.

When only the time portion of the date time part is specified, then the input is evaluated as the time offset of the current day. If a reference time is specified, then this would be the time offset relative to the day of the reference time.

The interval part follows the date time part in one of the following formats. If the date time part is specified in a DateTime format (format parsed by DateTime.TryParse), then only the first format with interval names specified is allowed unless the date time part is enclosed in double or single quotes (" or ').

{+|-}<number>[.<number>] <interval> { [+|-]<number>[.<number>] <interval> }*


{+|-}{ hh | [hh][:[mm][:ss[.ff]]] }

Elements in square brackets ([ and ]) are optional. Alternatives are separated by a vertical bar (|). One selection from the list of alternatives enclosed in braces ({ and }) and separated by vertical bars (|) is required. A plus sign (+) after a group enclosed in braces ({ and }) indicates that zero or more instances of the group is allowed. The following table describes each element.

Element Description
<number> A number consisting of one or more digits.
<interval> The name, short name, or plural name of a standard interval. The table below defines the standard intervals.
+ An optional plus sign, which indicates a positive value.
- An optional minus sign, which indicates a negative value.
. A culture-sensitive symbol that separates seconds from fractions of a second. The invariant format uses a period (".") character.
hh Hours. If hours are omitted, then time separator must be specified before the minutes.
: A culture-sensitive time separator symbol. The invariant format uses a colon (":") character.
mm Optional minutes.
ss Optional seconds.
ff Optional fractional seconds.

Note to callers

Some formats with missing hours, minutes, and/or seconds that were supported by PI Time are not supported. For example "hh:mm" is supported, but "hh::ss", ":mm:ss", and "::s" are some formats that are not supported. The format must be supported by Microsoft .NET's DateTime.TryParse method.

Some characters used in PI Time strings are not URL-safe. For example, the plus sign ('+') represents a space in a URL. Make sure to URL encode any PI Time strings.

This is a table of the standard intervals. Either the plural full name, singular full name, or short name can be used as the name of the interval. The 'Fractions Allowed' column indicates if a fractional value is allowed for the interval type.

Name Short Name Fractions Allowed
millisecond(s) ms yes
second(s) s yes
minute(s) m yes
hour(s) h yes
day(s) d no
month(s) mo no
week(s) w no
weekday(s) wd no
yearday(s) yd no


Enabling Operational Intelligence