OPC Studio User's Guide and Reference
UAIndexRangeList Class
Members  Example 



View with Navigation Tools
OpcLabs.EasyOpcUA Assembly > OpcLabs.EasyOpc.UA Namespace : UAIndexRangeList Class
List of index ranges. Can be used to identify the whole array, a single element of a structure or an array, or a single range of indexes for arrays.
Object Model
UAIndexRangeList ClassUAIndexRange Class
Syntax
Remarks

 

Introduction

OPC Unified Architecture has support for single- and multidimensional arrays in data values. In addition, it is also possible to work with (read, write, subscribe to) only a subset of an array, so that the whole (potentially large) array does not have to be transferred between the OPC server and OPC client.

OPC Studio uses Index Range Lists (UAIndexRangeList objects) to control which parts of array value should be accessed. An index range list can be used to identify the whole array, a single element of a structure or an array, or a single range of indexes for arrays. Index Range List is basically a list of individual Index Ranges (UAIndexRange objects), each containing a range for a single dimension of an array.

There is an implicit conversion from an integer (Int32) to a UAIndexRange, so if your language (such as C#) supports implicit conversions, an index range containing just a single element can be written simply as the element index, without explicitly constructing the UAIndexRange object.

Besides constructing the UAIndexRangeList from individual UAIndexRange objects, it is also possible to specify the index range list by parsing a string, using static UAIndexRangeList.TryParse method.

Examples of index range strings:

Dimensions are separated by commas. A minimum and maximum value, separated by a colon, denotes a range of index. If the colon is missing, only a single for an index is selected. An empty string denotes the whole array.

One-dimensional index range lists can be easily constructed using the UAIndexRangeList.OneDimension static method, passing it either the single index, or minimum and maximum indices.

UAIndexRangeList can be given as IndexRangeList property of the UAAttributeArguments object (and derived objects, such as UAReadArguments, UAWriteArguments, UAWriteValueArguments, and EasyUAMonitoredItemArguments). You can then pass this object to a corresponding method on the main EasyUAClient object.

Examples

.NET

// This example shows how to read a range of values from an array.
//
// 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 OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UACommonDocExamples._UAIndexRangeList
{
    partial class Usage
    {
        public static void ReadValue()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object
            var client = new EasyUAClient();

            // Obtain the value, indicating that just the elements 2 to 4 should be returned
            object value;
            try
            {
                value = client.ReadValue(
                    new UAReadArguments(
                        endpointDescriptor,
                        "nsu=http://test.org/UA/Data/ ;ns=2;i=10305",   // /Data.Static.Array.Int32Value
                        UAIndexRangeList.OneDimension(2, 4)));
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Cast to typed array
            var arrayValue = (Int32[]) value;

            // Display results
            for (int i = 0; i < 3; i++)
                Console.WriteLine("arrayValue[{0}]: {1}", i, arrayValue[i]);


            // Example output:
            //arrayValue[0]: 180410224
            //arrayValue[1]: 1919239969
            //arrayValue[2]: 1700185172
        }
    }
}

COM

// This example shows how to read a range of values from an array.
//
// Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
// OPC client and subscriber examples in Object Pascal (Delphi) on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-OP .
// 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.

class procedure Usage.ReadValue;
var
  Client: _EasyUAClient;
  EndpointDescriptor: string;
  ReadArguments1: _UAReadArguments;
  Arguments, Results: OleVariant;
  I: Cardinal;
  IndexRange: _UAIndexRange;
  IndexRangeList: OpcLabs_EasyOpcUA_TLB._UAIndexRangeList;
  ArrayValue: OleVariant;
  Value: Integer;
  ValueResult: _ValueResult;
begin
  EndpointDescriptor := 
    //'http://opcua.demo-this.com:51211/UA/SampleServer';
    //'https://opcua.demo-this.com:51212/UA/SampleServer/';
    'opc.tcp://opcua.demo-this.com:51210/UA/SampleServer';

  // Instantiate the client object
  Client := CoEasyUAClient.Create;

  // Prepare the arguments, indicating that just the elements 2 to 4 should be returned.
  IndexRangeList := CoUAIndexRangeList.Create;
  IndexRange := CoUAIndexRange.Create;
  IndexRange.Minimum := 2;
  IndexRange.Maximum := 4;
  IndexRangeList.Add(IndexRange);

  ReadArguments1 := CoUAReadArguments.Create;
  ReadArguments1.EndpointDescriptor.UrlString := EndpointDescriptor;
  ReadArguments1.NodeDescriptor.NodeId.ExpandedText := 'nsu=http://test.org/UA/Data/ ;ns=2;i=10305';
  ReadArguments1.IndexRangeList := IndexRangeList;

  Arguments := VarArrayCreate([0, 0], varVariant);
  Arguments[0] := ReadArguments1;

  // Obtain value.
  TVarData(Results).VType := varArray or varVariant;
  TVarData(Results).VArray := PVarArray(Client.ReadMultipleValues(Arguments));

  ValueResult := IInterface(Results[0]) as _ValueResult;
  if not ValueResult.Succeeded then
    begin
      WriteLn(' *** Failure: ', ValueResult.Exception.GetBaseException.Message);
      Exit;
    end;

  // Display results
  ArrayValue := ValueResult.Value;
  for I := VarArrayLowBound(ArrayValue, 1) to VarArrayHighBound(ArrayValue, 1) do
  begin
      Value := ArrayValue[I];
      WriteLn('arrayValue[', I, ']: ', Value);
  end;

  VarClear(Results);
  VarClear(Arguments);

  // Example output:
  //arrayValue[0]: 180410224
  //arrayValue[1]: 1919239969
  //arrayValue[2]: 1700185172
end;

Python

# This example shows how to read a range of values from an array.
#
# 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 .NET namespaces.
from OpcLabs.EasyOpc.UA import *
from OpcLabs.EasyOpc.UA.OperationModel import *


endpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:51210/UA/SampleServer')
# or 'http://opcua.demo-this.com:51211/UA/SampleServer' (currently not supported)
# or 'https://opcua.demo-this.com:51212/UA/SampleServer/'

# Instantiate the client object.
client = EasyUAClient()

# Obtain the value, indicating that just the elements 2 to 4 should be returned
try:
    arrayValue = IEasyUAClientExtension.ReadValue(client,
                                                  endpointDescriptor,
                                                  UANodeDescriptor('nsu=http://test.org/UA/Data/ ;ns=2;i=10305'),    # /Data.Static.Array.Int32Value
                                                  UAIndexRangeList.OneDimension(2, 4))
except UAException as uaException:
    print('*** Failure: ' + uaException.GetBaseException().Message)
    exit()

# Display results.
for i, elementValue in enumerate(arrayValue):
    print('arrayValue[', i, ']: ', elementValue, sep='')

print()
print('Finished.')

 

 

.NET

// This example shows how to subscribe to range of values from an array.
//
// 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 OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UACommonDocExamples._UAIndexRangeList
{
    partial class Usage
    {
        public static void Subscribe()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object
            var client = new EasyUAClient();

            Console.WriteLine("Subscribing to range...");
            var attributeArguments = new UAAttributeArguments(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10933")
                {
                    IndexRangeList = UAIndexRangeList.OneDimension(2, 4)
                };
            var monitoredItemArguments = new UAMonitoredItemArguments(attributeArguments, monitoringParameters:1000);
            // The callback is a lambda expression the displays the value
            client.SubscribeMonitoredItem(monitoredItemArguments,
                (sender, eventArgs) =>
                {
                    if (eventArgs.Succeeded)
                    {
                        var arrayValue = eventArgs.AttributeData.Value as Int32[];
                        if (!(arrayValue is null))
                            Console.WriteLine($"Value: {{{String.Join(",", arrayValue)}}}");
                    }
                    else
                        Console.WriteLine($"*** Failure: {eventArgs.ErrorMessageBrief}");
                });

            Console.WriteLine("Processing data change events for 10 seconds...");
            System.Threading.Thread.Sleep(10 * 1000);

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

            Console.WriteLine("Waiting for 2 seconds...");
            System.Threading.Thread.Sleep(2 * 1000);
        }
    }
}

Python

# This example shows how to subscribe to range of values from an array.
#
# 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.UA import *
from OpcLabs.EasyOpc.UA.OperationModel import *


def dataChangeNotification(sender, eventArgs):
    # Display value.
    if eventArgs.Succeeded:
        arrayValue = eventArgs.AttributeData.Value
        print('Value: {', ", ".join(["{}"]*len(arrayValue)).format(*arrayValue), '}', sep='')
    else:
        print('*** Failure: ', eventArgs.ErrorMessageBrief, sep='')


endpointDescriptor = UAEndpointDescriptor('opc.tcp://opcua.demo-this.com:51210/UA/SampleServer')
# or 'http://opcua.demo-this.com:51211/UA/SampleServer' (currently not supported)
# or 'https://opcua.demo-this.com:51212/UA/SampleServer/'

# Instantiate the client object.
client = EasyUAClient()

print('Subscribing to range...')
attributeArguments = UAAttributeArguments(endpointDescriptor, UANodeDescriptor('nsu=http://test.org/UA/Data/ ;i=10933'))
attributeArguments.IndexRangeList = UAIndexRangeList.OneDimension(2, 4)
monitoredItemArguments = UAMonitoredItemArguments(attributeArguments, UAMonitoringParameters(1000))
IEasyUAClientExtension.SubscribeMonitoredItem(client,
    monitoredItemArguments,
    EasyUADataChangeNotificationEventHandler(dataChangeNotification))

print('Processing data change events for 10 seconds...')
time.sleep(10)

print('Unsubscribing...')
client.UnsubscribeAllMonitoredItems()

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

print('Finished.')

 

 

Example
// This example shows how to read a range of values from an array.
//
// 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 OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UACommonDocExamples._UAIndexRangeList
{
    partial class Usage
    {
        public static void ReadValue()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object
            var client = new EasyUAClient();

            // Obtain the value, indicating that just the elements 2 to 4 should be returned
            object value;
            try
            {
                value = client.ReadValue(
                    new UAReadArguments(
                        endpointDescriptor,
                        "nsu=http://test.org/UA/Data/ ;ns=2;i=10305",   // /Data.Static.Array.Int32Value
                        UAIndexRangeList.OneDimension(2, 4)));
            }
            catch (UAException uaException)
            {
                Console.WriteLine("*** Failure: {0}", uaException.GetBaseException().Message);
                return;
            }

            // Cast to typed array
            var arrayValue = (Int32[]) value;

            // Display results
            for (int i = 0; i < 3; i++)
                Console.WriteLine("arrayValue[{0}]: {1}", i, arrayValue[i]);


            // Example output:
            //arrayValue[0]: 180410224
            //arrayValue[1]: 1919239969
            //arrayValue[2]: 1700185172
        }
    }
}
// This example shows how to subscribe to range of values from an array.
//
// 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 OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace UACommonDocExamples._UAIndexRangeList
{
    partial class Usage
    {
        public static void Subscribe()
        {
            UAEndpointDescriptor endpointDescriptor =
                "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
            // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
            // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

            // Instantiate the client object
            var client = new EasyUAClient();

            Console.WriteLine("Subscribing to range...");
            var attributeArguments = new UAAttributeArguments(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10933")
                {
                    IndexRangeList = UAIndexRangeList.OneDimension(2, 4)
                };
            var monitoredItemArguments = new UAMonitoredItemArguments(attributeArguments, monitoringParameters:1000);
            // The callback is a lambda expression the displays the value
            client.SubscribeMonitoredItem(monitoredItemArguments,
                (sender, eventArgs) =>
                {
                    if (eventArgs.Succeeded)
                    {
                        var arrayValue = eventArgs.AttributeData.Value as Int32[];
                        if (!(arrayValue is null))
                            Console.WriteLine($"Value: {{{String.Join(",", arrayValue)}}}");
                    }
                    else
                        Console.WriteLine($"*** Failure: {eventArgs.ErrorMessageBrief}");
                });

            Console.WriteLine("Processing data change events for 10 seconds...");
            System.Threading.Thread.Sleep(10 * 1000);

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

            Console.WriteLine("Waiting for 2 seconds...");
            System.Threading.Thread.Sleep(2 * 1000);
        }
    }
}
// Shows how to create an observable for a range of OPC UA array elements, and subscribe to it.
//
// 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 OpcLabs.EasyOpc.UA.Reactive;
using System;
using System.Threading;
using OpcLabs.EasyOpc.UA;
using OpcLabs.EasyOpc.UA.OperationModel;

namespace ReactiveDocExamples
{
    namespace _UADataChangeNotificationObservable
    {
        partial class Subscribe
        {
            public static void IndexRangeList()
            {
                // Define which server we will work with.
                UAEndpointDescriptor endpointDescriptor =
                    "opc.tcp://opcua.demo-this.com:51210/UA/SampleServer";
                // or "http://opcua.demo-this.com:51211/UA/SampleServer" (currently not supported)
                // or "https://opcua.demo-this.com:51212/UA/SampleServer/"

                Console.WriteLine("Creating observable...");
                var attributeArguments = new UAAttributeArguments(endpointDescriptor, "nsu=http://test.org/UA/Data/ ;i=10933")
                {
                    IndexRangeList = UAIndexRangeList.OneDimension(2, 4)
                };
                var monitoredItemArguments = new UAMonitoredItemArguments(attributeArguments, monitoringParameters: 1000);
                UADataChangeNotificationObservable<Int32[]> observable =
                    UADataChangeNotificationObservable.Create<Int32[]>(monitoredItemArguments);

                Console.WriteLine("Subscribing...");
                using (observable.Subscribe(e => Console.WriteLine(
                    (e.Exception is null) ? e.AttributeData.ToString() : e.Exception.GetBaseException().ToString())))
                {
                    Console.WriteLine("Waiting for 10 seconds...");
                    Thread.Sleep(10*1000);

                    Console.WriteLine("Unsubscribing...");
                }

                Console.WriteLine("Waiting for 2 seconds...");
                Thread.Sleep(2 * 1000);
            }
        }
    }
}
Inheritance Hierarchy

System.Object
   System.Collections.Generic.List<T>
      OpcLabs.EasyOpc.UA.UAIndexRangeList

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