unsubscribeValues Function
The unsubscribeValues
method allows terminating any subscription to one or multiple properties in a Desigo CC system that were previously created by calling the subscribeValues method. On this purpose, the result of the subscribeValues
method invocation must be provided as parameter.
Syntax
It is possible to unsubscribe from the change of value of one or multiple properties of one or multiple system objects. See the following syntax.
unsubscribeValues(<subscribeResult>);
Parameters Usage
<subscribeResult>:
Object that is returned as result of asubscribeValues
call.
It may be necessary to keep this parameter in a global variable for other usage, for example in a callback.
Result
- If any errors occurred during the unsubscribe operation, the
unsubscribeValues
method returns the unsubscribeValuesResult object with the error property that indicates the reason why the operation failed.
Error Handling
Errors can occur in case:
- The call to the method
unsubscribeValues
is using a system object whose value is not yet defined, theunsubscribeValues
cannot be performed, or the SubscribeValuesResult contains a value of invalid type or null. The following message is traced in the Trace Viewer: Unsubscribe failed (the input object type is invalid).
Examples of Use
How to subscribe by passing the callback name and then unsubscribe in the callback if the new value is "stop"
var obj1 = new BrowserObject("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1");
var subscribeResult1 = subscribeValues(obj1, ["Value"], "onValueChanged");
console("Subscription1: {0}", subscribeResult1);
...
function onValueChanged(object, values) {
var newValue = values["Value"].Value;
console("Object = {0}; Value: {1}", object, newValue);
if (newValue === "stop") {
unsubscribeValues(subscribeResult1);
console("Unsubscribe executed");
}
}
At the end of the subscription, the output in the Console expander is:
"Subscription succeeded"
"Object = System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1; Value: My Text1"
At any change of the property Value of the monitored object, the output in the Console expander is:
"Object = System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1; Value: My Text2"
As soon as Text1.Value is equal to stop
, unsubscribeValues
is called, and the output in the Console expander is:
"Unsubscribe executed"
Note that the result of the subscription is stored in the subscribeResult1
global variable. The subscription was made with the execution of the callback function on the Initial Value.
How to perform two subscriptions referring the same function as callback
var obj1 = new BrowserObject("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1");
var subscribeResult1 = subscribeValues(obj1, "Value", "onValueChanged");
console("Subscription1: {0}", subscribeResult1);
var obj2 = new BrowserObject("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text2");
var obj3 = new BrowserObject("System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_2.Text3");
var subscribeResult2 = subscribeValues([obj2, obj3], ["Value"], onValueChanged, false);
console("Subscription2: {0}", subscribeResult2);
}
...
function onValueChanged(object, values) {
var newValue = values["Value"].Value;
console("Object = {0}; Value: {1}", object, newValue);
if (newValue === "stop1") {
unsubscribeValues(subscribeResult1);
} else if (newValue === "stop2") {
unsubscribeValues(subscribeResult2);
}
}
The first subscription was made on a single object using the string containing the callback name ("onValueChanged"
).
The second subscription was made on multiple objects using the function name as callback (onValueChanged
).
The unsubscription was made within the callback:
- From the first subscription if the notified value is "stop1"
- From the second subscription if the notified value is "stop2"
At the end of the subscription, the output in the Console expander is:
"Subscription1 succeeded"
"Subscription2 succeeded"
"Object = System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1; Value: My Text1"
At any change of the property Value of the object obj1
, the output in the Console expander is:
"System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text1; Value: My New Text1"
At any change of the property Value of the objects obj2
and obj3
, the output in the Console expander is:
"System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_1.Text2"; Value: My New Text2"
"System1.ManagementView:ManagementView.FieldNetworks.MyOPCNet.Server_Matrikon.Group_2.Text3; Value: My New Text3"
The value changes continue until:
- The notified value is equal to
"stop1",
for the subscription onobj1
- The notified value is equal to
"stop2",
for the subscription onobj2
andobj3
Note that the results of the subscriptions are stored into two global variables: subscribeResult1
and subscribeResult2
. The first subscription was made by executing the callback function on the Initial Value. Both the subscriptions refer to the same callback function: one passed as object and the other passed as string. Note also that, the callback function checks on two different values (stop1
and stop2
) for the different unsubscribe actions.