OPC Historical Data Access 1.20 Client communication protocol

Supported device types and versions
Communication line configuration
Communication station configuration
I/O tag configuration
The setting of the right strategy for data reading
DCOM configuration for connecting to remote OPC server
Errors and problems
Literature
Changes and modifications
Document revisions

Supported device types and versions

The protocol implements the client side of communication with OPC (OLE for Process Control) HDA (Historical Data Access) servers according to specifications OPC HDA ver. 1.20.

Communication line configuration

Communication line category: OPC Client.

OPC parameters:

• OPC Host: It is required only for "Remote" access, i.e. it is defined only for OPC server type "Remote" (string max. 50 characters). OPC HDA Server must be installed on a computer. You can enter the names according to UNC (Universal Naming Convention) (e.g. "\\server" or "server"), DNS domain names (e.g. "domain.com", "example.company.com") or IP address ("196.54.23.113").
• Backup Host: It is required only for "Remote" access. It is a backup OPC host. If it is defined, D2000 KOM tries to establish a communication alternately with OPC Host and Backup Host after a failure of communication.
• OPC Server: A name (ProgID) of OPC server (string max. 50 characters).
• Server Type: "InProc", "Local" or "Remote".

Communication line parameters

Following communication line parameters can be configured for protocol "OPC Historical Data Access 1.20 Client":

Communication station configuration

Communication protocol: OPC Historical Data Access 1.20.

This communication protocol does not require any address parameters for a station.

Station protocol parameters

You may configure the following station parameters:

Table 1

Keyword	Full name	Meaning	Unit	Default value
FULL_DEBUG	Full Debug	It turns the debug records on. It significantly increases the number of information about communication. We recommend activating it only when detecting problems and debugging communication.	YES/NO	NO
RCD	Reconnect/Reinitialisation Delay	Delay after the following failed operations: creating of items - GetItemHandles, reconnection to OPC HDA Server after it failed, was stopped or a network disconnect, creating of items after reconnection to OPC HDA Server.	sec	5
BNDS	Include Bounds	It sets the "Bounds" parameter (the reading of the threshold limits of interval even if they are beyond the interval) in synchronous/asynchronous reading of "raw" values.	YES/NO	NO
ASM	Async Mode	It sets an asynchronous mode of activity when data reading. See the chapter The setting of the right strategy for data reading.	YES/NO	NO
NVAL	Maximum number of values	It sets the parameter NumItems when synchronous/asynchronous reading of "raw" values. The implicit value 0 represents all values in the given interval. See the chapter Setting of the right strategy for data reading.	Positive integer number	0
RINTR	Resample Interval	It sets the value of "ResampleInterval" when synchronous/asynchronous reading of "processed" values. See the chapter Setting of the right strategy for data reading.	ddd hh:mi:ss	60 sec
UINTR	Update Interval	It sets the value of "UpdateInterval" in the callings "AdviseRaw" and "AdviseProcessed". See the chapter Setting of the right strategy for data reading.	ss.mss	1 sec
QERR	QERR Value	An integer value of "ERROR" status for conversion to the quaternary input Qi.	0,1,2,3	3
QOFF	QOFF Value	An integer value of "OFF" status for conversion to the quaternary input Qi.	0,1,2,3	2
QON	QON Value	An integer value of "ON" status for conversion to the quaternary input Qi.	0,1,2,3	1
QTRANS	QTRANS Value	An integer value of "TRANS" status for conversion to the quaternary input Qi.	0,1,2,3	0
OPCHQED	Map ExtraData as flag	Mapping of "Extra Data" OPC HDA flag of quality to the attributes of I/O tag value.	None, FA, FB, FC, FD, FE, FF, FG, FH, FI, FJ, FK, FL, FM, FN, FO, FP	None
OPCHQIN	Map Interpolated as flag	Mapping of "Interpolated" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQRA	Map Raw as flag	Mapping of "Raw" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQCA	Map Calculated as flag	Mapping of "Calculated" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQNB	Map NoBound as flag	Mapping of "No Bound" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQND	Map NoData as flag	Mapping of "No Data" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQDL	Map DataLost as flag	Mapping of "Data Lost" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQCO	Map Conversion as flag	Mapping of "Conversion" OPC HDA flag of quality to the attributes of I/O tag value.
OPCHQPA	Map Partial as flag	Mapping of "Partial" OPC HDA flag of quality to the attributes of I/O tag value.
OPCQFNS	Map NonSpecific as flag	Mapping of "Non Specific" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFLO	Map LocalOverride as flag	Mapping of "LocalOverride" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFCE	Map ConfigError as flag	Mapping of "Config Error" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFNC	Map NotConnected as flag	Mapping of "Not Connected" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFDF	Map DeviceFailure as flag	Mapping of "Device Failure" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFSF	Map SensorFailure as flag	Mapping of "Sensor Failure" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFLK	Map LastKnown as flag	Mapping of "Last Known" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFCF	Map CommFailure as flag	Mapping of "Comm Failure" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFOOS	Map OutOfService as flag	Mapping of "Out Of Service" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFWID	Map WaitingForInitData as flag	Mapping of "Waiting For Initial Data" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFLU	Map LastUsable as flag	Mapping of "Last Usable" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFSC	Map SensorCal as flag	Mapping of "Sensor Cal" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFEGUE	Map EGUExceeded as flag	Mapping of "EGU Exceeded" OPC DA flag of quality to the attributes of I/O tag value.
OPCQFSN	Map SubNormal as flag	Mapping of "Sub Normal" OPC DA flag of quality to the attributes of I/O tag value.

I/O tag configuration

I/O tag types: Ai, Ci, Di, Qi,  TiA, TiR, TxtI.

The address of the I/O tag requires to set "OPC Item ID" (string max. 200 characters).

Other required parameters ("OPC HDA Item Parameters") are:

• The selection between "Raw" and "Processed" type of value which is read.
• If you choose "Processed", then set also "Aggregate".
• The option "Async Advise" to permit the asynchronous continuous data acquisition.

The setting of the right strategy for data reading

OPC Historical Data Access is a specification that enables to read the historical data - either "raw" or "processed". Data may be read by the synchronous or asynchronous callings. The asynchronous interface enables also "advise" of required data, i.e. a periodical (see the parameter "Update Interval") sending of the current values from OPC HDA Server by the asynchronous call-back in a client - KOM process. The only required interface, according to the specification of OPC HDA, is "SyncRead" for the reading of "raw" data synchronously.

In D2000 KOM Process, the OPC HDA protocol is implemented in a way that enables the reading of archive data as effectively as possible, including the updating of the last values, so that it avoids combining "OPC Historical Access" protocol with "OPC Data Access" one. The GETOLDVAL tell command enables to trigger the reading of historical data in any time interval. The obtained data are saved to D2000 Archiv if the primary archive value was used for archiving of the particular I/O tag.

The current data may be acquired using two strategies:

1. Minimalist:
   It uses only the synchronous interface "SyncRead". According to the setting of station time parameters, the "ReadRaw" and "ReadProcessed" functions are called periodically. The required interval of values starts from the time of the last valid value up to the current time. If several values have been received in a given interval, the last value with the latest timestamp is considered to be a current value. The other values are sent as "old" values to the server and are stored in the D2000 Archiv.
2. Advise:
   It uses the functions of asynchronous interface "AsyncRead", "AdviseRaw", and "AdviseProcessed". OPC HDA Server sends the last valid data of "raw" or "processed" items in the period which is defined in the parameter "Update Interval". If no new value is in the defined interval, OPC HDA Server returns the "No Data" quality flag.

The "Async Mode" parameter enables setting a fully asynchronous mode, which uses only the "AsyncRead" interface. However, the asynchronous mode has some limitations, which is why we do not recommend it in these situations:

• When reading "raw" data asynchronously, repeated reading of data that could not be returned by a single call is not supported (the OPC_S_MOREDATA flag is returned).
• In asynchronous mode, the right timing of finishing the transaction of the GETOLDVAL command is not implemented. It causes an ineffective saving of received values by D2000 Archiv.

The OPC Historical Data Access protocol does not support the data writing (the interfaces "SyncUpdate" and "ReadUpdate"). Also, the "SyncAnnotations", "AsyncAnnotations", "Browser" and "Playback" interfaces are not supported.

DCOM configuration for connecting to remote OPC server

Remote browsing/local registration of OPC Server

Since the version 7.01.020 rel. 055 and higher, the D2000 KOM Process supports the acquisition of OPC Servers' GUIDs from ProgID on remote computers via DCOM interface with the help of OPCENUM utility (remote browsing). If the OPCENUM utility/windows service has been installed on a remote OPC server and the level of access rights enables remote browsing, the local registration of the OPC server is not necessary on the side of the client. The OPCENUM utility is a part of the "OPC Core Components Redistributable" package. You can find it on http://www.opcfoundation.org or as a part of OPC Server installation.

The registration of the OPC Server is not necessary on the side of the OPC client (D2000 KOM). However, if you decide to register it, you can use one of these two ways:

1. Some of the OPC Servers are supplied with a setup program to support the connection of OPC clients of "third parties" to the remote OPC Server. These programs are named for example "OPC Server Connect". After their installing, OPC Server (its ProgID) appears in the list of OPC Servers on the client computer. D2000 OPC Client will use this information only for getting of CLSID from ProgID (see the communication line configuration). The registered OPC Server, however, cannot be operated on the client-side.
2. Manual registration of OPC Server on the client side. Follow these steps:
   
   
   • Copy OPC Server (.exe file + necessary .dll files) into the auxiliary directory on the client PC.
   • Start a command line in this directory.
   • Register OPC Server. If OPC Server is named e.g. "OPCSERVER.EXE" on the disk, then write the command:
     "OPCSERVER.EXE /regserver"
     and press ENTER.
   • Delete the auxiliary directory.

Always read the instructions for installation OPC Server and check your steps with those stated in the manual.

The setting of access rights

The connection to the remote OPC Server is subject to the access right control of Windows. For this reason, the same user (together with the password) must be created on both the computer. On the OPC client side, the user must be logged on. On the OPC Server, the user must have certain access rights therefore follow these instructions:

• Start the program "DCOMCNFG" in the command line on a computer with OPC Server. Check, if DCOM is enabled - the "Enable Distributed COM on this computer" option.
• Find OPC Server in the list and open the "Properties" dialog window. Open the "Security" tab.
• Switch "Launch Permissions" to "Customize" and click the "Edit..." button.
• Check the particular user in the list or add him to it.
• Do the same for "Access Permissions".

Wrong setting of the access rights will probably cause an error (see the "COM/OPC error dump" chapter):

ERROR: ServerProgID caused COM/OPC error 80070005H on CoCreateInstanceEx(CLSCTX_REMOTE_SERVER), Error string : Access is denied.

Track records in the system Event Viewer.

You can avoid this problem, if you add a group "Everyone" to "Launch Permissions" and "Access Permissions". To ensure that the OPC Server will be started under the particular user account (and no under "SYSTEM account"), open the "Identity" tab and fill the data for "This user". In this case, you cannot consider OPC Server to be safely configured.

OPC Client (D2000 KOM) is not allowed to be started as "Windows service" with parameters "/X1" or "/X2", because then it does not work under the logged-on user but under  "SYSTEM account". Authentication of the access rights by the OPC Server will fail. Use a start parameter "/X4".

Read the instructions to OPC Server again and keep the producer recommendations.

For the user of WindowsXP (or higher) with SP2, we recommend changing the parameter "Network access: Let Everyone permissions apply to anonymous users" to "Enabled" in the settings "Local Security Policy/Security Options".

Errors and problems

The error messages, mentioned below, may occur during the start, or during communication. It is recommended to activate the monitoring of communication in the configuration of the line for easier identification of problems. You can choose it from these levels:

• Monitor (at least)
• Monitor & Disk (recommended)
• Disk (recommended)

When you set "Monitor & Disk" or "Disk", the file "line_name.LOG" occurs in the "Trace" subdirectory of the application directory on the computer with the running communication process. This file contains all the debug and error messages.

COM/OPC error dump

The error messages mentioned in the chapter "Errors and problems" are generated in a higher level of OPC client. Most of the mentioned errors will be described on COM/OPC level. The format of these error messages is as follows:

WARNING/ERROR: ServerProgID caused COM/OPC error ErrorCodeHexadecimal on CallDescription, Error string : ErrorDescription

Example:

ERROR: Matrikon.OPC.Simulation.1 caused COM/OPC error C0040008H on IOPCHDA_Server::ValidateItemIDs('ItemID'), Error string : OPC_E_INVALIDITEMID The item definition doesn't conform to the server's syntax.

These error messages are important for an analysis of the problem. If problems occur, they will be required by the technical support of the Ipesoft company.

Literature

The documents OPC Foundation may be found on http://www.opcfoundation.org/.

• OPC FOUNDATION, Historical Data Access Specification, Version 1.20, December 10, 2003.
• OPC FOUNDATION, OPC Common Definitions and Interfaces, Version 1.0, October 27, 1998.
• OPC FOUNDATION, Using OPC via DCOM with Microsoft Windows XP Service Pack 2, (C) 2004 OPC Foundation Inc.

Other:

• OPC DCOM White Paper, Richard C. Harrison, Intellution Inc. © Intellution Inc. 1998

Changes and modifications

• October 15, 2007 - document creating

Document revision

• Ver. 1.0 – October 15, 2007
• Ver. 1.1 - Feb 7th, 2021 - added parameter "Authentication Level"