Errata exists for this version of the document.
The HistoryRead Service defined in OPC 10000-4 can perform several different functions. The HistoryReadDetails parameter is an Extensible Parameter that specifies which function to perform and the details that are specific to that function. See OPC 10000-4 for the definition of Extensible Parameter. Table 19 lists the symbolic names of the valid Extensible Parameter structures. Some structures will perform different functions based on the setting of its associated parameters. For simplicity a functionality of each structure is listed. For example, text such as ‘using the Read modified functionality’ refers to the function the HistoryRead Service performs using the Extensible Parameter structure ReadRawModifiedDetails with the isReadModified Boolean parameter set to TRUE.
Table 19 – HistoryReadDetails parameterTypeIds
|
Symbolic Name |
Functionality |
Description |
|
ReadEventDetails |
Read event |
This structure selects a set of Events from the history database by specifying a filter and a time domain for one or more Objects or Views. See 6.4.2.1. When this parameter is specified the Server returns a HistoryEvent structure for each operation (see 6.5.4). |
|
ReadRawModifiedDetails |
Read raw |
This structure selects a set of values from the history database by specifying a time domain for one or more Variables. See 6.4.3.1. When this parameter is specified the Server returns a HistoryData structure for each operation (see 6.5.2). |
|
ReadRawModifiedDetails |
Read modified |
This parameter selects a set of modified values from the history database by specifying a time domain for one or more Variables. See 6.4.3.1. When this parameter is specified the Server returns a HistoryModifiedData structure for each operation (see 6.5.3). |
|
ReadProcessedDetails |
Read processed |
This structure selects a set of Aggregate values from the history database by specifying a time domain for one or more Variables. See 6.4.4.1. When this parameter is specified the Server returns a HistoryData structure for each operation (see 6.5.2) |
|
ReadAtTimeDetails |
Read at time |
This structure selects a set of raw or interpolated values from the history database by specifying a series of timestamps for one or more Variables. See 6.4.5.1. When this parameter is specified the Server returns a HistoryData structure for each operation (see Clause 6.5.2). |
|
ReadAnnotationDataDetails |
Read Annotation Data |
This structure selects a set of Annotation Data from the history database by specifying a series of timestamps for one or more Variables. See 6.4.6.1. When this parameter is specified the Server returns a HistoryAnnotationData structure for each operation (see Clause 6.5.5). |
Table 20 defines the ReadEventDetails structure. This parameter is only valid for Objects that have the EventNotifier Attribute set to TRUE (see OPC 10000-3). Two of the three parameters, numValuesPerNode, startTime, and endTime shall be specified.
|
Name |
Type |
Description |
|
ReadEventDetails |
Structure |
Specifies the details used to perform an Event history read. |
|
numValuesPerNode |
Counter |
The maximum number of values returned for any Node over the time range. If only one time is specified, the time range shall extend to return this number of values. The default value of 0 indicates that there is no maximum. |
|
startTime |
UtcTime |
Beginning of period to read. The default value of DateTime.MinValue indicates that the startTime is Unspecified. |
|
endTime |
UtcTime |
End of period to read. The default value of DateTime.MinValue indicates that the endTime is Unspecified. |
|
Filter |
EventFilter |
A filter used by the Server to determine which HistoricalEventNode should be included. This parameter shall be specified and at least one EventField is required. The EventFilter parameter type is an Extensible parameter type. It is defined and used in the same manner as defined for monitored data items which are specified in OPC 10000-4. This filter also specifies the EventFields that are to be returned as part of the request. |
The ReadEventDetails structure is used to read the Events from the history database for the specified time domain for one or more HistoricalEventNodes . The Events are filtered based on the filter structure provided. This filter includes the EventFields that are to be returned. For a complete description of filter refer to OPC 10000-4.
The startTime and endTime are used to filter on the Time field for Events.
The time domain of the request is defined by startTime, endTime, and numValuesPerNode; at least two of these shall be specified. If endTime is less than startTime, or endTime and numValuesPerNode alone are specified then the data will be returned in reverse order with later/newer data provided first as if time were flowing backward. If all three are specified then the call shall return up to numValuesPerNode results going from startTime to endTime, in either ascending or descending order depending on the relative values of startTime and endTime. If numValuesPerNode is 0 then all of the values in the range are returned. The default value is used to indicate when startTime, endTime or numValuesPerNode are not specified.
It is specifically allowed for the startTime and the endTime to be identical. This allows the Client to request the Event at a single instance in time. When the startTime and endTime are identical then time is presumed to be flowing forward. If no data exists at the time specified then the Server shall return the Good_NoData StatusCode.
If a startTime, endTime and numValuesPerNode are all provided, and if more than numValuesPerNode Events exist within that time range for a given Node, then only numValuesPerNode Events per Node are returned along with a ContinuationPoint. When a ContinuationPoint is returned, a Client wanting the next numValuesPerNode values should call HistoryRead again with the continuationPoin t set.
If the request takes a long time to process then the Server can return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Client timeout hint. It may take longer than the Client timeout hint to retrieve any results. In this case the Server may return zero results with a ContinuationPoint that allows the Server to resume the calculation on the next Client HistoryRead call.
For an interval in which no data exists, the corresponding StatusCode shall be Good_NoData.
The filter parameter is used to determine which historical Events and their corresponding fields are returned. It is possible that the fields of an EventType are available for real time updating, but not available from the historian. In this case a StatusCode value will be returned for any Event field that cannot be returned. The value of the StatusCode shall be Bad_NoData.
If the requested TimestampsToReturn is not supported for a Node then the operation shall return the Bad_TimestampNotSupported StatusCode. When reading Events this only applies to Event fields that are of type DataValue.
Table 21 defines the ReadRawModifiedDetails structure. Two of the three parameters, numValuesPerNode, startTime, and endTime shall be specified.
Table 21 – ReadRawModifiedDetails
|
Name |
Type |
Description |
|
ReadRawModifiedDetails |
Structure |
Specifies the details used to perform a “raw” or “modified” history read. |
|
isReadModified |
Boolean |
TRUE for Read Modified functionality, FALSE for Read Raw functionality. Default value is FALSE. |
|
startTime |
UtcTime |
Beginning of period to read. Set to default value of DateTime.MinValue if no specific start time is specified. |
|
endTime |
UtcTime |
End of period to read. Set to default value of DateTime.MinValue if no specific end time is specified. |
|
numValuesPerNode |
Counter |
The maximum number of values returned for any Node over the time range. If only one time is specified, the time range shall extend to return this number of values. The default value 0 indicates that there is no maximum. |
|
returnBounds |
Boolean |
A Boolean parameter with the following values: TRUEBounding Values should be returned FALSEAll other cases |
When this structure is used for reading Raw Values (isReadModified is set to FALSE), it reads the values, qualities, and timestamps from the history database for the specified time domain for one or more HistoricalDataNodes . This parameter is intended for use by a Client that wants the actual data saved within the historian. The actual data may be compressed or may be all raw data collected for the item depending on the historian and the storage rules invoked when the item values were saved. When returnBounds is TRUE, the Bounding Values for the time domain are returned. The optional Bounding Values are provided to allow the Client to interpolate values for the start and end times when trending the actual data on a display.
The time domain of the request is defined by startTime, endTime, and numValuesPerNode; at least two of these shall be specified. If endTime is less than startTime, or endTime and numValuesPerNode alone are specified then the data will be returned in reverse order, with later data coming first as if time were flowing backward. If a startTime, endTime and numValuesPerNode are all provided and if more than numValuesPerNode values exist within that time range for a given Node then only numValuesPerNode values per Node shall be returned along with a continuationPoint. When a continuationPoint is returned, a Client wanting the next numValuesPerNode values shall call ReadRaw again with the continuationPoint set. If numValuesPerNode is 0, then all the values in the range are returned. A default value of DateTime.MinValue (see OPC 10000-6) is used to indicate when startTime or endTime is not specified.
It is specifically allowed for the startTime and the endTime to be identical. This allows the Client to request just one value. When the startTime and endTime are identical then time is presumed to be flowing forward. It is specifically not allowed for the Server to return a Bad_InvalidArgument StatusCode if the requested time domain is outside of the Server's range. Such a case shall be treated as an interval in which no data exists.
If the request takes a long time to process then the Server can return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Client timeout hint. It may take longer than the Client timeout hint to retrieve any results. In this case the Server may return zero results with a ContinuationPoint that allows the Server to resume the calculation on the next Client HistoryRead call.
If Bounding Values are requested and a non-zero numValuesPerNode was specified then any Bounding Values returned are included in the numValuesPerNode count. If numValuesPerNode is 1 then only the start bound is returned (the end bound if the reverse order is needed). If numValuesPerNode is 2 then the start bound and the first data point are returned (the end bound if reverse order is needed). When Bounding Values are requested and no bounding value is found then the corresponding StatusCode entry will be set to Bad_BoundNotFound, a timestamp equal to the start or end time as appropriate, and a value of null. How far back or forward to look in history for Bounding Values is Server dependent.
For an interval in which no data exists, if Bounding Values are not requested, then the corresponding StatusCode shall be Good_NoData. If Bounding Values are requested and one or both exist, then the result code returned is Success and the bounding value(s) are returned.
For cases where there are multiple values for a given timestamp, all but the most recent are considered to be Modified values and the Server shall return the most recent value. If the Server returns a value which hides other values at a timestamp then it shall set the ExtraData bit in the StatusCode associated with that value. If the Server contains additional information regarding a value then the ExtraData bit shall also be set. It indicates that ModifiedValues are available for retrieval, see 6.4.3.3.
If the requested TimestampsToReturn is not supported for a Node, the operation shall return the Bad_TimestampNotSupported StatusCode.
When this structure is used for reading Modified Values (isReadModified is set to TRUE), it reads the modified values, StatusCodes, timestamps, modification type, the user identifier, and the timestamp of the modification from the history database for the specified time domain for one or more HistoricalDataNodes . If there are multiple replaced values the Server shall return all of them. The updateType specifies what value is returned in the modification record. If the updateType is INSERT the value is the new value that was inserted. If the updateType is anything else the value is the old value that was changed. See 6.8 HistoryUpdateDetails parameter for details on what updateTypes are available.
The purpose of this function is to read values from history that have been Modified. The returnBounds parameter shall be set to FALSE for this case, otherwise the Server returns a Bad_InvalidArgument StatusCode.
The domain of the request is defined by startTime, endTime, and numValuesPerNode; at least two of these shall be specified. If endTime is less than startTime, or endTime and numValuesPerNode alone are specified, then the data shall be returned in reverse order with the later data coming first. If all three are specified then the call shall return up to numValuesPerNode results going from StartTime to EndTime, in either ascending or descending order depending on the relative values of StartTime and EndTime. If more than numValuesPerNode values exist within that time range for a given Node then only numValuesPerNode values per Node are returned along with a continuationPoint. When a continuationPoint is returned, a Client wanting the next numValuesPerNode values should call ReadRaw again with the continuationPoint set. If numValuesPerNode is 0 then all of the values in the range are returned. If the Server cannot return all modified values for a given timestamp in a single response then it shall return modified values with the same timestamp in subsequent calls.
If the request takes a long time to process then the Server can return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Client timeout hint. It may take longer than the Client timeout hint to retrieve any results. In this case the Server may return zero results with a ContinuationPoint that allows the Server to resume the calculation on the next Client HistoryRead call.
If a value has been modified multiple times then all values for the time are returned. This means that a timestamp can appear in the array more than once. The order of the returned values with the same timestamp should be from the most recent to oldest modification timestamp, if startTime is less than or equal to endTime. If endTime is less than startTime, then the order of the returned values will be from the oldest modification timestamp to the most recent. It is Server dependent whether multiple modifications are kept or only the most recent.
A Server does not have to create a modification record for data when it is first added to the historical collection. If it does then it shall set the ExtraData bit and the Client can read the modification record using a ReadModified call. If the data is subsequently modified the Server shall create a second modification record which is returned along with the original modification record whenever a Client uses the ReadModified call if the Server supports multiple modification records per timestamp.
If the requested TimestampsToReturn is not supported for a Node then the operation shall return the Bad_TimestampNotSupported StatusCode.
Table 22 defines the structure of the ReadProcessedDetails structure.
Table 22 – ReadProcessedDetails
|
Name |
Type |
Description |
|
ReadProcessedDetails |
Structure |
Specifies the details used to perform a “processed” history read. |
|
startTime |
UtcTime |
Beginning of period to read. |
|
endTime |
UtcTime |
End of period to read. |
|
ProcessingInterval |
Duration |
Interval between returned Aggregate values. The value 0 indicates that there is no ProcessingInterval defined. |
|
aggregateType[] |
NodeId |
The NodeId of the HistoryAggregate object that indicates the list of Aggregates to be used when retrieving the processed history. SeeOPC 10000-13 for details. |
|
aggregateConfiguration |
Aggregate Configuration |
Aggregate configuration structure. |
|
useServerCapabilitiesDefaults |
Boolean |
As described in OPC 10000-4. |
|
TreatUncertainAsBad |
Boolean |
As described in OPC 10000-13. |
|
PercentDataBad |
Byte |
As described in OPC 10000-13. |
|
PercentDataGood |
Byte |
As described in OPC 10000-13. |
|
UseSlopedExtrapolation |
Boolean |
As described in OPC 10000-13. |
SeeOPC 10000-13 for details on possible NodeId values for the aggregateType parameter.
This structure is used to compute Aggregate values, qualities, and timestamps from data in the history database for the specified time domain for one or more HistoricalDataNodes . The time domain is divided into intervals of duration ProcessingInterval. The specified Aggregate Type is calculated for each interval beginning with startTime by using the data within the next ProcessingInterval.
For example, this function can provide hourly statistics such as Maximum, Minimum, and Average for each item during the specified time domain when ProcessingInterva l is 1 hour.
The domain of the request is defined by startTime, endTime, and ProcessingInterval. All three shall be specified. If endTime is less than startTime then the data shall be returned in reverse order with the later data coming first. If startTime and endTime are the same then the Server shall return Bad_InvalidArgument as there is no meaningful way to interpret such a case. If the ProcessingInteval is specified as 0 then Aggregates shall be calculated using one interval starting at startTime and ending at endTime.
The aggregateType[] parameter allows a Client to request multiple Aggregate calculations per requested NodeId. If multiple Aggregates are requested then a corresponding number of entries are required in the NodesToRead array.
For example, to request Min Aggregate for NodeId FIC101, FIC102, and both Min and Max Aggregates for NodeId FIC103 would require NodeId FIC103 to appear twice in the NodesToRead array request parameter.
|
aggregateType[] |
NodesToRead[] |
|
Min |
FIC101 |
|
Min |
FIC102 |
|
Min |
FIC103 |
|
Max |
FIC103 |
If the array of Aggregates does not match the array of NodesToRead then the Server shall return a StatusCode of Bad_AggregateListMismatch.
The aggregateConfiguration parameter allows a Client to override the Aggregate configuration settings supplied by the AggregateConfiguration Object on a per call basis. SeeOPC 10000-13 for more information on Aggregate configurations. If the Server does not support the ability to override the Aggregate configuration settings then it shall return a StatusCode of Bad_ AggregateConfigurationRejected. If the Aggregate is not valid for the Node then the StatusCode shall be Bad_AggregateNotSupported.
The values used in computing the Aggregate for each interval shall include any value that falls exactly on the timestamp at the beginning of the interval, but shall not include any value that falls directly on the timestamp ending the interval. Thus, each value shall be included only once in the calculation. If the time domain is in reverse order then we consider the later timestamp to be the one beginning the subinterval, and the earlier timestamp to be the one ending it. Note that this means that simply swapping the start and end times will not result in getting the same values back in reverse order as the intervals being requested in the two cases are not the same.
If an Aggregate is taking a long time to calculate then the Server can return partial results with a continuation point. This might be done if the calculation is going to take more time than the Client timeout hint. In some cases it may take longer than the Client timeout hint to calculate even one Aggregate result. Then the Server may return zero results with a continuation point that allows the Server to resume the calculation on the next Client read call.
Refer toOPC 10000-13 for handling of Aggregate specific cases.
Table 23 defines the ReadAtTimeDetails structure.
|
Name |
Type |
Description |
|
ReadAtTimeDetails |
Structure |
Specifies the details used to perform an “at time” history read. |
|
reqTimes [] |
UtcTime |
The entries define the specific timestamps for which values are to be read. |
|
useSimpleBounds |
Boolean |
Use SimpleBounds to determine the value at the specific timestamp. |
The ReadAtTimeDetails structure reads the values and qualities from the history database for the specified timestamps for one or more HistoricalDataNodes . This function is intended to provide values to correlate with other values with a known timestamp. For example, a Client may need to read the values of sensors when lab samples were collected.
The order of the values and qualities returned shall match the order of the timestamps supplied in the request.
When no value exists for a specified timestamp, a value shall be Interpolated from the surrounding values to represent the value at the specified timestamp. The interpolation will follow the same rules as the standard Interpolated Aggregate as outlined inOPC 10000-13.
If the useSimpleBounds flag is True and Interpolation is required then simple bounding values will be used to calculate the data value. If useSimpleBounds is False and Interpolation is required then interpolated bounding values will be used to calculate the data value. SeeOPC 10000-13 for the definition of simple bounding values and interpolated bounding values.
If a value is found for the specified timestamp, then the Server will set the StatusCode InfoBits to be Raw. If the value is Interpolated from the surrounding values, then the Server will set the StatusCode InfoBits to be Interpolated.
If the read request is taking a long time to calculate then the Server may return zero results with a ContinuationPoint that allows the Server to resume the calculation on the next Client HistoryRead call.
If the requested TimestampsToReturn is not supported for a Node, then the operation shall return the Bad_TimestampNotSupported StatusCode.
Table 24 defines the ReadAnnotationDataDetails structure.
Table 24 – ReadAnnotaionDataDetails
|
Name |
Type |
Description |
|
ReadAnnotationDataDetails |
Structure |
Specifies the details used to perform an “at time” history read. |
|
reqTimes [] |
UtcTime |
The entries define the specific timestamps for which values are to be read. |
The ReadAnnotationDataDetails structure reads the Annotaion Data from the history database for the specified timestamps for one or more HistoricalDataNodes .
The order of the Annotations Data returned shall match the order of the timestamps supplied in the request.
If Annotation Data is not supported for a HistoricalDataNode then the StatusCode shall be Bad_HistoryOperationUnsupported.
If the read request is taking a long time to calculate then the Server may return zero results with a ContinuationPoint that allows the Server to resume the calculation on the next Client HistoryRead call.