This Service is used to create and add one or more MonitoredItems to a Subscription. A MonitoredItem is deleted automatically by the Server when the Subscription is deleted. Deleting a MonitoredItem causes its entire set of triggered item links to be deleted, but has no effect on the MonitoredItems referenced by the triggered items.
Calling the CreateMonitoredItems Service repetitively to add a small number of MonitoredItems each time may adversely affect the performance of the Server. Instead, Clients should add a complete set of MonitoredItems to a Subscription whenever possible.
When a MonitoredItem is added, the Server performs initialization processing for it. The initialization processing is defined by the Notification type of the item being monitored. Notification types are specified in this document and in the Access Type Specification parts of OPC 10000, such as OPC 10000-8. See OPC 10000-1 for a description of the Access Type Parts. Clients may receive Notifications for added MonitoredItems before the CreateMonitoredItems Response is received. Clients set the ClientHandle for the MonitoredItem in the CreateMonitoredItems Request and are therefore able to process the Notifications received before the CreateMonitoredItems Response is received.
When a user adds a monitored item that the user is denied read access to, the add operation for the item shall succeed and the bad status Bad_NotReadable or Bad_UserAccessDenied shall be returned in the Publish response. This is the same behaviour for the case where the access rights are changed after the call to CreateMonitoredItems. If the access rights change to read rights, the Server shall start sending data for the MonitoredItem. The same procedure shall be applied for an IndexRange that does not deliver data for the current value but could deliver data in the future. Servers should return all other errors as CreateMonitoredItems results but all possible errors are allowed to be returned in the Publish response.
Monitored Nodes can be removed from the AddressSpace after the creation of a MonitoredItem. This does not affect the validity of the MonitoredItem but a Bad_NodeIdUnknown shall be returned in the Publish response. It is possible that the MonitoredItem becomes valid again if the Node is added again to the AddressSpace and the MonitoredItem still exists.
If a NodeId is known to be valid by a Server but the corresponding Node Attributes are currently not available, the Server may allow the creation of a MonitoredItem and return an appropriate Bad StatusCode in the Publish response.
The return diagnostic info setting in the request header of the CreateMonitoredItems or the last ModifyMonitoredItems Service is applied to the Monitored Items and is used as the diagnostic information settings when sending Notifications in the Publish response.
Illegal request values for parameters that can be revised do not generate errors. Instead the Server will choose default values and indicate them in the corresponding revised parameter.
It is strongly recommended by OPC UA that a Client reuses a Subscription after a short network interruption by activating the existing Session on a new SecureChannel as described in 6.7. If a Client called CreateMonitoredItems during the network interruption and the call succeeded in the Server but did not return to the Client, then the Client does not know if the call succeeded. The Client may receive data changes for these monitored items but is not able to remove them since it does not know the Server handle for each monitored item. There is also no way for the Client to detect if the create succeeded. To delete and recreate the Subscription is also not an option since there may be several monitored items operating normally that should not be interrupted. To resolve this situation, the Server Object provides a Method GetMonitoredItems that returns the list of Server and client handles for the monitored items in a Subscription. This Method is defined in OPC 10000-5. The Server shall verify that the Method is called within the Session context of the Session that owns the Subscription.
Table 69 defines the parameters for the Service.
Table 69 – CreateMonitoredItems Service Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 for RequestHeader definition). |
|
subscriptionId |
IntegerId |
The Server-assigned identifier for the Subscription that will report Notifications for this MonitoredItem (see 7.19 for IntegerId definition). |
|
timestampsToReturn |
Enum Timestamps ToReturn |
An enumeration that specifies the timestamp Attributes to be transmitted for each MonitoredItem. The TimestampsToReturn enumeration is defined in 7.40. When monitoring Events, this applies only to Event fields that are of type DataValue. |
|
itemsToCreate [] |
MonitoredItem CreateRequest |
A list of MonitoredItems to be created and assigned to the specified Subscription. This structure is defined in-line with the following indented items. |
|
itemToMonitor |
ReadValueId |
Identifies an item in the AddressSpace to monitor. To monitor for Events, the attributeId element of the ReadValueId structure is the id of the EventNotifier Attribute. The ReadValueId type is defined in 7.29. |
|
monitoringMode |
Enum MonitoringMode |
The monitoring mode to be set for the MonitoredItem. The MonitoringMode enumeration is defined in 7.23. |
|
requestedParameters |
Monitoring Parameters |
The requested monitoring parameters. Servers negotiate the values of these parameters based on the Subscription and the capabilities of the Server. The MonitoringParameters type is defined in 7.21. |
|
|
|
|
|
Response |
|
|
|
responseHeader |
Response Header |
Common response parameters (see 7.34 for ResponseHeader definition). |
|
results [] |
MonitoredItem CreateResult |
List of results for the MonitoredItems to create. The size and order of the list matches the size and order of the itemsToCreate request parameter. This structure is defined in-line with the following indented items. |
|
statusCode |
StatusCode |
StatusCode for the MonitoredItem to create (see 7.39 for StatusCode definition). |
|
monitoredItemId |
IntegerId |
Server-assigned id for the MonitoredItem (see 7.19 for IntegerId definition). This id is unique within the Subscription, but might not be unique within the Server or Session. This parameter is present only if the statusCode indicates that the MonitoredItem was successfully created. |
|
revisedSampling Interval |
Duration |
The actual sampling interval that the Server will use. This value is based on a number of factors, including capabilities of the underlying system. The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval. If the requested samplingInterval is higher than the maximum sampling interval supported by the Server, the maximum sampling interval is returned. |
|
revisedQueueSize |
Counter |
The actual queue size that the Server will use. |
|
filterResult |
Extensible Parameter MonitoringFilterResult |
Contains any revised parameter values or error results associated with the MonitoringFilter specified in requestedParameters. This parameter may be null if no errors occurred. The MonitoringFilterResult parameter type is an extensible parameter type specified in 7.22. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the MonitoredItems to create (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the itemsToCreate 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 70 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 70 – CreateMonitoredItems 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_SubscriptionIdInvalid |
See Table 182 for the description of this result code. |
Table 71 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.
Table 71 – CreateMonitoredItems Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_MonitoringModeInvalid |
See Table 183 for the description of this result code. |
|
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. If the ArrayDimensions have a fixed length that cannot change and no data exists within the range of indexes specified, Bad_IndexRangeNoData is returned in CreateMonitoredItems. Otherwise if the length of the array is dynamic, the Server shall return this status in a Publish response for the MonitoredItem if no data exists within the range. |
|
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_MonitoredItemFilterInvalid |
See Table 183 for the description of this result code. |
|
Bad_MonitoredItemFilterUnsupported |
See Table 183 for the description of this result code. |
|
Bad_FilterNotAllowed |
See Table 183 for the description of this result code. |
|
Bad_TooManyMonitoredItems |
The Server has reached its maximum number of monitored items. |