5 Service Sets ToC Previous Next

5.10 Attribute Service Set ToC Previous Next

5.10.3 HistoryRead ToC Previous Next

5.10.3.1 Description ToC

This Service is used to read historical values or Events of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to read the entire set of indexed values as a composite, to read individual elements or to read ranges of elements of the composite. Servers may make historical values available to Clients using this Service, although the historical values themselves are not visible in the AddressSpace.

The AccessLevel Attribute defined in OPC 10000-3 indicates a Node’s support for historical values. Several request parameters indicate how the Server is to access values from the underlying history data source. The EventNotifier Attribute defined in OPC 10000-3 indicates a Node’s support for historical Events.

The continuationPoint parameter in the HistoryRead is used to mark a point from which to continue the read if not all values could be returned in one response. The value is opaque for the Client and is only used to maintain the state information for the Server to continue from. A Server may use the timestamp of the last returned data item if the timestamp is unique. This can reduce the need in the Server to store state information for the continuation point.

In some cases it may take longer than the Client timeout hint to read the data for all nodes to read. Then the Server may return zero results with a continuation point for the affected nodes before the timeout expires. That allows the Server to resume the data acquisition on the next Client read call.

For additional details on reading historical data and historical Events see OPC 10000-11.

5.10.3.2 Parameters ToC

Table 56 defines the parameters for the Service.

Table 56 – HistoryRead Service Parameters

Name Type Description
Request    
   requestHeader RequestHeader Common request parameters (see 7.28 for RequestHeader definition).
   historyReadDetails Extensible Parameter
HistoryReadDetails
The details define the types of history reads that can be performed. The HistoryReadDetails parameter type is an extensible parameter type formally defined in OPC 10000-11. The ExtensibleParameter type is defined in 7.12.
   timestampsToReturn Enum
TimestampsTo Return
An enumeration that specifies the timestamps to be returned for each requested Variable Value Attribute. The TimestampsToReturn enumeration is defined in 7.35.
Specifying a TimestampsToReturn of NEITHER is not valid. A Server shall return a Bad_InvalidTimestampArgument StatusCode in this case.
OPC 10000-11 defines exceptions where this parameter shall be ignored.
   releaseContinuation
   Points
Boolean A Boolean parameter with the following values:
   TRUE passed continuationPoints shall be reset to free resources in the Server.
   FALSE passed continuationPoints shall be used to get the next set of historical information.
A Client shall always use the continuation point returned by a HistoryRead response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of historical information, HistoryRead shall be called with this parameter set to TRUE.
   nodesToRead [] HistoryReadValueId This parameter contains the list of items upon which the historical retrieval is to be performed. This structure is defined in-line with the following indented items.
      nodeId NodeId If the HistoryReadDetails is RAW, PROCESSED, MODIFIED or ATTIME:
The nodeId of the Nodes whose historical values are to be read. The value returned shall always include a timestamp.
If the HistoryReadDetails is EVENTS:
The NodeId of the Node whose Event history is to be read.
If the Node does not support the requested access for historical values or historical Events the appropriate error response for the given Node shall be generated.
      indexRange NumericRange This parameter is used to identify a single element of an array, or a single range of indexes for arrays. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.22.
This parameter is null if the value is not an array. However, if the value is an array, and this parameter is null, then all elements are to be included in the range.
      dataEncoding QualifiedName A QualifiedName that specifies the data encoding to be returned for the Value to be read (see 7.24 for definition how to specify the data encoding).
This parameter only applies if the DataType of the Variable is a subtype of Structure. It is an error to specific this parameter if the DataType of the Variable is not a subtype of Structure.
The parameter is ignored when reading history of Events.
      continuationPoint ContinuationPoint For each NodesToRead item this parameter specifies a continuation point returned from a previous HistoryRead call, allowing the Client to continue that read from the last value received.
The HistoryRead is used to select an ordered sequence of historical values or events. A continuation point marks a point in that ordered sequence, such that the Server returns the subset of the sequence that follows that point.
A null value indicates that this parameter is not used.
See 7.6 for a general description of continuation points.
This continuation point is described in more detail in OPC 10000-11.
Response    
   responseHeader ResponseHeader Common response parameters (see 7.29 for ResponseHeader type).
   results [] HistoryReadResult List of read results. The size and order of the list matches the size and order of the nodesToRead request parameter. This structure is defined in-line with the following indented items.
      statusCode StatusCode StatusCode   for the NodesToRead item (see 7.34 for StatusCode definition).
      continuationPoint ContinuationPoint This parameter is used only if the number of values to be returned is too large to be returned in a single response or if the timeout provided as hint by the Client is close to expiring and not all nodes have been processed.
When this parameter is not used, its value is null.
Servers   shall support at least one continuation point per Session. Servers specify a max history continuation points per Session in the Server capabilities Object defined in OPC 10000-5. A continuation point shall remain active until the Client passes the continuation point to HistoryRead or the Session is closed. If the max continuation points have been reached the oldest continuation point shall be reset.
      historyData Extensible Parameter
HistoryData
The history data returned for the Node.
The HistoryData parameter type is an extensible parameter type formally defined in OPC 10000-11. It specifies the types of history data that can be returned. The ExtensibleParameter base type is defined in 7.12.
   diagnosticInfos [] Diagnostic Info List of diagnostic information. The size and order of the list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the request.

5.10.3.3 Service results ToC

Table 57 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 57 – HistoryRead Service Result Codes

Symbolic Id Description
Bad_NothingToDo See Table 177 for the description of this result code.
Bad_TooManyOperations See Table 177 for the description of this result code.
Bad_TimestampsToReturnInvalid See Table 177 for the description of this result code.
Bad_HistoryOperationInvalid See Table 178 for the description of this result code.
Bad_HistoryOperationUnsupported See Table 178 for the description of this result code.
The requested history operation is not supported by the server.

5.10.3.4 StatusCodes ToC

Table 58 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 178. History access specific StatusCodes are defined in OPC 10000-11.

Table 58 – HistoryRead Operation Level Result Codes

Symbolic Id Description
Bad_NodeIdInvalid See Table 178 for the description of this result code.
Bad_NodeIdUnknown See Table 178 for the description of this result code.
Bad_DataEncodingInvalid See Table 178 for the description of this result code.
Bad_DataEncodingUnsupported See Table 178 for the description of this result code.
Bad_UserAccessDenied See Table 177 for the description of this result code.
Bad_ContinuationPointInvalid See Table 177 for the description of this result code.
Bad_InvalidTimestampArgument The defined timestamp to return was invalid.
Bad_HistoryOperationUnsupported See Table 178 for the description of this result code.
The requested history operation is not supported for the requested node.
Bad_NoContinuationPoints See Table 178 for the description of this result code.
See 7.6 for the rules to apply this status code.

Previous Next