6 Historical Access specific usage of Services ToC Previous Next

6.4 HistoryReadDetails parameters ToC Previous Next

6.4.2 ReadEventDetails structure ToC Previous Next

6.4.2.1 ReadEventDetails structure details ToC

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.

Table 20 – ReadEventDetails

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.

6.4.2.2 Read Event functionality ToC

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 continuationPoint 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.

Previous Next