OPC Studio User's Guide and Reference
SubscribeItem(IEasyDAClient,String,String,String,VarType,Int32,Single,EasyDAItemChangedEventHandler,Object) Method
Example 



OpcLabs.EasyOpcClassicCore Assembly > OpcLabs.EasyOpc.DataAccess Namespace > IEasyDAClientExtension Class > SubscribeItem Method : SubscribeItem(IEasyDAClient,String,String,String,VarType,Int32,Single,EasyDAItemChangedEventHandler,Object) Method
The client object that will perform the operation.

This is typically the EasyDAClient object.

The value of this parameter cannot be null (Nothing in Visual Basic).

Name of the machine (empty string for local computer).

The value represents a UNC or DNS computer name. Any string can be passed to this parameter (i.e. will not cause System.ArgumentException), but not all values make sense and will work when an operation using them is attempted. IPv6 addresses are normally enclosed between '[' and ']'.

The value of this parameter cannot be null (Nothing in Visual Basic).

Contains ProgID of the OPC server.

The value of this parameter cannot be null (Nothing in Visual Basic).

ID of the item that will be subscribed to.

The value of this parameter cannot be null (Nothing in Visual Basic).

Specifies the data type requested. Passing OpcLabs.BaseLib.ComInterop.VarTypes.Empty means that the server's canonical data type should be used.

Because the OpcLabs.BaseLib.ComInterop.VarType has an implicit conversion from System.Int32 and OpcLabs.BaseLib.ComInterop.VarTypes, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use an integer (representing the numerical value of the COM VARTYPE), or an element of the OpcLabs.BaseLib.ComInterop.VarTypes enumeration (or an allowed combination of OpcLabs.BaseLib.ComInterop.VarTypes flags) in place of this parameter, and the corresponding data type specification will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the OpcLabs.BaseLib.ComInterop.VarType.VarType Constructor(Int32) or OpcLabs.BaseLib.ComInterop.VarType.VarType Constructor(VarTypes) constructor instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

How often should the updates be received (number of milliseconds)
The percent change in an item value that will cause an update
A callback method to be invoked for each significant item change.

The value of this parameter can be null (Nothing in Visual Basic).

The state object (can be any object supplied by your code); available in event notifications.

The value of this parameter can be null (Nothing in Visual Basic).

Subscribe to OPC item. Specify machine name, server class, item ID, data type, requested update rate, percent deadband, callback method, and a user-defined state object.
Syntax
'Declaration
 

<ExtensionAttribute()>
Public Overloads Shared Function SubscribeItem( _
   ByVal client As IEasyDAClient, _
   ByVal machineName As String, _
   ByVal serverClass As String, _
   ByVal itemId As String, _
   ByVal dataType As VarType, _
   ByVal requestedUpdateRate As Integer, _
   ByVal percentDeadband As Single, _
   ByVal callback As EasyDAItemChangedEventHandler, _
   ByVal state As Object _
) As Integer
'Usage
 

Dim client As IEasyDAClient
Dim machineName As String
Dim serverClass As String
Dim itemId As String
Dim dataType As VarType
Dim requestedUpdateRate As Integer
Dim percentDeadband As Single
Dim callback As EasyDAItemChangedEventHandler
Dim state As Object
Dim value As Integer
 
value = IEasyDAClientExtension.SubscribeItem(client, machineName, serverClass, itemId, dataType, requestedUpdateRate, percentDeadband, callback, state)
[Extension()]
public static int SubscribeItem( 
   IEasyDAClient client,
   string machineName,
   string serverClass,
   string itemId,
   VarType dataType,
   int requestedUpdateRate,
   float percentDeadband,
   EasyDAItemChangedEventHandler callback,
   object state
)
[Extension()]
public:
static int SubscribeItem( 
   IEasyDAClient^ client,
   String^ machineName,
   String^ serverClass,
   String^ itemId,
   VarType^ dataType,
   int requestedUpdateRate,
   float percentDeadband,
   EasyDAItemChangedEventHandler^ callback,
   Object^ state
)

Parameters

client
The client object that will perform the operation.

This is typically the EasyDAClient object.

The value of this parameter cannot be null (Nothing in Visual Basic).

machineName
Name of the machine (empty string for local computer).

The value represents a UNC or DNS computer name. Any string can be passed to this parameter (i.e. will not cause System.ArgumentException), but not all values make sense and will work when an operation using them is attempted. IPv6 addresses are normally enclosed between '[' and ']'.

The value of this parameter cannot be null (Nothing in Visual Basic).

serverClass
Contains ProgID of the OPC server.

The value of this parameter cannot be null (Nothing in Visual Basic).

itemId
ID of the item that will be subscribed to.

The value of this parameter cannot be null (Nothing in Visual Basic).

dataType
Specifies the data type requested. Passing OpcLabs.BaseLib.ComInterop.VarTypes.Empty means that the server's canonical data type should be used.

Because the OpcLabs.BaseLib.ComInterop.VarType has an implicit conversion from System.Int32 and OpcLabs.BaseLib.ComInterop.VarTypes, in languages that support implicit conversion operators (such as C# or VB.NET), you can simply use an integer (representing the numerical value of the COM VARTYPE), or an element of the OpcLabs.BaseLib.ComInterop.VarTypes enumeration (or an allowed combination of OpcLabs.BaseLib.ComInterop.VarTypes flags) in place of this parameter, and the corresponding data type specification will be constructed automatically. When the implicit conversion operators are not supported (such as with Python.NET), you can use the OpcLabs.BaseLib.ComInterop.VarType.VarType Constructor(Int32) or OpcLabs.BaseLib.ComInterop.VarType.VarType Constructor(VarTypes) constructor instead.

The value of this parameter cannot be null (Nothing in Visual Basic).

requestedUpdateRate
How often should the updates be received (number of milliseconds)
percentDeadband
The percent change in an item value that will cause an update
callback
A callback method to be invoked for each significant item change.

The value of this parameter can be null (Nothing in Visual Basic).

state
The state object (can be any object supplied by your code); available in event notifications.

The value of this parameter can be null (Nothing in Visual Basic).

Return Value

The method returns an integer handle that uniquely identifies the item subscription.
Exceptions
ExceptionDescription
System.ArgumentException

One of the arguments provided to a method is not valid.

This is a usage error, i.e. it will never occur (the exception will not be thrown) in a correctly written program. Your code should not catch this exception.

System.ArgumentNullException

A null reference (Nothing in Visual Basic) is passed to a method that does not accept it as a valid argument.

This is a usage error, i.e. it will never occur (the exception will not be thrown) in a correctly written program. Your code should not catch this exception.

System.ArgumentOutOfRangeException

The value of an argument is outside the allowable range of values as defined by the invoked method.

This is a usage error, i.e. it will never occur (the exception will not be thrown) in a correctly written program. Your code should not catch this exception.

Remarks
If callback is a null reference, only the ItemChanged events are generated, but no callback method is invoked.

This is an extension method (info: C#, VB.NET). In languages that have support for extensions methods (such as C# and VB.NET), you can use the extension method as if it were a regular method on the object that is its first parameter. In other languages (such as with Python.NET), you will call the extension as a static method, and pass it the object on which it acts as its first parameter.

Example
// This example shows how subscribe to changes of a single item with percent deadband.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using System.Diagnostics;
using System.Threading;
using OpcLabs.BaseLib.ComInterop;
using OpcLabs.EasyOpc.DataAccess;

namespace DocExamples.DataAccess._EasyDAClient
{
    partial class SubscribeItem
    {
        public static void PercentDeadband()
        {
            // Instantiate the client object.
            var client = new EasyDAClient();

            const float percentDeadband = 5.0f;
            Console.WriteLine($"Subscribing with {percentDeadband}% deadband...");
            // The callback is a lambda expression the displays the value
            client.SubscribeItem("", "OPCLabs.KitServer.2", "Simulation.Ramp 0:100 (10 s)", 
                VarTypes.Empty, requestedUpdateRate:100, percentDeadband:percentDeadband, 
                (sender, eventArgs) =>
                {
                    Debug.Assert(!(eventArgs is null));

                    if (eventArgs.Succeeded)
                    {
                        Debug.Assert(!(eventArgs.Vtq is null));
                        Console.WriteLine(eventArgs.Vtq.ToString());
                    }
                    else
                        Console.WriteLine("*** Failure: {0}", eventArgs.ErrorMessageBrief);
                },
                state:null);

            Console.WriteLine("Processing item changed events for 10 seconds...");
            Thread.Sleep(10 * 1000);

            Console.WriteLine("Unsubscribing...");
            client.UnsubscribeAllItems();

            Console.WriteLine("Waiting for 2 seconds...");
            Thread.Sleep(2 * 1000);
        }
    }
}
' This example shows how subscribe to changes of a single item with percent deadband.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.BaseLib.ComInterop
Imports OpcLabs.EasyOpc.DataAccess

Namespace DataAccess._EasyDAClient
    Partial Friend Class SubscribeItem
        Shared Sub PercentDeadband()
            ' Instantiate the client object
            Dim client = New EasyDAClient()

            Const percentDeadband As Single = 5.0F
            Console.WriteLine("Subscribing with {0}% deadband...", percentDeadband)
            ' The callback is a lambda expression the displays the value
            client.SubscribeItem("", "OPCLabs.KitServer.2", "Simulation.Ramp 0:100 (10 s)",
                VarTypes.Empty, requestedUpdateRate:=100, percentDeadband:=percentDeadband,
                    Sub(sender, eventArgs)
                        Debug.Assert(eventArgs IsNot Nothing)
                        If eventArgs.Succeeded Then
                            Debug.Assert(eventArgs.Vtq IsNot Nothing)
                            Console.WriteLine(eventArgs.Vtq.ToString())
                        Else
                            Console.WriteLine("*** Failure: {0}", eventArgs.ErrorMessageBrief)
                        End If
                    End Sub,
                    state:=Nothing)

            Console.WriteLine("Processing item changed events for 10 seconds...")
            Threading.Thread.Sleep(10 * 1000)

            Console.WriteLine("Unsubscribing...")
            client.UnsubscribeAllItems()

            Console.WriteLine("Waiting for 2 seconds...")
            Threading.Thread.Sleep(2 * 1000)
        End Sub
    End Class
End Namespace
# This example shows how subscribe to changes of a single item with percent deadband.
#
# 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 .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from OpcLabs.EasyOpc.DataAccess import *


# Item changed callback.
def itemChangedCallback(sender, e):
    assert e is not None
    if e.Succeeded:
        assert e.Vtq is not None
        print(e.Vtq)
    else:
        print('*** Failure: ', e.ErrorMessageBrief, sep='')


PERCENT_DEADBAND = 5.0

# Instantiate the client object.
client = EasyDAClient()

print('Subscribing item changes with ', PERCENT_DEADBAND, '% deadband...', sep='')
# The callback is a regular method that displays the value.
IEasyDAClientExtension.SubscribeItem(client,
                                     '', 'OPCLabs.KitServer.2', 'Simulation.Ramp 0:100 (10 s)', 50,
                                     EasyDAItemChangedEventHandler(itemChangedCallback))

print('Processing item change callbacks for 10 seconds...')
time.sleep(10)

print('Unsubscribing all items...')
client.UnsubscribeAllItems()

print('Waiting for 2 seconds...')
time.sleep(2)

print('Finished.')

// This example shows how subscribe to changes of a single item with percent deadband.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in C# on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-CSharp .
// Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
// a commercial license in order to use Online Forums, and we reply to every post.

using System;
using System.Diagnostics;
using System.Threading;
using OpcLabs.BaseLib.ComInterop;
using OpcLabs.EasyOpc.DataAccess;

namespace DocExamples.DataAccess.Xml
{
    partial class SubscribeItem
    {
        public static void PercentDeadbandXml()
        {
            // Instantiate the client object.
            var client = new EasyDAClient();

            const float percentDeadband = 5.0f;
            Console.WriteLine($"Subscribing with {percentDeadband}% deadband...");
            // The callback is a lambda expression the displays the value
            client.SubscribeItem("http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx", new DAItemDescriptor("Dynamic/Analog Types/Double", 
                VarTypes.Empty), new DAGroupParameters(requestedUpdateRate:100, percentDeadband:percentDeadband), 
                (sender, eventArgs) =>
                {
                    Debug.Assert(!(eventArgs is null));

                    if (eventArgs.Succeeded)
                    {
                        Debug.Assert(!(eventArgs.Vtq is null));
                        Console.WriteLine(eventArgs.Vtq.ToString());
                    }
                    else
                        Console.WriteLine("*** Failure: {0}", eventArgs.ErrorMessageBrief);
                },
                state:null);

            Console.WriteLine("Processing item changed events for 10 seconds...");
            Thread.Sleep(10 * 1000);

            Console.WriteLine("Unsubscribing...");
            client.UnsubscribeAllItems();

            Console.WriteLine("Waiting for 2 seconds...");
            Thread.Sleep(2 * 1000);
        }
    }
}
' This example shows how subscribe to changes of a single item with percent deadband.
'
' Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
' OPC client and subscriber examples in VB.NET on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBNET .
' Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
' a commercial license in order to use Online Forums, and we reply to every post.

Imports OpcLabs.BaseLib.ComInterop
Imports OpcLabs.EasyOpc.DataAccess

Namespace DataAccess.Xml
    Partial Friend Class SubscribeItem
        Shared Sub PercentDeadbandXml()
            ' Instantiate the client object
            Dim client = New EasyDAClient()

            Const percentDeadband As Single = 5.0F
            Console.WriteLine($"Subscribing with {percentDeadband}% deadband...")
            ' The callback is a lambda expression the displays the value
            client.SubscribeItem("http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx", New DAItemDescriptor("Dynamic/Analog Types/Double",
                VarTypes.Empty), New DAGroupParameters(requestedUpdateRate:=100, percentDeadband:=percentDeadband),
                    Sub(sender, eventArgs)
                        Debug.Assert(eventArgs IsNot Nothing)
                        If eventArgs.Succeeded Then
                            Debug.Assert(eventArgs.Vtq IsNot Nothing)
                            Console.WriteLine(eventArgs.Vtq.ToString())
                        Else
                            Console.WriteLine("*** Failure: {0}", eventArgs.ErrorMessageBrief)
                        End If
                    End Sub,
                    state:=Nothing)

            Console.WriteLine("Processing item changed events for 10 seconds...")
            Threading.Thread.Sleep(10 * 1000)

            Console.WriteLine("Unsubscribing...")
            client.UnsubscribeAllItems()

            Console.WriteLine("Waiting for 2 seconds...")
            Threading.Thread.Sleep(2 * 1000)
        End Sub
    End Class
End Namespace
# This example shows how subscribe to changes of a single item with percent deadband.
#
# 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 .
# Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
# a commercial license in order to use Online Forums, and we reply to every post.
# The QuickOPC package is needed. Install it using "pip install opclabs_quickopc".
import opclabs_quickopc
import time

# Import .NET namespaces.
from OpcLabs.BaseLib.ComInterop import *
from OpcLabs.EasyOpc import *
from OpcLabs.EasyOpc.DataAccess import *
from OpcLabs.EasyOpc.DataAccess.OperationModel import *


# Item changed callback
def itemChanged(sender, e):
    assert e is not None
    if e.Succeeded:
        assert e.Vtq is not None
        print(e.Vtq)
    else:
        print('*** Failure: ', e.ErrorMessageBrief, sep='')


PERCENT_DEADBAND = 5.0

# Instantiate the client object
client = EasyDAClient()

print('Subscribing with ', PERCENT_DEADBAND, '% deadband...', sep='')
# The callback is a regular method that displays the value.
IEasyDAClientExtension.SubscribeItem(client,
    ServerDescriptor('http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx'),
    DAItemDescriptor('Dynamic/Analog Types/Double', VarType(VarTypes.Empty)),
    DAGroupParameters(100, PERCENT_DEADBAND),
    EasyDAItemChangedEventHandler(itemChanged),
    None)

print('Processing item changed events for 10 seconds...')
time.sleep(10)

print('Unsubscribing all items...')
client.UnsubscribeAllItems()

print('Waiting for 2 seconds...')
time.sleep(2)
Requirements

Target Platforms: .NET Framework: Windows 10 (selected versions), Windows 11 (selected versions), Windows Server 2016, Windows Server 2022; .NET: Linux, macOS, Microsoft Windows

See Also

Reference

IEasyDAClientExtension Class
IEasyDAClientExtension Members
Overload List

 

 

Copyright © 2004-2025 CODE Consulting and Development, s.r.o., Plzen. All rights reserved. Web page: www.opclabs.com

Documentation Home, Send Feedback. Resources: Knowledge Base, Product Downloads. Technical support: Online Forums, FAQ.

Missing some example? Ask us for it on our Online Forums! You do not have to own a commercial license in order to use Online Forums, and we reply to every post.