OPC Studio User's Guide and Reference
ReadMultipleItems Method (_EasyDAClient)
Example 



View with Navigation Tools
OpcLabs.EasyOpcClassic Assembly > OpcLabs.EasyOpc.DataAccess.ComTypes Namespace > _EasyDAClient Interface : ReadMultipleItems Method
Array of arguments, one element per each OPC item involved in the operation.

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

The individual elements of the parameter value cannot be null (Nothing in Visual Basic).

Reads multiple named items from an OPC server or OPC servers, using array of argument objects as an input. Values, qualities and timestamps are returned.
Syntax
'Declaration
 

<NotNullAttribute()>
Function ReadMultipleItems( _
   ByVal argumentsArray As Object _
) As Object()
 
'Usage
 

Dim instance As _EasyDAClient
Dim argumentsArray As Object
Dim value() As Object
 
value = instance.ReadMultipleItems(argumentsArray)

Parameters

argumentsArray
Array of arguments, one element per each OPC item involved in the operation.

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

The individual elements of the parameter value cannot be null (Nothing in Visual Basic).

Return Value

The function returns an array of OpcLabs.EasyOpc.DataAccess.OperationModel.DAVtqResult objects. The indices of elements in the output array are the same as those in the input array, argumentsArray.

This method never returns null (Nothing in Visual Basic).

The individual elements of the returned value are never null (Nothing in Visual Basic).

Exceptions
ExceptionDescription
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.

Remarks

The ReadMultipleItems method uses the first available data from the server for each item; it does not wait until the quality becomes "uncertain" or "good". The function performs all individual operations in parallel, but only returns after all individual operations are completed (or their timeouts elapse).

This method does not throw an exception in case of OPC operation failures. Instead, the eventual exception related to each item is returned in Exception property of each returned OpcLabs.EasyOpc.DataAccess.OperationModel.DAVtqResult element.

The size of the input array will become the size of the output array. The element positions (indices) in the output array are the same as in the input array.

This member or type is for use from COM. It is not meant to be used from .NET or Python. Refer to the corresponding .NET member or type instead, if you are developing in .NET or Python.

The server(s) can be local or can be remotely accessed via DCOM.

Optionally, a specific data type can be requested, or an access path can be specified (OPC DA 1.0 only).

This method operates on multiple items at once. If you only have one item, you can use the ReadItem(IEasyDAClient,DAReadItemArguments) method instead.

Example

COM

COM

COM

COM

COM

COM

COM

// This example shows how to read 4 items from an OPC XML-DA server at once, and display their values, timestamps
// and qualities.
//
// 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 ReadMultipleItems.MainXml;
var
  Arguments: OleVariant;
  Client: OpcLabs_EasyOpcClassic_TLB._EasyDAClient;
  I: Cardinal;
  ReadItemArguments1: _DAReadItemArguments;
  ReadItemArguments2: _DAReadItemArguments;
  ReadItemArguments3: _DAReadItemArguments;
  ReadItemArguments4: _DAReadItemArguments;
  VtqResult: _DAVtqResult;
  Results: OleVariant;
begin
  ReadItemArguments1 := CoDAReadItemArguments.Create;
  ReadItemArguments1.ServerDescriptor.UrlString := 'http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx';
  ReadItemArguments1.ItemDescriptor.ItemID := 'Dynamic/Analog Types/Double';

  ReadItemArguments2 := CoDAReadItemArguments.Create;
  ReadItemArguments2.ServerDescriptor.UrlString := 'http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx';
  ReadItemArguments2.ItemDescriptor.ItemID := 'Dynamic/Analog Types/Double[]';

  ReadItemArguments3 := CoDAReadItemArguments.Create;
  ReadItemArguments3.ServerDescriptor.UrlString := 'http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx';
  ReadItemArguments3.ItemDescriptor.ItemID := 'Dynamic/Analog Types/Int';

  ReadItemArguments4 := CoDAReadItemArguments.Create;
  ReadItemArguments4.ServerDescriptor.UrlString := 'http://opcxml.demo-this.com/XmlDaSampleServer/Service.asmx';
  ReadItemArguments4.ItemDescriptor.ItemID := 'SomeUnknownItem';

  Arguments := VarArrayCreate([0, 3], varVariant);
  Arguments[0] := ReadItemArguments1;
  Arguments[1] := ReadItemArguments2;
  Arguments[2] := ReadItemArguments3;
  Arguments[3] := ReadItemArguments4;

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

  TVarData(Results).VType := varArray or varVariant;
  TVarData(Results).VArray := PVarArray(
    Client.ReadMultipleItems(Arguments));

  // Display results
  for I := VarArrayLowBound(Results, 1) to VarArrayHighBound(Results, 1) do
  begin
      VtqResult := IInterface(Results[I]) as _DAVtqResult;
      if VtqResult.Exception <> nil then
      begin
        WriteLn('results[', i, '] *** Failure: ', VtqResult.ErrorMessageBrief);
        Continue;
      end;
      WriteLn('results[', i, '].Vtq.ToString(): ', VtqResult.Vtq.ToString);
  end;

  VarClear(Results);
  VarClear(Arguments);
end;
// This example shows how to read 4 items at once, and display their values, timestamps and qualities.
//
// 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 ReadMultipleItems.Main;
var
  Arguments: OleVariant;
  Client: OpcLabs_EasyOpcClassic_TLB._EasyDAClient;
  I: Cardinal;
  ReadItemArguments1: _DAReadItemArguments;
  ReadItemArguments2: _DAReadItemArguments;
  ReadItemArguments3: _DAReadItemArguments;
  ReadItemArguments4: _DAReadItemArguments;
  VtqResult: _DAVtqResult;
  Results: OleVariant;
begin
  ReadItemArguments1 := CoDAReadItemArguments.Create;
  ReadItemArguments1.ServerDescriptor.ServerClass := 'OPCLabs.KitServer.2';
  ReadItemArguments1.ItemDescriptor.ItemID := 'Simulation.Random';

  ReadItemArguments2 := CoDAReadItemArguments.Create;
  ReadItemArguments2.ServerDescriptor.ServerClass := 'OPCLabs.KitServer.2';
  ReadItemArguments2.ItemDescriptor.ItemID := 'Trends.Ramp (1 min)';

  ReadItemArguments3 := CoDAReadItemArguments.Create;
  ReadItemArguments3.ServerDescriptor.ServerClass := 'OPCLabs.KitServer.2';
  ReadItemArguments3.ItemDescriptor.ItemID := 'Trends.Sine (1 min)';

  ReadItemArguments4 := CoDAReadItemArguments.Create;
  ReadItemArguments4.ServerDescriptor.ServerClass := 'OPCLabs.KitServer.2';
  ReadItemArguments4.ItemDescriptor.ItemID := 'Simulation.Register_I4';

  Arguments := VarArrayCreate([0, 3], varVariant);
  Arguments[0] := ReadItemArguments1;
  Arguments[1] := ReadItemArguments2;
  Arguments[2] := ReadItemArguments3;
  Arguments[3] := ReadItemArguments4;

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

  TVarData(Results).VType := varArray or varVariant;
  TVarData(Results).VArray := PVarArray(
    Client.ReadMultipleItems(Arguments));

  // Display results
  for I := VarArrayLowBound(Results, 1) to VarArrayHighBound(Results, 1) do
  begin
      VtqResult := IInterface(Results[I]) as _DAVtqResult;
      if VtqResult.Succeeded then
        WriteLn('results(', i, ').Vtq.ToString(): ', VtqResult.Vtq.ToString)
      else
        WriteLn('results(', i, ') *** Failure: ', VtqResult.ErrorMessageBrief);
  end;

  VarClear(Results);
  VarClear(Arguments);
end;
Rem This example repeatedly reads a large number of items.
Rem
Rem Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
Rem OPC client and subscriber examples in VBScript on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBScript .
Rem Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
Rem a commercial license in order to use Online Forums, and we reply to every post.

Option Explicit

Const repeatCount = 10
Const numberOfItems = 1000

WScript.Echo "Creating array of arguments..."
Dim arguments(): ReDim arguments(numberOfItems - 1)
Dim i: For i = 0 To numberOfItems - 1
    Dim copy: copy = Int(i / 100) + 1
    Dim phase: phase = i Mod 100
    Dim itemId: itemId = "Simulation.Incrementing.Copy_" & copy & ".Phase_" & phase
    WScript.Echo itemId

    Dim ReadItemArguments: Set ReadItemArguments = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
    ReadItemArguments.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
    ReadItemArguments.ItemDescriptor.ItemID = itemId

    Set arguments(i) = ReadItemArguments
Next

Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.DataAccess.EasyDAClient")

Dim iRepeat: For iRepeat = 1 To repeatCount
    WScript.Echo "Reading items..."
    Dim results: results = Client.ReadMultipleItems(arguments)

    Dim successCount: successCount = 0
    For i = LBound(results) To UBound(results)
        Dim VtqResult: Set VtqResult = results(i)
        If VtqResult.Succeeded Then successCount = successCount + 1
    Next
    WScript.Echo "Success count: " & successCount
Next
Rem This example shows how to read 4 items at once synchronously, and display their values, timestamps and qualities.
Rem
Rem Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
Rem OPC client and subscriber examples in VBScript on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBScript .
Rem Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
Rem a commercial license in order to use Online Forums, and we reply to every post.

Option Explicit

Dim ReadItemArguments1: Set ReadItemArguments1 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments1.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments1.ItemDescriptor.ItemID = "Simulation.Random"

Dim ReadItemArguments2: Set ReadItemArguments2 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments2.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments2.ItemDescriptor.ItemID = "Trends.Ramp (1 min)"

Dim ReadItemArguments3: Set ReadItemArguments3 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments3.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments3.ItemDescriptor.ItemID = "Trends.Sine (1 min)"

Dim ReadItemArguments4: Set ReadItemArguments4 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments4.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments4.ItemDescriptor.ItemID = "Simulation.Register_I4"

Dim arguments(3)
Set arguments(0) = ReadItemArguments1
Set arguments(1) = ReadItemArguments2
Set arguments(2) = ReadItemArguments3
Set arguments(3) = ReadItemArguments4

Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.DataAccess.EasyDAClient")

' Specify that only synchronous method is allowed. By default, both synchronous and asynchronous methods are allowed, and 
' the component picks a suitable method automatically. Disallowing asynchronous method leaves only the synchronous method
' available for selection.
Client.InstanceParameters.Mode.AllowAsynchronousMethod = False

Dim results: results = Client.ReadMultipleItems(arguments)

Dim i: For i = LBound(results) To UBound(results)
    Dim VtqResult: Set VtqResult = results(i)
    If VtqResult.Succeeded Then
        WScript.Echo "results(" & i & ").Vtq.ToString(): " & VtqResult.Vtq.ToString()
    Else
        WScript.Echo "results(" & i & ") *** Failure: " & VtqResult.ErrorMessageBrief
    End If
Next
# This example shows how to read 2 items (first valid, second invalid), test for success of each read and display either 
# the DAVtq or the Exception.
#
# The Python for Windows (pywin32) extensions package is needed. Install it using "pip install pypiwin32".
# CAUTION: We now recommend using Python.NET package instead. Full set of examples with Python.NET is available!
#
# Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
import win32com.client

# Instantiate the client object
client = win32com.client.Dispatch('OpcLabs.EasyOpc.DataAccess.EasyDAClient') 

#
readItemArguments1 = win32com.client.Dispatch('OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments')
readItemArguments1.ServerDescriptor.ServerClass = 'OPCLabs.KitServer.2'
readItemArguments1.ItemDescriptor.ItemID = 'Simulation.Random'

readItemArguments2 = win32com.client.Dispatch('OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments')
readItemArguments2.ServerDescriptor.ServerClass = 'OPCLabs.KitServer.2'
readItemArguments2.ItemDescriptor.ItemID = 'UnknownItem'

arguments = [
    readItemArguments1,
    readItemArguments2,
    ]
results = client.ReadMultipleItems(arguments)

for i, vtqResult in enumerate(results):
    if vtqResult.Succeeded:
        print('results(' + str(i) + '): ' + str(vtqResult.Vtq))
    else:
        print('results(' + str(i) + ') *** Failure: ' + vtqResult.ErrorMessageBrief)

Rem This example attempts to read 3 items (first valid, second invalid, third valid again), and display their values, 
Rem timestamps and qualities. Without testing for a success, a run-time error occurs when accessing the Vtq property
Rem of a failed result.
Rem
Rem Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
Rem OPC client and subscriber examples in VBScript on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBScript .
Rem Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
Rem a commercial license in order to use Online Forums, and we reply to every post.

Option Explicit

Dim ReadItemArguments1: Set ReadItemArguments1 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments1.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments1.ItemDescriptor.ItemID = "Simulation.Random"

Dim ReadItemArguments2: Set ReadItemArguments2 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments2.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments2.ItemDescriptor.ItemID = "UnknownItem"

Dim ReadItemArguments3: Set ReadItemArguments3 = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
ReadItemArguments3.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
ReadItemArguments3.ItemDescriptor.ItemID = "Trends.Ramp (1 min)"

Dim arguments(2)
Set arguments(0) = ReadItemArguments1
Set arguments(1) = ReadItemArguments2
Set arguments(2) = ReadItemArguments3

Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.DataAccess.EasyDAClient")
Dim results: results = Client.ReadMultipleItems(arguments)

Dim i: For i = LBound(results) To UBound(results)
    ' This is an anti-example - you should not access the Vtq property without testing the success first!
    WScript.Echo "results(" & i & ").Vtq.ToString(): " & results(i).Vtq.ToString()
Next
Rem This example measures the time needed to read 2000 items all at once, and in 20 groups by 100 items.
Rem
Rem Find all latest examples here: https://opclabs.doc-that.com/files/onlinedocs/OPCLabs-OpcStudio/Latest/examples.html .
Rem OPC client and subscriber examples in VBScript on GitHub: https://github.com/OPCLabs/Examples-QuickOPC-VBScript .
Rem Missing some example? Ask us for it on our Online Forums, https://www.opclabs.com/forum/index ! You do not have to own
Rem a commercial license in order to use Online Forums, and we reply to every post.

Option Explicit

Const numberOfGroups = 100
Const itemsInGroup = 20
Dim totalItems: totalItems = numberOfGroups*itemsInGroup

Rem Make the measurements 10 times; note that first time the times might be longer.
Dim i: For i = 1 To 10

    Rem Pause - we do not want the component to use the values it has in memory
    WScript.Sleep 2*1000

    WScript.Echo
    WScript.Echo "Reading all items at once, and measuring the time..."
    Dim startTime1: startTime1 = Timer
    ReadAllAtOnce
    WScript.Echo "ReadAllAtOnce has taken (milliseconds): " & (Timer - startTime1)*1000

    Rem Pause - we do not want the component to use the values it has in memory
    WScript.Sleep 2*1000

    WScript.Echo
    WScript.Echo "Reading items in groups, and measuring the time..."
    Dim startTime2: startTime2 = Timer
    ReadInGroups
    WScript.Echo "ReadInGroups has taken (milliseconds): " & (Timer - startTime2)*1000
Next



Rem Read all items at once
Sub ReadAllAtOnce
    Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.DataAccess.EasyDAClient")

    Rem Create an array of item Ids for all items
    Dim arguments(): ReDim arguments(totalItems - 1)
    Dim index: index = 0
    Dim iLoop: For iLoop = 0 To numberOfGroups - 1
        Dim iItem: For iItem = 0 To itemsInGroup - 1
            Dim ReadItemArguments: Set ReadItemArguments = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
            ReadItemArguments.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
            ReadItemArguments.ItemDescriptor.ItemID = "Simulation.Incrementing.Copy_" & (iLoop + 1) & ".Phase_" & (iItem + 1)

            Set arguments(index) = ReadItemArguments
            index = index + 1
        Next
    Next

    Rem Perform the OPC read
    Dim results: results = Client.ReadMultipleItems(arguments)

    Rem Count successful results
    Dim successCount: successCount = 0
    Dim i: For i = LBound(results) To UBound(results)
        Dim VtqResult: Set VtqResult = results(i)
        If VtqResult.Succeeded Then successCount = successCount + 1
    Next

    If successCount <> totalItems Then
        WScript.Echo "Warning: There were some failures, success count is " & successCount
    End If
End Sub



Rem Read items in groups
Sub ReadInGroups
    Dim Client: Set Client = CreateObject("OpcLabs.EasyOpc.DataAccess.EasyDAClient")

    Dim successCount: successCount = 0
    Dim arguments(): ReDim arguments(itemsInGroup - 1)
    Dim iLoop: For iLoop = 0 To numberOfGroups - 1
        'WScript.Echo iloop

        Rem Create an array of item Ids for items in one group
        Dim iItem: For iItem = 0 To itemsInGroup - 1
            Dim ReadItemArguments: Set ReadItemArguments = CreateObject("OpcLabs.EasyOpc.DataAccess.OperationModel.DAReadItemArguments")
            ReadItemArguments.ServerDescriptor.ServerClass = "OPCLabs.KitServer.2"
            ReadItemArguments.ItemDescriptor.ItemID = "Simulation.Incrementing.Copy_" & (iLoop + 1) & ".Phase_" & (iItem + 1)
            Set arguments(iItem) = ReadItemArguments
        Next

        Rem Perform the OPC read
        Dim results: results = Client.ReadMultipleItems(arguments)

        Rem Count successful results (totalling to previous value)
        For iItem = LBound(results) To UBound(results)
            Dim VtqResult: Set VtqResult = results(iItem)
            If VtqResult.Succeeded Then successCount = successCount + 1
        Next
    Next

    If successCount <> totalItems Then
        WScript.Echo "Warning: There were some failures, success count is " & successCount
    End If
End Sub
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

_EasyDAClient Interface
_EasyDAClient Members

 

 

Copyright © 2004-2024 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.