Access Historical Data

HDA Programming Overview

This section illustrates the basic steps to create an OPC Toolbox™ Historical Data Access (HDA) application by retrieving historical data from the Triangle Wave and Saw-toothed Wave signals provided by the Matrikon™ OPC Simulation Server.


To run the sample code in the following steps you need the Matrikon OPC Simulation Server on your local machine. For installation details, see Install an OPC DA or HDA Simulation Server for OPC Classic Examples. The code requires only minor changes to work with other servers.

Step 1: Locate Your OPC Historical Data Access Server

In this step, you obtain two pieces of information that the toolbox needs to uniquely identify the OPC Historical Data Access server that you want to connect to. You use this information when creating an OPC Historical Data Access (HDA) client object, described in Step 2: Create an OPC Historical Data Access Client Object.

The first piece of information is the host name of the server computer. The host name (a descriptive name like "HistorianServer" or an IP address such as qualifies that computer on the network, and is used by the OPC protocols to determine the available OPC servers on that computer. In any OPC Toolbox™ application, you must know the name of the OPC server's host, so that a connection with that host can be established. Your network administrator can provide a list of host names that provide OPC servers on your network. In this example, you will use localhost as the host name, because you will connect to the OPC server on the same machine as the client.

The second piece of information is the OPC server's server ID. Each OPC server on a particular host is identified by a unique server ID (also called the Program ID or ProgID), which is allocated to that server on installation. The server ID is a character vector, usually containing periods.

Although your network administrator can provide a list of server IDs for a particular host, you can query the host for all available OPC servers. Discover Available HDA Servers discusses how to query hosts from the command line.

Use the opchdaserverinfo function to query from the command line.

hostInfo = opchdaserverinfo('localhost')
hostInfo = 
             1x4 OPC HDA ServerInfo array:
index    Host                 ServerID          HDASpecification              Description                   
  1    localhost  Advosol.HDA.Test.3                 HDA1         Advosol HDA Test Server V3.0
  2    localhost  IntegrationObjects.OPCSimulator.1  HDA1         Integration Objects OPC DA DX HDA Simulator 2
  3    localhost  IntegrationObjects.OPCSimulator.1  HDA1         Integration Objects' OPC DA/HDA Server Simulator
  4    localhost  Matrikon.OPC.Simulation.1          HDA1         MatrikonOPC Server for Simulation and Testing

Examining the returned structure in more detail provides the server IDs of each OPC server.

allServers = {hostInfo.ServerID}
allServers =
Columns 1 through 3
	'Advosol.HDA.Test.3'  'IntegrationObjects.OPCSimulator.1'  'IntegrationObjects.OPCSimulator.1'
Column 4

Step 2: Create an OPC Historical Data Access Client Object

After determining the host name and server ID of the OPC server to connect to, create an OPC HDA client object. The client controls the connection status to the server, and stores events that occur from that server.

Use the opchda function, specifying the host name and Server ID arguments.

hdaClient = opchda('localhost','Matrikon.OPC.Simulation.1')
hdaClient =
OPC HDA Client localhost/Matrikon.OPC.Simulation.1:
          Host: localhost
      ServerID: Matrikon.OPC.Simulation.1
       Timeout: 10 seconds

        Status: disconnected

    Aggregates: -- (client is disconnected)
ItemAttributes: -- (client is disconnected)

For details on creating clients, see Create an OPC HDA Client Object.

Step 3: Connect to the OPC Historical Data Access Server

OPC Historical Data Access Client objects are not automatically connected to the server when they are created.

Use the connect function to connect an OPC HDA client object to the server at the command line.


Step 4: Retrieve Historical Data

Generate Historical Data

After connecting to the HDA server you can read historical data values for the Saw-toothed Waves.Real8 and Triangle Waves.Real8 items. The Matrikon Simulation Server stores data only for items that have been activated and read by an OPC Data Access client. For this reason, run this code to generate and automatically store data in the historian.

Enter the following at the command line:

da = opcda('localhost','Matrikon.OPC.Simulation.1');
grp = addgroup(da);
additem(grp,'Saw-toothed Waves.Real8');
additem(grp,'Triangle Waves.Real8');
logDuration = 2*60;
logRate = 0.2;
numRecords = ceil(logDuration./logRate);
grp.UpdateRate = logRate;
grp.RecordsToAcquire = numRecords;

Read a Value from the Historical Data Access Server

To read historical values from an HDA server for a particular time range, use the readRaw function. This function takes a list of items as well as a start and end time (demarcating the time span) for which historical data is required.

data = hdaClient.readRaw({'Saw-toothed Waves.Real8','Triangle Waves.Real8'},now-100000,now)
data = 
1-by-2 OPC HDA Data object:
        ItemID                 Value            Start TimeStamp           End TimeStamp              Quality        
Saw-toothed Waves.Real8  200 double values  2010-11-02 12:22:32.981  2010-11-02 12:23:13.363  1 unique quality [Raw]
Triangle Waves.Real8     199 double values  2010-11-02 12:22:33.141  2010-11-02 12:23:13.293  1 unique quality [Raw]


The retrieved historical data contains a Value, Timestamp, and Quality for each data point. To view these elements from the previous example, use the following instructions:


Step 5: Plot the Data

Use this code to generate the plot figure:

axis tight

Step 6: Clean Up

After using OPC Toolbox objects at the MATLAB® command line or from your own functions, you must remove them from the OPC Toolbox engine with the delete function. Note that when you delete a toolbox object, the children of that object are automatically removed from the toolbox engine.

clear hdaClient data

Details of OPC Toolbox object management are discussed in Delete Objects.