OPC Studio User's Guide and Reference
UADataSetSubscriptionDescriptor Class
'Declaration<ComDefaultInterfaceAttribute(OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor)> <ComVisibleAttribute(True)> <GuidAttribute("377752BF-B7E1-48BC-ABD3-F3E652C673C5")> <TypeConverterAttribute(OpcLabs.EasyOpc.UA.PubSub.Implementation.UADataSetSubscriptionDescriptorConverter)> <ValueControlAttribute("OpcLabs.EasyOpc.UA.Forms.Internal.PubSub.UADataSetSubscriptionDescriptorPhysicalControl, OpcLabs.EasyOpcForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=True, PageId=200)> <CLSCompliantAttribute(True)> <SerializableAttribute()> Public NotInheritable Class UADataSetSubscriptionDescriptor Inherits OpcLabs.BaseLib.Info Implements LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.Aliasing.ComTypes._Aliasable, OpcLabs.BaseLib.Aliasing.IAliasable, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor, System.ICloneable, System.IFormattable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
'UsageDim instance As UADataSetSubscriptionDescriptor
[ComDefaultInterface(OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor)] [ComVisible(true)] [Guid("377752BF-B7E1-48BC-ABD3-F3E652C673C5")] [TypeConverter(OpcLabs.EasyOpc.UA.PubSub.Implementation.UADataSetSubscriptionDescriptorConverter)] [ValueControl("OpcLabs.EasyOpc.UA.Forms.Internal.PubSub.UADataSetSubscriptionDescriptorPhysicalControl, OpcLabs.EasyOpcForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=true, PageId=200)] [CLSCompliant(true)] [Serializable()] public sealed class UADataSetSubscriptionDescriptor : OpcLabs.BaseLib.Info, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.Aliasing.ComTypes._Aliasable, OpcLabs.BaseLib.Aliasing.IAliasable, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor, System.ICloneable, System.IFormattable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
[ComDefaultInterface(OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor)] [ComVisible(true)] [Guid("377752BF-B7E1-48BC-ABD3-F3E652C673C5")] [TypeConverter(OpcLabs.EasyOpc.UA.PubSub.Implementation.UADataSetSubscriptionDescriptorConverter)] [ValueControl("OpcLabs.EasyOpc.UA.Forms.Internal.PubSub.UADataSetSubscriptionDescriptorPhysicalControl, OpcLabs.EasyOpcForms, Version=5.80.82.1, Culture=neutral, PublicKeyToken=6faddca41dacb409", Export=true, PageId=200)] [CLSCompliant(true)] [Serializable()] public ref class UADataSetSubscriptionDescriptor sealed : public OpcLabs.BaseLib.Info, LINQPad.ICustomMemberProvider, OpcLabs.BaseLib.Aliasing.ComTypes._Aliasable, OpcLabs.BaseLib.Aliasing.IAliasable, OpcLabs.BaseLib.ComTypes._Info, OpcLabs.BaseLib.ComTypes._Object2, OpcLabs.EasyOpc.UA.PubSub.ComTypes._UADataSetSubscriptionDescriptor, System.ICloneable, System.IFormattable, System.Runtime.Serialization.ISerializable, System.Xml.Serialization.IXmlSerializable
If you are on Windows, you can also use the OPC UA PubSub Demo Application to experiment with various settings. This allows you to try out and determine the correct parameters before you put them into the code.
A subscription is initiated by calling the SubscribeDataSet Method on the EasyUASubscriber Class. In its basic form, the method takes a single argument which is an instance of the EasyUASubscribeDataSetArguments Class, and this argument contains all the information necessary to perform the subscription. The object and all the sub-objects it contains are rather complex.
The picture below is meant to give you at least a general overview about what this object contains. There are more "smaller" properties to the individual objects on the picture, but we do not care about them for now.
The main parts of the EasyUASubscribeDataSetArguments is the DataSetSubscriptionDescriptor: it describes the dataset(s) you want to subscribe to.
The ResolverDescriptor in the DataSetSubscriptionDescriptor is for OPC UA PubSub logical resolution, if used.
Inside the dataset subscription descriptor, you always need to specify the PubSub connection, using the ConnectionDescriptor Property. You will typically also need to fill in data in the Filter Property (see Message Filtering (OPC UA PubSub)), and sometimes provide the DataSetMetaData Property (see Dataset Metadata (OPC UA PubSub)). The CommunicationParameters Property is used to specify details about the communication, message receive timeout, and parameters specific to message or transport protocol mapping.
There are many (extension method) overloads of the SubscribeDataSet Method, with various combinations of arguments. These overloads allow you to bypass the construction of the whole EasyUASubscribeDataSetArguments hierarchy, and pass in simply the parts you need.
The example below subscribes to all dataset messages on an OPC-UA PubSub connection with UDP UADP mapping. The connection is specified by its physical parameters, using the scheme name "opc.udp" and the IP address of the multicast group to listen on.
The example specifies just the PubSub connection, and receives all PubSub messages it encounters. In .NET, it illustrates the use of a SubscribeDataSet Method overload that takes just the PubSub connection descriptor as an input.
The information you pass in to the SubscribeDataSet Method may either be used "as is", or it may be subject to OPC UA PubSub logical resolution first. As explained in OPC UA PubSub Descriptors, you can pass in the physical identifiers, the logical identifiers, or both. The OPC UA PubSub logical resolution mechanism will be invoked if the dataset subscription descriptor requires resolution (this term is explained in OPC UA PubSub Descriptors).
We can reformulate it so: If you have specified physical identifiers everywhere, they will be directly used, and no logical resolution will take place - even if there are logical identifies filled in as well. If, however, you have a PubSub object somewhere in the descriptors that is only specified by its logical identifier but no physical identifier, the logical resolution mechanism will be used.
There are two ways your program can be informed about dataset messages that you have subscribed to:
It is also possible to specify a non-null callback parameter, and hook an event handler as well. In this case, the callback method will be invoked in addition to the event handlers.
The event arguments of the DataSetMessage Event are of type EasyUADataSetMessageEventArgs. Because it is indirectly derived from the OperationEventArgs, it contains the Exception Property which is null for success notifications, and non-null in case of failure. You can use the Succeeded Property to make the corresponding test. The actual data of the dataset, if available, is in the DataSetData Property.
The EasyUADataSetMessageEventArgs also contain, in their Arguments Property, a copy of the arguments (EasyUASubscribeDataSetArguments Class) you have used when making the dataset subscription that caused this event or callback. You can use this property to identify the dataset subscription, in case you are using event handlers and have made more subscriptions on the same object, or if you have used the same callback methods with multiple subscriptions. Specifically, the State Property in the EasyUASubscribeDataSetArguments can be used for any information you need to pass from the code that makes the subscription to the code that handles the dataset messages.
The EasyUASubscriber invokes the DataSetMessage event or callback when a new dataset message (you have subscribed to) arrives, but also in some other cases. Below is a list of possible property value combinations and their meaning.
The main causes for failures are
If the OPC UA PubSub logical resolution took place, the ResolvedDataSetSubscriptionDescriptor Property is filled in with a dataset subscription descriptor that is derived from the one you have specified when calling the SubscribeDataSet Method, but with the logical identifiers resolved to physical ones.
The dataset message event notification has a PubSubLocators Property. This property is always non-null (even in case of errors), and contains the information that allows to relate the event to its "source" in the OPC UA PubSub model. The object (UAPubSubLocators Class) has properties for a publisher Id, writer group Id, writer group name, dataset writer Id, and dataset writer name. The component will fill in as many of these properties as possible, given the circumstances. Knowing such relation comes handy when the dataset subscription filter is not for a single dataset, but for multiple datasets. Note that all information contained in the PubSubLocators Property is also available inside the dataset data. The difference is that the PubSubLocators object is present even in cases when there is dataset data - such as in case of errors. The PubSubLocators thus allow to determine the "source" of the error programmatically.
A typical task when processing the dataset message is to extract one or more fields from the dataset and process them further. The field is identified by its name (or an index in its string form, such "#0", if field names are not available) in the FieldDataDictionary. The example below shows how it can be done.
If metadata is available, you can alternatively use the FieldDataDictionaryById Property, which also contains the data for each field of the dataset message, but keyed by a datasetfield Id (a GUID).
Depending how OPC UA PubSub is configured, the publisher might be always sending all fields of the dataset with every dataset message, or it may use a combination of key frames and delta frames. While the key frame dataset message includes values for all fields of the dataset, the delta frame only contains values of the fields that have changed since the previous dataset message.
Key frames and delta frames are a concept that exists purely to spare the network bandwidth. When you subscribe with QuickOPC, the delta frames are interpreted internally, and a full dataset is always shipped to you in the dataset message event or callback. This way, you do not have to put in any additional code to handle the distinction between key frames and delta frames.
It is not necessary to unsubscribe and subscribe again, if you want to change some parameters of existing subscription, such as its filter (Message Filtering (OPC UA PubSub)) or the associated metadata (Dataset Metadata (OPC UA PubSub)). You change the parameters by calling the ChangeDataSetSubscription Method, passing it the dataset subscription handle, and the new parameters in form of an instance of the EasyUADataSetSubscriptionChangeArguments Class.
There is also an extension method (an overload - with the same name) that allows you to easily pass in just the dataset subscription handle, and a new filter.
If you no longer want to receive dataset messages, you need to unsubscribe. This is achieved by calling the UnsubscribeDataSet Method, passing it the dataset subscription handle obtained when calling the SubscribeDataSet Method.
Example:
You can also unsubscribe from all dataset messages you have previously subscribed to (on the same instance of the EasyUASubscriber Class) by calling the UnsubscribeAllDataSets Method.
QuickOPC merges together requests to the same PubSub objects. If, for example, you make multiple dataset subscriptions and they all use the same PubSub connection, QuickOPC will only make the connection once.
This merging is performed among all subscriptions on all EasyUASubscriber objects that have their Isolated Property set to 'false' (the default). If you set the Isolated Property on some EasyUASubscriber object to 'true', the merging is then performed on the subscriptions made on that object only.
Newer versions of OPC UA specification allow the publishers to inform interested parties about their status, either cyclically, or when the status changes. OPC Studio recognizes and processes the publisher status messages in UADP and JSON message mappings. Any non-operational publisher status is reported as an error through the dataset subscription event handler or callback.
This functionality is commonly used with OPC UA PubSub Topic Tree, in which case the topic tree rules prescribe the name of the topic where the status messages for a particular publisher are located.
// This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary // for their decoding directly in the code. // // In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see // https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. // // Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . using System; using System.Collections.Generic; using System.Threading; using OpcLabs.EasyOpc.UA; using OpcLabs.EasyOpc.UA.PubSub; using OpcLabs.EasyOpc.UA.PubSub.Configuration; using OpcLabs.EasyOpc.UA.PubSub.OperationModel; namespace UADocExamples.PubSub._EasyUASubscriber { partial class SubscribeDataSet { public static void Metadata() { // Define the PubSub connection we will work with. Uses implicit conversion from a string. UAPubSubConnectionDescriptor pubSubConnectionDescriptor = "opc.udp://239.0.0.1"; // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to // the statement below. Your actual interface name may differ, of course. //pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet"; // Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. // The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. var filter = new UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30), writerGroupDescriptor: 101); // Define the metadata, with the use of collection initializer for its fields. var metaData = new UADataSetMetaData { new UAFieldMetaData("BoolToggle", UABuiltInType.Boolean), new UAFieldMetaData("Int32", UABuiltInType.Int32), new UAFieldMetaData("Int32Fast", UABuiltInType.Int32), new UAFieldMetaData("DateTime", UABuiltInType.DateTime) }; // Define the dataset subscription, with specific communication parameters. // The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field // encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, // which is also the case here, but we are specifying the dataset offset anyway, for illustration. var dataSetSubscriptionDescriptor = new UADataSetSubscriptionDescriptor( pubSubConnectionDescriptor, filter, metaData) { CommunicationParameters = { UadpDataSetReaderMessageParameters = { DataSetOffset = 15 }} }; // Instantiate the subscriber object and hook events. var subscriber = new EasyUASubscriber(); subscriber.DataSetMessage += subscriber_DataSetMessage_Metadata; Console.WriteLine("Subscribing..."); subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor); Console.WriteLine("Processing dataset message events for 20 seconds..."); Thread.Sleep(20 * 1000); Console.WriteLine("Unsubscribing..."); subscriber.UnsubscribeAllDataSets(); Console.WriteLine("Waiting for 1 second..."); // Unsubscribe operation is asynchronous, messages may still come for a short while. Thread.Sleep(1 * 1000); Console.WriteLine("Finished."); } static void subscriber_DataSetMessage_Metadata(object sender, EasyUADataSetMessageEventArgs e) { // Display the dataset. if (e.Succeeded) { // An event with null DataSetData just indicates a successful connection. if (!(e.DataSetData is null)) { Console.WriteLine(); Console.WriteLine($"Dataset data: {e.DataSetData}"); foreach (KeyValuePair<string, UADataSetFieldData> pair in e.DataSetData.FieldDataDictionary) Console.WriteLine(pair); } } else { Console.WriteLine(); Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}"); } } // Example output: // //Subscribing... //Processing dataset message events for 20 seconds... // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3072 {System.Int32}; Good] //[Int32Fast, 894 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3072 {System.Int32}; Good] //[Int32Fast, 920 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3073 {System.Int32}; Good] //[Int32Fast, 1003 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3073 {System.Int32}; Good] //[Int32Fast, 1074 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, True {System.Boolean}; Good] //[Int32, 3074 {System.Int32}; Good] //[Int32Fast, 1140 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good] // //... } }
# This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary # for their decoding directly in the code. # # In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see # https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. # # Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . # OPC client and subscriber examples in Python on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-Python . # The QuickOPC package is needed. Install it using "pip install opclabs_quickopc". import opclabs_quickopc import time # Import .NET namespaces. from OpcLabs.EasyOpc.UA import * from OpcLabs.EasyOpc.UA.PubSub import * from OpcLabs.EasyOpc.UA.PubSub.Configuration import * from OpcLabs.EasyOpc.UA.PubSub.OperationModel import * def dataSetMessage(sender, e): # Display the dataset. if e.Succeeded: # An event with null DataSetData just indicates a successful connection. if e.DataSetData is not None: print('') print('Dataset data: ', e.DataSetData, sep='') for pair in e.DataSetData.FieldDataDictionary: print(pair) else: print('') print('*** Failure: ', e.ErrorMessageBrief, sep='') # Define the PubSub connection we will work with. Uses implicit conversion from a string. pubSubConnectionDescriptor = UAPubSubConnectionDescriptor.op_Implicit('opc.udp://239.0.0.1') # In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to # the statement below. Your actual interface name may differ, of course. #pubSubConnectionDescriptor.ResourceAddress.InterfaceName = 'Ethernet' # Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. # The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. filter = UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30), UAWriterGroupDescriptor(101)) # Define the metadata. metaData = UADataSetMetaData() metaData.Add(UAFieldMetaData('BoolToggle', UABuiltInType.Boolean)) metaData.Add(UAFieldMetaData('Int32', UABuiltInType.Int32)) metaData.Add(UAFieldMetaData('Int32Fast', UABuiltInType.Int32)) metaData.Add(UAFieldMetaData('DateTime', UABuiltInType.DateTime)) # Define the dataset subscription, with specific communication parameters. # The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field # encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, # which is also the case here, but we are specifying the dataset offset anyway, for illustration. dataSetSubscriptionDescriptor = UADataSetSubscriptionDescriptor(pubSubConnectionDescriptor, filter, metaData) dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15 # Instantiate the subscriber object and hook events. subscriber = EasyUASubscriber() subscriber.DataSetMessage += dataSetMessage print('Subscribing...') subscriber.SubscribeDataSet(EasyUASubscribeDataSetArguments(dataSetSubscriptionDescriptor)) print('Processing dataset message events for 20 seconds...') time.sleep(20) print('Unsubscribing...') subscriber.UnsubscribeAllDataSets() print('Waiting for 1 second...') # Unsubscribe operation is asynchronous, messages may still come for a short while. time.sleep(1) subscriber.DataSetMessage -= dataSetMessage print('Finished.')
' This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary ' for their decoding directly in the code. ' ' In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see ' https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. ' ' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . Imports OpcLabs.EasyOpc.UA Imports OpcLabs.EasyOpc.UA.PubSub Imports OpcLabs.EasyOpc.UA.PubSub.Configuration Imports OpcLabs.EasyOpc.UA.PubSub.OperationModel Namespace PubSub._EasyUASubscriber Partial Friend Class SubscribeDataSet Public Shared Sub Metadata() ' Define the PubSub connection we will work with. Uses implicit conversion from a string. Dim pubSubConnectionDescriptor As UAPubSubConnectionDescriptor = "opc.udp://239.0.0.1" ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to ' the statement below. Your actual interface name may differ, of course. ' pubSubConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet" ' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. ' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. Dim filter = New UASubscribeDataSetFilter(UAPublisherId.CreateUInt16(30)) filter.WriterGroupDescriptor.WriterGroupId = 101 ' Define the metadata, with the use of collection initializer for its fields. Dim metaData = New UADataSetMetaData From { New UAFieldMetaData("BoolToggle", UABuiltInType.Boolean), New UAFieldMetaData("Int32", UABuiltInType.Int32), New UAFieldMetaData("Int32Fast", UABuiltInType.Int32), New UAFieldMetaData("DateTime", UABuiltInType.DateTime) } ' Define the dataset subscription, with specific communication parameters. ' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field ' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, ' which is also the case here, but we are specifying the dataset offset anyway, for illustration. Dim dataSetSubscriptionDescriptor = New UADataSetSubscriptionDescriptor( pubSubConnectionDescriptor, filter, metaData) dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15 ' Instantiate the subscriber object and hook events. Dim subscriber = New EasyUASubscriber() AddHandler subscriber.DataSetMessage, AddressOf subscriber_DataSetMessage_Metadata Console.WriteLine("Subscribing...") subscriber.SubscribeDataSet(dataSetSubscriptionDescriptor) Console.WriteLine("Processing dataset message events for 20 seconds...") Threading.Thread.Sleep(20 * 1000) Console.WriteLine("Unsubscribing...") subscriber.UnsubscribeAllDataSets() Console.WriteLine("Waiting for 1 second...") ' Unsubscribe operation is asynchronous, messages may still come for a short while. Threading.Thread.Sleep(1 * 1000) Console.WriteLine("Finished...") End Sub Private Shared Sub subscriber_DataSetMessage_Metadata(ByVal sender As Object, ByVal e As EasyUADataSetMessageEventArgs) ' Display the dataset. If e.Succeeded Then ' An event with null DataSetData just indicates a successful connection. If e.DataSetData IsNot Nothing Then Console.WriteLine() Console.WriteLine($"Dataset data: {e.DataSetData}") For Each pair As KeyValuePair(Of String, UADataSetFieldData) In e.DataSetData.FieldDataDictionary Console.WriteLine(pair) Next End If Else Console.WriteLine() Console.WriteLine($"*** Failure: {e.ErrorMessageBrief}") End If End Sub End Class ' Example output ' 'Subscribing... 'Processing dataset message events for 20 seconds... ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 894 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 920 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1003 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1074 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, True {System.Boolean}; Good] '[Int32, 3074 {System.Int32}; Good] '[Int32Fast, 1140 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good] ' '... End Namespace
// This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary // for their decoding directly in the code. // // In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see // https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. // // Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . type TSubscriberEventHandlers78 = class procedure OnDataSetMessage( ASender: TObject; sender: OleVariant; const eventArgs: _EasyUADataSetMessageEventArgs); end; class procedure SubscribeDataSet.Metadata; var ConnectionDescriptor: _UAPubSubConnectionDescriptor; Field1, Field2, Field3, Field4: _UAFieldMetaData; MetaData: _UADataSetMetaData; SubscribeDataSetArguments: _EasyUASubscribeDataSetArguments; Subscriber: TEasyUASubscriber; SubscriberEventHandlers: TSubscriberEventHandlers78; begin // Define the PubSub connection we will work with. SubscribeDataSetArguments := CoEasyUASubscribeDataSetArguments.Create; ConnectionDescriptor := SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor; ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString := 'opc.udp://239.0.0.1'; // In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to // the statement below. Your actual interface name may differ, of course. //ConnectionDescriptor.ResourceAddress.InterfaceName := 'Ethernet'; // Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. // The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetUint16Identifier(30); SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId := 101; // Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message. MetaData := CoUADataSetMetaData.Create; // Field1 := CoUAFieldMetaData.Create; Field1.BuiltInType := UABuiltInType_Boolean; Field1.Name := 'BoolToggle'; MetaData.Add(Field1); // Field2 := CoUAFieldMetaData.Create; Field2.BuiltInType := UABuiltInType_Int32; Field2.Name := 'Int32'; MetaData.Add(Field2); // Field3 := CoUAFieldMetaData.Create; Field3.BuiltInType := UABuiltInType_Int32; Field3.Name := 'Int32Fast'; MetaData.Add(Field3); // Field4 := CoUAFieldMetaData.Create; Field4.BuiltInType := UABuiltInType_DateTime; Field4.Name := 'DateTime'; MetaData.Add(Field4); // SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData := MetaData; // Define the specific communication parameters for the dataset subscription. // The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field // encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, // which is also the case here, but we are specifying the dataset offset anyway, for illustration. SubscribeDataSetArguments.DataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset := 15; // Instantiate the subscriber object and hook events. Subscriber := TEasyUASubscriber.Create(nil); SubscriberEventHandlers := TSubscriberEventHandlers78.Create; Subscriber.OnDataSetMessage := SubscriberEventHandlers.OnDataSetMessage; WriteLn('Subscribing...'); Subscriber.SubscribeDataSet(SubscribeDataSetArguments); WriteLn('Processing dataset message for 20 seconds...'); PumpSleep(20*1000); WriteLn('Unsubscribing...'); Subscriber.UnsubscribeAllDataSets; WriteLn('Waiting for 1 second...'); // Unsubscribe operation is asynchronous, messages may still come for a short while. PumpSleep(1*1000); WriteLn('Finished.'); FreeAndNil(Subscriber); FreeAndNil(SubscriberEventHandlers); end; procedure TSubscriberEventHandlers78.OnDataSetMessage( ASender: TObject; sender: OleVariant; const eventArgs: _EasyUADataSetMessageEventArgs); var Count: Cardinal; DictionaryEntry2: _DictionaryEntry2; Element: OleVariant; FieldDataDictionaryEnumerator: IEnumVariant; begin // Display the dataset. if eventArgs.Succeeded then begin // An event with null DataSetData just indicates a successful connection. if eventArgs.DataSetData <> nil then begin WriteLn; WriteLn('Dataset data: ', eventArgs.DataSetData.ToString); FieldDataDictionaryEnumerator := eventArgs.DataSetData.FieldDataDictionary.GetEnumerator; while (FieldDataDictionaryEnumerator.Next(1, Element, Count) = S_OK) do begin DictionaryEntry2 := IUnknown(Element) as _DictionaryEntry2; WriteLn(DictionaryEntry2.ToString); end; end; end else begin WriteLn; WriteLn('*** Failure: ', eventArgs.ErrorMessageBrief); end; end; // Example output: // //Subscribing... //Processing dataset message events for 20 seconds... // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3072 {System.Int32}; Good] //[Int32Fast, 894 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3072 {System.Int32}; Good] //[Int32Fast, 920 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3073 {System.Int32}; Good] //[Int32Fast, 1003 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, False {System.Boolean}; Good] //[Int32, 3073 {System.Int32}; Good] //[Int32Fast, 1074 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] // //Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 //[BoolToggle, True {System.Boolean}; Good] //[Int32, 3074 {System.Int32}; Good] //[Int32Fast, 1140 {System.Int32}; Good] //[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good] // //...
Rem This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary Rem for their decoding directly in the code. Rem Rem In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see Rem https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. Rem Rem Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . Option Explicit Const UABuiltInType_Boolean = 1 Const UABuiltInType_Int32 = 6 Const UABuiltInType_DateTime = 13 ' Define the PubSub connection we will work with. Dim SubscribeDataSetArguments: Set SubscribeDataSetArguments = CreateObject("OpcLabs.EasyOpc.UA.PubSub.OperationModel.EasyUASubscribeDataSetArguments") Dim ConnectionDescriptor: Set ConnectionDescriptor = SubscribeDataSetArguments.DataSetSubscriptionDescriptor.ConnectionDescriptor ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1" ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to ' the statement below. Your actual interface name may differ, of course. ' ConnectionDescriptor.ResourceAddress.InterfaceName = "Ethernet" ' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. ' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.PublisherId.SetUInt16Identifier 30 SubscribeDataSetArguments.DataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId = 101 ' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message. Dim MetaData: Set MetaData = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UADataSetMetaData") ' Dim Field1: Set Field1 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData") Field1.BuiltInType = UABuiltInType_Boolean Field1.Name = "BoolToggle" MetaData.Add(Field1) ' Dim Field2: Set Field2 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData") Field2.BuiltInType = UABuiltInType_Int32 Field2.Name = "Int32" MetaData.Add(Field2) ' Dim Field3: Set Field3 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData") Field3.BuiltInType = UABuiltInType_Int32 Field3.Name = "Int32Fast" MetaData.Add(Field3) ' Dim Field4: Set Field4 = CreateObject("OpcLabs.EasyOpc.UA.PubSub.Configuration.UAFieldMetaData") Field4.BuiltInType = UABuiltInType_DateTime Field4.Name = "DateTime" MetaData.Add(Field4) ' Set SubscribeDataSetArguments.DataSetSubscriptionDescriptor.DataSetMetaData = MetaData ' Define the specific communication parameters for the dataset subscription. ' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field ' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, ' which is also the case here, but we are specifying the dataset offset anyway, for illustration. SubscribeDataSetArguments.DataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15 ' Instantiate the subscriber object and hook events. Dim Subscriber: Set Subscriber = CreateObject("OpcLabs.EasyOpc.UA.PubSub.EasyUASubscriber") WScript.ConnectObject Subscriber, "Subscriber_" WScript.Echo "Subscribing..." Subscriber.SubscribeDataSet SubscribeDataSetArguments WScript.Echo "Processing dataset message events for 20 seconds..." WScript.Sleep 20*1000 WScript.Echo "Unsubscribing..." Subscriber.UnsubscribeAllDataSets WScript.Echo "Waiting for 1 second..." ' Unsubscribe operation is asynchronous, messages may still come for a short while. WScript.Sleep 1*1000 WScript.Echo "Finished." Sub Subscriber_DataSetMessage(Sender, e) ' Display the dataset. If e.Succeeded Then ' An event with null DataSetData just indicates a successful connection. If Not (e.DataSetData Is Nothing) Then WScript.Echo WScript.Echo "Dataset data: " & e.DataSetData Dim Pair: For Each Pair in e.DataSetData.FieldDataDictionary WScript.Echo Pair Next End If Else WScript.Echo WScript.Echo "*** Failure: " & e.ErrorMessageBrief End If End Sub ' Example output: ' 'Subscribing... 'Processing dataset message events for 20 seconds... ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 894 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 920 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1003 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1074 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, True {System.Boolean}; Good] '[Int32, 3074 {System.Int32}; Good] '[Int32Fast, 1140 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good] ' '...
REM This example shows how to subscribe to dataset messages with RawData field encoding, specifying the metadata necessary REM for their decoding directly in the code. REM REM In order to produce network messages for this example, run the UADemoPublisher tool. For documentation, see REM https://kb.opclabs.com/UADemoPublisher_Basics . In some cases, you may have to specify the interface name to be used. REM REM Find all latest examples here : https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html . ' The subscriber object, with events 'Public WithEvents Subscriber3 As EasyUASubscriber Private Sub EasyUASubscriber_SubscribeDataSet_Metadata_Command_Click() OutputText = "" ' Define the PubSub connection we will work with. Dim subscribeDataSetArguments As New EasyUASubscribeDataSetArguments Dim ConnectionDescriptor As UAPubSubConnectionDescriptor Set ConnectionDescriptor = subscribeDataSetArguments.dataSetSubscriptionDescriptor.ConnectionDescriptor ConnectionDescriptor.ResourceAddress.ResourceDescriptor.UrlString = "opc.udp://239.0.0.1" ' In some cases you may have to set the interface (network adapter) name that needs to be used, similarly to ' the statement below. Your actual interface name may differ, of course. 'ConnectionDescriptor.ResourceAddress.InterfaceName := 'Ethernet'; ' Define the filter. Publisher Id (unsigned 16-bits) is 30, and the writer group Id is 101. ' The dataset writer Id (1) must not be specified in the filter, because it does not appear in the message. Call subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.PublisherId.SetUInt16Identifier(30) subscribeDataSetArguments.dataSetSubscriptionDescriptor.Filter.WriterGroupDescriptor.WriterGroupId = 101 ' Define the metadata. For UADP, the order of field metadata must correspond to the order of fields in the dataset message. Dim metaData As New UADataSetMetaData ' Dim field1 As New UAFieldMetaData field1.BuiltInType = UABuiltInType_Boolean field1.Name = "BoolToggle" metaData.Add field1 ' Dim field2 As New UAFieldMetaData field2.BuiltInType = UABuiltInType_Int32 field2.Name = "Int32" metaData.Add field2 ' Dim field3 As New UAFieldMetaData field3.BuiltInType = UABuiltInType_Int32 field3.Name = "Int32Fast" metaData.Add field3 ' Dim field4 As New UAFieldMetaData field4.BuiltInType = UABuiltInType_DateTime field4.Name = "DateTime" metaData.Add field4 ' Set subscribeDataSetArguments.dataSetSubscriptionDescriptor.DataSetMetaData = metaData ' Define the specific communication parameters for the dataset subscription. ' The dataset offset is needed with messages that do not contain dataset writer Ids and use RawData field ' encoding. An exception to this rule is when the dataset is the only or first in the dataset message payload, ' which is also the case here, but we are specifying the dataset offset anyway, for illustration. subscribeDataSetArguments.dataSetSubscriptionDescriptor.CommunicationParameters.UadpDataSetReaderMessageParameters.DataSetOffset = 15 ' Instantiate the subscriber object and hook events. Set Subscriber3 = New EasyUASubscriber OutputText = OutputText & "Subscribing..." & vbCrLf Call Subscriber3.SubscribeDataSet(subscribeDataSetArguments) OutputText = OutputText & "Processing dataset message for 20 seconds..." & vbCrLf Pause 20000 OutputText = OutputText & "Unsubscribing..." & vbCrLf Subscriber3.UnsubscribeAllDataSets OutputText = OutputText & "Waiting for 1 second..." & vbCrLf ' Unsubscribe operation is asynchronous, messages may still come for a short while. Pause 1000 Set Subscriber3 = Nothing OutputText = OutputText & "Finished." & vbCrLf End Sub Private Sub Subscriber3_DataSetMessage(ByVal sender As Variant, ByVal eventArgs As EasyUADataSetMessageEventArgs) ' Display the dataset If eventArgs.Succeeded Then ' An event with null DataSetData just indicates a successful connection. If Not eventArgs.DataSetData Is Nothing Then OutputText = OutputText & vbCrLf OutputText = OutputText & "Dataset data: " & eventArgs.DataSetData & vbCrLf Dim dictionaryEntry2 : For Each dictionaryEntry2 In eventArgs.DataSetData.FieldDataDictionary OutputText = OutputText & dictionaryEntry2 & vbCrLf Next End If Else OutputText = OutputText & vbCrLf OutputText = OutputText & "*** Failure: " & eventArgs.ErrorMessageBrief & vbCrLf End If End Sub ' Example output: ' 'Subscribing... 'Processing dataset message events for 20 seconds... ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 894 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3072 {System.Int32}; Good] '[Int32Fast, 920 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:14 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1003 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, False {System.Boolean}; Good] '[Int32, 3073 {System.Int32}; Good] '[Int32Fast, 1074 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:15 PM {System.DateTime}; Good] ' 'Dataset data: Good; Data; publisher=(UInt16)30, group=101, fields: 4 '[BoolToggle, True {System.Boolean}; Good] '[Int32, 3074 {System.Int32}; Good] '[Int32Fast, 1140 {System.Int32}; Good] '[DateTime, 10/1/2019 12:21:16 PM {System.DateTime}; Good] ' '...
System.Object
OpcLabs.BaseLib.Object2
OpcLabs.BaseLib.Info
OpcLabs.EasyOpc.UA.PubSub.UADataSetSubscriptionDescriptor