The HDA Client toolkit dll takes care of all the details necessary to interface to OPC Historical Data Access Servers. INteraction with the dll is by means of a simply API to select and read items based on selected timestamps. The demo version of the dll, (available below), allows you to create a complete working HDA Client solution for your custom application without cost or obligation. The API is fully documented and supported. After you have successfully integrated your application with the dll, and are satisfied that it works to your satisfaction, you may purchase a developer's license for the toolkit to remove the time limit. (The demo version of the dll will time-out after 30 minutes of operation.) The complete working source code for the dll is also available.
The WinTECH Software Rapid HDA Client Development DLL, (WtHDAClient), provides an easy to use API for integrating a custom application with data from any OPC HDA Server. All the details of DCOM, OPC and HDA are handled by the DLL, which allows an application to easily obtain data points from a Server, without having to be concerned with the actual implementation of the underlying interfaces. The DLL may be easily integrated with existing applications, or new ones. All required OPC HDA Interfaces are supported.
WtHDAclient.lib contains the export definitions for the DLL’s API. Include this file with the project files for the custom application and include WtHDAclientAPI.h with those modules which will be making calls into the DLL. If programming in Visual Basic, include the module1.bas from the VBA_example, (supplied with the demo), into your project.
WtHDAclient.dll exports two functions that allow the controlling application to obtain a list of available HDA Servers. The first function scans the Windows Registry on either the local or remote machine, (specified by the MachineName argument), to obtain the list of installed HDA Servers.
int NumberOfHDAServers (LPCSTR MachineName);
Once the number of servers has been returned from WtHDAclient.dll, the application can iterate through the list of names by calling:
BOOL GetHDAServerName (int index, LPSTR Buffer, int BufSize);
A user supplied character buffer receives a name from the Server list as identified by a passed index. BufSize identifies the length of the user supplied character buffer and prevents the dll from loading a name that's too long. GetHDAServerName returns TRUE if a valid Server name is returned in Buffer, otherwise the return value is FALSE.
HANDLE ConnectHDA(LPCSTR MachineName, LPCSTR ServerName);
This function returns a valid HANDLE if a connection could be established to the HDA Server defined by MachineName and ServerName. Multiple simultaneous connections to different servers may be established, and the returned HANDLE identifies the connection for future calls to create groups and items. Passing a Null String as the MachineName parameter identifies the local machine.
void PASCAL FAR DisconnectHDA(HANDLE hConnect);
When an application terminates, it is responsible for disconnecting from an attached Server. The DisconnectHDA() function will provide a clean shutdown of the connection defined by hConnect.
int NumberOfHDAItems(HANDLE hConnect);
BOOL GetHDAItemName (HANDLE hConnect, int index, char *pBuf, int BufSize);
These two functions operate similarly to those which allow you to obtain the list of Server names. NumberOfHDAItems() returns the total number of unique tags supported by a connected Server. Incrementally calling GetHDAItemName will step through all the available tag names to allow the controlling application to select an item or present a Browse list to the user. NumberOfHDAItems will browse the complete list of item names from the server and present the list in a ‘FLAT’ format.
HANDLE GetHDAItemHandle (HANDLE hConnect, LPCSTR ItemName, DWORD ClientHandle);
BOOL ReleaseHDAItemHandle (HANDLE hConnect, HANDLE hServer);
These two functions allow the application to obtain and release the server handle for an HDA item tag. The handle is used in subsequent calls to read and write item values.
DWORD ReadHDAItemValues (HANDLE hConnect, HANDLE hItem, BOOL GetBoundingValues, FILETIME Start, FILETIME End, DWORD MaxValues, FILETIME *pTimeStamps, VARIANT *pValues, DWORD *pQualities);
The application can read data items from the HDA server between the specified Start & End times. hConnect specifies the Server. hItem is that returned from GetHDAItemHandle. If GetBoundingValues is TRUE the server will return the item value at or immediately prior to the Start time and the value at or immediately following the End time. Values are returned in the three arrays supplied by the user up to MaxValues. The return value contains the number of items read from the server. If the most significant bit of the return value is set, it indicates that more data was available from the server than would fit in the allocated buffers.
int NumberOfHDAAttributes (HANDLE hConnect);
BOOL GetHDAAttributeDescr (HANDLE hConnect, int index, DWORD *pAttrId, VARTYPE *pVT, char *pNameBuf,
int nBufSize, char *pDescBuf, int dBufSize);
These two functions may be used to obtain the list of HDA Item Attributes from the connected server. NumberOfHDAAttributes returns the number of attributes supported by the server and the description of each attribute may be obtained by calling GetHDAAttributeDescr. This function returns the attribute name, description, Id, and Variant Type in the user supplied buffers. TRUE is returned if the function is successful, otherwise FALSE.
DWORD ReadHDAItemAttributes (HANDLE hConnect, HANDLE hItem, DWORD AttrID, FILETIME Start, FILETIME End, DWORD MaxValues, FILETIME *pTimeStamps, VARIANT *pValues);
If the connected server supports archiving of item attribute values, the client application may retrieve historical data using the ReadHDAItemAttributes function. Start & End specify the time period of interest. The user supplied buffers, (pTimeStamps & pValues), will be filled with data from the serevr corresponding to the selected item and Attribute identification. The number of item attributes actually read will be returned. If the most significant bit of the return value is set, it indicates that more data was available than would fit in the allocated buffer space, (defined by MaxValues).
int NumberOfHDAAggregates (HANDLE hConnect);
BOOL GetHDAAggregateDescr (HANDLE hConnect, int index, DWORD *pAggrId, char *pNameBuf,
int nBufSize, char *pDescBuf, int dBufSize);
These two functions may be used to obtain the list of HDA Item Aggregates from the connected server. NumberOfHDAAggregates returns the number of aggregates supported by the server and the description of each aggregate may be obtained by calling GetHDAAggregateDescr. This function returns the aggregate name, description, and Id in the user supplied buffers. TRUE is returned if the function is successful, otherwise FALSE.
DWORD ReadHDAProcessedItemValues (HANDLE hConnect, HANDLE hItem, DWORD AggregateID, FILETIME Start, FILETIME End, FILETIME ReSampleInterval, DWORD MaxValues, FILETIME *pTimeStamps, VARIANT *pValues, DWORD *pQualities);
The client application may obtain calculated values from the server by calling ReadHDAProcessedItemValues with the selected item and aggregate identifications. Start and End times specify the time period of interest and ReSampleInterval determines the individual time periods over which to perform the calculations. Values returned from the server will be stored in the user-supplied buffers, (pTimeStamps, pValues, & pQualities), up to the maximum number of values specified by MaxValues. The return value for this function returns the actual number of values returned. If the most significant bit of the return value is set, it indicates that more data was available than would fit in the allocated buffer space, (defined by MaxValues).
Last Updated: Feb 13, 2006
Return to
WinTECH Automation Apps..