ReadItem(IEasyDAClient,ServerDescriptor,DAItemDescriptor,DAReadParameters) Method

Reads a named item from an OPC server. Value, quality and timestamp are returned. Reads a named item using descriptor objects for the OPC server and OPC-DA item, and specifying read parameters such as the data source or value age.

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
<ExtensionAttribute()>
<NotNullAttribute()>
Public Overloads Shared Function ReadItem( _
   ByVal client As IEasyDAClient, _
   ByVal serverDescriptor As ServerDescriptor, _
   ByVal itemDescriptor As DAItemDescriptor, _
   ByVal readParameters As DAReadParameters _
) As DAVtq

'Usage
 
Dim client As IEasyDAClient
Dim serverDescriptor As ServerDescriptor
Dim itemDescriptor As DAItemDescriptor
Dim readParameters As DAReadParameters
Dim value As DAVtq
 
value = IEasyDAClientExtension.ReadItem(client, serverDescriptor, itemDescriptor, readParameters)

[Extension()]
[NotNull()]
public static DAVtq ReadItem( 
   IEasyDAClient client,
   ServerDescriptor serverDescriptor,
   DAItemDescriptor itemDescriptor,
   DAReadParameters readParameters
)

[Extension()]
[NotNull()]
public:
static DAVtq^ ReadItem( 
   IEasyDAClient^ client,
   ServerDescriptor^ serverDescriptor,
   DAItemDescriptor^ itemDescriptor,
   DAReadParameters^ readParameters
)

Parameters

client: The client object that will perform the operation.
serverDescriptor: The OPC server involved in the operation.
itemDescriptor: The OPC item involved in the operation.
readParameters: Read parameters, such as the data source or value age.

Return Value

If successful, the function returns a DAVtq object. The object contains the value, timestamp and quality of the OPC item requested.

Exceptions

Exception	Description
OpcLabs.EasyOpc.OperationModel.OpcException	Thrown when the OPC operation fails.
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 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.

The ReadItem method only waits for the first update from the server (or until the timeout elapses); it does not wait until the quality becomes "uncertain" or "good".

Example

CSharp
PowerShell
VB.NET

// This example shows how to read a single item, and display its value, timestamp and quality.

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

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

            DAVtq vtq;
            try
            {
                vtq = client.ReadItem("", "OPCLabs.KitServer.2", "Simulation.Random");
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }

            Console.WriteLine("Vtq: {0}", vtq);
        }
    }
}

# This example shows how to read a single item, and display its value, timestamp and quality.

#requires -Version 5.1
using namespace OpcLabs.EasyOpc.DataAccess
using namespace OpcLabs.EasyOpc.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

try {
    $vtq = [IEasyDAClientExtension]::ReadItem($client, "", "OPCLabs.KitServer.2", "Simulation.Random")
}
catch [OpcException] {
    Write-Host "*** Failure: $($PSItem.Exception.GetBaseException().Message)"
    return
}

Write-Host "Vtq: $($vtq)"

' This example shows how to read a single item, and display its value, timestamp and quality.

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

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

            Dim vtq As DAVtq
            Try
                vtq = client.ReadItem("", "OPCLabs.KitServer.2", "Simulation.Random")
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try

            Console.WriteLine("Vtq: {0}", vtq)
        End Sub
    End Class
End Namespace

CSharp
VB.NET

// Shows how different data types can be read, including rare types and arrays of values.

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

namespace DocExamples.DataAccess._EasyDAClient
{
    partial class ReadItem
    {
        // Instantiate the client object.
        static readonly EasyDAClient Client = new EasyDAClient();

        static void ReadAndDisplay(string itemId)
        {
            Console.WriteLine();
            Console.WriteLine("Reading \"{0}\"...", itemId);

            DAVtq vtq;
            try
            {
                vtq = Client.ReadItem("OPCLabs.KitServer.2", itemId);
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }
            Console.WriteLine("Vtq: {0}", vtq);
        }

        public static void DataTypes()
        {
            ReadAndDisplay("Simulation.Register_EMPTY");
            ReadAndDisplay("Simulation.Register_NULL");
            ReadAndDisplay("Simulation.Register_DISPATCH");

            ReadAndDisplay("Simulation.ReadValue_I2");
            ReadAndDisplay("Simulation.ReadValue_I4");
            ReadAndDisplay("Simulation.ReadValue_R4");
            ReadAndDisplay("Simulation.ReadValue_R8");
            ReadAndDisplay("Simulation.ReadValue_CY");
            ReadAndDisplay("Simulation.ReadValue_DATE");
            ReadAndDisplay("Simulation.ReadValue_BSTR");
            ReadAndDisplay("Simulation.ReadValue_BOOL");
            ReadAndDisplay("Simulation.ReadValue_DECIMAL");
            ReadAndDisplay("Simulation.ReadValue_I1");
            ReadAndDisplay("Simulation.ReadValue_UI1");
            ReadAndDisplay("Simulation.ReadValue_UI2");
            ReadAndDisplay("Simulation.ReadValue_UI4");
            ReadAndDisplay("Simulation.ReadValue_INT");
            ReadAndDisplay("Simulation.ReadValue_UINT");

            ReadAndDisplay("Simulation.ReadValue_ArrayOfI2");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfI4");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfR4");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfR8");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfCY");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfDATE");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfBSTR");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfBOOL");
            //ReadAndDisplay("Simulation.ReadValue_ArrayOfDECIMAL");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfI1");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI1");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI2");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI4");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfINT");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUINT");
        }
    }
}

' Shows how different data types can be read, including rare types and arrays of values.

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

Namespace DocExamples.DataAccess._EasyDAClient
    Partial Friend Class ReadItem
        Private Shared ReadOnly DAClient As New EasyDAClient()

        Private Shared Sub ReadAndDisplay(itemId As String)
            Console.WriteLine()
            Console.WriteLine("Reading ""{0}""...", itemId)

            Dim vtq As DAVtq
            Try
                vtq = DAClient.ReadItem("OPCLabs.KitServer.2", itemId)
            Catch opcException As OpcException
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message)
                Exit Sub
            End Try

            Console.WriteLine("Vtq.ToString(): {0}", vtq.ToString())
        End Sub

        Shared Sub DataTypes()
            ReadAndDisplay("Simulation.Register_EMPTY")
            ReadAndDisplay("Simulation.Register_NULL")
            ReadAndDisplay("Simulation.Register_DISPATCH")

            ReadAndDisplay("Simulation.ReadValue_I2")
            ReadAndDisplay("Simulation.ReadValue_I4")
            ReadAndDisplay("Simulation.ReadValue_R4")
            ReadAndDisplay("Simulation.ReadValue_R8")
            ReadAndDisplay("Simulation.ReadValue_CY")
            ReadAndDisplay("Simulation.ReadValue_DATE")
            ReadAndDisplay("Simulation.ReadValue_BSTR")
            ReadAndDisplay("Simulation.ReadValue_BOOL")
            ReadAndDisplay("Simulation.ReadValue_DECIMAL")
            ReadAndDisplay("Simulation.ReadValue_I1")
            ReadAndDisplay("Simulation.ReadValue_UI1")
            ReadAndDisplay("Simulation.ReadValue_UI2")
            ReadAndDisplay("Simulation.ReadValue_UI4")
            ReadAndDisplay("Simulation.ReadValue_INT")
            ReadAndDisplay("Simulation.ReadValue_UINT")

            ReadAndDisplay("Simulation.ReadValue_ArrayOfI2")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfI4")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfR4")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfR8")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfCY")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfDATE")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfBSTR")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfBOOL")
            'ReadAndDisplay("Simulation.ReadValue_ArrayOfDECIMAL");
            ReadAndDisplay("Simulation.ReadValue_ArrayOfI1")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI1")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI2")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUI4")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfINT")
            ReadAndDisplay("Simulation.ReadValue_ArrayOfUINT")
        End Sub
    End Class
End Namespace

CSharp

// This example shows how to read a single item from the device, and display its value, timestamp and quality.

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

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

            Console.WriteLine("Reading item...");
            DAVtq vtq;
            try
            {
                // DADataSource enumeration:
                // Selects the data source for OPC reads (from device, from OPC cache, or dynamically determined).
                // The data source (memory, OPC cache or OPC device) selection is based on the desired value age and
                // current status of data received from the server.

                vtq = client.ReadItem("OPCLabs.KitServer.2", "Simulation.Random", DADataSource.Device);
            }
            catch (OpcException opcException)
            {
                Console.WriteLine("*** Failure: {0}", opcException.GetBaseException().Message);
                return;
            }

            Console.WriteLine("Vtq: {0}", vtq);
        }
    }
}

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

IEasyDAClientExtension Class
IEasyDAClientExtension Members
Overload List