Errata exists for this version of the document.
When accessing HistoricalDataNodes via the HistoryRead Service, requests can set a flag, returnBounds, indicating that BoundingValues are requested. For a complete description of the Extensible Parameter HistoryReadDetails that include StartTime, EndTime and NumValuesPerNode, see 6.4. The concept of Bounding Values and how they affect the time domain that is requested as part of the HistoryRead request is further explained in 4.4. 4.4 also provides examples of TimeDomains to further illustrate the expected behaviour.
When making a request for historical data using the HistoryRead Service, the required parameters include at least 2 of these three parameters: startTime, endTime and numValuesPerNode. What is returned when Bounding Values are requested varies according to which of these parameters are provided. For a historian that has values stored at 5:00, 5:02, 5:03, 5:05 and 5:06, the data returned when using the Read Raw functionality is given by Table 1. In the table, FIRST stands for a tuple with a value of null, a timestamp of the specified StartTime, and a StatusCode of Bad_BoundNotFound. LAST stands for a tuple with a value of null, a timestamp of the specified EndTime, and a StatusCode of Bad_BoundNotFound.
In some cases, attempting to locate bounds, particularly FIRST or LAST points, may be resource intensive for Servers. Therefore how far back or forward to look in history for Bounding Values is Server dependent, and the Server search limits may be reached before a bounding value can be found. There are also cases, such as reading Annotations or Attribute data where Bounding Values may not be appropriate. For such use cases it is permissible for the Server to return a StatusCode of Bad_BoundNotSupported.
Table 1 – Bounding Value examples
|
Start Time |
End Time |
numValuesPerNode |
Bounds |
Data Returned |
|
5:00 |
5:05 |
0 |
Yes |
5:00, 5:02, 5:03, 5:05 |
|
5:00 |
5:05 |
0 |
No |
5:00, 5:02, 5:03 |
|
5:01 |
5:04 |
0 |
Yes |
5:00, 5:02, 5:03, 5:05 |
|
5:01 |
5:04 |
0 |
No |
5:02, 5:03 |
|
5:05 |
5:00 |
0 |
Yes |
5:05, 5:03, 5:02, 5:00 |
|
5:05 |
5:00 |
0 |
No |
5:05, 5:03, 5:02 |
|
5:04 |
5:01 |
0 |
Yes |
5:05, 5:03, 5:02, 5:00 |
|
5:04 |
5:01 |
0 |
No |
5:03, 5:02 |
|
4:59 |
5:05 |
0 |
Yes |
FIRST, 5:00, 5:02, 5:03, 5:05 |
|
4:59 |
5:05 |
0 |
No |
5:00, 5:02, 5:03 |
|
5:01 |
5:07 |
0 |
Yes |
5:00, 5:02, 5:03, 5:05, 5:06, LAST |
|
5:01 |
5:07 |
0 |
No |
5:02, 5:03, 5:05, 5:06 |
|
5:00 |
5:05 |
3 |
Yes |
5:00, 5:02, 5:03 |
|
5:00 |
5:05 |
3 |
No |
5:00, 5:02, 5:03 |
|
5:01 |
5:04 |
3 |
Yes |
5:00, 5:02, 5:03 |
|
5:01 |
5:04 |
3 |
No |
5:02, 5:03 |
|
5:05 |
5:00 |
3 |
Yes |
5:05, 5:03, 5:02 |
|
5:05 |
5:00 |
3 |
No |
5:05, 5:03, 5:02 |
|
5:04 |
5:01 |
3 |
Yes |
5:05, 5:03, 5:02 |
|
5:04 |
5:01 |
3 |
No |
5:03, 5:02 |
|
4:59 |
5:05 |
3 |
Yes |
FIRST, 5:00, 5:02 |
|
4:59 |
5:05 |
3 |
No |
5:00, 5:02, 5:03 |
|
5:01 |
5:07 |
3 |
Yes |
5:00, 5:02, 5:03 |
|
5:01 |
5:07 |
3 |
No |
5:02, 5:03, 5:05 |
|
5:00 |
UNSPECIFIED |
3 |
Yes |
5:00, 5:02, 5:03 |
|
5:00 |
UNSPECIFIED |
3 |
No |
5:00, 5:02, 5:03 |
|
5:00 |
UNSPECIFIED |
6 |
Yes |
5:00, 5:02, 5:03, 5:05, 5:06, LASTa |
|
5:00 |
UNSPECIFIED |
6 |
No |
5:00, 5:02, 5:03, 5:05, 5:06 |
|
5:07 |
UNSPECIFIED |
6 |
Yes |
5:06, LAST |
|
5:07 |
UNSPECIFIED |
6 |
No |
NODATA |
|
UNSPECIFIED |
5:06 |
3 |
Yes |
5:06,5:05,5:03 |
|
UNSPECIFIED |
5:06 |
3 |
No |
5:06,5:05,5:03 |
|
UNSPECIFIED |
5:06 |
6 |
Yes |
5:06,5:05,5:03,5:02,5:00,FIRSTb |
|
UNSPECIFIED |
5:06 |
6 |
No |
5:06, 5:05, 5:03, 5:02, 5:00 |
|
UNSPECIFIED |
4:48 |
6 |
Yes |
5:00, FIRST |
|
UNSPECIFIED |
4:48 |
6 |
No |
NODATA |
|
4:48 |
4:48 |
0 |
Yes |
FIRST,5:00 |
|
4:48 |
4:48 |
0 |
No |
NODATA |
|
4:48 |
4:48 |
1 |
Yes |
FIRST |
|
4:48 |
4:48 |
1 |
No |
NODATA |
|
4:48 |
4:48 |
2 |
Yes |
FIRST,5:00 |
|
5:00 |
5:00 |
0 |
Yes |
5:00,5:02c |
|
5:00 |
5:00 |
0 |
No |
5:00 |
|
5:00 |
5:00 |
1 |
Yes |
5:00 |
|
5:00 |
5:00 |
1 |
No |
5:00 |
|
5:01 |
5:01 |
0 |
Yes |
5:00, 5:02 |
|
5:01 |
5:01 |
0 |
No |
NODATA |
|
5:01 |
5:01 |
1 |
Yes |
5:00 |
|
5:01 |
5:01 |
1 |
No |
NODATA |
|
aThe timestamp of LAST cannot be the specified End Time because there is no specified End Time. In this situation the timestamp for LAST will be equal to the previous timestamp returned plus one second. b The timestamp of FIRST cannot be the specified End Time because there is no specified Start Time. In this situation the timestamp for FIRST will be equal to the previous timestamp returned minus one second. c When the Start Time = End Time (there is data at that time), and Bounds is set to True, the start bounds will equal the Start Time and the next data point will be used for the end bounds. |
||||