InputString Property (PITimeFormat Object)

See Also     Example         


InputString is a Read/Write property used for setting the object's time based on a string representing wall clock time. When retrieved this property contains the string used to set the object's time (as opposed to the formatted OutputString). If the object's time is set using any other property (UTCSeconds, LocalDate or UTCFileTime) this string is cleared.



The object placeholder is an object expression that evaluates to a PITimeFormat object.



The time properties OutputString, LocalDate, UTCSeconds or UTCFileTime for the passed InputString are evaluated when the property InputString is set for a PITimeFormat object. For a DynamicTime object, the passed InputString is checked for validity when set, but evaluation occurs whenever one of the object's time properties is retrieved. Therefore, the time for the InputStrings "*", "Today", "Yesterday" is constant for PITimeFormat, but varies for a DynamicTime depending on when it is called.

The LocaleIndependent property determines if localized time strings are used in parsing. When set to true the time string is parsed as a PI time format, expecting time strings for month, weekday, "Today" and "Yesterday" in English. When set to false, local regional settings govern the parsing including date-time format preferences. If locale specific parsing fails PI time string parsing is also attempted even when LocaleIndependent is false. Since PI time strings expect a date format of day-month-year, this may cause ambiguity in cases where the date format for a machine's locale is different. Therefore, when specifying PI time strings with LocaleIndependent false, four digit years should be used to prevent ambiguity.

The supported string formats are relative times, combination times, absolute times, where the absolute times may be one of PI time, ISO 8601 time and local system time as indicated by regional settings. Examples of each type are shown below. An absolute time may be enclosed in quotes. Any string not enclosed in quotes will be checked for relative formats and absolute time formats.


PI time formats (for example 23-Jun-02 14:23:01) have been extended from the PI-API syntax to include fractional seconds (day-month-year h:m:s.fraction) and optionally a 4 digit year. If a leading date is not entered, the current date is assumed. If a trailing time is not entered, zero is assumed for the hour, minute and seconds. The year may be a two digit or four digit year. The date portion (day-month-year) need not be fully specified.  The following combinations are supported for the date portion of the string.

Any omitted specification is assumed to be the current day, month or year. If a single number is entered, it is assumed to be the day of the month. If it is out of range for a day, the number is interpreted as a year. The time portion (h:m:s.fraction) also supports these additional formats, Any omitted time specification (h, m or s) is assumed to be zero. For example, ":7:00" is the seventh minute of the current day. "20 7:00" is the seventh hour of the twentieth of the current month). This parsing scheme differs from the PI PE syntax by not using an additional leading colon to indicate a time string. The InputString property and the PI PE syntax parse the same when a date is entered before the time specification.


Relative time formats (for example +1h) and combination time formats (for example *+1h), may be formatted as,

The "start time" may be "Today", "Yesterday", a weekday name, "*", a PI time, local system time, ISO 8601 time, or omitted. Omitting the leading "start time" is equivalent to "*" (current time) for PITimeFormat objects. "Today" and "Yesterday" are the beginning of the specified day at 0 hours local time. Weekday names must be a MemberShortName or MemberName property from the weekday ITimeInterval object. The most current occurance of the specified weekday at 0 hours local time is used for the "start time". For example, if the current time is a Tuesday, specifying an InputString of Wednesday would set the time to the beginning of the day six days ago. The "number" may be a double, but some intervals such as year and month do not support fractional values. The "interval" must be a member of the TimeIntervals collection. Multiple sums and/or differences may be combined with a given start time. For example, an InputString of "T - 1 mo + 8 h" sets the time to 1 month ago plus 8 hours. Since some intervals in the TimeIntervals collection do time arithmetic in UTC time intervals (hours, minutes, seconds) and some use local time arithmetic, the order for multiple intervals in InputString is to sum all local time intervals and then add all UTC time intervals to the resulting time.


Local system time formats may contain month and day strings localized by the operating system, configurable ordering of the date, configurable date separators and configurable time separators. The local system time format has been extended to allow a fractional second to be specified. The date and time portions of the string can take the partial formats described under the PI time formats section.


ISO 8601 time format (for example 1995-12-31T23:59:59.3) adds a "T" to separate the date and time instead of a space. The order of the date is year-month-day.

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error Description
tseFRACTIONSNOTALLOWED Fractional intervals are not allowed.
tseNAMENOTFOUND Name not found in collection
tseTIMEINVALID The time is invalid.

Enabling Operational Intelligence