OPC UA Connector

The OPC UA Connector module connects UA Office Link to OPC UA servers. Data can be received from the OPC UA Connector to, for example, store data into databases via the ODBC connector and data can be sent to the OPC UA connector from the same or a different connector. You can, for example, transfer data from a database to OPC UA servers or transfer data between OPC UA servers.

After installation, you’ll find the OPC UA Connector listed in the UA Office Link Desktop application.

../_images/main-opcuaconnector.png

OPC UA I/O Function Library

The OPC UA I/O Dynamic Link Library for Microsoft Windows serves as a drop-in replacement for OPC Office Link’s RisOpcIO library for OPC DA Classic. Use the library in your own applications to very quickly communicate with OPC UA servers to read or write data. Follow these steps to use the OPC UA I/O library instead of the RisOpcIO library.

  1. Install UA Office Link
    Run the UA Office Link installer on the machine where you want to use the OPC UA I/O library and ensure that that the OPC UA Connector is included. The OPC UA I/O library is installed together with the OPC UA connector.
  2. Add OPC UA server(s)
    Use the UA Office Link Desktop application to add OPC UA servers that you wish to communicate with. As usually required for OPC UA clients, you will need to create or import an UA Office Link application certificate and ensure that the OPC UA server trusts the UA Office Link certificate and vice versa. If your OPC UA server requires authentication then you will need to allow UA Office Link to store credentials for use by the OPC UA I/O library.
  3. Map data points
    The RisOpcIO library addresses OPC DA servers by name (the ‘Program ID’) or by name, GUID (globally unique identifier) and host name if a remote OPC server is used; data points are identified by the OPC Item ID. In contrast, the OPC UA I/O library identifies OPC UA servers by the name given to the OPC UA server in the UA Office Link Desktop application and the data points are identified by an expanded form of the OPC UA Node ID that includes the namespace URI (see the following sections for a further explanation). You need to identify the OPC UA data points that correspond to the OPC DA data points used in the RisOpcIO library and then replace OPC DA server names with OPC UA server names and OPC DA Item IDs with corresponding OPC UA Node IDs. This, of course, assumes that the same underlying data points are accessible by OPC UA servers.
  4. Reference the OPC UA I/O library
    The OPC UA I/O library is call-compatible with the RisOpcIO library and you can reference the ‘Rensen.OpcUa.IO.dll’ instead of the ‘RisOpcIo.dll’.

Note

Note that the OPC UA I/O library has the same architecture (32-bit) and limitations (use of ANSI OPC server names, group names and item IDs) as the original RisOpcIO library. Please contact support@ris.co.nz for 64-bit or Unicode versions. Note also that the OPCCopy function is no longer supported.

OPC UA I/O Functions

Function signatures

The following function signatures are suitable for use in, for example, Microsoft Excel VBA modules. Other programming languages that allow loading of an external DLL module may use the OPC UA I/O library by using their own language specific signatures.

Function results

All functions return an Integer error code, the error codes are listed at the end of the chapter. An error code of zero means that the function call was successful. Many functions take the OPC UA server name as a parameter. This is the OPC UA server name that you see in the UA Office Link Desktop application window.

Passing OPC UA Node IDs

OPC UA Servers identify individual nodes by a namespace URI and a further identifier. While an OPC Client has a session with an OPC server a namespace index can be used instead of the URI, however, between OPC server re-starts or between client sessions, the OPC server’s namespace indices may change and a persistent reference to an OPC UA node must therefore contain the namespace URI and not the namespace index. The OPC UA I/O library therefore expects definition of OPCNodeIds as a string in the form

nsu=namespaceUri;i=1234

The i element refers to a numeric identifier. Other valid OPC UA identifiers (i.e. s for string identifers, g for GUID identifiers and b for opaque identifers are also acceptable)

Tip

Use the OPCLockServer and OPCUnlockServer functions for any repeated read or write operations to avoid re-establishing OPC UA client sessions for each call.

OPC Item Functions

OPCRead

This function reads the specified OPCNodeId from the specified OPC server. If the function succeeds, then the value read is stored in Value.

Public Declare Function OPCRead Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCNodeId As String,
    ByRef Value As Variant
) As Integer

OPCWrite

The function writes Value to the specified OPCNodeId using the specified OPC server.

Public Declare Function OPCWrite Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCNodeId As String,
    ByRef Value As Variant
) As Integer

OPCCopy

This function is not supported in the OPC UA I/O library and will always return an unspecified error.

Public Declare Function OPCCopy Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCNodeId As String
) As Integer

OPC Server Functions

These functions manage OPC server connections. Call the OPCGetLastError function after a library function has returned an error code to obtain additional error information. Note that OPCLockServer simply keeps a connection to the OPC server alive; other OPC clients can still access the OPC server as usual.

OPCLockServer

If you intend to read and write a number of OPC items, call this function to keep an OPC server connection alive for faster execution. A call to OPCLockServer must be followed by OPCUnlockServer when the read/write operations are done.

Public Declare Function OPCLockServer Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String
) As Integer

OPCUnlockServer

OPCUnlockServer releases an OPC server connection previously locked in memory by OPCLockServer.

Public Declare Function OPCUnlockServer Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String
) As Integer

OPCLockRemoteServer

The function is maintained for backward compatibility. The GuidStr and RemoteHostName parameters are ignored and the function behaves like OPCLockServer.

Public Declare Function OPCLockRemoteServer Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal GuidStr As String,
    ByVal RemoteHostName As String
) As Integer

OPCUnlockRemoteServer

The function is maintained for backward compatibility and behaves like OPCUnlockServer.

Public Declare Function OPCUnlockRemoteServer Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String
) As Integer

OPCGetLastError

Call this function in case any of the other functions has returned an error. This will retrieve additional error information (if available).

Public Declare Function OPCGetLastError Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByRef ErrorMsg As Variant
) As Integer

OPC Group Functions

OPC group functions allow efficient reading or writing of multiple items over a period of time.

OPCAddGroup

Use this function to create a group containing multiple items. Before you can add groups to the OPC server identified by OPCServerName, you must call OPCLockServer or OPCLockRemoteServer for the OPC server. The OPCGroupName can be any name of your choice; the name is used to identify the group in other functions. The OPCNodeIds must be passed as a variant containing an array of string-type variants (the string identifying the OPC item); this data type corresponds directly to the Excel Range value type.

Public Declare Function OPCAddGroup Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCGroupName As String,
    ByRef OPCNodeIds As Variant
) As Integer

OPCReadGroup

Call this function to read values for all items within a group. You must have previously called OPCAddGroup with a group name of OPCGroupName. Values is a variant that contains an array of variants (OPC item values read are stored into these variants); this data type corresponds directly to the Excel Range value type.

Public Declare Function OPCReadGroup Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String,
    ByRef Values As Variant
) As Integer

OPCWriteGroup

Call this function to write values for all items within a group. You must have previously called OPCAddGroup with a group name of OPCGroupName. Values are passed as a variant that contains an array of variants (containing the values to write); this data type corresponds directly to the Excel Range value type.

Public Declare Function OPCWriteGroup Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String,
    ByRef Values As Variant
) As Integer

OPCRemoveGroup

Call this function when the group is no longer needed, passing the group name as a parameter.

Public Declare Function OPCRemoveGroup Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String
) As Integer

OPCGroupEnableCacheReads

By default the OPCReadGroup function requests data synchronously from the OPC server. By calling OPCGroupEnableCacheReads the OPC server is asked to check for data updates in regular intervals (as given by CacheUpdateRateMilliSeconds) and then send data only when it changes. An internal cache is maintained to keep the latest data available for requests. Subsequently, calls to OPCReadGroup will read OPC item values from the internal cache instead of sending requests to the OPC server. Enabling cache reads can be very efficient if group values are read on a regular basis.

Public Declare Function OPCGroupEnableCacheReads Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String,
    ByVal CacheUpdateRateMilliSeconds As Integer
) As Integer

OPCGroupDisableCacheReads

This function disables cache reads for the group referenced by OPCGroupName and subsequent calls to OPCReadGroup will query the OPC Server synchronously.

Public Declare Function OPCGroupDisableCacheReads Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String
) As Integer

Extended Functions

OPCReadEx

Similar to OPCRead; this function additionally returns the quality and timestamp of the item.

Public Declare Function OPCReadEx Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCNodeId As String,
    ByRef Value As Variant,
    ByRef Quality As Variant,
    ByRef Timestamp As Variant
) As Integer

OPCReadGroupEx

Similar to OPCReadEx, additionally read qualities and timestamps of all group items. You can pass empty variants.

Public Declare Function OPCReadGroupEx Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String,
    ByRef Values As Variant,
    ByRef Quality As Variant,
    ByRef Timestamp As Variant
) As Integer

OPCGetItemInfo

Reads type information and access rights of the item. Returned type numbers are number codes according to Microsoft’s VARIANT types; access rights are item access right number codes according to the OPC specification.

Public Declare Function OPCGetItemInfo Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCServerName As String,
    ByVal OPCNodeId As String,
    ByRef ItemType As Variant,
    ByRef ItemAccessRight As Variant
) As Integer

OPCGetGroupItemsInfo

Similar to OPCGetItemInfo; the function returns item IDs, types and access rights for all group items. You can pass empty variants.

Public Declare Function OPCGetGroupItemsInfo Lib "Rensen.OpcUa.IO.dll" (
    ByVal OPCGroupName As String,
    ByRef ItemIds As Variant,
    ByRef ItemTypes As Variant,
    ByRef ItemAccessRigths As Variant
) As Integer

Tip

The most efficient way to read or write multiple OPC items over a period of time is as follows:

  • Call OPCLockServer once for each OPC server.
  • Call OPCAddGroup once for each group.
  • Call OPCGroupEnableCacheReads once for each group.
  • Repeat calls to OPCReadGroup or OPCWriteGroup as desired
  • Call OPCRemoveGroup for reach group.
  • Finally, call OPCUnlockServer once for each OPC server.

Error Codes

All library functions return one of the following Integer error codes.

Code Error
0 No error
-1 Out of memory
-2 OPC server not found
-3 Failed to create OPC server
-4 Failed to create OPC group
-5 Failed to create OPC item
-6 Unused
-7 OPC item read error
-8 OPC item write error
-10 General Error
-11 Duplicate Group
-12 OPCLockServer or OPCLockRemoteServer not called
-13 Invalid parameter or parameter type
-14 Group not found
-15 Group item value count different from group item count
-16 OPC server does not support a required interface
-17 OPC server call failed