The HistoryRead Servicedefined in OPC 10000-4can perform several different functions. The HistoryReadDetailsparameter is an Extensible Parameterthat specifies which function to perform and the details that are specific to that function. See OPC 10000-4for the definition of Extensible Parameter. Table 19lists the symbolic names of the valid Extensible Parameterstructures. 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 Serviceperforms using the Extensible Parameterstructure 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 Eventsfrom the history database by specifying a filter and a time domain for one or more Objects orViews. See 6.4.2.1.

When this parameter is specified the Serverreturns 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 Serverreturns a HistoryData structure for each operation (see 6.5.2).

ReadRawModifiedDetails

Read modified

This parameter selects a set of modified valuesfrom the history database by specifying a time domain for one or more Variables. See 6.4.3.1.

When this parameter is specified the Serverreturns a HistoryModifiedData structure for each operation (see 6.5.3).

ReadProcessedDetails

Read processed

This structure selects a set of Aggregatevalues 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 Serverreturns 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 Serverreturns a HistoryData structure for each operation (see Clause 6.5.2).

ReadAnnotationDataDetails

Read Annotation Data

This structure selects a set of Annotation Datafrom 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 Serverreturns a HistoryAnnotationData structure for each operation (see Clause 6.5.5).

Table 20defines the ReadEventDetailsstructure. This parameter is only valid for Objectsthat have the EventNotifier Attributeset to TRUE (see OPC 10000-3). Two of the three parameters, numValuesPerNode, startTime, and endTimeshall be specified.

Table 20– ReadEventDetails

Name

Type

Description

ReadEventDetails

Structure

Specifies the details used to perform an Eventhistory 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.MinValueindicates that the startTimeis Unspecified.

endTime

UtcTime

End of period to read. The default value of DateTime.MinValueindicates that the endTime is Unspecified.

Filter

EventFilter

A filter used by the Server to determine which HistoricalEventNodeshould be included. This parameter shall be specified and at least one EventFieldis required. The EventFilterparameter 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 EventFieldsthat are to be returned as part of the request.

The ReadEventDetailsstructure is used to read the Eventsfrom the history database for the specified time domain for one or more HistoricalEventNodes. The Eventsare filtered based on the filter structure provided. This filter includes the EventFieldsthat are to be returned. For a complete description of filter refer to OPC 10000-4.

The startTimeand endTimeare 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 endTimeis less than startTime, or endTimeand numValuesPerNodealone 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 startTimeto endTime, in either ascending or descending order depending on the relative values of startTimeand endTime. If numValuesPerNode is 0 then all of the values in the range are returned. The default value is used to indicate when startTime, endTimeor numValuesPerNodeare not specified.

It is specifically allowed for the startTimeand the endTimeto be identical. This allows the Clientto request the Eventat a single instance in time. When the startTimeand endTimeare identical then time is presumed to be flowing forward. If no data exists at the time specified then the Servershall return the Good_NoData StatusCode.

If a startTime, endTimeand numValuesPerNodeare all provided, and if more than numValuesPerNode Eventsexist within that time range for a given Node, then only numValuesPerNode Eventsper Nodeare returned along with a ContinuationPoint. When a ContinuationPointis returned, a Clientwanting the next numValuesPerNodevalues should call HistoryReadagain with the continuationPoint set.

If the request takes a long time to process then the Servercan return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Clienttimeout hint. It may take longer than the Clienttimeout hint to retrieve any results. In this case the Servermay return zero results with a ContinuationPointthat allows the Serverto resume the calculation on the next Client HistoryReadcall.

For an interval in which no data exists, the corresponding StatusCodeshall be Good_NoData.

The filter parameteris used to determine which historical Eventsand their corresponding fields are returned. It is possible that the fields of an EventTypeare available for real time updating, but not available from the historian. In this case a StatusCodevalue will be returned for any Eventfield that cannot be returned. The value of the StatusCodeshall be Bad_NoData.

If the requested TimestampsToReturnis not supported for a Nodethen the operation shall return the Bad_TimestampNotSupported StatusCode. When reading Eventsthis only applies to Eventfields that are of type DataValue.

Table 21defines the ReadRawModifiedDetailsstructure. Two of the three parameters, numValuesPerNode, startTime, and endTimeshall 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.MinValueif 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 RawValues (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 Clientthat 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 Clientto 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 endTimeand numValuesPerNodealone 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, endTimeand numValuesPerNodeare all provided and if more than numValuesPerNodevalues exist within that time range for a given Nodethen only numValuesPerNodevalues per Node shall be returned along with a continuationPoint. When a continuationPoint is returned, a Clientwanting the next numValuesPerNode values shall call ReadRaw again with the continuationPointset. If numValuesPerNodeis 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 startTimeor endTimeis not specified.

It is specifically allowed for the startTimeand the endTimeto be identical. This allows the Clientto request just one value. When the startTimeand endTimeare identical then time is presumed to be flowing forward. It is specifically not allowed for the Serverto return a Bad_InvalidArgumentStatusCodeif 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 Servercan return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Clienttimeout hint. It may take longer than the Clienttimeout hint to retrieve any results. In this case the Servermay return zero results with a ContinuationPointthat allows the Serverto resume the calculation on the next Client HistoryReadcall.

If Bounding Values are requested and a non-zero numValuesPerNodewas specified then any Bounding Values returned are included in the numValuesPerNodecount. If numValuesPerNodeis 1 then only the start bound is returned (the end bound if the reverse order is needed). If numValuesPerNodeis 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 StatusCodeentry 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 Serverdependent.

For an interval in which no data exists, if Bounding Values are not requested, then the corresponding StatusCodeshall 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 valuesand the Servershall return the most recent value. If the Serverreturns a value which hides other values at a timestamp then it shall set the ExtraDatabit in the StatusCodeassociated with that value. If the Servercontains 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 ModifiedValues (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 Servershall 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 HistoryUpdateDetailsparameter 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 Serverreturns 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 endTimeand numValuesPerNodealone 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 StartTimeand EndTime. If more than numValuesPerNodevalues exist within that time range for a given Node then only numValuesPerNodevalues per Node are returned along with a continuationPoint. When a continuationPoint is returned, a Clientwanting the next numValuesPerNodevalues should call ReadRawagain with the continuationPointset. If numValuesPerNodeis 0 then all of the values in the range are returned. If the Servercannot return all modified valuesfor 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 Servercan return partial results with a ContinuationPoint. This might be done if the request is going to take more time than the Clienttimeout hint. It may take longer than the Clienttimeout hint to retrieve any results. In this case the Servermay return zero results with a ContinuationPointthat allows the Serverto resume the calculation on the next Client HistoryReadcall.

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 startTimeis less than or equal to endTime. If endTimeis less than startTime, then the order of the returned values will be from the oldest modification timestamp to the most recent. It is Serverdependent whether multiple modifications are kept or only the most recent.

A Serverdoes 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 Clientcan read the modification record using a ReadModified call. If the data is subsequently modified the Servershall create a second modification record which is returned along with the original modification record whenever a Clientuses the ReadModified call if the Serversupports multiple modification records per timestamp.

If the requested TimestampsToReturn is not supported for a Nodethen the operation shall return the Bad_TimestampNotSupported StatusCode.

Table 22defines 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 Aggregatevalues. The value 0 indicates that there is no ProcessingIntervaldefined.

aggregateType[]

NodeId

The NodeId of the HistoryAggregate object that indicates the list of Aggregates to be used when retrieving the processed history. SeeOPC 10000-13for details.

aggregateConfiguration

Aggregate

Configuration

Aggregateconfiguration 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-13for details on possible NodeIdvalues for the aggregateTypeparameter.

This structure is used to compute Aggregatevalues, 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 intervalbeginning with startTimeby 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 ProcessingInterval is 1 hour.

The domain of the request is defined by startTime, endTime, and ProcessingInterval. All three shall be specified. If endTimeis less than startTimethen the data shall be returned in reverse order with the later data coming first. If startTimeand endTimeare the same then the Servershall return Bad_InvalidArgumentas there is no meaningful way to interpret such a case. If the ProcessingIntevalis specified as 0 then Aggregatesshall be calculated using one interval starting at startTimeand ending at endTime.

The aggregateType[] parameter allows a Clientto request multiple Aggregatecalculations per requested NodeId. If multiple Aggregatesare requested then a corresponding number of entries are required in the NodesToRead array.

For example, to request Min Aggregatefor NodeId FIC101, FIC102, and both Min and Max Aggregatesfor 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 Aggregatesdoes not match the array of NodesToReadthen the Servershall return a StatusCodeof Bad_AggregateListMismatch.

The aggregateConfiguration parameter allows a Clientto override the Aggregateconfiguration settings supplied by the AggregateConfiguration Objecton a per call basis. SeeOPC 10000-13for more information on Aggregateconfigurations. If the Serverdoes not support the ability to override the Aggregateconfiguration settings then it shall return a StatusCodeof Bad_ AggregateConfigurationRejected. If the Aggregateis not valid for the Nodethen the StatusCodeshall be Bad_AggregateNotSupported.

The values used in computing the Aggregatefor 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 intervalsbeing requested in the two cases are not the same.

If an Aggregateis taking a long time to calculate then the Servercan return partial results with a continuation point. This might be done if the calculation is going to take more time than the Clienttimeout hint. In some cases it may take longer than the Clienttimeout hint to calculate even one Aggregateresult. Then the Servermay return zero results with a continuation point that allows the Serverto resume the calculation on the next Clientread call.

Refer toOPC 10000-13for handling of Aggregatespecific cases.

Table 23defines the ReadAtTimeDetails structure.

Table 23– ReadAtTimeDetails

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 Clientmay 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 Interpolatedfrom the surrounding values to represent the value at the specified timestamp. The interpolation will follow the same rules as the standard Interpolated Aggregateas outlined inOPC 10000-13.

If the useSimpleBounds flag is True and Interpolation is required then simple bounding valueswill be used to calculate the data value. If useSimpleBounds is False and Interpolation is required then interpolated bounding valueswill be used to calculate the data value. SeeOPC 10000-13for the definition of simple bounding valuesand interpolated bounding values.

If a value is found for the specified timestamp, then the Serverwill set the StatusCode InfoBitsto be Raw. If the value is Interpolatedfrom the surrounding values, then the Serverwill set the StatusCode InfoBitsto be Interpolated.

If the read request is taking a long time to calculate then the Servermay return zero results with a ContinuationPointthat allows the Serverto resume the calculation on the next Client HistoryReadcall.

If the requested TimestampsToReturn is not supported for a Node, then the operation shall return the Bad_TimestampNotSupported StatusCode.

Table 24defines 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 Datareturned shall match the order of the timestamps supplied in the request.

If Annotation Datais not supported for a HistoricalDataNodethen the StatusCodeshall be Bad_HistoryOperationUnsupported.

If the read request is taking a long time to calculate then the Servermay return zero results with a ContinuationPointthat allows the Serverto resume the calculation on the next Client HistoryReadcall.