This Service Set provides Services to access Attributes that are part of Nodes.
This Service is used to read one or more Attributes 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.
The maxAge parameter is used to direct the Server to access the value from the underlying data source, such as a device, if its copy of the data is older than that which the maxAge specifies. If the Server cannot meet the requested maximum age, it returns its “best effort” value rather than rejecting the request.
Table 53 defines the parameters for the Service.
Table 53 – Read Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 for RequestHeader definition). |
|
maxAge |
Duration |
Maximum age of the value to be read in milliseconds. The age of the value is based on the difference between the ServerTimestamp and the time when the Server starts processing the request. For example if the Client specifies a maxAge of 500 milliseconds and it takes 100 milliseconds until the Server starts processing the request, the age of the returned value could be 600 milliseconds prior to the time it was requested. If the Server has one or more values of an Attribute that are within the maximum age, it can return any one of the values or it can read a new value from the data source. The number of values of an Attribute that a Server has depends on the number of MonitoredItems that are defined for the Attribute. In any case, the Client can make no assumption about which copy of the data will be returned. If the Server does not have a value that is within the maximum age, it shall attempt to read a new value from the data source. If the Server cannot meet the requested maxAge, it returns its “best effort” value rather than rejecting the request. This may occur when the time it takes the Server to process and return the new data value after it has been accessed is greater than the specified maximum age. If maxAge is set to 0, the Server shall attempt to read a new value from the data source. If maxAge is set to the max Int32 value or greater, the Server shall attempt to get a cached value. Negative values are invalid for maxAge. |
|
timestampsTo Return |
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.40. |
|
nodesToRead [] |
ReadValueId |
List of Nodes and their Attributes to read. For each entry in this list, a StatusCode is returned, and if it indicates success, the Attribute Value is also returned. The ReadValueId parameter type is defined in 7.29. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.34 for ResponseHeader definition). |
|
results [] |
DataValue |
List of Attribute values (see 7.11 for DataValue definition). The size and order of this 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. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information (see 7.12 for DiagnosticInfo definition). The size and order of this 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. |
Table 54 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 54 – Read Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 182 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 182 for the description of this result code. |
|
Bad_MaxAgeInvalid |
The max age parameter is invalid. |
|
Bad_TimestampsToReturnInvalid |
See Table 182 for the description of this result code. |
Table 55 defines values for the operation level statusCode contained in the DataValue structure of each results element. Common StatusCodes are defined in Table 183.
Table 55 – Read Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NodeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. |
|
Bad_AttributeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeNoData |
See Table 183 for the description of this result code. |
|
Bad_DataEncodingInvalid |
See Table 183 for the description of this result code. |
|
Bad_DataEncodingUnsupported |
See Table 183 for the description of this result code. |
|
Bad_NotReadable |
See Table 183 for the description of this result code. |
|
Bad_UserAccessDenied |
See Table 182 for the description of this result code. |
|
Bad_SecurityModeInsufficient |
See Table 183 for the description of this result code. |
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.
Table 56 defines the parameters for the Service.
Table 56 – HistoryRead Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 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.17. |
|
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.40. Specifying a TimestampsToReturn of NEITHER is not valid. A Server shall return a Bad_TimestampsToReturnInvalid 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: TRUEpassed continuationPoints shall be reset to free resources in the Server. FALSEpassed 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.27. This parameter is null or empty if the value is not an array. However, if the value is an array, and this parameter is null or empty, 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.29 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 specify 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 or empty value indicates that this parameter is not used. See 7.9 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.34 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.39 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 or empty. 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.17. |
|
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. |
Table 57 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 57 – HistoryRead Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 182 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 182 for the description of this result code. |
|
Bad_TimestampsToReturnInvalid |
See Table 182 for the description of this result code. |
|
Bad_HistoryOperationInvalid |
See Table 183 for the description of this result code. |
|
Bad_HistoryOperationUnsupported |
See Table 183 for the description of this result code. The requested history operation is not supported by the Server. |
Table 58 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183. History access specific StatusCodes are defined in OPC 10000-11.
Table 58 – HistoryRead Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NodeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. |
|
Bad_DataEncodingInvalid |
See Table 183 for the description of this result code. |
|
Bad_DataEncodingUnsupported |
See Table 183 for the description of this result code. |
|
Bad_UserAccessDenied |
See Table 182 for the description of this result code. |
|
Bad_ContinuationPointInvalid |
See Table 182 for the description of this result code. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeNoData |
See Table 183 for the description of this result code. |
|
Bad_HistoryOperationUnsupported |
See Table 183 for the description of this result code. The requested history operation is not supported for the requested node. |
|
Bad_NoContinuationPoints |
See Table 183 for the description of this result code. See 7.9 for the rules to apply this status code. |
This Service is used to write values to one or more Attributes of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to write the entire set of indexed values as a composite, to write individual elements or to write ranges of elements of the composite.
The values are written to the data source, such as a device, and the Service does not return until it writes the values or determines that the value cannot be written. In certain cases, the Server will successfully write to an intermediate system or Server, and will not know if the data source was updated properly. In these cases, the Server should report a success code that indicates that the write was not verified. In the cases where the Server is able to verify that it has successfully written to the data source, it reports an unconditional success.
The order the operations are processed in the Server is not defined and depends on the different data sources and the internal Server logic. If an Attribute and Node combination is contained in more than one operation, the order of the processing is undefined. If a Client requires sequential processing the Client needs separate Service calls.
It is possible that the Server may successfully write some Attributes, but not others. Rollback is the responsibility of the Client.
If a Server allows writing of Attributes with the DataType LocalizedText, the Client can add or overwrite the text for a locale by writing the text with the associated LocaleId. Writing a null String for the text for a locale shall delete the String for that locale. Writing a null String for the locale and a non-null String for the text is setting the text for an invariant locale. Writing a null String for the text and a null String for the locale shall delete the entries for all locales. If a Client attempts to write a locale that is either syntactically invalid or not supported, the Server returns Bad_LocaleNotSupported. The Write behaviour for Value Attributes with a LocalizedText DataType is Server specific but it is recommended to follow the same rules.
Table 59 defines the parameters for the Service.
Table 59 – Write Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 for RequestHeader definition). |
|
nodesToWrite [] |
WriteValue |
List of Nodes and their Attributes to write. This structure is defined in-line with the following indented items. |
|
nodeId |
NodeId |
NodeId of the Node that contains the Attributes. |
|
attributeId |
IntegerId |
Id of the Attribute. This shall be a valid Attribute id. The IntegerId is defined in 7.19. The IntegerIds for the Attributes are defined in OPC 10000-6. |
|
indexRange |
NumericRange |
This parameter is used to identify a single element of an array, or a single range of indexes for arrays. The array in this context includes String and ByteString. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27. This parameter is not used if the specified Attribute is not an array. However, if the specified Attribute is an array and this parameter is not used, then all elements are to be included in the range. The parameter is null or empty if not used. A Server shall return a Bad_WriteNotSupported error if an indexRange is provided and writing of indexRange is not possible for the Node. |
|
value |
DataValue |
The Node’s Attribute value (see 7.11 for DataValue definition). If the indexRange parameter is specified then the Value shall be an array even if only one element is being written. If the SourceTimestamp or the ServerTimestamp is specified, the Server shall use these values. The Server returns a Bad_WriteNotSupported error if it does not support writing of timestamps. A Server shall return a Bad_TypeMismatch error if the data type of the written value is not the same type or subtype of the Attribute’s DataType. Based on the DataType hierarchy, subtypes of the Attribute DataType shall be accepted by the Server. Servers may reject subtypes defined in newer specification versions than supported by the Server with Bad_TypeMismatch. For the Value Attribute the DataType is defined through the DataType Attribute. A ByteString is structurally the same as a one dimensional array of Byte. A Server shall accept a ByteString if an array of Byte is expected. The Server returns a Bad_DataEncodingUnsupported error if it does not support the provided data encoding. Simple DataTypes (see OPC 10000-3) use the same representation on the wire as their super types and therefore writing a value of a simple DataType cannot be distinguished from writing a value of its super type. The Server shall assume that by receiving the correct wire representation for a simple DataType the correct type was chosen. Servers are allowed to impose additional data validations on the value independent of the encoding (e.g. having an image in GIF format in a ByteString). In this case the Server shall return a Bad_TypeMismatch error if the validation fails. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.34 for ResponseHeader definition). |
|
results [] |
StatusCode |
List of results for the Nodes to write (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the nodesToWrite request parameter. There is one entry in this list for each Node contained in the nodesToWrite parameter. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the Nodes to write (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToWrite request 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. |
Table 60 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 60 – Write Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 182 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 182 for the description of this result code. |
Table 61 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.
Table 61 – Write Operation Level Result Codes
|
Symbolic Id |
Description |
|
Good_CompletesAsynchronously |
See Table 182 for the description of this result code. The value was successfully written to an intermediate system but the Server does not know if the data source was updated properly. |
|
Bad_NodeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. |
|
Bad_AttributeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. It is also used if writing of IndexRange is supported in general for a Node but the passed IndexRange cannot be written by the Server. |
|
Bad_IndexRangeNoData |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeDataMismatch |
The data to be written does not match the IndexRange. |
|
Bad_WriteNotSupported |
The requested write operation is not supported. If a Client attempts to write any value, status code, timestamp combination and the Server does not support the requested combination (which could be a single quantity such as just timestamp); than the Server shall not perform any write on this Node and shall return this StatusCode for this Node. It is also used if writing of IndexRanges is not supported for a Node. |
|
Bad_NotWritable |
See Table 183 for the description of this result code. |
|
Bad_UserAccessDenied |
See Table 182 for the description of this result code. The current user does not have permission to write the attribute. |
|
Bad_OutOfRange |
See Table 183 for the description of this result code. If a Client attempts to write a value outside the valid range like a value not contained in the enumeration data type of the Node, the Server shall return this StatusCode for this Node. This result code can be returned for any value that has the right DataType but does not comply with the restrictions defined by the Server implementation e.g. if a written String contains unsupported characters. |
|
Bad_TypeMismatch |
See Table 183 for the description of this result code. |
|
Bad_DataEncodingUnsupported |
See Table 183 for the description of this result code. |
|
Bad_NoCommunication |
See Table 183 for the description of this result code. |
|
Bad_LocaleNotSupported |
The locale in the requested write operation is not supported. |
This Service is used to update historical values or Events of one or more Nodes. Several request parameters indicate how the Server is to update the historical value or Event. Valid actions are Insert, Replace or Delete.
Table 62 defines the parameters for the Service.
Table 62 – HistoryUpdate Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 for RequestHeader definition). |
|
historyUpdateDetails [] |
Extensible Parameter HistoryUpdate Details |
The details defined for this update. The HistoryUpdateDetails parameter type is an extensible parameter type formally defined in OPC 10000-11. It specifies the types of history updates that can be performed. The ExtensibleParameter type is defined in 7.17. |
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.34 for ResponseHeader definition). |
|
results [] |
HistoryUpdate Result |
List of update results for the history update details. The size and order of the list matches the size and order of the details element of the historyUpdateDetails parameter specified in the request. This structure is defined in-line with the following indented items. |
|
statusCode |
StatusCode |
StatusCode for the update of the Node (see 7.39 for StatusCode definition). |
|
operationResults [] |
StatusCode |
List of StatusCodes for the operations to be performed on a Node. The size and order of the list matches the size and order of any list defined by the details element being reported by this result entry. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the operations to be performed on a Node (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of any list defined by the details element being reported by this results entry. 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. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the history update details. The size and order of the list matches the size and order of the details element of the historyUpdateDetails parameter specified in the request. 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. |
Table 63 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 63 – HistoryUpdate Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 182 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 182 for the description of this result code. |
Table 64 defines values for the statusCode and operationResults parameters that are specific to this Service. Common StatusCodes are defined in Table 183. History access specific StatusCodes are defined in OPC 10000-11.
Table 64 – HistoryUpdate Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NotWritable |
See Table 183 for the description of this result code. |
|
Bad_HistoryOperationInvalid |
See Table 183 for the description of this result code. |
|
Bad_HistoryOperationUnsupported |
See Table 183 for the description of this result code. |
|
Bad_UserAccessDenied |
See Table 182 for the description of this result code. The current user does not have permission to update the history. |