Time
Windows
Dates and times used to specify time windows should not contain blank characters and
should include the 4 digit year. An example date and time is “04MAR2003
1400”. If a single string is used to specify the time window, the starting date and
time must precede the ending date and time, for example dssFile.setTimeWindow
(“04MAR2003 1400 06APR2004 0900”). A relative time may be used in the single string
command, where the letter “T” represents the current time, and the days or hours can be
subtracted or added to that. For example dssFile.setTimeWindow(“T-14D T-2H”)
would specify the starting time as current time minus 14 days and the ending time as the
current time minus 2 hours.
Time Windows (specified by starting time and ending time) effect how the DSSFile.read(…)
method operates for the various data types.
-
Time-series data. The time window supplied to DSS.open(…) or
dssFile.setTimeWindow(…) specifies the default time window for all subsequent
dssFile.read(…) operations. If no time window is supplied to DSS.open(…)
then the default time window is undefined until dssFile.setTimeWindow(…) is
called. If the default time window is undefined, then all dssFile.read(…)
operations involving time-series data must specify a time window either
implicitly via the D-part of the specified pathname or explicitly via the startTime and
endTime parameters. The order of precedence for time windows is as follows:
-
Explicit time window. Specified in dssFile.read(pathname,
startTime, endTime) or dssFile.read(pathname, timeWindow). The D-part
of the pathname is ignored and may be empty.
-
Default time window. Specified in DSS.open(filename, startTime,
endTime) or DSS.open(filename, timeWindow) or
dssFile.setTimeWindow(startTime, endTime) or
dssFile.setTimeWindow(timeWindow). The D-part of the pathname is
ignored and may be empty. The default time window can be set to undefined by
calling dssFile.setTimeWindow(“”, “”).
-
Implicit time window. Specified as the D-part of the pathname supplied
to dssFile.read(pathname) when the default time window is undefined.
The D-part of the pathname must not be empty.
-
Paired data. Time windows have no effect on reading paired data records.
-
Stream rating data. Stream rating data are comprised of a
time-series of individual rating records for a common location. The reading
of stream rating data is not affected by default time windows. The implicit time
window for reading stream rating data is the entire time span covered by the rating
records. An explicit time window may be supplied by using the
dssFile.read(pathname, startTime, endTime) method. If an explicit time
window is specified, a (possible) subset of the rating records is retrieved that cover
the specified time window. The explicit time window is interpreted as the time
window containing all time-series data that is to be rated via the stream rating
data. The set of rating records retrieved for an explicit time window meets the
following criteria.
-
The earliest record retrieved is the latest rating that is on or before the start
of the time window. If no such record exists, the earliest record in the
rating time-series is retrieved.
-
The latest record retrieved is the earliest rating that is on or after the end of
the time window. If no such record exists, the latest record in the rating
time-series is retrieved.
-
All rating records between the earliest and latest retrieved records are also
retrieved.