WriteMultipleItemValues Method (IEasyDAClient)

Writes values into named items in an OPC server or OPC servers. Only the item values are written (qualities and timestamp are not written).

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
<ElementsNotNullAttribute()>
<NotNullAttribute()>
Function WriteMultipleItemValues( _
   ByVal argumentsArray() As DAItemValueArguments _
) As OperationResult()

'Usage
 
Dim instance As IEasyDAClient
Dim argumentsArray() As DAItemValueArguments
Dim value() As OperationResult
 
value = instance.WriteMultipleItemValues(argumentsArray)

[ElementsNotNull()]
[NotNull()]
OperationResult[] WriteMultipleItemValues( 
   DAItemValueArguments[] argumentsArray
)

[ElementsNotNull()]
[NotNull()]
array<OperationResult^>^ WriteMultipleItemValues( 
   array<DAItemValueArguments^>^ argumentsArray
)

Parameters

argumentsArray: Array of argument objects for the operation.

Return Value

The function returns an array of OpcLabs.BaseLib.OperationModel.OperationResult objects. The indices of elements in the output array are the same as those in the input arrays.

Exceptions

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

Remarks

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.

The server can be local or can be remotely accessed via DCOM. Optionally, an access path can be specified or a specific data type can be requested.

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.BaseLib.OperationModel.OperationResult element.

This is a multiple-operation method. In a properly written program, it does not throw any exceptions. You should therefore not put try/catch statements or similar constructs around calls to this method. The only exceptions thrown by this method are for usage errors, i.e. when your code violates the usage contract of the method, such as passing in invalid arguments or calling the method when the state of the object does not allow it. Any operation-related errors (i.e. errors that depend on external conditions that your code cannot reliably check) are indicated in the result objects returned by the method. For more information, see Multiple-operation Methods and Do not catch any exceptions with asynchronous or multiple-operation methods.

Example

CSharp
PowerShell
PHP
VB.NET

// Shows how to write into multiple OPC items using a single method call, and read multiple item values back.

using System;
using System.Diagnostics;
using OpcLabs.BaseLib.OperationModel;
using OpcLabs.EasyOpc.DataAccess;
using OpcLabs.EasyOpc.DataAccess.OperationModel;

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

            Console.WriteLine("Writing multiple item values...");
            OperationResult[] resultArray = client.WriteMultipleItemValues(
                new[] { 
                    new DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_I4", 12345),
                    new DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_BOOL", true),
                    new DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_R4", 234.56)
                });
            
            for (int i = 0; i < resultArray.Length; i++)
            {
                Debug.Assert(resultArray[i] != null);
                if (resultArray[i].Succeeded)
                    Console.WriteLine($"Result {i}: success");
                else
                {
                    Debug.Assert(!(resultArray[i].Exception is null));
                    Console.WriteLine($"Result {i} *** Failure: {resultArray[i].ErrorMessageBrief}");
                }
            }

            Console.WriteLine();
            Console.WriteLine("Reading multiple item values...");
            ValueResult[] valueResultArray = client.ReadMultipleItemValues("OPCLabs.KitServer.2",
                new DAItemDescriptor[] { 
                        "Simulation.Register_I4", 
                        "Simulation.Register_BOOL", 
                        "Simulation.Register_R4" });

            for (int i = 0; i < valueResultArray.Length; i++)
            {
                Debug.Assert(valueResultArray[i] != null);
                Console.WriteLine($"valueResultArray[{i}]: {valueResultArray[i]}");
            }


            // Example output:
            //
            //Writing multiple item values...
            //Result 0: success
            //Result 1: success
            //Result 2: success
            //
            //Reading multiple item values...
            //valueResultArray[0]: Success; 12345 {System.Int32}
            //valueResultArray[1]: Success; True {System.Boolean}
            //valueResultArray[2]: Success; 234.56 {System.Single}
        }
    }
}

# Shows how to write into multiple OPC items using a single method call, and read multiple item values back.

#requires -Version 5.1
using namespace OpcLabs.EasyOpc.DataAccess
using namespace OpcLabs.EasyOpc.DataAccess.OperationModel

# The path below assumes that the current directory is [ProductDir]/Examples-NET/PowerShell/Windows .
Add-Type -Path "../../../Assemblies/net47/OpcLabs.EasyOpcClassic.dll"

# Instantiate the client object.
$client = New-Object EasyDAClient

Write-Host "Writing multiple item values..."
$resultArray = $client.WriteMultipleItemValues(@(
    (New-Object DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_I4", 12345)),
    (New-Object DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_BOOL", $true)),
    (New-Object DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_R4", 234.56))
    ))

for ($i = 0; $i -lt $resultArray.Length; $i++) {
    $result = $resultArray[$i]
    if ($result.Succeeded) {
        Write-Host "Result $($i): success"
    }
    else {
        Write-Host "Result $($i) *** Failure: $($result.ErrorMessageBrief)"
    }
}

Write-Host 
Write-Host "Reading multiple item values..."
$valueResultArray = [IEasyDAClientExtension]::ReadMultipleItemValues($client, 
    "OPCLabs.KitServer.2", @(
        (New-Object DAItemDescriptor("Simulation.Register_I4")),
        (New-Object DAItemDescriptor("Simulation.Register_BOOL")),
        (New-Object DAItemDescriptor("Simulation.Register_R4"))
        ))

for ($i = 0; $i -lt $valueResultArray.Length; $i++) {
    $valueResult = $valueResultArray[$i]
    Write-Host "valueResultArray[$($i)]: $($valueResult)"
}


# Example output:
#
#Writing multiple item values...
#Result 0: success
#Result 1: success
#Result 2: success
#
#Reading multiple item values...
#valueResultArray[0]: Success; 12345 {System.Int32}
#valueResultArray[1]: Success; True {System.Boolean}
#valueResultArray[2]: Success; 234.56 {System.Single}

// This example shows how to write values into 3 items at once.

$ItemValueArguments1 = new COM("OpcLabs.EasyOpc.DataAccess.OperationModel.DAItemValueArguments");
$ItemValueArguments1->ServerDescriptor->ServerClass = "OPCLabs.KitServer.2";
$ItemValueArguments1->ItemDescriptor->ItemID = "Simulation.Register_I4";
$ItemValueArguments1->Value = 23456;

$ItemValueArguments2 = new COM("OpcLabs.EasyOpc.DataAccess.OperationModel.DAItemValueArguments");
$ItemValueArguments2->ServerDescriptor->ServerClass = "OPCLabs.KitServer.2";
$ItemValueArguments2->ItemDescriptor->ItemID = "Simulation.Register_R8";
$ItemValueArguments2->Value = 2.34567890;

$ItemValueArguments3 = new COM("OpcLabs.EasyOpc.DataAccess.OperationModel.DAItemValueArguments");
$ItemValueArguments3->ServerDescriptor->ServerClass = "OPCLabs.KitServer.2";
$ItemValueArguments3->ItemDescriptor->ItemID = "Simulation.Register_BSTR";
$ItemValueArguments3->Value = "ABC";

$arguments[0] = $ItemValueArguments1;
$arguments[1] = $ItemValueArguments2;
$arguments[2] = $ItemValueArguments3;

$Client = new COM("OpcLabs.EasyOpc.DataAccess.EasyDAClient");
$results = $Client->WriteMultipleItemValues($arguments);

for ($i = 0; $i < count($results); $i++)
{
    $OperationResult = $results[$i];
    if ($OperationResult->Succeeded)
        printf("Result %d: success\n", $i);
    else
        printf("Result  s\n", $i, $OperationResult->ErrorMessageBrief);
}

' This example shows how to write values into multiple items.

Imports OpcLabs.BaseLib.OperationModel
Imports OpcLabs.EasyOpc.DataAccess
Imports OpcLabs.EasyOpc.DataAccess.OperationModel

Namespace DocExamples.DataAccess._EasyDAClient
    Partial Friend Class WriteMultipleItemValues
        Public Shared Sub Main1()
            Dim client = New EasyDAClient()

            Dim argumentsArray = New DAItemValueArguments() { _
                New DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_I4", 12345), _
                New DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_BOOL", True), _
                New DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_R4", 234.56) _
            }

            Dim resultArray As OperationResult() = client.WriteMultipleItemValues(argumentsArray)

            For i = 0 To resultArray.Length - 1
                Debug.Assert(resultArray(i) IsNot Nothing)

                If resultArray(i).Succeeded Then
                    Console.WriteLine("Result {0}: success", i)
                Else
                    Console.WriteLine("Result {0} *** Failure: {1}", i, resultArray(i).ErrorMessageBrief)
                End If
            Next i

            Console.WriteLine("Reading multiple item values...")
            Dim valueResultArray() As ValueResult = client.ReadMultipleItemValues("OPCLabs.KitServer.2", _
                New DAItemDescriptor() { _
                    "Simulation.Register_I4",
                    "Simulation.Register_BOOL",
                    "Simulation.Register_R4"})

            For i = 0 To valueResultArray.Length - 1
                Debug.Assert(valueResultArray(i) IsNot Nothing)
                Console.WriteLine("valueResultArray[{0}]: {1}", i, valueResultArray(i))
            Next i

        End Sub
    End Class
End Namespace

CSharp
VB.NET

// Shows how to write into multiple OPC items using a single method call, specifying their requested data types.

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

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

            Console.WriteLine("Writing multiple item values...");
            OperationResult[] resultArray = client.WriteMultipleItemValues(new[] { 
                    new DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_I2", 12345) 
                        { ItemDescriptor = { RequestedDataType = VarTypes.I2}}, // <-- the requested data type
                    new DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_R4", 234.56)
                        { ItemDescriptor = { RequestedDataType = VarTypes.R4}}  // <-- the requested data type 
                });


            for (int i = 0; i < resultArray.Length; i++)
            {
                Debug.Assert(resultArray[i] != null);
                if (resultArray[i].Succeeded)
                    Console.WriteLine("Result {0}: success", i);
                else
                {
                    Debug.Assert(!(resultArray[i].Exception is null));
                    Console.WriteLine("Result {0} *** Failure: {1}", i, resultArray[i].ErrorMessageBrief);
                }
            }

            Console.WriteLine("Reading multiple item values...");
            ValueResult[] valueResultArray = client.ReadMultipleItemValues("OPCLabs.KitServer.2",
                new DAItemDescriptor[] { "Simulation.Register_I2", "Simulation.Register_R4" });

            for (int i = 0; i < valueResultArray.Length; i++)
            {
                Debug.Assert(valueResultArray[i] != null);
                Console.WriteLine("valueResultArray[{0}]: {1}", i, valueResultArray[i]);
            }
        }
    }
}

' Shows how to write into multiple OPC items using a single method call, specifying their requested data types.

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

Namespace DocExamples.DataAccess._EasyDAClient
    Partial Friend Class WriteMultipleItemValues
        Public Shared Sub RequestedDataType()
            Dim client = New EasyDAClient()

            Console.WriteLine("Writing multiple item values...")
            Dim resultArray = client.WriteMultipleItemValues(New DAItemValueArguments() { _
                New DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_I2", 12345) With _
                {.ItemDescriptor = New DAItemDescriptor() With {.RequestedDataType = VarTypes.I2}}, _
                New DAItemValueArguments("", "OPCLabs.KitServer.2", "Simulation.Register_R4", 234.56) With _
                {.ItemDescriptor = New DAItemDescriptor() With {.RequestedDataType = VarTypes.R4}} _
            })

            For i = 0 To resultArray.Length - 1
                Debug.Assert(resultArray(i) IsNot Nothing)
                If resultArray(i).Succeeded Then
                    Console.WriteLine("Result {0}: success", i)
                Else
                    Debug.Assert(resultArray(i).Exception IsNot Nothing)
                    Console.WriteLine("Result {0} *** Failure: {1}", i, resultArray(i).ErrorMessageBrief)
                End If
            Next i

            Console.WriteLine("Reading multiple item values...")
            Dim valueResultArray = client.ReadMultipleItemValues("OPCLabs.KitServer.2",
                    New DAItemDescriptor() {"Simulation.Register_I2", "Simulation.Register_R4"})

            For i = 0 To valueResultArray.Length - 1
                Debug.Assert(valueResultArray(i) IsNot Nothing)
                Console.WriteLine("valueResultArray[{0}]: {1}", i, valueResultArray(i))
            Next i
        End Sub
    End Class
End Namespace

CSharp
VB.NET

// This example measures the time needed to write 2000 item values all at once, and in 20 groups by 100 items.
// Note that the writes will currently all fail, as we do not have the appropriate writeable items available.

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

namespace DocExamples.DataAccess._EasyDAClient
{
    partial class WriteMultipleItemValues
    {
        const int NumberOfGroups = 100;
        const int ItemsInGroup = 20;
        private const int TotalItems = NumberOfGroups * ItemsInGroup;

        // Main method
        public static void TimeMeasurements()
        {
            // Make the measurements 10 times; note that first time the times might be longer.
            for (int i = 1; i <= 10; i++)
            {
                // Pause - we do not want the component to use the values it has in memory
                Thread.Sleep(2 * 1000);

                // Write all item values at once, and measure the time
                var stopwatch1 = new Stopwatch();
                stopwatch1.Start();
                WriteAllAtOnce();
                stopwatch1.Stop();
                Console.WriteLine("WriteAllAtOnce has taken (milliseconds): {0}", stopwatch1.ElapsedMilliseconds);

                // Pause - we do not want the component to use the values it has in memory
                Thread.Sleep(2 * 1000);

                // Write item values in groups, and measure the time
                var stopwatch2 = new Stopwatch();
                stopwatch2.Start();
                WriteInGroups();
                stopwatch2.Stop();
                Console.WriteLine("WriteInGroups has taken (milliseconds): {0}", stopwatch2.ElapsedMilliseconds);
            }
        }

        // Write all item values at once
        private static void WriteAllAtOnce()
        {
            // Instantiate the client object.
            var client = new EasyDAClient();

            // Create an array of arguments for all items
            var arguments = new DAItemValueArguments[TotalItems];
            int index = 0;
            for (int iLoop = 0; iLoop < NumberOfGroups; iLoop++)
                for (int iItem = 0; iItem < ItemsInGroup; iItem++)
                    arguments[index++] = new DAItemValueArguments(
                        "OPCLabs.KitServer.2",
                        String.Format("Simulation.Incrementing.Copy_{0}.Phase_{1}", iLoop + 1, iItem + 1),
                        0);

            // Perform the OPC write
            OperationResult[] operationResults = client.WriteMultipleItemValues(arguments);

            // Count successful results
            int successCount = 0;
            for (int iItem = 0; iItem < TotalItems; iItem++)
            {
                Debug.Assert(operationResults[iItem] != null);
                if (operationResults[iItem].Succeeded)
                    successCount++;
            }

            if (successCount != TotalItems)
                Console.WriteLine("Warning: There were some failures, success count is {0}", successCount);
        }

        // Write item values in groups
        private static void WriteInGroups()
        {
            var client = new EasyDAClient();

            int successCount = 0;
            for (int iLoop = 0; iLoop < NumberOfGroups; iLoop++)
            {
                // Create an array of item arguments for items in one group
                var arguments = new DAItemValueArguments[ItemsInGroup];
                for (int iItem = 0; iItem < ItemsInGroup; iItem++)
                    arguments[iItem] = new DAItemValueArguments(
                        "OPCLabs.KitServer.2",
                        String.Format("Simulation.Incrementing.Copy_{0}.Phase_{1}", iLoop + 1, iItem + 1),
                        0);

                // Perform the OPC write
                OperationResult[] operationResults = client.WriteMultipleItemValues(arguments);

                // Count successful results (totalling to previous value)
                for (int iItem = 0; iItem < ItemsInGroup; iItem++)
                {
                    Debug.Assert(operationResults[iItem] != null);
                    if (operationResults[iItem].Succeeded) successCount++;
                }
            }

            if (successCount != TotalItems)
                Console.WriteLine("Warning: There were some failures, success count is {0}", successCount);
        }
    }
}

' This example measures the time needed to write 2000 item values all at once, and in 20 groups by 100 items.
' Note that the writes will currently all fail, as we do not have the appropriate writeable items available.

Imports System.Threading
Imports OpcLabs.BaseLib.OperationModel
Imports OpcLabs.EasyOpc.DataAccess
Imports OpcLabs.EasyOpc.DataAccess.OperationModel

Namespace DocExamples.DataAccess._EasyDAClient
    Partial Friend Class WriteMultipleItemValues
        Private Const NumberOfGroups As Integer = 100
        Private Const ItemsInGroup As Integer = 20
        Private Const TotalItems As Integer = NumberOfGroups * ItemsInGroup

        ' Main method
        Public Shared Sub TimeMeasurements()
            ' Make the measurements 10 times; note that first time the times might be longer.
            For i As Integer = 1 To 10
                ' Pause - we do not want the component to use the values it has in memory
                Thread.Sleep(2 * 1000)

                '  Write all item values at once, and measure the time
                Dim stopwatch1 = New Stopwatch()
                stopwatch1.Start()
                WriteAllAtOnce()
                stopwatch1.Stop()
                Console.WriteLine("WriteAllAtOnce has taken (milliseconds): {0}", stopwatch1.ElapsedMilliseconds)

                ' Pause - we do not want the component to use the values it has in memory
                Thread.Sleep(2 * 1000)

                ' Write item values in groups, and measure the time
                Dim stopwatch2 = New Stopwatch()
                stopwatch2.Start()
                WriteInGroups()
                stopwatch2.Stop()
                Console.WriteLine("WriteInGroups has taken (milliseconds): {0}", stopwatch2.ElapsedMilliseconds)
            Next i
        End Sub

        '  Write all item values at once
        Private Shared Sub WriteAllAtOnce()
            Dim client = New EasyDAClient()

            ' Create an array of arguments for all items
            Dim arguments = New DAItemValueArguments(TotalItems - 1) {}
            Dim index As Integer = 0
            For iLoop As Integer = 0 To NumberOfGroups - 1
                For iItem As Integer = 0 To ItemsInGroup - 1
                    arguments(index) = New DAItemValueArguments(
                        "OPCLabs.KitServer.2",
                            String.Format("Simulation.Incrementing.Copy_{0}.Phase_{1}", iLoop + 1, iItem + 1),
                            0)
                    index += 1
                Next iItem
            Next iLoop

            ' Perform the OPC write
            Dim operationResults() As OperationResult = client.WriteMultipleItemValues(arguments)

            ' Count successful results
            Dim successCount As Integer = 0
            For iItem As Integer = 0 To TotalItems - 1
                Debug.Assert(operationResults(iItem) IsNot Nothing)
                If operationResults(iItem).Succeeded Then
                    successCount += 1
                End If
            Next iItem

            If successCount <> TotalItems Then
                Console.WriteLine("Warning: There were some failures, success count is {0}", successCount)
            End If
        End Sub

        ' Write item values in groups
        Private Shared Sub WriteInGroups()
            Dim client = New EasyDAClient()

            Dim successCount As Integer = 0
            For iLoop As Integer = 0 To NumberOfGroups - 1
                ' Create an array of item arguments for items in one group
                Dim arguments = New DAItemValueArguments(ItemsInGroup - 1) {}
                For iItem As Integer = 0 To ItemsInGroup - 1
                    arguments(iItem) = New DAItemValueArguments(
                            "OPCLabs.KitServer.2",
                            String.Format("Simulation.Incrementing.Copy_{0}.Phase_{1}", iLoop + 1, iItem + 1),
                            0)
                Next iItem

                ' Perform the OPC write
                Dim operationResults() As OperationResult = client.WriteMultipleItemValues(arguments)

                ' Count successful results (totalling to previous value)
                For iItem As Integer = 0 To ItemsInGroup - 1
                    Debug.Assert(operationResults(iItem) IsNot Nothing)
                    If operationResults(iItem).Succeeded Then
                        successCount += 1
                    End If
                Next iItem
            Next iLoop

            If successCount <> TotalItems Then
                Console.WriteLine("Warning: There were some failures, success count is {0}", successCount)
            End If
        End Sub
    End Class
End Namespace

Requirements

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

Reference

IEasyDAClient Interface
IEasyDAClient Members