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.