OPC Toolbox 2

Users Guide

Downloaded from www.Manualslib.com manuals search engine

How to Contact The MathWorks

Web
Newsgroup
www.mathworks.com/contact_TS.html Technical Support
www.mathworks.com

comp.soft-sys.matlab

[email protected]
[email protected]
[email protected]
[email protected]
[email protected]

Product enhancement suggestions

Bug reports
Documentation error reports
Order status, license renewals, passcodes
Sales, pricing, and general information

508-647-7000 (Phone)
508-647-7001 (Fax)
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
For contact information about worldwide offices, see the MathWorks Web site.
OPC Toolbox Users Guide
COPYRIGHT 20042010 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or
reproduced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation
by, for, or through the federal government of the United States. By accepting delivery of the Program
or Documentation, the government hereby agrees that this software or documentation qualifies as
commercial computer software or commercial computer software documentation as such terms are used
or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and
conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern
the use, modification, reproduction, release, performance, display, and disclosure of the Program and
Documentation by the federal government (or other entity acquiring for or through the federal government)
and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the
governments needs or is inconsistent in any respect with federal procurement law, the government agrees
to return the Program and Documentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand
names may be trademarks or registered trademarks of their respective holders.
Patents

The MathWorks products are protected by one or more U.S. patents. Please see
www.mathworks.com/patents for more information.

Downloaded from www.Manualslib.com manuals search engine

Revision History

June 2004
August 2004
October 2004
March 2005
April 2005
September 2005
March 2006
September 2006
March 2007
September 2007
March 2008
October 2008
March 2009
September 2009
March 2010

Downloaded from www.Manualslib.com manuals search engine

Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only
Online only

New for Version 1.0 (Release 14)

Revised for Version 1.1 (Release 14+)
Revised for Version 1.1.1 (Release 14SP1)
Revised for Version 1.1.2 (Release 14SP2)
Revised for Version 2.0 (Release 14SP2+)
Revised for Version 2.0.1 (Release 14SP3)
Revised for Version 2.0.2 (Release 2006a)
Revised for Version 2.0.3 (Release 2006b)
Revised for Version 2.0.4 (Release 2007a)
Revised for Version 2.1 (Release 2007b)
Revised for Version 2.1.1 (Release 2008a)
Revised for Version 2.1.2 (Release 2008b)
Revised for Version 2.1.3 (Release 2009a)
Revised for Version 2.1.4 (Release 2009b)
Revised for Version 2.1.5 (Release 2010a)

Downloaded from www.Manualslib.com manuals search engine

Contents
Introduction

1
Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About OPC Toolbox Software . . . . . . . . . . . . . . . . . . . . . . . .
About OPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding OPC Data Access Servers . . . . . . . . . . . . . .
Understanding the OPC Toolbox Object Hierarchy . . . . . .
How OPC Toolbox Objects Relate to OPC Servers . . . . . . .
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-2
1-2
1-3
1-4
1-6
1-7
1-8

..............

1-9

Preparing to Use OPC Toolbox Software . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the OPC Foundation Core Components . . . . . . .
Configuring DCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the Matrikon OPC Simulation Server . . . . . . . .

1-10
1-10
1-10
1-11
1-18

Exploring Available OPC Servers . . . . . . . . . . . . . . . . . . .

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Determining Server IDs for a Host . . . . . . . . . . . . . . . . . . .

1-19
1-19
1-19

Connecting to OPC Servers . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Client Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connecting a Client to the Server . . . . . . . . . . . . . . . . . . . .
Browsing the OPC Server Name Space . . . . . . . . . . . . . . . .

1-21
1-21
1-21
1-22
1-23

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unable to Find an OPC Server . . . . . . . . . . . . . . . . . . . . . . .
Class not registered Error . . . . . . . . . . . . . . . . . . . . . . . . .
Unable to Query the Server . . . . . . . . . . . . . . . . . . . . . . . . .
Unable to Connect to Server . . . . . . . . . . . . . . . . . . . . . . . . .
Unable to Create a Group . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error While Querying Interface . . . . . . . . . . . . . . . . . . . . . .

1-28
1-28
1-28
1-29
1-29
1-29
1-29
1-29

Getting Command-Line Function Help

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

2
Example: Basic OPC Toolbox Acquisition Procedure . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1: Open the OPC Tool GUI . . . . . . . . . . . . . . . . . . . . .
Step 2: Locate Your OPC Server . . . . . . . . . . . . . . . . . . . . .
Step 3: Create an OPC Data Access Client Object . . . . . . .
Step 4: Connect to the OPC Server . . . . . . . . . . . . . . . . . . .
Step 5: Create an OPC Data Access Group Object . . . . . . .
Step 6: Browse the Server Name Space . . . . . . . . . . . . . . . .
Step 7: Add OPC Data Access Items to the Group . . . . . . .
Step 8: View All Item Values . . . . . . . . . . . . . . . . . . . . . . . .
Step 9: Configure Group Properties for Logging . . . . . . . . .
Step 10: Log OPC Server Data . . . . . . . . . . . . . . . . . . . . . . .
Step 11: Plot the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 12: Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-2
2-2
2-3
2-4
2-6
2-10
2-12
2-13
2-17
2-21
2-23
2-25
2-26
2-28

Using OPC Toolbox Objects

vi

Creating OPC Toolbox Objects . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Data Access Group Objects . . . . . . . . . . . . . . . . . .
Creating Data Access Item Objects . . . . . . . . . . . . . . . . . . .
Building an Object Hierarchy with a Disconnected
Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating OPC Toolbox Object Vectors . . . . . . . . . . . . . . . . .
Working with Public Groups . . . . . . . . . . . . . . . . . . . . . . . .

3-8
3-9
3-12

Configuring OPC Toolbox Object Properties . . . . . . . . .

Purpose of Object Properties . . . . . . . . . . . . . . . . . . . . . . . .
Viewing the Values of Object Properties . . . . . . . . . . . . . . .
Viewing the Value of a Particular Property . . . . . . . . . . . .
Getting Information About Object Properties . . . . . . . . . . .
Setting the Value of an Object Property . . . . . . . . . . . . . . .
Viewing a List of All Settable Object Properties . . . . . . . . .

3-17
3-17
3-18
3-19
3-19
3-20
3-21

Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-23

Contents

Downloaded from www.Manualslib.com manuals search engine

3-2
3-2
3-2
3-5

Saving and Loading Objects . . . . . . . . . . . . . . . . . . . . . . . .

3-25

Reading, Writing, and Logging OPC Data

4
Reading and Writing Data . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading Data from an Item . . . . . . . . . . . . . . . . . . . . . . . . .
Writing Data to an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and Writing Multiple Values . . . . . . . . . . . . . . . . .

4-2
4-2
4-2
4-6
4-8

Data Change Events and Subscription . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring OPC Toolbox Objects for Data Change
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How OPC Toolbox Software Processes Data Change
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Customize the Data Change Event Response . . . . .

4-12
4-12

Logging OPC Server Data . . . . . . . . . . . . . . . . . . . . . . . . . .

How OPC Toolbox Software Logs Data . . . . . . . . . . . . . . . .
Configuring a Logging Session . . . . . . . . . . . . . . . . . . . . . . .
Executing a Logging Task . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Logged Data into the MATLAB Workspace . . . . . .

4-17
4-17
4-20
4-24
4-26

4-12
4-15
4-15

Working with OPC Data

5
Understanding OPC Data: Value, Quality, and
TimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Relationship Between Value, Quality, and
TimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Value, Quality, and TimeStamp Are Obtained . . . . . .

5-2
5-2
5-2
5-3

vii

Downloaded from www.Manualslib.com manuals search engine

Working with Structure Formatted Data . . . . . . . . . . . .

When Structures Are Used . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Performing a Read Operation on Multiple
Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interpreting Structure Formatted Data . . . . . . . . . . . . . . .
When to Use Structure Formatted Data . . . . . . . . . . . . . . .
Converting Structure Formatted Data to Array Format . .

5-8
5-10
5-13
5-13

Understanding Array Formatted Data . . . . . . . . . . . . . . .

Array Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conversion of Logged Data to Arrays . . . . . . . . . . . . . . . . .

5-15
5-15
5-16

Working with Different Data Types . . . . . . . . . . . . . . . . .

Conversion Between MATLAB Data Types and COM
Variant Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conversion of Values Written to an OPC Server . . . . . . . .
Conversion of Values Read from an OPC Server . . . . . . . .
Handling Arrays for Item Values . . . . . . . . . . . . . . . . . . . . .

5-18

5-8
5-8

5-18
5-20
5-20
5-20

Using Events and Callbacks

viii

Example: Using the Default Callback Function . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1: Create OPC Toolbox Group Objects . . . . . . . . . . . .
Step 2: Configure the Logging Task Properties . . . . . . . . .
Step 3: Configure the Callback Properties . . . . . . . . . . . . .
Step 4: Start the Logging Task . . . . . . . . . . . . . . . . . . . . . .
Step 5: Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-2
6-2
6-2
6-3
6-3
6-3
6-4

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-5

Retrieving Event Information . . . . . . . . . . . . . . . . . . . . . .

Event Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Accessing Data in the Event Log . . . . . . . . . . . . .

6-10
6-10
6-13

Creating and Executing Callback Functions . . . . . . . . .

Creating Callback Functions . . . . . . . . . . . . . . . . . . . . . . . .

6-16
6-16

Contents

Downloaded from www.Manualslib.com manuals search engine

Specifying Callback Functions . . . . . . . . . . . . . . . . . . . . . . .

Example: Viewing Recently Logged Data . . . . . . . . . . . . . .

6-18
6-20

Using the OPC Toolbox Block Library

7
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-2

Example: Reading and Writing Data from the Matrikon

OPC Simulation Server . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 1: Open the OPC Toolbox Block Library . . . . . . . . . . .
Step 2: Create a New Model . . . . . . . . . . . . . . . . . . . . . . . . .
Step 3: Drag the OPC Toolbox Blocks into the Model . . . .
Step 4: Drag Other Blocks to Complete the Model . . . . . . .
Step 5: Configure OPC Servers for the Model . . . . . . . . . . .
Step 6: Specify the Block Parameter Values . . . . . . . . . . . .
Step 7: Connect the Blocks . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 8: Run the Simulation . . . . . . . . . . . . . . . . . . . . . . . . .

7-3
7-3
7-4
7-5
7-6
7-7
7-9
7-12
7-15
7-16

Using the OPC Client Manager . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Clients to the OPC Client Manager . . . . . . . . . . . .
Removing Clients from the OPC Client Manager . . . . . . . .
Modifying the Server Timeout Value for a Client . . . . . . . .
Controlling Client/Server Connections . . . . . . . . . . . . . . . .

7-18
7-18
7-19
7-19
7-20
7-20

Function Reference

8
Object Creation and Configuration . . . . . . . . . . . . . . . . . .

8-2

Server Exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-2

Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-3

ix

Downloaded from www.Manualslib.com manuals search engine

OPC Data Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-3

Logging and Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-4

Simulink Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-4

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-5

Functions Alphabetical List

9
Property Reference

10

OPC Data Access Client Object Properties . . . . . . . . . . .

General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Callback Function and Event Properties . . . . . . . . . . . . . . .
Server Connection Properties . . . . . . . . . . . . . . . . . . . . . . . .

10-2
10-2
10-2
10-3

Data Access Group Object Properties . . . . . . . . . . . . . . . .

General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Callback Function and Event Properties . . . . . . . . . . . . . . .
Subscription and Logging Properties . . . . . . . . . . . . . . . . . .

10-4
10-4
10-4
10-5

Data Access Item Object Properties . . . . . . . . . . . . . . . . .

General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10-7
10-7
10-7

Contents

Downloaded from www.Manualslib.com manuals search engine

Properties Alphabetical List

11
Block Reference

12
OPC Quality Strings

A
Major Quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-2

Quality Substatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-3

Limit Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-6

OPC Server Item Properties

B
.........

B-2

OPC Specific Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-3

OPC Recommended Properties . . . . . . . . . . . . . . . . . . . . .

B-4

Understanding OPC Server Item Properties

Index

xi

Downloaded from www.Manualslib.com manuals search engine

xii

Contents

Downloaded from www.Manualslib.com manuals search engine

1
Introduction
Product Overview on page 1-2
Getting Command-Line Function Help on page 1-9
Preparing to Use OPC Toolbox Software on page 1-10
Exploring Available OPC Servers on page 1-19
Connecting to OPC Servers on page 1-21
Troubleshooting on page 1-28

Downloaded from www.Manualslib.com manuals search engine

Introduction

Product Overview
In this section...
About OPC Toolbox Software on page 1-2
About OPC on page 1-3
Understanding OPC Data Access Servers on page 1-4
Understanding the OPC Toolbox Object Hierarchy on page 1-6
How OPC Toolbox Objects Relate to OPC Servers on page 1-7
System Requirements on page 1-8

About OPC Toolbox Software

OPC Toolbox software is a collection of functions that extend the capability of
the MATLAB environment, and blocks that extend the Simulink simulation
environment. Using OPC Toolbox functions and blocks, you can acquire live
OPC data directly into MATLAB and Simulink, and write data directly to the
OPC server from MATLAB and Simulink.
OPC Toolbox software implements a hierarchical object-oriented approach
to communicating with OPC servers using the OPC Data Access Standard.
Using toolbox functions, you create an OPC Data Access Client object (opcda
client object) that represents the connection between MATLAB and an OPC
server. Using properties of the opcda client object you can control various
aspects of the communication link, such as time out periods, connection
status, and storage of events associated with that client. Connecting to OPC
Servers on page 1-21 describes how to create opcda objects.
Once you establish a connection to an OPC server, you create Data Access
Group objects (dagroup objects) that represent collections of OPC Data Access
Items. You then add Data Access Item objects (daitem objects) to that group,
for monitoring server item values from the OPC server and writing values to
the OPC server. You can use the dagroup object to perform such actions as
determining how often the items in the group must be updated, executing a
MATLAB function when the server provides notification of changes in item
state, and other tasks related to the group. Creating OPC Toolbox Objects

1-2

Downloaded from www.Manualslib.com manuals search engine

Product Overview

on page 3-2 describes how to create and configure dagroup objects and add
daitem objects to a group.
The OPC Data Access Standard does not provide access to historical
data. (While the OPC Foundation has defined the Historical Data Access
specification for access to historical data, a significant number of Data Access
servers do not support this standard.) Using OPC Toolbox software, you
can log records (a list of items that have changed, and their new values)
from an OPC Data Access Server to disk or to memory, for later processing.
The logging task is controlled by the dagroup object. Logging OPC Server
Data on page 4-17 describes how to log data using the OPC Toolbox logging
mechanism.
To work with the data you acquire, you must bring it into the MATLAB
workspace. When the records are acquired, the toolbox stores them in a
memory buffer or on disk. The toolbox provides several ways to bring one or
more records of data into the workspace where you can analyze or visualize
the data. Chapter 5, Working with OPC Data describes the different data
formats and their application.
You can enhance your OPC application by using event callbacks. The toolbox
has defined certain OPC Toolbox software occurrences, such as the start of
an acquisition task, as well as OPC server initiated occurrences, such as
notification that an items state has changed, as events. You can associate the
execution of a particular function with a particular event. Chapter 6, Using
Events and Callbacks describes this process.
When working in the Simulink environment, you can use blocks from the OPC
Toolbox block library to use live OPC data as inputs to your model and update
the OPC server with your model outputs. The OPC Toolbox block library
includes the capability of running Simulink models in pseudo real time, by
slowing the simulation to match the system clock. You can prototype control
systems, provide plant simulators, and perform optimization and tuning tasks
using Simulink and the OPC Toolbox block library. Chapter 7, Using the OPC
Toolbox Block Library describes how to use these blocks in a Simulink model.

About OPC
Open Process Control (OPC), also known as OLE for Process Control,
is a series of seven specifications defined by the OPC Foundation

1-3

Downloaded from www.Manualslib.com manuals search engine

Introduction

(http://www.opcfoundation.org) for supporting open connectivity in

industrial automation. OPC uses Microsoft DCOM technology to provide a
communication link between OPC servers and OPC clients. OPC has been
designed to provide reliable communication of information in a process plant,
such as a petrochemical refinery, an automobile assembly line, or a paper mill.
Before you interact with OPC servers using OPC Toolbox software, you should
understand the OPC client-server relationship, how OPC servers organize
their server items, and how clients can interact with those server items.
Understanding the OPC Toolbox Object Hierarchy on page 1-6 explains
these concepts in detail.

Understanding OPC Data Access Servers

OPC Toolbox software is an OPC Data Access client application, capable of
connecting to any OPC Data Access compliant server. By utilizing the OPC
Foundation Data Access standard, the toolbox does not require any knowledge
about the internal configuration and operation of the OPC server. Instead,
the Data Access Standard provides the common mechanism for the server
and client to interact with each other.
An OPC Data Access Server is identified by a unique server ID. The server ID
is unique to the computer on which the server is located. A combination of
the host name of the server computer, and the server ID of the OPC server,
provides a unique identifier for an OPC server on a network of computers.

OPC Server Name Spaces

All OPC servers are required to publish a name space, consisting of an
arrangement of the name of every server item (also known as an item ID)
associated with that server. The name space provides the internal map of
every device and location that the server is able to monitor and/or update.
The following figure shows a portion of the name space on a typical OPC
server.

1-4

Downloaded from www.Manualslib.com manuals search engine

Product Overview

Figure 1-1:

Example of OPC Server and Name Space

A server item represents a value on the OPC server that a client may be
interested in. A server item could represent a physical measurement device
(such as a temperature sensor), a particular component of a device (such as
the set-point for a controller), or a variable or storage location in a supervisory
control and data acquisition (SCADA) system. Each server item is uniquely
represented on the server by a fully qualified item ID. The fully qualified item
ID is usually made up of the path to that server item in the tree, with each
node name separated by a period character. In Figure 1-1, Example of OPC
Server and Name Space, the fully qualified item ID for the highlighted server
item might be Area01.UnitA.FIC01.PV.
Most OPC servers provide a hierarchical name space, where server items
are arranged in a tree-like structure. The tree can contain many different
categories (called branch nodes), each with one or more branches and/or leaf
nodes. A leaf node contains no other branches, and often represents a specific
server Item. The fully qualified item ID of a server item is simply the path to
that leaf node, with a server-dependent separator.
Some OPC servers provide only a flat name space, where server items are
all arranged in one single group. You could consider a flat name space as a
name space containing only leaf nodes.
It is possible to convert a hierarchical name space into a flat name space. It
is not always possible to convert a flat name space into a hierarchical name
space.

1-5

Downloaded from www.Manualslib.com manuals search engine

Introduction

For information on how to obtain the name space of an OPC server, see
Browsing the OPC Server Name Space on page 1-23.

Understanding the OPC Toolbox Object Hierarchy

OPC Toolbox software is implemented using three basic objects, designed to
help you manage connections to servers and collections of server items. The
three objects are arranged in a specific hierarchy, shown in the following
figure.

OPC Toolbox Object Hierarchy

1 OPC Data Access Client objects (opcda client objects) represent a

specific OPC client instance that can communicate with only one server.
You define the server using the Host and ServerID properties. The Host
property defines the computer on which the server is installed. The
ServerID property defines the Program ID (ProgID) of the server, created
when the server was installed on that host. The opcda client object acts as
a container for multiple group objects, and manages the connection to the
server, communication with the server, and server name space browsing.
2 Data Access Group objects (dagroup objects) represent containers for

one or more server items (data points on the server.) A dagroup object
manages how often the items in the group must be read, whether historical
item information must be stored, and also manages creation and deletion
of items. Groups cannot exist without an opcda client object. You create
dagroup objects using the addgroup function of an opcda client object.
3 Data Access Item objects (daitem objects) represent server items. Items

are defined by an item ID, which uniquely defines that server item in
the servers name space. A daitem object has a Value, a Quality, and a
TimeStamp, representing the information collected by the server from an

1-6

Downloaded from www.Manualslib.com manuals search engine

Product Overview

instrument or data point in a SCADA system. The Value, Quality, and

TimeStamp properties represent the information known to the server when
the server was last asked to access information from that instrument.
A dagroup object can only exist within an opcda client object. Similarly, a
daitem object can only exist within a dagroup object. You create dagroup
objects using the addgroup method of an opcda client object. You create
daitem objects using the additem method of the dagroup object.

How OPC Toolbox Objects Relate to OPC Servers

OPC Toolbox software uses objects to define the server that the client must
connect to, and the arrangement of items in groups. The following figure
shows the relationship between the OPC Toolbox objects and an OPC server.

Figure 1-2:

Relationship Between OPC Toolbox Objects and OPC Server

1-7

Downloaded from www.Manualslib.com manuals search engine

Introduction

The opcda client object establishes the connection between OPC Toolbox
software and the OPC server, using OPC Data Access Specification standards.
The standards are based on Microsoft COM/DCOM interoperability standards.
The daitem objects represent specific server items. Note that a client typically
requires only a subset of the entire name space of a server in order to operate
effectively. In Figure 1-2, Relationship Between OPC Toolbox Objects and
OPC Server only the PV and SP items of FIC01, and the LIT01 item, are
required for that particular group. Another group may only contain a single
daitem object, representing a single server item.
Note The dagroup object has no equivalent on the OPC server. However,
the server keeps a record of each group that a client has created, and uses
that group name to communicate to the client information about the items in
that group.

System Requirements
OPC Toolbox software provides the Data Access client capabilities from within
MATLAB. To use this toolbox functionality, you need access to an OPC server
that supports the Data Access Specification version 2.05. In addition, you will
need to ensure that you are able to connect to those OPC servers from the
computer on which the toolbox software is installed. For more information on
how to configure the client and server computers so that you can connect to an
OPC server, see Preparing to Use OPC Toolbox Software on page 1-10.

1-8

Downloaded from www.Manualslib.com manuals search engine

Getting Command-Line Function Help

Getting Command-Line Function Help

To get command-line function help, you can use the MATLAB help function.
For example, to get help for the opcserverinfo function, type
help opcserverinfo

However, OPC Toolbox software provides overloaded versions of several

MATLAB functions. That is, it provides toolbox-specific implementations of
these functions using the same function name.
For example, the toolbox provides an overloaded version of the isvalid
function. If you type
help isvalid

you get help for the MATLAB Timer object version of this function. You can
determine if a function is overloaded by examining the last section of the help.
For isvalid, the help contains the following overloaded versions (not all
are shown).
Overloaded methods
help serial/isvalid.m
help instrument/isvalid.m.
.
.
.
help opcroot/isvalid.m

To obtain help on the toolbox version of this function, type

help opcroot/isvalid

To avoid having to specify which overloaded version you want to view, use
the opchelp function.
opchelp isvalid

You can also use this function to get help on OPC Toolbox object properties.

1-9

Downloaded from www.Manualslib.com manuals search engine

Introduction

Preparing to Use OPC Toolbox Software

In this section...
Introduction on page 1-10
Installing the OPC Foundation Core Components on page 1-10
Configuring DCOM on page 1-11
Installing the Matrikon OPC Simulation Server on page 1-18

Introduction
Before you can communicate with OPC servers on your network, you need to
prepare your workstation (and possibly the OPC server host computer) to use
the technologies on which OPC Toolbox software is built. These technologies,
described in About OPC on page 1-3, allow you to browse for and connect to
OPC servers on your network, and allow those OPC servers to interact with
your MATLAB session using OPC Toolbox software.
The specific steps are described in the following sections.

Installing the OPC Foundation Core Components

The OPC Foundation has provided a set of tools for browsing other computers
on your network for OPC servers, and for communicating with the OPC
servers. These tools are called the OPC Foundation Core Components, and
are shipped with OPC Toolbox software.
To install the OPC Foundation Core Components, you use the opcregister
function. You can also use the opcregister function to remove or repair the
OPC Foundation Core Components installation.
Installing, repairing, and removing the OPC Foundation Core Components
follows the same steps:
1 If you are repairing or removing the OPC Foundation Core Components,

make sure that you do not have any OPC Toolbox objects in memory. Use
the opcreset function to clear all objects from memory.
opcreset;

1-10

Downloaded from www.Manualslib.com manuals search engine

Preparing to Use OPC Toolbox Software

2 Run opcregister with the action you would like to perform. If you do

not supply an option, the function assumes that you want to install the
components. Otherwise, use 'repair' to repair an installation (reinstall
the files), or 'remove' to remove the components.
opcregister('install')
3 You will be prompted to type Yes to confirm the action you want to

perform. You must type Yes exactly as shown, without any quotes. This
confirmation question is used to ensure that you acknowledge the action
that is about to take place.
4 The OPC Foundation Core Components will be installed, repaired, or

removed from your system.

5 If you receive a warning about having to reboot your computer, you must

quit MATLAB and restart your computer for the changes to take effect.

Configuring DCOM
DCOM is a client-server based architecture for enabling communication
between two applications running on distributed computers. The OPC
Data Access Specification utilizes DCOM for communication between the
OPC client (for example, OPC Toolbox software) and the OPC server. To
successfully use DCOM, those two computers must share a common security
configuration so that the two applications are granted the necessary rights to
communicate with each other.
This section describes two typical DCOM configuration options to allow OPC
Toolbox software to work. Other DCOM options might provide sufficient
permissions for the toolbox to work with an OPC server; the options described
here are known to work with tested vendors OPC servers.
There are two configuration types described in this section:
Configuring DCOM to Use Named User Security on page 1-12 describes
how to provide security between the client and server negotiated on
a dedicated named user basis. You do not have to be logged in as the
named user in order to use this mechanism; all communications between
the client and the server are performed using the dedicated named user,
independently of the user making the OPC requests. However, the identity

1-11

Downloaded from www.Manualslib.com manuals search engine

Introduction

used to run the OPC server must be available on the client machine, and
the password of that identity must match on both machines.
Configuring DCOM to Use No Security on page 1-17 describes a
configuration that provides no security between the client and server. Use
this option only if you are connecting to an OPC server on a dedicated,
private network. This configuration option has been known to cause some
Microsoft Windows services to fail.
You should use the named user configuration, unless your system
administrator indicates that no security is required for OPC access.
Caution If your OPC server software comes with DCOM setup guidelines,
you should follow the instructions provided by the OPC server vendor. The
guidelines provided in this section are generic and may not suit your specific
network and security model.

Note The following instructions apply to the Microsoft Windows XP operating

system with Service Pack 2. Users of other Microsoft Windows operating
systems should be able to adapt these instructions to configure DCOM on
their systems.

Configuring DCOM to Use Named User Security

To configure DCOM to use named user security, you will have to ensure
that both the server machine and client machine have a common user who
is granted DCOM access rights on both the server and client machines. You
should consult the following sections for information on configuring each
machine:
OPC Server Machine Configuration on page 1-13 provides the steps that
you must perform on each of the machines providing OPC servers.
Client Machine Configuration on page 1-14 provides the steps that you
must perform on the machine that will run MATLAB and OPC Toolbox
software.

1-12

Downloaded from www.Manualslib.com manuals search engine

Preparing to Use OPC Toolbox Software

OPC Server Machine Configuration. On the machines hosting the OPC

servers, perform the following steps:
1 Create a new local user. (You can also create a domain user if the server

and client machines are part of the same domain.) The name used in these
instructions is opc but you can choose any name, as long as you remain
consistent throughout these instructions.
2 Select Start > Settings > Control Panel. Double-click Administrative

Tools and then double-click Component Services. The Component

Services dialog appears.
3 Browse to Component Services > Computers > My Computer > DCOM

Config.
4 Locate your OPC server in the DCOM Config list. The example below shows

the Matrikon OPC Server for Simulation.

5 Right-click the OPC server object, and choose Properties.

6 In the General tab, ensure that the Authentication Level is set to Default.
7 In the Security tab, choose Customize for the Launch and Activation

Permissions, then click Edit. Ensure that the opc user is granted local
Launch and Activation permissions.

1-13

Downloaded from www.Manualslib.com manuals search engine

Introduction

8 In the Security tab, choose Customize for the Access Permissions, then

click Edit. Ensure that the opc user is granted local Access permissions.
9 In the Identity tab, select This user and type the name and password

for the opc user (created in step 1).

10 If the OPC server runs as a service, make sure that the service runs as the

opc user (created in step 1) and not as the system account.

11 Repeat steps 4 through 10 for each of the servers you want to connect to.

Client Machine Configuration. On the machine(s) that will be running

MATLAB and OPC Toolbox software, perform the following steps:
1 On the client machine(s), create the identical local user with the same

name and password permissions as you set up in step 1 of OPC Server

Machine Configuration on page 1-13.
2 Select Start > Settings > Control Panel. Double-click Administrative

Tools and then double-click Component Services. The Component

Services dialog appears.
3 Browse to Component Services > Computers > My Computer. Click

Configure My Computer in the Component Services toolbar as shown below.

1-14

Downloaded from www.Manualslib.com manuals search engine

Preparing to Use OPC Toolbox Software

4 Click the Default Properties tab, and ensure that Enable Distributed

COM is checked, and that the Default Authentication Level is set to

Connect and the Default Impersonation Level is set to Identify.

1-15

Downloaded from www.Manualslib.com manuals search engine

Introduction

5 Click the COM Security tab.

6 For the Access Permissions, click Edit Default and ensure that the opc

user is included in the Default Security list, and is granted both Local
Access and Remote Access permissions.
7 For the Launch and Activation permissions, click Edit Default and ensure

that the opc user is included in the Default Security list, and is granted
all rights (Local Launch, Remote Launch, Local Activation, and Remote
Activation).

1-16

Downloaded from www.Manualslib.com manuals search engine

Preparing to Use OPC Toolbox Software

Your local client machine and server applications are now configured to use
the same username when the server attempts to establish a connection back
to the client.

Configuring DCOM to Use No Security

Caution You should not use this option if you are not in a completely trusted
network. Turning off DCOM security means that any user on the network can
launch any COM object on your local machine. Consult with your network
administrator before following these instructions.
You must complete the following steps on both the client and server machines.
1 Select Start > Settings > Control Panel. Double-click Administrative

Tools and then double-click Component Services. The Component

Services dialog appears.
2 Browse to Component Services > Computers > My Computer. Click

the Configure My Computer button in the Component Services toolbar.

3 In the Default Properties tab, make sure that Enable Distributed COM

On This Computer is selected. Select None as the Default Authentication

Level, and Anonymous as the Default Impersonation Level.
4 In the COM Security tab, select Edit Limits from the Access Permissions

and ensure that Everyone and ANONYMOUS LOGON are both granted Local
Access and Remote Access.
5 In the COM Security tab, select Edit Limits from the Launch and

Activation Permissions and ensure that Everyone and ANONYMOUS LOGON

are both granted Local and Remote permissions (Local Launch, Remote
Launch, Local Activation and Remote Activation).
Both the client and the server are now configured so that anybody can access
any COM object on either machine.

1-17

Downloaded from www.Manualslib.com manuals search engine

Introduction

Caution This configuration is potentially dangerous in terms of security, and

is recommended for debugging purposes only.

Installing the Matrikon OPC Simulation Server

All examples in this guide and in the OPC Toolbox online help make use of a
Matrikon demonstration server that you can download free of charge from:
http://www.matrikonopc.com

On that page, select Downloads > Product Software, then select

MatrikonOPC Simulation Server Download.
Note You do not have to install the Matrikon OPC Simulation Server to
enable any functionality of OPC Toolbox software. The Simulation Server is
used purely for demonstrating the capabilities and syntax of OPC Toolbox
commands, and for providing fully working example code.
To install the Matrikon OPC Simulation Server, follow the installation
instructions with the software. When prompted for a server ID,
use the standard server ID assigned to the Simulation Server
('Matrikon.OPC.Simulation').

1-18

Downloaded from www.Manualslib.com manuals search engine

Exploring Available OPC Servers

Exploring Available OPC Servers

In this section...
Prerequisites on page 1-19
Determining Server IDs for a Host on page 1-19

Prerequisites
To interact with an OPC server, OPC Toolbox software needs two pieces of
information:
The hostname of the computer on which the OPC server has been installed.
Typically the hostname is a descriptive term (such as 'plantserver') or
an IP address (such as 192.168.2.205).
The server ID of the server you want to access on that host. Because a single
computer can host more than one OPC server, each OPC server installed
on that computer is given a unique ID during the installation process.
Your network administrator will be able to provide you with the hostnames
for all computers providing OPC servers on your network. You may also
obtain a list of server IDs for each host on your network, or you can use the
toolbox function opcserverinfo to access server IDs from a host, as described
in the following section.

Determining Server IDs for a Host

When an OPC server is installed, a unique server ID must be assigned to that
OPC server. The server ID provides a unique name for a particular instance
of an OPC server on a host, even if multiple copies of the same server software
are installed on the same machine.
To determine the server IDs of OPC servers installed on a host, call the
opcserverinfo function, specifying the hostname as the only argument.
When called with this syntax, opcserverinfo returns a structure containing
information about all the OPC servers available on that host.
info = opcserverinfo('localhost')

1-19

Downloaded from www.Manualslib.com manuals search engine

Introduction

info =
Host:
ServerID:
ServerDescription:
OPCSpecification:
ObjectConstructor:

'localhost'
{1x4 cell}
{1x4 cell}
{'DA2' 'DA2'
{1x4 cell}

'DA2'

'DA2'}

The fields in the structure returned by opcserverinfo provide the following

information.
Server Information Returned by opcserverinfo
Field

Description

Host

Text string that identifies the name of the host.

Note that no name resolution is performed on an
IP address.

ServerID

Cell array containing the server IDs of all OPC

servers accessible from that host.

ServerDescription

Cell array containing descriptive text for each

server.

OPCSpecification

Cell array containing the OPC Specification that the

server provides. Currently, OPC Toolbox software
supports only the 'DA2' specification.

ObjectConstructor

Cell array containing default syntax you can use to

create an OPC Data Access Client object associated
with the server. See Creating a Client Object on
page 1-21 for more information.

1-20

Downloaded from www.Manualslib.com manuals search engine

Connecting to OPC Servers

Connecting to OPC Servers

In this section...
Overview on page 1-21
Creating a Client Object on page 1-21
Connecting a Client to the Server on page 1-22
Browsing the OPC Server Name Space on page 1-23

Overview
After you get information about your OPC servers, described in Exploring
Available OPC Servers on page 1-19, you can establish a connection to the
server by creating an OPC Data Access Client (opcda) object and connecting
that client to the server. These steps are described in the following sections.
Note To run the sample code in the following examples, you must have
the Matrikon OPC Simulation Server available on your local machine. For
information on installing this, see Installing the Matrikon OPC Simulation
Server on page 1-18. The code requires only minor changes work with other
servers.

Creating a Client Object

To create an opcda object, call the opcda function specifying the hostname,
and server ID. You retrieved this information using the opcserverinfo
function (described in Exploring Available OPC Servers on page 1-19).
This example creates an opcda object to represent the connection to a
Matrikon OPC Simulation Server. The opcserverinfo function includes the
default opcda syntax in the ObjectConstructor field.
da = opcda('localhost', 'Matrikon.OPC.Simulation.1');

1-21

Downloaded from www.Manualslib.com manuals search engine

Introduction

Viewing a Summary of a Client Object

To view a summary of the characteristics of the opcda object you created,
enter the variable name you assigned to the object at the command prompt.
For example, this is the summary for the object da.
da

The items in this list correspond to the numbered elements in the object
summary:
1 The title of the Summary includes the name of the opcda client object. The

default name for a client object is made up of the 'host/serverID'. You

can change the name of a client object using the set function, described in
Configuring OPC Toolbox Object Properties on page 3-17.
2 The Server Parameters provide information on the OPC server that

the client is associated with. The host name, server ID, and connection
status are provided in this section. You connect to an OPC server using
the connect function, described in Connecting a Client to the Server
on page 1-22.
3 The Object Parameters section contains information on the OPC Data

Access Group (dagroup) objects configured on this client. You use group
objects to contain collections of items. Creating group objects is described
in Creating Data Access Group Objects on page 3-2.

Connecting a Client to the Server

You connect a client to the server using the connect function.
connect(da);

1-22

Downloaded from www.Manualslib.com manuals search engine

Connecting to OPC Servers

Once you have connected to the server, the Status information in the client
summary display will change from 'disconnected' to 'connected'.
If the client could not connect to the server for some reason (for example, if the
OPC server is shut down) an error message will be generated. For information
on troubleshooting connections to an OPC server, see Troubleshooting on
page 1-28.
Once you have connected the client to the server, you can perform the
following tasks:
Get diagnostic information about the OPC server, such as the server status,
last update time, and supported interfaces. You use the opcserverinfo
function to obtain this information. See opcserverinfo in the function
reference for more information.
Browse the OPC server name space for information on the available server
items. See Browsing the OPC Server Name Space on page 1-23 for details
on browsing the server name space.
Create group and item objects to interact with OPC server data. See
Creating OPC Toolbox Objects on page 3-2 for information on creating
group and item objects.

Browsing the OPC Server Name Space

A connected client object allows you to interact with the OPC server to obtain
information about the name space of that server. The server name space
provides access to all the data points provided by the OPC server by naming
each of the data points with a server item, and then arranging those server
items into a name space that provides a unique identifier for each server item.
This section describes how you use a connected client object to browse the
name space and find information about each server item. These activities are
described in the following sections:
Getting the Server Name Space on page 1-24 describes how to obtain a
server name space, or a partial server name space, using the getnamespace
and serveritems functions.
Getting Information about a Specific Server Item on page 1-26 describes
how to query the server for the properties of a specific server item.

1-23

Downloaded from www.Manualslib.com manuals search engine

Introduction

Getting the Server Name Space

You use the getnamespace function to retrieve the name space from an OPC
server. You must specify the client object that is connected to the server you
are interested in. The name space is returned to you as a structure array
containing information about each node in the name space.
The example below retrieves the name space of the Matrikon OPC Simulation
Server installed on the local host.
da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
ns = getnamespace(da)
ns =
3x1 struct array with fields:
Name
FullyQualifiedID
NodeType
Nodes

The fields of the structure are described in the following table.

Field

Description

Name

The name of the node, as a string.

FullyQualifiedID The fully qualified item ID of the node, as a string. The

fully qualified item ID is made up of the path to the

node, concatenated with '.' characters. You use the
fully qualified item ID when creating an item object
associated with this node.
NodeType

The type of node. NodeType can be 'branch' (contains

other nodes) or 'leaf' (contains no other branches).

Nodes

Child nodes. Nodes is a structure array with the same

fields as ns, representing the nodes contained in this
branch of the name space.

From the example above, exploring the name space shows.

ns(1)

1-24

Downloaded from www.Manualslib.com manuals search engine

Connecting to OPC Servers

ans =
Name: 'Simulation Items'
FullyQualifiedID: 'Simulation Items'
NodeType: 'branch'
Nodes: [8x1 struct]
ns(3)
ans =
Name: 'Clients'
FullyQualifiedID: 'Clients'
NodeType: 'leaf'
Nodes: []

From the information above, the first node is a branch node called
'Simulation Items'. Since it is a branch node, it is most likely not a valid
server item. The third node is a leaf node (containing no other nodes) with a
fully qualified ID of 'Clients'. Since this node is a leaf node, it is most likely
a server item that can be monitored by creating an item object.
To examine the nodes further down the tree, you need to reference the Nodes
field of a branch node. For example, the first node contained within the
'Simulation Items' node is obtained as follows.
ns(1).Nodes(1)
ans =
Name: 'Bucket Brigade'
FullyQualifiedID: 'Bucket Brigade.'
NodeType: 'branch'
Nodes: [14x1 struct]

The returned result shows that the first node of 'Simulation Items' is a
branch node named 'Bucket Brigade', and contains 14 nodes.
ns(1).Nodes(1).Nodes(9)
ans =
Name: 'Real8'
FullyQualifiedID: 'Bucket Brigade.Real8'

1-25

Downloaded from www.Manualslib.com manuals search engine

Introduction

NodeType: 'leaf'
Nodes: []

The ninth node in 'Bucket Brigade' is named 'Real8' and has a fully
qualified ID of 'Bucket Brigade.Real8'. You use the fully qualified ID
to refer to that specific node in the server name space when creating items
with OPC Toolbox software.
You can use the flatnamespace function to flatten a hierarchical name space.

Getting Information about a Specific Server Item

In addition to publishing a name space to all clients, an OPC server provides
information about the properties of each of the server items in the name
space. These properties provide information on the data format used by the
server to store the server item value, a description of the server item, and
additional properties configured when the server item was created. The
additional properties may include information on the range of the server item,
the maximum rate at which the server can update that server item value, etc.
You access a property using a defined set of property IDs. A property ID is
simply a number that defines a specific property of the server item. Property
IDs are divided into three categories:
OPC Specific Properties (1-99) that every OPC server must provide.
The OPC Specific Properties include the server items Value, Quality,
and Timestamp. See Understanding OPC Data: Value, Quality, and
TimeStamp on page 5-2 for more information on understanding OPC data.
OPC Recommended Properties (100-4999) that OPC servers can provide.
These properties include maximum and minimum values, a description of
the server item, and other commonly used properties. See Appendix B,
OPC Server Item Properties for more information on OPC Recommended
Properties.
Vendor Specific Properties (5000 and higher) that an OPC server can
define and use. These properties may be different for each OPC server,
and provide a space for OPC server manufacturers to define their own
properties.

1-26

Downloaded from www.Manualslib.com manuals search engine

Connecting to OPC Servers

You query a server items properties using the serveritemprops function,

specifying the client object, the fully qualified item ID of the server item you
are interested in, and an optional vector of property IDs that you wish to
retrieve. If you do not specify the property IDs, all properties defined for
that server item are returned to you.
Note You obtain the fully qualified item ID from the server using the
getnamespace function or the serveritems function, which simply returns all
fully qualified item IDs in a cell array of strings. See the function reference
for more information on the serveritems function.
The following example queries the Item Description property (ID 101) of the
server item 'Bucket Brigade.ArrayOfReal8' from the example in Getting
the Server Name Space on page 1-24.
p = serveritemprops(da, 'Bucket Brigade.ArrayOfReal8', 101)
p =
PropID: 101
PropDescription: 'Item Description'
PropValue: 'Bucket brigade item.'

For a list of OPC Foundation property IDs, see Appendix B, OPC Server
Item Properties.

1-27

Downloaded from www.Manualslib.com manuals search engine

Introduction

Troubleshooting
In this section...
Introduction on page 1-28
Unable to Find an OPC Server on page 1-28
Class not registered Error on page 1-29
Unable to Query the Server on page 1-29
Unable to Connect to Server on page 1-29
Unable to Create a Group on page 1-29
Error While Querying Interface on page 1-29

Introduction
If you are unable to establish a connection to an OPC server, the following
sections might help you to identify problems with installation and
configuration that could be preventing you from successfully querying and
connecting to OPC servers.
Most problems with connecting to an OPC server relate to the DCOM settings
on either the host or the client machine. For information on configuring
DCOM, see Configuring DCOM on page 1-11.

Unable to Find an OPC Server

First, check that you are able to communicate with the host from your client.
You can test this by attempting to run a Command Prompt and using the
'ping' command on the host. Alternatively, try to browse to the host using
the Network Neighborhood.
If you are able to communicate with the host, but you are unable to find an
OPC server (using the opcserverinfo command) on that host, then the OPC
Foundation Core Components may have to be reinstalled on your workstation.
You can run the opcregister function to repair your OPC Foundation Core
Components installation. For more information see Installing the OPC
Foundation Core Components on page 1-10.

1-28

Downloaded from www.Manualslib.com manuals search engine

Troubleshooting

Class not registered Error

If you get this error while attempting to query a server using opcserverinfo,
or when attempting to add a host in the OPC Tool GUI, the OPC Foundation
Core Components have not been installed correctly. Install the OPC
Foundation Core Components, as described in Installing the OPC Foundation
Core Components on page 1-10.

Unable to Query the Server

If you are unable to query the server using opcserverinfo, the most common
cause is incorrectly configured local DCOM security settings. Review the
section on Configuring DCOM on page 1-11.

Unable to Connect to Server

An inability to connect to the OPC server usually indicates that the security
model on the server is not allowing you to make an initial connection. Check
the DCOM configuration on the server, and review the section on Configuring
DCOM on page 1-11.

Unable to Create a Group

If you are able to connect to the server but cannot create a group, the most
common cause is incorrectly configured local DCOM security settings. Review
the section on Configuring DCOM on page 1-11.

Error While Querying Interface

If you get this error while attempting to add a group to a connected client
object,
Error occurred while querying interface: IID_IOPCDataCallback

your local DCOM security settings are not permitting the OPC server to
connect to the OPC Toolbox software client on the local machine. Review the
section on Configuring DCOM on page 1-11.

1-29

Downloaded from www.Manualslib.com manuals search engine

Introduction

1-30

Downloaded from www.Manualslib.com manuals search engine

2
Quick Start: Using the OPC
Tool GUI
The best way to learn about the capabilities of OPC Toolbox software is to
look at a simple example. This chapter illustrates the basic steps required
to log data from an OPC server for analysis and visualization. The example
uses OPC Tool, a graphical user interface (GUI) provided in the toolbox, to
demonstrate the process, and includes information on how to achieve the
same results from the command line.
This chapter contains cross-references to other sections in the documentation
that provide more in-depth discussions of the relevant concepts.

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Example: Basic OPC Toolbox Acquisition Procedure

In this section...
Overview on page 2-2
Step 1: Open the OPC Tool GUI on page 2-3
Step 2: Locate Your OPC Server on page 2-4
Step 3: Create an OPC Data Access Client Object on page 2-6
Step 4: Connect to the OPC Server on page 2-10
Step 5: Create an OPC Data Access Group Object on page 2-12
Step 6: Browse the Server Name Space on page 2-13
Step 7: Add OPC Data Access Items to the Group on page 2-17
Step 8: View All Item Values on page 2-21
Step 9: Configure Group Properties for Logging on page 2-23
Step 10: Log OPC Server Data on page 2-25
Step 11: Plot the Data on page 2-26
Step 12: Clean Up on page 2-28

Overview
This section illustrates the basic steps required to create an OPC Toolbox
application by visualizing the Triangle Wave and Saw-toothed Wave signals
provided with the Matrikon OPC Simulation Server. The application logs
data to memory and plots that data, highlighting uncertain or bad data
points. By visualizing the data you can more clearly see the relationships
between the signals.
Note To run the sample code in the following examples, you must have
the Matrikon OPC Simulation Server available on your local machine. For
information on installing this, see Installing the Matrikon OPC Simulation
Server on page 1-18. The code requires only minor changes to work with
other servers.

2-2

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

The example in this chapter uses the OPC Tool GUI. However, each step
contains information on how to complete that step using command-line
code. The entire example is contained in the demonstration file
opcdemo_quickstart.

Step 1: Open the OPC Tool GUI

To open the OPC Tool GUI, type opctool at the MATLAB prompt.
The GUI is displayed with no hosts, servers, or toolbox objects created. The
following figure shows the main components of the OPC Tool GUI.

OPC Tool Graphical User Interface

In the following steps, you will fill each of the panes with information required
to log data, and you will log the data, by creating and interacting with OPC
Toolbox objects.

2-3

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Command-Line Equivalent
Since this step simply opens the OPC Tool GUI, there is no equivalent
function when using the command line.

Step 2: Locate Your OPC Server

In this step, you obtain two pieces of information that the toolbox needs
to uniquely identify the OPC server that you want to access. You use this
information when you create an OPC Data Access Client object (opcda client
object), described in Step 3: Create an OPC Data Access Client Object on
page 2-6.
The first piece of information that you require is the hostname of the server
computer. The hostname (a descriptive name like "PlantServer" or an IP
address such as 192.168.16.32) qualifies that computer on the network, and
is used by the OPC Data Access protocols to determine the available OPC
servers on that computer, and to communicate with the computer to establish
a connection to the server. In any OPC Toolbox application, you must know
the name of the OPC servers host, so that a connection with that host can be
established. Your network administrator will be able to provide you with a
list of hostnames that provide OPC servers on your network. In this example,
you will use localhost as the hostname, because you will connect to the OPC
server on the same machine as the client.
The second piece of information that you require is the OPC servers 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 text string, usually containing periods.
Although your network administrator will be able to provide you with a list of
server IDs for a particular host, you can query the host for all available OPC
servers. Exploring Available OPC Servers on page 1-19 discusses how to
query hosts from the command line.
Using the OPC Tool GUI you can browse a host using the following steps:
1 In the Hosts and OPC Servers pane, click the Add host icon to open

the Host name dialog, shown below.

2-4

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Add Host Button and Resulting Host Name Dialog

2 In the Host name dialog, enter the name of the host. In this case, you can

use the "localhost" alias.

localhost

Click OK. The hostname will be added to the OPC Network tree view,
and the OPC servers installed on that host will automatically be found
and added to the tree view. Your Hosts and OPC Servers pane should
look similar to the one shown below.

Example of Hosts and OPC Servers Pane

Note that the local host in this example provides three OPC servers. The
Server ID for this example is 'Matrikon.OPC.Simulation.1'.

2-5

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Command-Line Equivalent
The command-line equivalent for this step uses the function opcserverinfo.
hostInfo = opcserverinfo('localhost')
hostInfo =
Host:
ServerID:
ServerDescription:
OPCSpecification:
ObjectConstructor:

'localhost'
{1x3 cell}
{1x3 cell}
{'DA2' 'DA2'
{1x3 cell}

'DA2'}

Examining the returned structure in more detail provides the server IDs of
each OPC server.
allServers = hostInfo.ServerID'
allServers =
'Matrikon.OPC.Simulation.1'
'ICONICS.Simulator.1'
'Softing.OPCToolboxDemo_ServerDA.1'

Step 3: Create an OPC Data Access Client Object

Once you have determined the hostname and server ID of the OPC server you
want to connect to, you can create an opcda client object. The client controls
the connection status to the server, and stores any events that take place
from that server (such as notification of data changing state, which is called a
data change event) in the event log. The opcda client object also contains any
Data Access Group objects that you create on the client. For more information
on the OPC Toolbox object hierarchy, see Understanding the OPC Toolbox
Object Hierarchy on page 1-6.
With the OPC Tool GUI, you can create a client directly from the Hosts and
OPC Servers pane.
Right-click the Matrikon server node and choose Create client. A client will
be created in the OPC Toolbox Objects pane, as shown in the following
figure.

2-6

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Server Context Menu and Client Node

The name of the client (displayed in the OPC Toolbox Objects pane) is
Host/ServerID, where Host is the hostname and ServerID is the Server
ID associated with that client. In this example, the clients name is
'localhost/Matrikon.OPC.Simulation.1'

2-7

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Once you have created the client, you can view the properties of the client
object in the Object Properties pane, as shown in the next figure.

Example of OPC Toolbox Objects Pane, Showing Client Properties

Alternative Methods for Creating Clients

You can also create a client in the OPC Tool GUI by using one of the following
methods:
Select the MATLAB OPC Clients node in the OPC Toolbox Objects
pane and click Add Client in the OPC Toolbox Objects toolbar.
Choose Add from the Client menu.
Right-click the MATLAB OPC Clients node in the OPC Toolbox Objects
tree and select Create Client.

2-8

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

If you select one of the methods described above, a dialog appears requesting
the hostname and server ID.

Add Client Dialog

When you supply a hostname, you will be able to select the Server ID
from a list, by clicking Select. Using the Add client dialog, you can also
automatically attempt to connect to the server when the client is created, by
checking Connect after creating OPC Client before clicking OK.

Command-Line Equivalent
The command-line equivalent of this step involves using the opcda function,
specifying the hostname and Server ID arguments.
da = opcda('localhost', 'Matrikon.OPC.Simulation.1')
da =
OPC Data Access Object: localhost/Matrikon.OPC.Simulation.1
Server Parameters
Host:
localhost
ServerID:
Matrikon.OPC.Simulation.1
Status:
disconnected
Object Parameters
Group:
0-by-1 dagroup object

For more information on creating clients, see Creating a Client Object on

page 1-21.

2-9

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Step 4: Connect to the OPC Server

OPC Data Access Client objects are not automatically connected to the server
when they are created. This allows you to fully configure an OPC Toolbox
object hierarchy (a client with groups and items) prior to connecting to the
server, or without a server even being present.
Note The Add Client dialog described in Alternative Methods for Creating
Clients on page 2-8 can connect the client to the server after creating the
client object.
To connect the client to the server, you can use the OPC Toolbox Objects
toolbar, shown in the following figure.

OPC Toolbox Objects Toolbar

Click Connect in the OPC Toolbox Objects toolbar. If the client is able to
connect to the server, the icon for that client in the OPC Toolbox Objects
tree will change to show that the client is connected. If the client could not
connect to the server, an error dialog will show any error message returned.
See Troubleshooting on page 1-28 for information on why a client may not
be able to connect to a server.

2-10

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

When you connect an opcda client object to the server associated with that
client, the server node in the Hosts and OPC Servers pane also updates
to show that the server has a connection to a client in the GUI. With that
connection, the properties of the server are displayed in the Hosts and OPC
Servers pane. For this example, a typical view of the GUI after connecting to
a client is shown in the next figure.

Example of Connected Client and OPC Server Properties

The OPC server properties include diagnostic information, such as the

supported OPC Data Access interfaces, the time the server was started, and
the current server status.

Command-Line Equivalent
You use the connect function to connect an opcda client object to the server
at the command line.
connect(da)

2-11

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Step 5: Create an OPC Data Access Group Object

You create Data Access Group objects (dagroup objects) to control and contain
a collection of Data Access Item objects (daitem objects). A dagroup object
controls how often the server must notify you of any changes in the item
values, control the activation status of the items in that group, and define,
start, and stop logging tasks.
To create a dagroup object, click Add group in the OPC Toolbox Objects
toolbar. A group is created and automatically named, either by the OPC
server or by OPC Toolbox software.

Example of OPC Data Access Group Properties Pane

On their own, dagroup objects are not useful. Once you add items to a group,
you can control those items, read values from the server for all the items in a
group, and log data for those items, using the dagroup object. In Step 6 you

2-12

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

browse the OPC server for available tags. Step 7 involves adding the items
associated with those tags to the dagroup object.

Command-Line Equivalent
To create dagroup objects from the command line, you use the addgroup
function. This example adds a group to the opcda client object already created.
grp = addgroup(da)
grp =
OPC Group Object: Group0
Object Parameters
GroupType:
private
Item:
0-by-1 daitem object
Parent:
localhost/Matrikon.OPC.Simulation.1
UpdateRate:
0.5
DeadbandPercent: 0
Object Status
Active:
on
Subscription:
on
Logging:
off
LoggingMode:
memory

See Creating Data Access Group Objects on page 3-2 for more information
on creating group objects from the command line.

Step 6: Browse the Server Name Space

All OPC servers provide access to server items via a server name space. The
name space is an ordered list of the server items, usually arranged in a
hierarchical format for easy access. A server item (also known as a tag) is a
measurement or data point on a server, providing information from a device
(such as a pressure sensor) or from another software package that supplies
data through OPC Data Access (such as a SCADA package).

2-13

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Note If you know the item IDs of the server items you are interested in, you
can skip this section and proceed to Step 7: Add OPC Data Access Items to
the Group on page 2-17. In this example, assume that you do not know the
exact item IDs, although you do know that you want to log information from
the Saw-toothed Waves and Triangular Waves provided by the Matrikon
Simulation Server.
The Namespace tab of the Hosts and Servers pane allows you to graphically
browse a servers name space. Because most OPC servers contain thousands
of server items, retrieving a name space can be time consuming. When you
connect to a server for the first time, the name space is not automatically
retrieved. You have to request the name space using one of the View buttons
in the Server Namespace toolbar, as shown in the following figure.

Namespace Toolbar Showing View Buttons

Click View hierarchical namespace to retrieve the hierarchical name space for
the Matrikon OPC Server. A tree view containing the Matrikon name space is
shown in the pane. Your pane should look similar to the following figure.

Example of Populated Namespace Tree

2-14

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Note If you choose to view the name space as flat, you get a single list of all
server items in the name space, expanded to their fully qualified names. A
fully qualified name can be used to create a daitem object.
Browsing the name space using the GUI also provides some property
information for each server item. The properties include the published OPC
Item properties such as Value, Quality, and Timestamp, plus additional
properties published by the OPC server that may provide more information
on that particular server item. For a list of standard OPC properties and an
explanation of their use, consult Appendix B, OPC Server Item Properties.
In this example, you need to locate the Saw-toothed Waves and Triangle
Waves signals in the Matrikon Simulation Server. You can achieve this using
the following steps:
1 Ensure that you are viewing the hierarchical name space.
2 Expand the Simulation items node. You will see all the signal types

that the Matrikon Server simulates.

3 Expand the Saw-toothed Waves node. A number of leaf nodes appear. A

leaf node contains no other nodes, and usually signifies a tag on an OPC
server.

2-15

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

4 Select the Real8 leaf node. You will see the properties of the server item in

the properties table below the name space tree, as shown in the following
figure.

Example of Server Tag Properties

Note the Item Canonical DataType property, which is double. The

Canonical DataType is the data type that the server uses to store the
server items value.
5 Select the UInt2 leaf node. You will notice that the properties update, and

the Item Canonical Datatype property for this server item is uint16.
(MATLAB denotes integers with the number of bits in the integer, such as
uint16; the Matrikon Server uses the COM Variant convention denoting
the number of bytes, such as UInt2.)
You can continue browsing the server name space using the Server
Namespace pane in the GUI. One unique characteristic of the Matrikon
Simulation Server is that you can view the connected clients through the
name space, by selecting the Clients node in the root of the name space.
In Step 7, you will add three items to your newly created group object, using
the Server Namespace pane.

2-16

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Command-Line Equivalent
From the command line, you can browse the server name space using the
serveritems function. You need to supply a connected opcda client object
to the serveritems function, and an optional string to limit the returned
results. The string can contain wildcard characters (*). An example of using
serveritems is as follows.
sawtoothItems = serveritems(da, '*Saw*')
sawtoothItems =
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed
'Saw-toothed

Waves.'
Waves.Int1'
Waves.Int2'
Waves.Int4'
Waves.Money'
Waves.Real4'
Waves.Real8'
Waves.UInt1'
Waves.UInt2'
Waves.UInt4'

The command-line equivalent for obtaining the server item properties is

serveritemprops. See the serveritemprops reference page for more
information on using the function.

Step 7: Add OPC Data Access Items to the Group

Now that you have found the server items in the name space, you can add
Data Access Item objects (daitem object) for those tags to the dagroup object
you created in Step 5. A daitem object is a link to a tag in the name space,
providing the tag value, and additional information on that item, such as the
Canonical Data Type.
Using the GUI, you create items directly from the name space tree, using a
context menu on each node in the tree.
Browse to Simulated Items > Saw-toothed Waves > Real8, and right-click
that node to bring up the context menu. Selecting Add to from the context
menu provides you with a list of created groups for the item associated with

2-17

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

that server, and a menu item to create a New group (and add the item to
that group).
The menu displayed for this example is shown in the following figure.

Example of Context Menu for Namespace Node

Click Group0 to add the item to the already existing group that you created
in Step 5. A daitem object is created in the OPC Toolbox Objects pane. The
following figure shows the newly created item highlighted, with the properties
of the item shown in the Properties pane.

2-18

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Example of Data Access Item Object and Properties

Reading a Value from the Server

A daitem object initially contains no information about the server item that it
represents. The daitem object only updates when the server notifies the client
of a change in status for that item (the notification is called a data change
event) or the client specifically reads a value from the server. Using the GUI,
you can force a read of the item by clicking Read in the Properties pane
of the required item.
Click Read. The Value, Quality, and Timestamp fields in the GUI will
update. Value contains the last value that the server read from that
particular item. Quality provides a measure of how meaningful Value is.
If Quality is Good, then the Value can be trusted to be the same as the
device or object to which the item refers, but only at the time provided by the
Timestamp field. If Quality is anything other than Good, then the Value
of the item is questionable.

2-19

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Each time you read or obtain data from the server through a data change
event, the server will provide you with updated Value, Quality, and
Timestamp values.

Adding More Items to the Group

Using the Namespace pane, expand the Triangle Waves node and add
items for the Real8 and UInt2 server items. You will then have three items
associated with your dagroup object. In Step 8, you configure a logging
session for that group. You then log data in Step 9 from the three items you
just created, and visualize the data in Step 10.

Command-Line Equivalent
You use the additem function to add items to a dagroup object. You need
to pass the dagroup object to which the items will be added, and the fully
qualified item ID as a string. The item IDs were found using the serveritems
function in Step 6.
itm1 = additem(grp, 'Saw-toothed Waves.Real8')
itm1 =
OPC Item Object: Saw-toothed Waves.Real8
Object Parameters
Parent:
Group0
AccessRights:
read/write
DataType:
double
Object Status
Active:
on
Data:
Value:
Quality:
Timestamp:

You can add multiple items to the group in one additem call, by specifying
multiple ItemID values in a cell array.
itms = additem(grp, {'Triangle Waves.Real8', ...
'Triangle Waves.UInt2'})
itms =

2-20

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

OPC Item Object Array:

Index: DataType: Active:
1
double
on
2
uint16
on

ItemID:
Triangle Waves.Real8
Triangle Waves.UInt2

For more information on adding items to groups, see Creating Data Access
Item Objects on page 3-5.

Step 8: View All Item Values

You can view the Value, Quality, and Timestamp for each item using the
items properties pane. However, that view only provides access to one item at
a time. The group object is designed to allow you to read and write values from
all items in the group, and to log data to memory and/or disk. You use the
Group Read/Write pane to view the values of the items you created in Step
7 to determine the approximate range of values that each items value varies
over. The information from this pane will help you to verify that the data is
updating, and whether you can plot the data in one set of axes or in subplots.
Click Group0 in the OPC Toolbox Objects pane. Select the Read/Write
tab in the top of the Group properties pane. The OPC Toolbox Objects
pane should now look similar to the one shown in the following figure.

2-21

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Example of Group Read/Write Pane

The Value, Quality, and Timestamp values in the table of items will
continually update as long as you have Subscription enabled. Subscription
controls whether data change events are sent by the OPC server to the
toolbox, for items whose values change. UpdateRate and DeadbandPercent
define how often the items must be queried for a new value, and whether
all value changes or only changes of a specified magnitude are sent to the
toolbox. For more information on Subscription, see Data Change Events and
Subscription on page 4-12.
By observing the data for a while, you will see that the three signals appear
to have similar ranges. This indicates that you can visualize the data in the
same axes when you plot it in Step 11.

2-22

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

You can also use the Group Read/Write pane for writing values to many
items simultaneously. Specify a value in the Write column of the Item
data table for each item you want to write to, and click Write, to be able to
write to those items.
In Step 10 you will configure a logging task and log data for the three items.

Command-Line Equivalent
You can use the read function with a group object as the first parameter to
read values from all items in a group. The read function is discussed in more
detail in Reading and Writing Data on page 4-2.

Step 9: Configure Group Properties for Logging

Now that your dagroup object contains items, you can use the group to control
the interaction of those items with the server. In this step, you configure the
group to log data from those items for 2 minutes at 0.2-second intervals. You
will use the logged data in Step 11 to visualize the signals produced by the
Matrikon Simulation Server.
OPC Data Access Servers provide access only to "live" data (the last known
value of each server item in their name space). In many cases, a single value
of a signal is not useful, and a time series containing the signal value over a
period of time is helpful in analyzing that signal or signal set. OPC Toolbox
software allows you to log all items in a group to disk or memory, and to
retrieve that data for analysis in MATLAB.
You configure a logging session using the dagroup object. By modifying the
properties associated with logging, you control how often the data must be
sent from the server to the client, how many records the group must log, and
where to log the data. This information is summarized in the Logging pane
of the dagroup object properties in the GUI.

2-23

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

Select the Logging tab in the Properties pane. The following figure shows
the Logging pane for the dagroup object created in this example.

Example of Logging Pane for Data Access Group Objects

Using the Logging pane, configure the logging session using the following
steps:
1 Set Update rate to 0.2.
2 Set Number of records to log to 600. Because you want to log for

2 minutes (120 seconds) at 0.2-second update rates, you need 600 (i.e.,
120/0.2) records.
You can leave the rest of the logging properties at their default values,
because this example uses data logged to memory.
In Step 10 you log the data. In Step 11 you will visualize the data.

2-24

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

Command-Line Equivalent
You use the set function to set OPC Toolbox object properties. From the
MATLAB command line, you can calculate the number of records required
for the logging task.
logDuration = 2*60;
logRate = 0.2;
numRecords = ceil(logDuration./logRate)
set(grp, 'UpdateRate',logRate,'RecordsToAcquire',numRecords);

Step 10: Log OPC Server Data

In Step 9 you configured the dagroup objects logging properties. Your object
is now ready to log the required amount of data to memory.
Click Start in the Logging tab. The logging task will begin, and the OPC
Toolbox software engine will receive and store the data from the OPC server.
The progress bar indicates the status of the logging task, as shown in the
following figure.

Example of Logging Task in Progress

Note The logging task occurs in the background. You can continue working
in MATLAB while a logging task is in operation. The logging task is not
affected by any other computation taking place in MATLAB, and MATLAB is
not blocked from processing by the logging task.
Wait for the task to complete before continuing with Step 11.

Command-Line Equivalent
You use the start function with the required dagroup object to start a
logging task.

2-25

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

start(grp)

Although the logging operation takes place in the background, you can
instruct MATLAB to wait for the logging task to complete, using the wait
function.
wait(grp)

Step 11: Plot the Data

In this introductory example, you use the GUI to visualize the data logged
in Step 10. In a more complex task, you would export the logged data to the
workspace and use MATLAB functions to analyze and interpret the logged
data.
When the logging task stops, the Logging pane will update to show that the
task is complete. An example of the logging status portion of the Logging
pane after a completed task is shown in the following figure.

Example of Logging Pane After Logging has Completed

To view the data from the GUI, click Plot. The logged data will be retrieved
from the toolbox engine and displayed in a MATLAB figure window. The
format of the displayed data and annotation options are controlled by settings
in the Plot options frame of the Logging pane. By default, the plot will
be annotated with any data points that have a Quality other than Good.
Values whos Quality is Bad are annotated with a large red circle with a black
border, and Values with Quality of Repeat are annotated with a yellow star.
You should always view the Quality returned with the Value of an item to
determine if the Value is meaningful or not. The relationship between the
Value and Quality of an item is discussed in Understanding OPC Data:
Value, Quality, and TimeStamp on page 5-2.

2-26

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

An example of the plotted data is shown in the next figure.

Example of Data Plot from a Logging Task

Note Your plotted data will almost certainly not look like the one shown here,
because the logging task was executed at a different time.
Notice how the three signals seem almost completely unrelated, except for the
period of the two Real8 signals. The peak values for each signal are different,
as are the periods for the two Triangle Waves signals. By visualizing the
data, you can gain some insight into the way the Matrikon OPC Simulation
Server simulates each tag. In this case, it is apparent that Real8 and UInt2
signals have a different period.

Command-Line Equivalent
When your logging task has completed you transfer data from the toolbox
engine to the MATLAB workspace using the getdata function, which provides

2-27

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

two types of output, depending on the datatype argument. For more

information see getdata in the reference pages. In this case you retrieve the
data into separate arrays, and plot the data.
The example below reproduces the figure display that you get when you click
Plot.
[logIDs, logVal, logQual, logTime, logEvtTime] = ...
getdata(grp, 'double');
plot(logTime, logVal);
axis tight
datetick('x', 'keeplimits')
legend(logIDs)

Step 12: Clean Up

When you are finished with an OPC task, you should remove the task objects
from memory and clear the MATLAB workspace of the variables associated
with these objects. The OPC Tool GUI will automatically delete all objects
that it creates from the toolbox engine. If you work only in the OPC Tool GUI,
you do not need to perform any further cleanup other than to close the GUI.
You close the GUI by using the Exit option in the File menu, or by using the
Close button in the title bar. You will be prompted to save the OPC Tool
session. You can choose to save the session to an OPC Session File (.osf file)
for later use, or exit without saving.

Command-Line Equivalent
When you use OPC Toolbox objects from the MATLAB command line, or from
your own functions, you must remove them from the OPC Toolbox software
engine using the delete function. Note that when you delete a toolbox object,
the children of that object are automatically removed from the toolbox engine.
In the following example, there is no need to delete grp and itm, as they
are children of da.
disconnect(da)
delete(da)
clear da grp itm
close(gcf)

2-28

Downloaded from www.Manualslib.com manuals search engine

Example: Basic OPC Toolbox Acquisition Procedure

OPC Toolbox object management is discussed in more detail in Deleting

Objects on page 3-23.

2-29

Downloaded from www.Manualslib.com manuals search engine

Quick Start: Using the OPC Tool GUI

2-30

Downloaded from www.Manualslib.com manuals search engine

3
Using OPC Toolbox Objects
To interact with an OPC server, you need to create toolbox objects. You create
an OPC Data Access Client (opcda client) object to provide a connection to
a particular OPC server. You then create one or more Data Access Groups
(dagroup objects) to control sets of Data Access Items (daitem objects), which
represent links to server items. OPC Toolbox objects are described in more
detail in Understanding the OPC Toolbox Object Hierarchy on page 1-6.
This chapter describes how to create and configure toolbox objects to interact
with an OPC server. Chapter 4, Reading, Writing, and Logging OPC Data
provides information on how to use the OPC Toolbox objects to exchange data
with an OPC server.
Creating OPC Toolbox Objects on page 3-2
Configuring OPC Toolbox Object Properties on page 3-17
Deleting Objects on page 3-23
Saving and Loading Objects on page 3-25

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

Creating OPC Toolbox Objects

In this section...
Overview on page 3-2
Creating Data Access Group Objects on page 3-2
Creating Data Access Item Objects on page 3-5
Building an Object Hierarchy with a Disconnected Client on page 3-8
Creating OPC Toolbox Object Vectors on page 3-9
Working with Public Groups on page 3-12

Overview
The first step in interacting with an OPC server from MATLAB software is to
establish a connection between the server and OPC Toolbox software. You
create opcda client objects to control the connection between an OPC server
and the toolbox. Then you create dagroup objects to manage sets of daitem
objects, and then you create the daitem objects themselves, which represent
server items. A server item corresponds to a physical device or to a storage
location in a SCADA system or DCS.
You must create the toolbox objects in the order described above. Connecting
to OPC Servers on page 1-21 describes how to create an opcda client object.
This section discusses how to create and configure dagroup and daitem
objects.

Creating Data Access Group Objects

Once you have created an opcda client object, you can add groups to the client.
A dagroup object manages multiple daitem objects. Using a dagroup object,
you can read data from all items in that group in one action, write data to
the items in the group, define actions to take when any of the items in that
group change value, or log data for all the items in that group for analysis
and processing.
To create a dagroup object, you use the addgroup function, specifying the
opcda client object that you want to add the group to, and an optional group

3-2

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

name. See Specifying a Group Name on page 3-3 for rules on defining your
own group name.
The example below creates an opcda client object, connects that object to the
server, and adds two groups to the client. The first group is automatically
named by the server, and the second group is given a specified name.
da = opcda('localhost', 'Matrikon.OPC.Simulation.1');
connect(da);
grp1 = addgroup(da);
grp2 = addgroup(da, 'MyGroup');

Specifying a Group Name

Every OPC server requires that each group created by the client has a
unique name. This allows the OPC server to uniquely identify the group
when a client makes a server request using that group. The name can be
any nonempty string.
You do not need to specify a group name for each group that you add to a
client. If you do not specify a name, the OPC server will automatically assign
a group name for you. Each OPC server defines different rules for automatic
naming of groups.
If you attempt to create a group with the same name as a group already
created for that client, an error will be generated.
See Deleting Objects on page 3-23 for information about how groups are
automatically named when you create groups with a disconnected client.

Viewing a Summary of a Group Object

To view a summary of the characteristics of the dagroup object you created,
enter the variable name you assigned to the object at the command prompt.
For example, this is the summary for the object grp1.
grp1

3-3

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

The items in this list correspond to the numbered elements in the object
summary:
1 The title of the Summary includes the name of the dagroup object. In the

example, this is the server-assigned name Group0.

2 The Object Parameters section lists the values of key dagroup object

properties. These properties describe the type of group, the daitem objects
associated with the group, the name of the groups parent opcda client
object, and properties that control how the server updates item information
for this group. In the example, any items created in this group will be
updated at half-second intervals, with a deadband of 0%. For information
on how the server updates item information, see Data Change Events and
Subscription on page 4-12.
3 The Object Status section lists the current state of the object. A dagroup

object can be in one of several states:

The Active state defines whether any operation on the group applies
to the item.
The Subscription state defines whether changes in the items value or
quality will produce a data change event. See Data Change Events and
Subscription on page 4-12 for more information about the Subscription
property.

3-4

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

The Logging state describes whether the group is logging or not. See
Logging OPC Server Data on page 4-17 for information on how to log
data.
4 The Logging Parameters section describes the values of the logging

properties for that group. Logging properties control how the dagroup
object logs data, including the duration of the logging task and the
destination of logged data. See Logging OPC Server Data on page 4-17 for
information on logging data using dagroup objects.

Using a Group Object

A dagroup object with no items does not perform any useful functions. Once
you have added items to a group, you can use the group to
Read data from, and write data to, the OPC server. See Reading and
Writing Data on page 4-2 for more information.
Control how an OPC server notifies MATLAB about changes in any
item associated with a dagroup object. See Data Change Events and
Subscription on page 4-12 for more information.
Log data from all items in that group, for later processing and analysis.
Logging OPC Server Data on page 4-17 describes how to control logging.

Creating Data Access Item Objects

A dagroup object provides a container for collecting one or more daitem
objects. A daitem object provides a link to a specific server item. The daitem
object defines how you want to retrieve and store the client-side value of the
server item, and also stores the last data retrieved from the server for that
server item. You can use a daitem object to read data from the server for that
server item, or to write values to that server item on the server.
You create a daitem object using the additem function, specifying the dagroup
object to which the item must be added and the fully qualified item ID of the
server item. You can obtain a list of the fully qualified item IDs for all server
items using the serveritems function.
The example below builds on the example in Creating Data Access Group
Objects on page 3-2 by adding a daitem object to the first group created

3-5

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

in that example. The server item associated with this item is called
'Random.Real8'.
itm1 = additem(grp1, 'Random.Real8');

Specifying a Local Data Type for the Item

When you create a daitem object, you create an object that stores the value of
the server item locally on the client. You can specify that the local storage
data type be different from the server storage data type. For example, you can
specify that a value stored on the server as an integer be stored in MATLAB
as a double-precision floating-point value, because you know that you will be
performing double-precision calculations with that items value.
Although it is possible to modify the data type of the item after it is created,
you can also create an item with a specific data type by specifying the
data type as the third parameter to the additem function. The data type
specification must be a string describing that data type. Valid OPC data
types are any MATLAB numeric data type, plus 'char', and 'logical'. See
Working with Different Data Types on page 5-18 for more information on
supported data types.
The example below adds another item to the group grp1 created by the
example in Creating Data Access Group Objects on page 3-2. The item
ID is 'Random.UInt2', which is stored on the server as an unsigned 16-bit
integer. By specifying the data type as 'double', the value will be returned
to MATLAB and stored locally as a double-precision floating-point number.
itm2 = additem(grp1, 'Random.UInt2', 'double');

Note The conversion process from the servers data type to the items data
type is performed by the server, using Microsoft COM Variant conversion
rules. If you attempt to convert a value to a data type that does not have that
values range, the OPC server will return an error when attempting to update
the value of that item. You should then change the data type to one that has
the same or larger range than the server items data type. See Working with
Different Data Types on page 5-18 for more information.

3-6

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

Specifying the Active Status of an Item Object

You can optionally specify the Active status of an daitem object by passing a
string as the fourth parameter to the additem function. The Active status
can be 'on' or 'off'. An item with an Active status of 'off' behaves as if
the item was never created: No server updates of the items value will take
place, and a read or write with that item will fail. You use the Active status
to temporarily disable an item without deleting that item from MATLAB.
For more information on the Active status, see the reference page for the
Active property.

Viewing a Summary of the Item Object

To view a summary of the characteristics of the daitem object you created,
enter the variable name you assigned to the object at the command prompt.
For example, this is the summary for the object itm1.
itm1

The items in this list correspond to the numbered elements in the object
summary:
1 The title of the Summary includes the fully qualified item ID of the item. In

the example, the item is associated with the 'Random.Real8' server item.
2 The Object Parameters section lists the values of key daitem object

properties. These properties describe the name of the items Parent group,
and the Access Rights advertised by the server.

3-7

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

3 The Object Status section lists the Active state of the object. The Active

state defines whether any operation on the parent group applies to the item,
and whether you want to be notified of any changes in the items value.
4 The Data Parameters section lists the Data Type used by the daitem

object to store the value, and the Value, Quality, and TimeStamp of the
last value obtained from the server for this item. For more information on
the Value, Quality, and TimeStamp of an item, see Understanding OPC
Data: Value, Quality, and TimeStamp on page 5-2.

Using an Item Object

You create a daitem object to query the value of the associated server item, or
to write values to that server item. You can write values to a single item, and
read values from a single item, using the daitem object. For more information
on reading and writing values, see Reading and Writing Data on page 4-2.
You can also use the parent dagroup object to read and write values for all
of the daitem objects contained in that group, or to log changes in the items
value for a period of time. See Logging OPC Server Data on page 4-17 for
information on logging data.

Building an Object Hierarchy with a Disconnected

Client
When you create objects with a connected client, OPC Toolbox software
validates those objects with the OPC server before creating them on the
client. For example, when adding a group to the client using the addgroup
function, the validation process ensures that no other group with the same
name exists on the server, and that the server will accept the group. When
adding an item, the item ID is verified to be a valid server item.
Occasionally you may wish to build up a toolbox object hierarchy without
connecting to the server. For example, you may be off site and wish to
configure a logging task for use on the following day, rather than wait to
configure the objects for that task when you are on site.
OPC Toolbox software allows you to configure an entire toolbox object
hierarchy without connecting to the server. However, without a connection to
the server, the toolbox cannot validate the created objects with that server.

3-8

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

Instead, OPC Toolbox software will perform some basic validation on the
objects you create, and revalidate those objects with the server when you
connect to the server.
When you create toolbox objects with a disconnected client, the following
validation is performed:
When adding a group using the addgroup function, if you do not specify
a name, OPC Toolbox software automatically assigns a unique name
'groupN', where N is the lowest integer that ensures that the group name
is unique. For example, the first group created will be 'group1', then
'group2', and so on.
When you specify a group name when using the addgroup function, an
error will be generated if a group with the same name already exists.
When adding an item to a group using the additem function, an error will
be generated only if an item with the same name already exists in that
group. No other checking is performed on the item.
When adding an item to a group, if you do not specify a data type for that
item, the data type is set to 'unknown'. When you connect to the server,
the data type will be changed to the server items CanonicalDataType.
Despite all of the checks described above, the server may not accept all
objects created on a disconnected client when that client is connected to the
server using the connect function. For example, an items item ID may not
be valid for that server, or a group name may not be valid for that server.
When you connect a client to the server using connect, any objects that the
server rejects will be deleted from the object hierarchy, and a warning will
be generated. In this way, all objects on a connected client are guaranteed
to have been accepted by the server.

Creating OPC Toolbox Object Vectors

OPC Toolbox software supports the use of object vectors. An object vector is
a single variable in the MATLAB workspace containing a reference to more
than one object. For example, all the groups added to an opcda client object
are stored in the clients Group property. The Group property contains a
dagroup object vector that represents all groups in that client. Similarly,

3-9

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

a dagroup object has an Item property that contains a reference to every

daitem object created in the group.
You can construct vectors using any of the standard concatenation techniques
available in MATLAB. However, OPC Toolbox software imposes some
limitations on the construction of object vectors:
Objects must be the same class. For example, you can concatenate two
dagroup objects, but you cannot concatenate a dagroup object with a
daitem object.
Group and item objects must have the same parent.
One of the dimensions of the resulting array must be scalar. You can create
a column vector (m-by-1 objects) or a row vector (1-by-n objects), but not an
m-by-n matrix.
OPC Toolbox software does not fill in missing elements in a vector. Instead,
an error is generated. For example, you cannot assign a scalar object at the
4th index to a scalar object.
The following sections discuss how to create and use toolbox object vectors:
Constructing Object Vectors on page 3-10 describes how to create object
vectors.
Displaying a Summary of Object Vectors on page 3-11 describes how
object vectors are displayed at the command line.
Using Object Vectors on page 3-12 describes how you can use object
vectors with OPC Toolbox software.

Constructing Object Vectors

You can construct an object vector using any of the following techniques:
Using concatenation of lists of individual object variables
Using indexed assignment
Using object properties to retrieve object vectors

3-10

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

Creating object vectors using concatenation. To construct an OPC

Toolbox object vector using concatenation, you use the normal MATLAB
syntax for concatenation. Create a list of all objects you want to create, and
surround that list with square brackets ([]). Separate each element of the
object vector by either a comma (,) to create a row vector, or a semicolon (;) to
create a column vector.
The following example creates three fictitious opcda client objects, and
concatenates them into a row vector.
da1
da2
da3
dav

=
=
=
=

opcda('Host1','Dummy.Server.1');
opcda('Host2','Dummy.Server.2');
opcda('Host3','Dummy.Server.3');
[da1, da2, da3];

Creating object vectors using indexed assignment. Indexed assignment

refers to creating vectors by assigning elements to specific indices in the
vector. The following example constructs the same three-element opcda client
object vector as in the previous example, using indexed assignment.
dav(1) = opcda('Host1','Dummy.Server.1');
dav(2) = opcda('Host2','Dummy.Server.2');
dav(3) = opcda('Host3','Dummy.Server.3');

Creating object vector using object properties. You may obtain an object
vector if you assign the Group property of a opcda client object, or the Item
property of a dagroup object, to a variable. If the client has more than one
group, or the group has more than one item, the resulting property is an
object vector.
For information on obtaining object properties, see Viewing the Value of a
Particular Property on page 3-19.

Displaying a Summary of Object Vectors

To view a summary of an object vector, type the name of the object vector at
the command prompt. For example, this is the summary of the client vector
dav.
dav =

3-11

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

OPC Data Access Object Array:

Index:
1
2
3

Status:
disconnected
disconnected
disconnected

Name:
Host1/Dummy.Server.1
Host2/Dummy.Server.2
Host3/Dummy.Server.3

The summary information for each OPC Toolbox object class is different.
However, the basic display is similar.

Using Object Vectors

You use object vectors just as you would a normal object variable. The
function you call with the object vector simply gets applied to all objects in
the vector. For example, passing the client vector dav to the connect function
connects each object in the vector to its OPC server.
Note Some OPC Toolbox functions do not accept object vectors as arguments.
If you attempt to use an object vector with a function that does not accept
object vectors, an error will be generated. Consult the relevant function
reference page for information on whether a function supports object vectors.
If you need to extract elements of an object vector, use standard MATLAB
indexing notation. For example, the following example extracts the second
element from the client vector dav.
dax = dav(2);

Working with Public Groups

The OPC Data Access Specification provides a mechanism for sharing group
configuration amongst many clients. Normally, a client has private access to a
group; no other client connected to the same server can see that group, and
the items configured in that group. However, a client can define a group as
public, allowing other clients connected to the same server to gain access to
that group.

3-12

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

Note The OPC Data Access Specification defines the support for public groups
as optional. Consequently, some OPC servers will not support public groups.
A public group differs from a private group in the following ways:
Once a group is defined as public, you cannot add items to that group, nor
remove items from the group. This restriction ensures that every client
using that public group has access to the same items, and does not need to
worry about items being added or removed from that group. You should
ensure that a groups items are correct before making that group public.
Each client that accesses the public group is able to set its own group
properties, such as the UpdateRate, DeadbandPercent, Active, and
Subscription properties. For example, one client can define an
UpdateRate of 10 seconds for a public group, while another client specifies
the UpdateRate as 2 seconds.
Each public group defined on a server must have a unique name. If you
attempt to create a public group with a name that is the same as a public
group on the server, an error is generated.
A single client cannot have a public group and a private group with the
same name. For example, you cannot connect to a public group named
'LogGroup' and then create a private group called 'LogGroup'.
Using OPC Toolbox software, you can define and publish your own public
groups or connect to existing public groups. You an also request that public
groups be removed from an OPC server. The following sections illustrate how
you can work with public groups using OPC Toolbox software:
Defining a New Public Group on page 3-14 describes how you can create
new public groups.
Connecting to an Existing Public Group on page 3-14 describes how you
can utilise a public group that is already defined on the server.
Removing Public Groups from the Server on page 3-16 describes how you
can remove public groups from an OPC server.

3-13

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

Defining a New Public Group

You define a new public group by creating a private group in the normal way
(described in Creating Data Access Group Objects on page 3-2) and then
converting that private group into a public group.
You use the makepublic function to convert a private group into a public
group. The only argument to the makepublic function is the group object that
you want to convert to a public group.
The following example creates a private group, with specific items in that
group. The group is then converted into a public group.
da = opcda('localhost', 'My.Server.1');
grp = addgroup(da, 'PublicGrpExample');
itms = additem(grp, {'Item.ID.1', 'Item.ID.2'});
makepublic(grp);

You can check the group type using the GroupType property.
get(grp, 'GroupType')
ans =
public

Connecting to an Existing Public Group

In addition to creating new public groups, you can also create a connection
to an existing public group on the server. To obtain a list of available public
groups on a server, you use the opcserverinfo function, passing the client
object that is connected to the server as the argument. The returned structure
includes a field called 'PublicGroups', containing a cell array of public
groups defined on that server. If the 'PublicGroups' field is empty, then you
should check the 'SupportedInterfaces' field to ensure that the server
supports public groups. A server that supports public groups will implement
the IOPCServerPublicGroups interface.
Once you have a list of available public groups, you can create a connection to
that group using the addgroup function, passing it the client that is connected
to the server containing the public group, the name of the public group, and
the 'public' group type specifier.

3-14

Downloaded from www.Manualslib.com manuals search engine

Creating OPC Toolbox Objects

Note You cannot create a connection to an existing public group if your client
object is disconnected from the server.
The following example connects to a public group named 'PublicTrends' on
the server with program ID 'My.Server.1'.
da = opcda('localhost', 'My.Server.1');
connect(da);
pubGrp = addgroup(da, 'PublicTrends', 'public');

When you connect to a public group, the items in that group are automatically
created for you.
itm = get(pubGrp, 'Items');
itm =
OPC Item Object Array:
Index:
1
2
3

DataType:
double
uint16
double

Active:
on
on
on

ItemID:
item.id.1
item.id.2
item.id.3

You cannot add items to or remove items from a public group. However, you
can still modify the update rate of the group, the dead band percent, and the
active and subscription status of the group, and you can use the group to read,
write, or log data as you would for a private group.
When you have finished using a public group, you can use the delete function
to remove that group from your client object. Deleting the group from the
client does not remove the public group from the server; other clients might
require that group after you have finished with it. Instead, deleting the
group from the client indicates to the server that you are no longer interested
in the group.

3-15

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

Removing Public Groups from the Server

You can request that a public group be removed from a server using the
removepublicgroup function, passing the client object that is connected to
the server and the name of the public group to remove.
Caution The OPC Data Access Specification does not provide any security
mechanism for removing public groups; any client can request that a public
group be removed. You should use this function with extreme caution!
If any clients are currently connected to that group, the server will issue a
warning stating that the group will be removed when all clients have finished
using the group.

3-16

Downloaded from www.Manualslib.com manuals search engine

Configuring OPC Toolbox Object Properties

Configuring OPC Toolbox Object Properties

In this section...
Purpose of Object Properties on page 3-17
Viewing the Values of Object Properties on page 3-18
Viewing the Value of a Particular Property on page 3-19
Getting Information About Object Properties on page 3-19
Setting the Value of an Object Property on page 3-20
Viewing a List of All Settable Object Properties on page 3-21

Purpose of Object Properties

All OPC Toolbox objects support properties that enable you to control
characteristics of the object:
The opcda client object properties control aspects of the connection to the
OPC server, and event information obtained from the server. For example,
you can use the Timeout property to define how long to wait for the server
to respond to a request from the client.
The dagroup object properties control aspects of the collection of items
contained within that group, including all logging properties. For example,
the UpdateRate property defines how often the items in the group must be
checked for value changes, as well as the rate at which data will be sent
from the server during a logging session.
The daitem object properties control aspects of a single server item. For
example, you use the DataType property to define the data type that the
server must use to send values of that server item to the OPC Toolbox
software.
For all three toolbox objects, you can use the same toolbox functions to
View a list of all the properties supported by the object, with their current
values
View the value of a particular property

3-17

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

Get information about a property

Set the value of a property

Viewing the Values of Object Properties

To view all the properties of an OPC Toolbox object, with their current values,
use the get function.
If you do not specify a return value, the get function displays the object
properties in categories that group similar properties together. You use the
display form of the get function to view the value of all properties for the
toolbox object.
This example uses the get function to display a list of all the properties of
the OPC dagroup object grp.
get(grp)
General Settings:
DeadbandPercent = 0
GroupType = private
Item = []
Name = group1
Parent = [1x1 opcda]
Tag =
TimeBias = 0
Type = dagroup
UpdateRate = 0.5000
UserData = []
Callback Function Settings:
CancelAsyncFcn = @opccallback
DataChangeFcn = []
ReadAsyncFcn = @opccallback
RecordsAcquiredFcn = []
RecordsAcquiredFcnCount = 20
StartFcn = []
StopFcn = []
WriteAsyncFcn = @opccallback

3-18

Downloaded from www.Manualslib.com manuals search engine

Configuring OPC Toolbox Object Properties

Subscription and Logging Settings:

Active = on
LogFileName = opcdatalog.olf
Logging = off
LoggingMode = memory
LogToDiskMode = index
RecordsAcquired = 0
RecordsAvailable = 0
RecordsToAcquire = 120
Subscription = on

Viewing the Value of a Particular Property

To view the value of a particular property of an OPC Toolbox object, use the
get function, specifying the name of the property as an argument. You can
also access the value of the property as you would a field in a MATLAB
structure.
This example uses the get function to retrieve the value of the Subscription
property for the dagroup object.
get(grp,'Subscription')
ans =
on

This example illustrates how to access the same property by referencing the
object as if it were a MATLAB structure.
grp.Subscription
ans =
on

Getting Information About Object Properties

To get information about a particular property, you can view the reference
page for the property in Chapter 9, Functions Alphabetical List. You can
also get information about a particular property at the command line by using
the propinfo or opchelp functions.

3-19

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

The propinfo function returns a structure that contains information about

the property, such as its data type, default value, and a list of all possible
values if the property supports such a list. This example uses propinfo to
get information about the LoggingMode property.
propinfo(grp,'LoggingMode')
ans =
Type:
Constraint:
ConstraintValue:
DefaultValue:
ReadOnly:

'string'
'enum'
{'memory' 'disk'
'memory'
'whileLogging'

'disk&memory'}

The opchelp function returns reference information about the property with
a complete description. This example uses opchelp to get information about
the LoggingMode property.
opchelp(grp,'LoggingMode')

Setting the Value of an Object Property

To set the value of a particular property of an OPC Toolbox object, use the set
function, specifying the name of the property as an argument. You can also
assign the value to the property as you would a field in a MATLAB structure.
Note Because some properties are read-only, only a subset of the toolbox
object properties can be set. Use the property reference pages or the propinfo
function to determine if a property is read-only.
This example uses the set function to set the value of the LoggingMode
property.
set(grp,'LoggingMode','disk&memory')

To verify the new value of the property, use the get function.
get(grp,'LoggingMode')

3-20

Downloaded from www.Manualslib.com manuals search engine

Configuring OPC Toolbox Object Properties

ans =
disk&memory

This example sets the value of a property by assigning the value to the object
as if it were a MATLAB structure.
grp.LoggingMode = 'disk';
grp.LoggingMode
ans =
disk

Viewing a List of All Settable Object Properties

To view a list of all the properties of a toolbox object that can be set, use the
set function.
set(grp)
General Settings:
DeadbandPercent
Name
Tag
TimeBias
UpdateRate
UserData
Callback Function Settings:
CancelAsyncFcn: string -or- function handle -or- cell array
DataChangeFcn: string -or- function handle -or- cell array
ReadAsyncFcn: string -or- function handle -or- cell array
RecordsAcquiredFcn: string -or- function handle -or- cell array
RecordsAcquiredFcnCount
StartFcn: string -or- function handle -or- cell array
StopFcn: string -or- function handle -or- cell array
WriteAsyncFcn: string -or- function handle -or- cell array
Subscription and Logging Settings:
Active: [ {on} | off ]
LogFileName

3-21

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

LoggingMode: [ {memory} | disk | disk&memory ]

LogToDiskMode: [ {index} | append | overwrite ]
RecordsToAcquire
Subscription: [ {on} | off ]

When using the set function to display a list of settable properties, all
properties that have a predefined set of acceptable values list those values
after the property. The default value is enclosed in curly braces ({}). For
example, from the display shown above, you can set the Subscription
property for a dagroup object to 'on' or 'off', with the default value being
'on'. You can set the LogFileName property to any value.

Special Read-Only Modes

Some OPC Toolbox object properties change their read-only status, depending
on the state of an object (defined by another property of that object, or the
parent of that object). The toolbox uses two special read-only modes:
'whileConnected': These properties cannot be changed while the client
is connected to the OPC server. For example, the clients Host property is
read-only while connected.
'whileLogging': These properties cannot be changed while the dagroup
object is logging. For example, the LoggingMode property is read-only
while logging. For more information on logging, see Logging OPC Server
Data on page 4-17.
'whilePublic': These properties cannot be changed because the group is a
public group. For more information on public groups, see Working with
Public Groups on page 3-12.
Note Properties that modify their read-only state are always displayed
when using set to display settable properties, even when they cannot be
changed because of the state of the object.
To determine if a property has a modifiable read-only state, use the propinfo
function.

3-22

Downloaded from www.Manualslib.com manuals search engine

Deleting Objects

Deleting Objects
When you finish using your OPC Toolbox objects, use the delete function
to remove them from memory. After deleting them, clear the variables
that reference the objects from the MATLAB workspace by using the clear
function.
Note When you delete an opcda client object, all the group and item objects
associated with the opcda client object are also deleted. Similarly, when you
delete a dagroup object, all daitem objects associated with that dagroup
object are deleted.
To illustrate the deletion process, this example creates several opcda client
objects and then deletes them.
Step 1: Create several clients
This example creates several opcda client objects using fictitious host and
server ID properties.
da1 = opcda('Host1','Dummy.Server.1');
da2 = opcda('Host2','Dummy.Server.2');
da3 = opcda('Host3','Dummy.Server.3');

Step 2: Delete clients

Always remove toolbox objects from memory, and the variables that reference
them, when you no longer need them.
You can delete toolbox objects using the delete function.
delete(da1)
delete(da2)
delete(da3)

Note that the variables associated with the objects remain in the workspace.
whos

3-23

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

Name

Size

da1
da2
da3

1x1
1x1
1x1

Bytes
636
636
636

Class
opcda object
opcda object
opcda object

These variables are not valid OPC Toolbox objects.

isvalid(da1)
ans =
0

To remove these variables from the workspace, use the clear command.
Note You can delete toolbox object vectors using the delete function. You
can also delete individual elements of a toolbox object vector.

3-24

Downloaded from www.Manualslib.com manuals search engine

Saving and Loading Objects

Saving and Loading Objects

Using the save command, you can save an OPC Toolbox object to a MAT-file,
just as you would any workspace variable. This example saves the dagroup
object grp to the MAT-file myopc.mat.
save myopc grp

When you save a toolbox object, all the toolbox objects in that object hierarchy
are also saved. For example, if you save a dagroup object, the client, all
groups associated with that client and all items created in those groups are
saved along with the dagroup object. However, only those objects you elect to
save will be created in the MATLAB workspace. Other objects will be created
with no reference to them in the workspace. To obtain a reference to an
existing OPC Toolbox object, use the opcfind function.
To load a toolbox object that was saved to a MAT-file into the MATLAB
workspace, use the load command. For example, to load grp from MAT-file
myopc.mat, use
load myopc

Note The values of read-only properties are not saved. When you load a
toolbox object into the MATLAB workspace, read-only properties revert back
to their default values. To determine if a property is read-only, use the
propinfo function or see Chapter 11, Properties Alphabetical List.

3-25

Downloaded from www.Manualslib.com manuals search engine

Using OPC Toolbox Objects

3-26

Downloaded from www.Manualslib.com manuals search engine

4
Reading, Writing, and
Logging OPC Data
The core of any OPC Toolbox software application is the exchange of data
between the MATLAB workspace and one or more OPC servers. You create
and configure toolbox objects to support the reading, writing, and data logging
functions that you require for your application.
Using OPC Toolbox software you can exchange data with an OPC server
in a number of ways. You can read and write data from the MATLAB
command line or other MATLAB functions. You can configure toolbox objects
to automatically run MATLAB code when the server notifies the objects that
data has changed on the server. You can also log changes in OPC server data
to a disk file or to memory, for further analysis.
This chapter provides information on how to exchange data with an OPC
server.
Reading and Writing Data on page 4-2
Data Change Events and Subscription on page 4-12
Logging OPC Server Data on page 4-17

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Reading and Writing Data

In this section...
Introduction on page 4-2
Reading Data from an Item on page 4-2
Writing Data to an Item on page 4-6
Reading and Writing Multiple Values on page 4-8

Introduction
Using OPC Toolbox software, you can exchange data with the OPC server
using individual items, or using the dagroup object to perform the operation
on multiple items. The reading and writing operation can be performed
synchronously, so that your MATLAB session will wait for the operation to
complete, or asynchronously, allowing your MATLAB session to continue
processing while the operation takes place in the background.

Reading Data from an Item

You can read data from any item that is associated with a connected client.
When you perform the read operation on an item, the server will return
information about the server item associated with that item ID. The read
operation can be performed synchronously or asynchronously:
Using Synchronous Read Operations on page 4-2 describes how to
perform synchronous read operations. Synchronous read operations can
request data from the servers cache, or directly from the device.
Using Asynchronous Read Operations on page 4-5 describes how to
perform asynchronous read operations.

Using Synchronous Read Operations

A synchronous read operation means that MATLAB will wait for the server
to return data from a read request before continuing processing. The data
returned by the server can come from the servers cache, or you can request
that the server read values from the device that the server item refers to.

4-2

Downloaded from www.Manualslib.com manuals search engine

Reading and Writing Data

You use the read function to perform synchronous read operations, passing
the daitem object associated with the server item you want to read. If the
read operation is successful, the data is returned in a structure containing
information about the read operation, including the value of the server item,
the quality of that value, and the time that the server obtained that value.
The items Value, Quality and Timestamp properties are also updated to
reflect the values obtained from the read operation.
The following example creates an opcda client object and configures a group
with one item, 'Random.Real8'. A synchronous read operation is then
performed on the item.
da = opcda('localhost', 'Matrikon.OPC.Simulation.1');
connect(da);
grp = addgroup(da);
itm1 = additem(grp, 'Random.Real8');
r = read(itm1)
r =
ItemID:
Value:
Quality:
TimeStamp:
Error:

'Random.Real8'
4.3252e+003
'Good: Non-specific'
[2004 3 2 9 50 26.6710]
''

Specifying the Source of the Read Operation. By default, a synchronous

read operation will return data from the OPC servers cache. By reading from
the cache, you do not have to wait for a possibly slow device to provide data
to the server. You can specify the source of the synchronous read operation
as the second parameter to the read function. If the source is specified as
'device', the server will read a value from the device, and return that value
to you (as well as updating the server cache with that value).
Note Reading from the device may be slow. If the read operation generates a
time-out error, you may need to increase the value of the Timeout property of
the opcda client object associated with the group or item in order to support
synchronous reads from the device.

4-3

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

The following example reads data from the device associated with itm1.
r = read(itm1, 'device')
r =
ItemID:
Value:
Quality:
TimeStamp:
Error:

'Random.Real8'
9.1297e+003
'Good: Non-specific'
[2004 3 2 10 8 20.2650]
''

Reading from the Cache with Inactive Items. In order to reduce

communication traffic and speed up data access, OPC servers do not store all
server item values in their cache. Only those server items that are active will
be stored in the server cache. Therefore, synchronous read operations from
the cache on an inactive item will return data that may not correspond to the
current device value. If you attempt to read data from an inactive item using
the read function, and do not specify 'device' as the source, the Quality will
be set to 'Bad: Out of Service'.
You control the active status of an item using the Active property.
The following example sets the Active property of the item to 'off' and
attempts to read from the cache.
itm1.Active = 'off';
r = read(itm1)
Warning: One or more items is inactive.
(Type "warning off opc:read:iteminactive" to suppress this
warning.)
r =
ItemID:
Value:
Quality:
TimeStamp:
Error:

4-4

Downloaded from www.Manualslib.com manuals search engine

'Random.Real8'
8.4278e+003
'Bad: Out of Service'
[2004 3 2 10 17 19.9370]
''

Reading and Writing Data

Using Asynchronous Read Operations

An asynchronous read operation creates a request to read data, and then
sends that request to the server. Once the request has been accepted,
MATLAB continues processing the next instruction without waiting to receive
any values from the server. When the data is ready to be returned, the server
sends the data back to MATLAB by generating a read async event. MATLAB
will handle that event as soon as it is able to perform that task.
Asynchronous read operations always return data from the device.
By using an asynchronous read operation, you can continue performing tasks
in MATLAB while the value is being read from the device, and then process
the returned value when the server is able to provide it back to MATLAB.
You perform asynchronous read operations using the readasync function,
passing the daitem object that you want to read from. If successful, the
function will return a transaction ID, a unique identifier for that asynchronous
transaction. You can use that transaction ID to identify the read operation
when it is returned through the read async event.
When an asynchronous read operation is processed in MATLAB, the items
Value, Quality and Timestamp properties are also updated to reflect the
values obtained from the asyncrhonous read operation.
The following example of using an asynchronous read operation uses the
default callback for a read async event. The default callback is set to the
opccallback function, which displays information about the event in the
command line.
tid = readasync(itm1)
tid =
3

The transaction ID for this operation is 3. A little while later, the default
callback function displays the following information at the command line.
OPC ReadAsync event occurred at local time 10:44:49
Transaction ID: 3

4-5

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Group Name: Group0

1 items read.

You can change the read async event callback function by setting the
ReadAsyncFcn property of the dagroup object. For more information on
callbacks and events, see Chapter 6, Using Events and Callbacks.

Writing Data to an Item

You can write data to individual items, or to groups of items. This section
describes how to write data to individual items. See Reading and Writing
Multiple Values on page 4-8 for information on using dagroup objects to
write data to multiple items.
You can write data to an OPC server using a synchronous write operation,
in which case MATLAB will wait for the server to acknowledge that the
write operation succeeds, or using an asynchronous write operation, in which
case MATLAB is free to continue performing other tasks while the write
operation takes place. Because write operations always apply directly to the
device, a synchronous write operation may take a significant amount of time,
particularly if the device that you are writing to has a slow connection to
the OPC server.

Using Synchronous Write Operations

You use the write function to perform synchronous write operations. The
first argument is the daitem object that represents the server item you want
to write to. The second argument is the value that you want to write to that
server item. The write function does not return any results, but will generate
an error if the write operation is not successful.
The following example creates an item with item ID 'Bucket Brigade.Real8'
and writes the value 10.34 to the item. The value is then read using a
synchronous read operation.
itm2 = additem(grp, 'Bucket Brigade.Real8');
write(itm2, 10.34)
r = read(itm2, 'device')

You do not need to ensure that the data type of the value you are writing,
and the data type of the daitem object, are the same. OPC Toolbox software

4-6

Downloaded from www.Manualslib.com manuals search engine

Reading and Writing Data

relies on the server to perform the conversion from the data type you provide,
to the data type required for that server item. For information on how the
toolbox handles different data types, see Working with Different Data Types
on page 5-18.

Using Asynchronous Write Operations

An asynchronous write operation creates a request to write data, and then
sends that request to the server. Once the request has been accepted,
MATLAB continues processing the next instruction without waiting for the
data to be written. When the write operation completes on the server, the
server notifies MATLAB that the operation completed by generating a write
async event containing information on whether the write operation succeeded,
and an error message if applicable. MATLAB will handle that event as soon
as it is able to perform that task.
You use the writeasync function to write values to the server asynchronously.
The first argument is the daitem object that represents the server item you
want to write to. The second argument is the value you want to write to that
server item. The return value is the transaction ID of the operation. You can
use the transaction ID to identify the write operation when it is returned
through the write async event.
The following example uses asynchronous operations to write the value 57.8
to the item 'Bucket Brigade.Real8' created earlier.
tid = writeasync(itm2, 57.8)
tid =
4

A while later, the standard callback (opccallback) will display the results of
the write operation to the command line.
OPC WriteAsync event occurred at local time 11:15:27
Transaction ID: 4
Group Name: Group0
1 items written.

4-7

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

You can change the write async event callback function by setting the
WriteAsyncFcn property of the dagroup object. For more information on
events and callbacks, see Chapter 6, Using Events and Callbacks.

Reading and Writing Multiple Values

When you use the read and write operation on a single daitem object, you
read or write a single value per transaction. OPC Toolbox software allows you
to perform one operation to read multiple item values, or to write multiple
values. You can also use a dagroup object to read and write values using all
items in the group, or you can perform read and write operations on item
object vectors.
A daitem object vector is a single variable in the MATLAB workspace
containing more than one daitem object. You can construct item vectors
using any of the standard concatenation techniques available in MATLAB.
See Creating OPC Toolbox Object Vectors on page 3-9 for information on
creating and working with toolbox object vectors.
When you perform any read or write operation on a dagroup object, it is the
equivalent of performing the operation on the Item property of that group,
which is a daitem object vector representing all items that are contained
within the dagroup object.
The following sections describe how to perform read and write operations
on multiple items:
Reading Multiple Values on page 4-8 describes how to read multiple
values from an item vector or dagroup object.
Writing Multiple Values on page 4-10 describes how to write multiple
values to an item vector or dagroup object.
Error Handling for Multiple Item Read and Write Operations on page
4-10 explains how OPC Toolbox software deals with errors when performing
read and write operations on multiple objects.

Reading Multiple Values

The following sections describe how synchronous read operations and
asynchronous read operations behave for multiple items.

4-8

Downloaded from www.Manualslib.com manuals search engine

Reading and Writing Data

Synchronous Read Operations. When you read multiple values using the
read function, the returned value will be a structure array. Each element of
the structure will contain the same fields. One of the fields is the item ID that
the information in that element of the structure refers to.
The following example performs a synchronous read operation on the dagroup
object created in the previous examples in this section.
r = read(grp)
r =
2x1 struct array with fields:
ItemID
Value
Quality
TimeStamp
Error

To display the first record in the structure array, use indexing into the
structure.
r(1)
ans =
ItemID:
Value:
Quality:
TimeStamp:
Error:

'Random.Real8'
3.7068e+003
'Good: Non-specific'
[2004 3 2 11 49 52.5460]
''

To display all values of a particular field, you can use the list generation
syntax in MATLAB. Enclosing that list in a cell array groups the values into
one variable.
{r.Value}
ans =
{3.7068e+003

10}

4-9

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Asynchronous Read Operations. When you read multiple values using

the readasync function, the return value is still a single transaction ID. The
multiple values will be returned in the read async event structure passed to
the ReadAsyncFcn callback. For information on the structure of the read
async event, see Event Types on page 6-5.

Writing Multiple Values

When you perform a write operation on multiple items you need to specify
multiple values, one for each item you are writing to. OPC Toolbox software
requires these multiple values to be in a cell array, since the data types for
each value may be different. For information on constructing cell arrays,
see MATLAB Programming.
Note Even if you are using the same data type for every value being written
to the dagroup object or daitem object vector, you must still use a cell array to
specify the individual values. Use the num2cell function to convert numeric
arrays to cell arrays.
The following example writes values to a dagroup object containing two items.
write(grp, {1.234, 5.43})

Error Handling for Multiple Item Read and Write Operations

When reading and writing with multiple items, an error generated by
performing the operation on one item will not automatically generate an
error in MATLAB. The following rules apply to reading and writing with
multiple items:
If all items fail the operation, an error will be generated. The error message
will contain specific information for each item about why the item failed.
If some items fail but some succeed, the operation does not error, but
generates a warning, listing which items failed and the reason for failure.
Note that for asynchronous read and write operations, items may fail
early (during the request for the operation) or late (when the information

4-10

Downloaded from www.Manualslib.com manuals search engine

Reading and Writing Data

is returned from the server). If any items fail late, an error event will be
generated in addition to the read async event or write async event.

4-11

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Data Change Events and Subscription

In this section...
Introduction on page 4-12
Configuring OPC Toolbox Objects for Data Change Events on page 4-12
How OPC Toolbox Software Processes Data Change Events on page 4-15
How to Customize the Data Change Event Response on page 4-15

Introduction
Using the read and readasync functions described in Reading Data from
an Item on page 4-2, you can obtain information about OPC server item
values upon request. The OPC Data Access specification provides another
mechanism for clients to get information on server item values. This
mechanism allows the OPC server to notify a client when a server items
value or quality has updated. This mechanism is called a data change event.
OPC Toolbox software supports data change event notification by executing a
MATLAB function when a data change event is received from a connected OPC
server. This section describes how to use the data change event notification.

Configuring OPC Toolbox Objects for Data Change

Events
A data change event occurs at the dagroup object level. Using dagroup
object properties, you can control whether a data change event is generated
for a particular group, the minimum time between successive events, and
the MATLAB function to run when the event notification is received and
processed by OPC Toolbox software. You can also control which items in a
particular group should be monitored for data changes. In this way, you can
control the number and frequency of data change events that MATLAB has to
process. On a busy OPC server, you can also turn off data change notification
for groups that you are not currently interested in.
The following sections describe how to control data change notification.
Controlling Data Change Notification for a Group on page 4-13 describes
how to turn off data change notification for a dagroup object.

4-12

Downloaded from www.Manualslib.com manuals search engine

Data Change Events and Subscription

Temporarily Disabling Items in a Group on page 4-14 describes how to

control which items in a group must be monitored for data changes.
How to Customize the Data Change Event Response on page 4-15
provided information on how to configure the MATLAB function to run
when a data change event occurs.

Controlling Data Change Notification for a Group

The following properties of a dagroup object control whether a server notifies
the group of data changes on items in that group:
UpdateRate: The UpdateRate property defines the rate at which an OPC
server must monitor server item values and generate data change events.
Even if a server items value changes more frequently than the update rate,
the OPC server will only generate a data change at the interval specified by
the update rate.
Subscription: The Subscription property defines whether the OPC
server will generate a data change event for the group. When you create
a dagroup object, the Subscription property is set to 'on'. When you
set the Subscription property to 'off', you tell the OPC server not to
generate data change events for that group.
Active: The Active property must be 'on' for data change events to be
generated. When you create a dagroup object, the Active property is set
to 'on'. When you set the Active property to 'off', you remove any
ability to read data from the group, whether through read operations or
data change events.

4-13

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

A summary of group read, write, and data change behavior for the Active
and Subscription properties is given in the following table.
Active

Subscription

Read

Write

Data Change

'on'

'on'

Yes

Yes

Yes

'on'

'off'

Yes

Yes

No

'off'

'on'

No

No

No

'off'

'off'

No

No

No

Temporarily Disabling Items in a Group

You can temporarily disable items in a group without deleting the item from
the group. When you disable a daitem object, the OPC server no longer
monitors changes in the associated server items value, and will therefore not
generate data change events when the value of that server item changes.
You can disable a daitem object by setting that objects Active property to
'off'. You can reenable the daitem object by setting the Active property
to 'on'.

Forcing a Data Change Event

You can force an OPC server to generate a data change event for all active
items in a group by using the refresh function with the dagroup object as the
first argument. The OPC server will generate a data change event containing
information for every active item in the group.
You can pass an optional second argument to the refresh function to instruct
the OPC server where to source the data values that are sent back in the
data change event. By specifying a source of 'device', you instruct the
OPC server to update the values from the device. By specifying a source
of 'cache' (the default) you instruct the OPC server to return values from
the OPC servers cache.

4-14

Downloaded from www.Manualslib.com manuals search engine

Data Change Events and Subscription

How OPC Toolbox Software Processes Data Change

Events
OPC Toolbox software uses data change events for a number of tasks. The
following activities take place when a data change event occurs:
1 The Value, Quality, and TimeStamp properties of the daitem object are

automatically updated. For more information on these properties, see

Understanding OPC Data: Value, Quality, and TimeStamp on page 5-2.
2 If the dagroup object is logging, the data change event is logged to memory

and/or disk as a record. For information on logging, see Logging OPC

Server Data on page 4-17.
3 If the dagroup objects DataChangeFcn property is not empty, that function

is called with the data change event information. By default, this property
is empty, since data change events occur frequently. You can customize
the behavior of the toolbox by setting this property to call a function that
you choose. For information on the data change event, see the reference
page for the DataChangeFcn property.
Note If you disable data change events by setting the Subscription
property to 'off' or the Active property to 'off', none of the activities
listed above can take place. You cannot change the Active or Subscription
properties while a dagroup object is logging, otherwise the logging task
may never complete.

How to Customize the Data Change Event Response

One of the activities that occurs when OPC Toolbox software receives a data
change event from the OPC server is the running of the function defined in the
DataChangeFcn property. By setting this property to a the name of a function
that you have written, you can fully customize the data change event behavior
of the toolbox. For example, you may configure a dagroup object to monitor a
server item that is updated from an operator interface. By pushing a button
on the operator interface, the server item value will change, initiating a data
change event on that group. By configuring the DataChangeFcn property to
run a MATLAB function that performs control loop optimization, you can

4-15

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

allow an operator to initiate a control loop performance test on all critical

control loops in the plant.

4-16

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

Logging OPC Server Data

In this section...
How OPC Toolbox Software Logs Data on page 4-17
Configuring a Logging Session on page 4-20
Executing a Logging Task on page 4-24
Getting Logged Data into the MATLAB Workspace on page 4-26

How OPC Toolbox Software Logs Data

The OPC Data Access Specification, which OPC Toolbox software implements,
provides access to current values of data on an OPC server. Often, for analysis,
troubleshooting, and prototyping purposes, you will want to know how OPC
server data has changed over a period of time. For example, you can use time
series data to perform control loop optimization or system identification on a
portion of your plant. OPC Toolbox software provides a logging mechanism
that stores a history of data that changed over a period of time. This section
discusses how to configure and execute a logging task using the toolbox.
Note The OPC Toolbox software logging mechanism is not designed to
replace a data historian or database application that logs data for an extended
period. Rather, the logging mechanism allows you to quickly configure a task
to log data on an occasional basis, where modifications to the plant-wide data
historian may be unfeasible.
OPC Toolbox software uses the data change event to log data. Each data
change event that is logged is called a record. The record contains information
about the time the client logged the record, and details about each item in
the data change event. Data change events are discussed in detail in Data
Change Events and Subscription on page 4-12.
The use of a data change event for logging means that you should consider the
following points when planning a logging session:

4-17

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Logging takes place at the group level When planning a logging

task, configure the group with only the items you need to log. Including
more items than you need to will only increase memory and/or disk usage,
and using that data may be more difficult due to unnecessary items in
the data set.
Inactive items in a group will not be logged You must ensure that
the items you need to log are active when you start a logging session.
You control the active state of a daitem object using the Active property
of the daitem object.
Data change events (records) may not include all items A data
change event contains only the items in the group that have changed their
value and/or quality state since the last update. Hence, a record is not
guaranteed to contain every data item. You need to consider this when
planning your logging session.
OPC logging tasks are not guaranteed to complete Because data
change events only happen when an item in the group changes state on
the server, it is possible to start a logging task that will never finish. For
example, if the items in a group never change, a data change event will
never be generated for that group. Hence, no records will be logged.
Logged data is not guaranteed to be regularly sampled It is
possible to force a data change event at any time (see Forcing a Data
Change Event on page 4-14). If you do this during a logging task, the
data change events may occur at irregular sample times. Also, a data
change event may not contain information for every item in the group.
Consequently, logged OPC server data may not occur at regular sample
times.
An overview of the logging task, and a representation of how the above points
impact the logging session, is provided in the following section.

Example: An Overview of a Logging Task

To illustrate a typical logging task, the following example logs to disk and
memory six records of data from two items provided by the Matrikon OPC
Simulation Server. During the logging task, data is retrieved from memory.
When the task stops, the remaining records are retrieved.

4-18

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

Step 1: Create the OPC Toolbox object hierarchy. This example creates
a hierarchy of OPC Toolbox objects for two items provided by the Matrikon
Simulation Server. To run this example on your system, you must have the
Matrikon Simulation Server installed. Alternatively, you can replace the
values used in the creation of the objects with values for a server you can
access.
da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
grp = addgroup(da,'CallbackTest');
itm1 = additem(grp,'Triangle Waves.Real8');
itm2 = additem(grp,'Saw-Toothed Waves.Boolean');

Step 2: Configure the logging duration. This example sets the

UpdateRate value to 1 second, and the RecordsToAcquire property to 6.
See Controlling the Duration of a Logging Session on page 4-21 for more
information on this step.
set(grp,'UpdateRate',1);
set(grp,'RecordsToAcquire',6);

Step 3: Configure the logging destination. In this example, data is

logged to disk and memory. The disk filename is set to LoggingExample.olf.
The LogToDiskMode property is set to 'overwrite', so that if the filename
exists, the toolbox engine must overwrite the file. See Controlling the Logged
Data Destination on page 4-22 for more information on this step.
set(grp,'LoggingMode', 'disk&memory');
set(grp,'LogFileName', 'LoggingExample.olf');
set(grp,'LogToDiskMode','overwrite');

Step 4: Start the logging task. Start the dagroup object. The logging task
is started, and the group summary updates to reflect the logging status. See
Starting a Logging Task on page 4-24 for more information on this step.
start(grp)
grp

4-19

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Step 5: Monitor the Logging Progress. After about 3 seconds, retrieve

and show the last acquired value. After another second, obtain the first two
records during the logging task. Then wait for the logging task to complete.
See Monitoring the Progress of a Logging Task on page 4-24 for more
information on this step.
pause(3.5)
sPeek = peekdata(grp, 1);
% Display the local event time, item IDs and values
disp(sPeek.LocalEventTime);
disp({sPeek.Items.ItemID;sPeek.Items.Value});
pause(1)
sGet = getdata(grp, 2);
wait(grp)

Step 6: Retrieve the data. This example retrieves the balance of the
records into a structure array. See Retrieving Data from Memory on page
4-27 for more information on this step.
sFinished = getdata(grp, grp.RecordsAvailable);

Step 7: Clean up. When you no longer need them, always remove from
memory any toolbox objects and the variables that reference them. Deleting
the opcda client object also deletes the group and daitem objects.
disconnect(da)
delete(da)
clear da grp itm1 itm2

Configuring a Logging Session

A logging session is associated with a dagroup object. Before you start a
logging session, you will need to ensure that the logging session is correctly
configured. This section explains how you can control
The duration of a logging session (see Controlling the Duration of a
Logging Session on page 4-21). By default, a group will log approximately
one minute of data at half second intervals.
The destination of logged data (see Controlling the Logged Data
Destination on page 4-22). By default, a group will log data to memory.

4-20

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

The response to events that take place during a logging session (see
Configuring Logging Callbacks on page 4-23). By default, a logging
session takes no action in response to events that take place during a
logging session.

Controlling the Duration of a Logging Session

While you cannot guarantee that a logging session will take a specific amount
of time (see How OPC Toolbox Software Logs Data on page 4-17), you can
control the rate at which the server will update the items and how many
records the logging task should store before automatically stopping the
logging task. You control these aspects of a logging task by using the following
properties of the dagroup object:
UpdateRate: The UpdateRate property defines how often the item values
are inspected.
RecordsToAcquire: The RecordsToAcquire property defines how many
records OPC Toolbox software must log before automatically stopping a
logging session. A logging task can also be stopped manually, using the
stop function.
DeadbandPercent: The DeadbandPercent property does not control the
duration of a logging task directly, but has a significant influence over how
often a data change event is generated for analog items (an item whose
value is not confined to discrete values). By setting the DeadbandPercent
property to 0, you can ensure that a data change event occurs each time
a value changes. For more information on DeadbandPercent, consult the
property reference page.
You can use the UpdateRate and RecordsToAcquire properties to define the
minimum duration of a logging task. The duration of a logging task is at least
UpdateRate * RecordsToAcquire

For example, if the UpdateRate property is 10 (seconds) and the

RecordsToAcquire property is 360, then provided that a data change event
is generated each time the server queries the item values, the logging task
will take 3600 seconds, or one hour, to complete.

4-21

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Controlling the Logged Data Destination

OPC Toolbox software allows you to log data to memory, to a disk file, or both
memory and a disk file. When logging data to memory, you can log only as
much data as will fit into available memory. Also, if you delete the dagroup
object that logged the data without extracting that data to the MATLAB
workspace, the data will be lost. The advantage of logging data to memory is
that logging to memory is faster than using a disk file.
Logging data to a disk file usually means that you can log more data, and the
data is not lost if you quit MATLAB or delete the dagroup object that logged
the data. However, reading data from a disk file is slower than reading data
from memory.
The LoggingMode property of a dagroup object controls where logged data
is stored. You can specify 'memory' (the default value), or 'disk', or
'disk&memory' as the value for LoggingMode.
The following properties control how OPC Toolbox software logs data to disk.
You must set the LoggingMode property to 'disk' or 'disk&memory' for
these properties to take effect:
LogFileName: The LogFileName property is a string that specifies the
name of the disk file that is used to store logged data. If the file does
not exist, data will be logged to that filename. If the file does exist, the
LogToDiskMode property defines how the toolbox behaves.
LogToDiskMode: The LogToDiskMode property controls how OPC Toolbox
software handles disk logging when the file specified by LogFileName
already exists. Each time a logging task is started, if the LoggingMode is
set to 'disk' or 'disk&memory', the toolbox checks to see if a file with
the name specified by the LogFileName property exists. If the file exists,
the toolbox will take the following action, based on the LogToDiskMode
property:

'append': When LogToDiskMode is set to 'append', logged data will be

added to the existing data in the file.

'overwrite': When LogToDiskMode is set to 'overwrite', all existing

data in the file will be removed without warning, and new data will
be logged to the file.

4-22

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

'index': When LogToDiskMode is set to 'index', OPC Toolbox software

automatically changes the log filename, according to the following
algorithm:

The first log filename attempted is specified by the initial value of

LogFileName.
If the attempted filename exists, LogFileName is modified by adding a
numeric identifier. For example, if LogFileName is initially specified as
'groupRlog.olf', then groupRlog.olf is the first attempted filename,
groupRlog01.olf is the second filename, and so on. If LogFileName
already contains numeric characters, they are used to determine the
next sequence in the modifier. For example, if the LogFileName is
initially specified as 'groupRlog010.olf', and groupRlog010.olf
exists, the next attempted file is groupRlog011.olf, and so on.
The actual filename used is the first filename that does not exist. In
this way, each consecutive logging operation is written to a different
file, and no previous data is lost.

Configuring Logging Callbacks

You can configure the dagroup object so that MATLAB will automatically
execute a function when the logging task starts, when the logging task stops,
and each time a specified number of records is acquired during a logging
task. The dagroup object has three callback properties that are used during
a logging session. Each callback property defines the action to take when a
particular logging event occurs:
Start event: A start event is generated when a logging task starts.
Records acquired event: A records acquired event is generated each
time a logging task acquires a set number of records.
Stop event: A stop event is generated when a logging task stops, either
automatically, or by the user calling the stop function.
For more information on configuring callbacks, see Chapter 6, Using Events
and Callbacks For an example of using callbacks in a logging task, see
Example: Viewing Recently Logged Data on page 6-20.

4-23

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

Executing a Logging Task

Once you have configured your logging task you can execute the task.
Executing a logging task involves starting the logging task, monitoring the
task progress, and stopping the logging task.

Starting a Logging Task

You start a logging task by calling the start function, passing the dagroup
object that you want to start logging. The following example starts a logging
task for the dagroup object grp.
start(grp);

When you start a logging task, certain group and item properties become
read-only, as modifying these properties during a logging task would
corrupt the logging process. Also, the dagroup object performs the following
operations:
1 Generates a start event and executes the StartFcn callback.
2 If Subscription is 'off', sets Subscription to 'on' and issues a warning.
3 Removes all records associated with the object from the OPC Toolbox

software engine.
4 Sets RecordsAcquired and RecordsAvailable to 0.
5 Sets the Logging property to 'on'.

For more information on callbacks and events, see Chapter 6, Using Events
and Callbacks

Monitoring the Progress of a Logging Task

During a logging task, you can monitor the progress of the task by examining
the following properties of the dagroup object:
Logging: The Logging property is set to 'on' at the start of a logging task,
and set to 'off' when the logging task stops.
RecordsAcquired: The RecordsAcquired property contains the number
of records that have been logged to the destination specified by the

4-24

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

LoggingMode property. When a start function is called, RecordsAcquired

is set to 0. When RecordsAcquired reaches RecordsToAcquire, the logging

task stops automatically.

RecordsAvailable: The RecordsAvailable property contains the number
of records that have been stored in the OPC Toolbox software engine for
this logging task. Data is only logged to memory if the LoggingMode is set
to 'memory' or 'disk&memory'. You extract data from the toolbox engine
using the getdata function. See Getting Logged Data into the MATLAB
Workspace on page 4-26 for more information on using getdata.
You can monitor these properties in the summary display of a dagroup object,
by typing the name of the dagroup object at the command line.
grp
grp =
Summary of OPC Data Access Group Object: group1
Object Parameters
Group Type
: private
Item
: 1-by-1 daitem object
Parent
: localhost/Matrikon.OPC.Simulation.1
Update Rate : 0.5
Deadband
: 0%
Object Status
Active
: on
Subscription : on
Logging
: on
Logging Parameters
Records
: 120
Duration
: at least 60 seconds
Logging to
: disk
Log File
: group1log.olf ('index' mode)
Status
: 5 records acquired since starting.
0 records available for GETDATA/PEEKDATA

Stopping a Logging Task

A logging task stops when one of the following conditions is met:

4-25

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

The number of records logged reaches the value defined by the

RecordsToAcquire property.
You manually stop the logging task by using the stop function.
The following example manually stops the logging task for dagroup object grp.
stop(grp);

When a logging task stops, the Logging property is set to 'off', a stop event
is generated, and the StopFcn callback is executed. For more information on
callbacks and events, see Chapter 6, Using Events and Callbacks.

Getting Logged Data into the MATLAB Workspace

OPC Toolbox software does not log data directly to the MATLAB workspace.
When logging to memory, the data is buffered in the toolbox engine in a
storage-efficient way. When logging to disk, the data is logged in ASCII
format. To analyze your data, you need to extract the data from the toolbox
engine or from a disk file into MATLAB for processing. This section describes
how to get your logged data into the MATLAB workspace. The following
sections describe this process:
Retrieving Data from Memory on page 4-27, discusses how to retrieve
data from the toolbox engine into MATLAB.
Retrieving Data from Disk on page 4-28, discusses how to retrieve data
from a disk file into MATLAB.
Whether you log data to memory or to disk, you can retrieve that logged data
in one of two formats:
Structure format: This format stores each data change event in a structure.
Data from a logging task is simply an array of such structures.
Array format: To visualize and analyze your data, you will need to work
with the time series of each of the items in the group. The array format is
the logged structure data, unpacked into separate arrays for the Value,
Quality, and TimeStamp.
These formats are discussed in more detail in Chapter 5, Working with
OPC Data.

4-26

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

Retrieving Data from Memory

You retrieve data from memory using the getdata function, passing the
dagroup object as the first argument, and the number of records you want
to retrieve as the second argument. The data is returned as a structure
containing data from each data change event in the logging task. For example,
to retrieve 20 records for the dagroup object grp:
s = getdata(grp, 20);

If you do not supply a second argument, getdata will try to retrieve the
number of records specified by the RecordsToAcquire property of the dagroup
object. If the OPC Toolbox software engine contains fewer records for the
group than the number requested, a warning is generated and all of the
available records will be retrieved.
To retrieve data in array format, you must indicate the data type of the
returned values. You pass a string defining that data type as an additional
argument to the getdata function. Valid data types are any MATLAB
numeric data type (for example, 'double' or 'uint32') plus 'cell' to denote
the MATLAB cell array data type.
When you specify a numeric data type or cell array as the data type for
getdata, the logged data is returned in separate arrays for the item IDs

logged, the value, quality, time stamp, and the local event time of each data
change event logged. You must therefore specify up to five output arguments
for the getdata function when retrieving data in array format.
For example, to retrieve 20 records of logged data in double array format
from dagroup object grp.
[itmID, val, qual, tStamp, evtTime] = getdata(grp, 20, 'double');

Once you have retrieved data to the MATLAB workspace using getdata,
the records are removed from the toolbox engine to free up memory for
additional logged records. If you specify a smaller number of records than
those available in memory, getdata will retrieve the oldest records. You can
use the RecordsAvailable property of the dagroup object to determine how
many records the toolbox engine has stored for that group.

4-27

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

During a logging task, you can examine the most recently acquired records
using the peekdata function, passing the dagroup object as the first
argument, and the number of records to retrieve as the second argument.
Data is returned in a structure. You cannot return data into separate arrays
using peekdata. You can convert the structure returned by peekdata into
separate arrays using the opcstruct2array function. Data retrieved using
peekdata is not removed from the toolbox engine.
For an example of using getdata and peekdata during a logging task, see
Example: An Overview of a Logging Task on page 4-18.
When you delete a dagroup object, the data stored in the toolbox engine for
that object is also deleted.

Retrieving Data from Disk

You can retrieve data from a disk file into the MATLAB workspace using the
opcread function. You pass the name of the file containing the logged OPC
data as the first argument. The data stored in the log file is returned as a
structure array, in the same format as the structure returned by getdata.
Records retrieved from a log file into the MATLAB workspace are not removed
from the log file.
You can specify a number of additional arguments to the opcread function,
that control the records that are retrieved from the file. The additional
arguments must be specified by an option name and the option value. The
following options are available.
Option Name

Option Value Description

'items'

Specify a cell array of item IDs that you want returned.

Items not in this list will not be read.

'dates'

Specify a date range for the event times. The range

must be [startDt endDt] where startDt and endDt
are MATLAB date numbers.

4-28

Downloaded from www.Manualslib.com manuals search engine

Logging OPC Server Data

Option Name

Option Value Description

'records'

Specify the index of records to retrieve as [startRec

endRec]. Records outside these indices will not be read.

'datatype'

Specify the data type, as a string, that should be used

for the returned values. Valid data type strings are
the same as for getdata. If you specify a numeric data
type or 'cell', the output will be returned in separate
arrays. If you specify a numeric array data type such
as 'double' or 'uint32', and the logged data contains
arrays or strings, an error will be generated and no data
will be returned.

The following example retrieves the data logged during the example on page
Example: An Overview of a Logging Task on page 4-18, first into a structure
array, and then records 3 to 6 are retrieved into separate arrays for Value,
Quality, and TimeStamp.
sDisk = opcread('LoggingExample.olf')
sDisk =
40x1 struct array with fields:
LocalEventTime
Items
[i,v,q,t,e] = opcread('LoggingExample.olf', ...
'records',[3,6], 'datatype','double')
i =
'Random.Real8'
'Random.UInt2'
'Random.Real4'
v =
1.0e+004 *
0.7819
3.0712
1.4771
1.5599
2.7792
2.2051
1.4682
0.4055
0.5315
0.0235
2.4473
1.5456
q =
'Good: Non-specific' 'Good: Non-specific' 'Good: Non-specific'
'Good: Non-specific' 'Good: Non-specific' 'Good: Non-specific'
'Good: Non-specific' 'Good: Non-specific' 'Good: Non-specific'
'Good: Non-specific' 'Good: Non-specific' 'Good: Non-specific'

4-29

Downloaded from www.Manualslib.com manuals search engine

Reading, Writing, and Logging OPC Data

t =
1.0e+005 *
7.3202
7.3202
7.3202
7.3202
e =
1.0e+005 *
7.3202
7.3202
7.3202
7.3202

7.3202
7.3202
7.3202
7.3202

7.3202
7.3202
7.3202
7.3202

Note For a record to be returned by opcread, it must satisfy all the options
passed to opcread.

4-30

Downloaded from www.Manualslib.com manuals search engine

5
Working with OPC Data
When an OPC server returns data from a read or logging operation, three
pieces of information make up the data. The Value, Quality, and Timestamp
all contribute information about the data point that is returned. As a result,
you need to understand how to deal with this information together, because
one aspect of the data in isolation will not provide a complete picture of the
data returned by a read operation, data change event, read async event, or
toolbox logging task.
This chapter describes how OPC Toolbox software handles data returned by
an OPC server.
Understanding OPC Data: Value, Quality, and TimeStamp on page 5-2
Working with Structure Formatted Data on page 5-8
Understanding Array Formatted Data on page 5-15
Working with Different Data Types on page 5-18

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Understanding OPC Data: Value, Quality, and TimeStamp

In this section...
Introduction on page 5-2
The Relationship Between Value, Quality, and TimeStamp on page 5-2
How Value, Quality, and TimeStamp Are Obtained on page 5-3

Introduction
OPC servers provide access to many server items. To reduce network traffic
between the server and the device associated with each server item (a field
instrument, or a memory location in a PLC, SCADA, or DCS system) the
OPC server stores information about each server item in the servers cache,
updating that information only as frequently as required to satisfy the
requests of all clients connected to that server. Because this process results in
data in the cache that may not reflect the actual value of the device, the OPC
server provides the client with additional information about that value.
This section describes the OPC Value, Quality, and TimeStamp properties,
and how they should be used together to assess the information provided by
an OPC server.

The Relationship Between Value, Quality, and

TimeStamp
Every server item on an OPC server has three properties that describe the
status of the device or memory location associated with that server item:
Value The Value of the server item is the last value that the OPC server
stored for that particular item. The value in the cache is updated whenever
the server reads from the device. The server reads values from the device
at the update rate specified by the dagroup objects UpdateRate property,
and only when the item and group are both active. You control the active
status of an item or group using that objects Active property.
In addition, for analog type data (data with the additional OPC Foundation
Recommended Properties 'High EU' and 'Low EU') the percentage
change between the cached value and the device value must exceed the

5-2

Downloaded from www.Manualslib.com manuals search engine

Understanding OPC Data: Value, Quality, and TimeStamp

DeadbandPercent property specified for that item in order for the cached
value to be updated.

Quality The Quality of the server item is a string that represents

information about how well the cache value matches the device value. The
Quality is made up of two parts: a major quality, which can be 'Good',
'Bad', or 'Uncertain', and a minor quality, which describes the reason
for the major quality. For more information on the Quality string, see
Appendix A, OPC Quality Strings.
The Quality of the server item can change without the Value changing.
For instance, if the OPC server attempts to obtain a Value from the device
but that operation fails, the Quality will be set to 'Bad'. Also, when you
change the clients Active property, the Quality will change.
You must always examine the Quality of an item before using the Value
property of that item.
TimeStamp The TimeStamp of a server item represents the most recent
time that the server assessed that the device set the Value and Quality
properties of that server item. The TimeStamp can change without the
Value changing. For example, if the OPC server obtains a value from the
device that is the same as the current Value, the TimeStamp property will
still be updated, even if the Value property is not.
OPC Toolbox software provides access to the Value, Quality, and TimeStamp
properties of a server item through properties of the daitem object associated
with that server item.

How Value, Quality, and TimeStamp Are Obtained

OPC Toolbox software provides all three OPC Data Access Standard
mechanisms for reading data from an OPC server. The toolbox uses these
three mechanisms in various ways to return data from those functions, to
provide event information, to update properties of toolbox objects, and to
log data to memory and disk.
The way OPC Toolbox software uses the three OPC Data Access mechanisms
is described in the following sections:
OPC Data Returned from Synchronous Read Operations on page 5-4
describes the synchronous read mechanism used by the read function.

5-3

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

OPC Data Returned in Asynchronous Read Operations on page 5-4

describes the asynchronous read mechanism used by the readasync
function.
OPC Data Returned from a Data Change Event on page 5-5 describes the
data change event notification mechanism used with subscribed, active
groups, with the refresh function, and by the toolbox logging process.

OPC Data Returned from Synchronous Read Operations

You initiate a synchronous read operation by using the read function. When
you read from a dagroup object, all items in that group are read in one
instruction.
You can specify the source of a synchronous read operation as 'cache' or
'device'. If you read from the cache, the server simply returns the value in
the cache. If you read from the device, the server will get the value from
the device and update the cache before sending the Value, Quality, and
TimeStamp information back as part of the read operation.
OPC Toolbox software returns the data in the output structure from the read
operation. Each element of the structure array contains information about
one of the items read.
Whenever you read values using the read function, the toolbox updates the
daitem objects Value, Quality, and TimeStamp properties with the values
read from the server.

OPC Data Returned in Asynchronous Read Operations

You initiate an asynchronous read operation by using the readasync function.
When you read from a dagroup object, all items in that group are read in
one instruction.
Asynchronous read operations always use the device as the source of the
read. Whenever you send an asynchronous read request, the server will read
values from the devices connected to the items. The server will then update
that server items Value, Quality, and TimeStamp in the cache before sending
an asynchronous read event back to the toolbox.

5-4

Downloaded from www.Manualslib.com manuals search engine

Understanding OPC Data: Value, Quality, and TimeStamp

OPC Toolbox software returns information from an asynchronous read

operation via the read async event structure. This event structure is stored in
the opcda client objects event log, which you can access using the EventLog
property of the client. The event structure is also passed to the callback
function defined in the ReadAsyncFcn property of the dagroup object that
initiated the asynchronous read operation. For more information on the
format of the event structures, see Event Structures on page 6-10.
When an asynchronous read operation succeeds, in addition to returning data
via the event structures, the toolbox also updates the Value, Quality, and
TimeStamp properties of the associated daitem object.

OPC Data Returned from a Data Change Event

The third mechanism for getting data from an OPC server involves the data
change event. The OPC server generates a data change event for a group at
the period specified by the UpdateRate property when the Value or Quality
of an item in the group changes. You do not have to specifically request a
data change event, because the OPC server will automatically generate a
data change event. However, you can force a data change event at any time
using the refresh function.
An OPC server will generate a data change event only for an active,
subscribed group containing active items. You control the active status of
dagroup objects and daitem objects by setting their Active property. You
control the subscribed status of a dagroup object by setting the Subscription
property of the dagroup object.
The following points describe how an OPC server generates a data change
event:
When you configure a group, you define the rate at which the server
must scan items in that group. This rate is controlled by the UpdateRate
property for a dagroup object. The server updates the Value, Quality, and
TimeStamp values in the cache for the items in that group at the required
update rate. Note that if a device cannot provide a value in that time, the
server may reduce the rate at which it updates the value in the server
cache for that item.

5-5

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

If you set an items Active property to 'off', the server will stop scanning
that item. You must set the Active property to 'on' for the server to scan
the item again.
If you set the Active property of a dagroup object to 'off', the server will
stop scanning all items in that group. You can still perform asynchronous
read operations, and synchronous read operations from the 'device', but
no operations involving the server cache can be performed. You must set
the Active property to 'on' to enable operations involving the server cache.
If the Subscription property for a dagroup object is set to 'on', then every
time the server updates cache values for the items in that group, the server
will send a data change event for that group, to the client object. The data
change event contains information about every item whose Value, Quality,
or TimeStamp updated.
If you set the Subscription property to 'off', then the OPC server will
not generate data change events. However, as long as the group is still
active, the OPC server will continue to scan all active items for that group,
at the rate specified by the UpdateRate property.
When the OPC server generates a data change event, OPC Toolbox software
performs the following tasks:
1 The daitem object Value, Quality, and TimeStamp properties are updated

for each item that is included in the data change event.

2 The callback function defined by the DataChangeFcn property of the

dagroup object is called. For more information on callbacks, see Creating

and Executing Callback Functions on page 6-16.

3 If the group is logging data, the data change event is stored in memory

and/or on disk. For more information on logging, see Logging OPC Server
Data on page 4-17.
4 If the group is logging, and the number of records acquired is a multiple

of the RecordsAcquiredFcnCount property of the dagroup object, then

the callback function defined by the RecordsAcquiredFcn property of the
dagroup object is called. For more information on callbacks, see Creating
and Executing Callback Functions on page 6-16.

5-6

Downloaded from www.Manualslib.com manuals search engine

Understanding OPC Data: Value, Quality, and TimeStamp

For more information on the structure of a data change event, see Data
Fields for Cancel Async, Data Change, Error, Read Async, and Write Async
Events on page 6-11.

5-7

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Working with Structure Formatted Data

In this section...
When Structures Are Used on page 5-8
Example: Performing a Read Operation on Multiple Items on page 5-8
Interpreting Structure Formatted Data on page 5-10
When to Use Structure Formatted Data on page 5-13
Converting Structure Formatted Data to Array Format on page 5-13

When Structures Are Used

OPC Toolbox software uses structures to return data from an OPC server,
for the following operations:
Synchronous read operations, executed using the read function.
Asynchronous read operations, executed using the readasync function.
Data change events generated by the OPC server for all active, subscribed
groups or through a refresh function call.
Retrieving logged data in structure format from memory using the getdata
or peekdata functions.
In all cases, the structure of the returned data is the same. This section
describes that structure, and how you can use the structure data to
understand OPC operations.

Example: Performing a Read Operation on Multiple

Items
To demonstrate how to use structure formatted data, the following example
reads values from three items on the Matrikon OPC Simulation Server.

Step 1: Create OPC Toolbox Group Objects

This example creates a hierarchy of OPC Toolbox objects for the Matrikon
Simulation Server. To run this example on your system, you must have the

5-8

Downloaded from www.Manualslib.com manuals search engine

Working with Structure Formatted Data

Matrikon Simulation Server installed. Alternatively, you can replace the

values used in the creation of the objects with values for a server you can
access.
da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
grp = addgroup(da,'StructExample');
itm1 = additem(grp,'Random.Real8');
itm2 = additem(grp,'Saw-toothed Waves.UInt2');
itm3 = additem(grp,'Random.Boolean');

Step 2: Read Data

This example reads values first from the device and then from the server
cache. The data is returned in structure format.
r1 = read(grp, 'device');
r2 = read(grp);

Step 3: Interpret the Data

The data is returned in structure format. To interpret the data, you must
extract the relevant information from the structures. In this example, you
compare the Value, Quality, and TimeStamp to confirm that they are the
same for both read operations.
disp({r1.ItemID;r1.Value;r2.Value})
disp({r1.ItemID;r1.Quality;r2.Quality})
disp({r1.ItemID;r1.TimeStamp;r2.TimeStamp})

Step 4: Read More Data

By reading first from the cache and then from the device, you can compare
the returned data to see if any change has occurred. In this case, the data
will not be the same.
r3 = read(grp);
r4 = read(grp, `device');
disp({r3.ItemID;r3.Value;r4.Value})

5-9

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Step 5: Clean Up
Always remove toolbox objects from memory, and the variables that reference
them, when you no longer need them.
disconnect(da)
delete(da)
clear da grp itm1 itm2 itm3

Interpreting Structure Formatted Data

All data returned by the read, opcread, and getdata functions, and included
in the data change and read async event structures passed to callback
functions, has the same underlying format. The format is best explained by
starting with the output from the read function, which provides the basic
building block of structure formatted data.

Structure Formatted Data for a Single Item

When you execute the read function with a single daitem object, the following
structure is returned.
rSingle = read(itm1)
rSingle =
ItemID:
Value:
Quality:
TimeStamp:
Error:

'Random.Real8'
1.0440e+004
'Good: Non-specific'
[2004 3 10 14 46 9.5310]
''

All structure formatted data for an item will contain the ItemID, Value,
Quality, and TimeStamp fields.
Note The Error field in this example is specific to the read function, and is
used to indicate any error message the server generated for that item.

5-10

Downloaded from www.Manualslib.com manuals search engine

Working with Structure Formatted Data

Structure Formatted Data for Multiple Items

If you execute the read function with a group object containing more than one
item, a structure array is returned.
rGroup = read(grp)
rGroup =
3x1 struct array with fields:
ItemID
Value
Quality
TimeStamp
Error

In this case, the structure array contains one element for each item that was
read. The ItemID field in each element identifies the item associated with
that element of the structure array.
Note When you perform asynchronous read operations, and for data change
events, the order of the items in the structure array is determined by the
OPC server. The order may not be the same as the order of the items passed
to the read function.

Structure Formatted Data for Events

Event structures contain information specifically about the event, as well as
the data associated with that event.
The following example displays the contents of a read async event.
cleareventlog(da);
tid = readasync(itm);
% Wait for the read async event to occur
pause(1);
event = get(da, 'EventLog')
event =

5-11

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Type: 'ReadAsync'
Data: [1x1 struct]

The Data field of the event structure contains

event.Data
ans =
LocalEventTime:
TransID:
GroupName:
Items:

[2004 3 11 10 59 57.6710]
4
'StructExample'
[1x1 struct]

The Items field of the Data structure contains

event.Data.Items
ans =
ItemID:
Value:
Quality:
TimeStamp:

'Random.Real8'
9.7471e+003
'Good: Non-specific'
[2004 3 11 10 59 57.6710]

From the example, you can see that the event structure embeds the structure
formatted data in the Items field of the Data structure associated with the
event. Additional fields of the Data structure provide information on the
event, such as the source of the event, the time the event was received by the
toolbox, and the transaction ID of that event.

Structure Formatted Data for a Logging Task

OPC Toolbox software logs data to memory and/or disk using the data change
event. When you return structure formatted data for a logging task using the
opcread or getdata function, the returned structure array contains the data
change event information arranged in a structure array. Each element of the
structure array contains a record, or data change event. The structure array
has the LocalEventTime and Items fields from the data change event. The
Items field is in turn a structure array containing the fields ItemID, Value,
Quality, and TimeStamp.

5-12

Downloaded from www.Manualslib.com manuals search engine

Working with Structure Formatted Data

When to Use Structure Formatted Data

For the read, read async and data change events, you must use structure
formatted data. However, for a logging task, you have the option of retrieving
the data in structure format, or numeric or cell array format.
For a logging task, you should use structure formatted data when you are
interested in
The raw event information returned by the OPC server. The raw
information may help in diagnosing the OPC server configuration or
the client configuration. For example, if you see a data value that does
not change frequently, yet you know that the device should be changing
frequently, you can examine the structure formatted data to determine
when the OPC server notifies clients of a change in Value, Quality and/or
TimeStamp.
Timing information rather than time series data. If you need to track
when an operator changed the state of a switch, structure formatted data
provides you with event-based data rather than time series data.
For other tasks that involve time series data, such as visualization of the
data, analysis, modeling, and optimization operations, you should consider
using the cell or numeric array output format for getdata and opcread. For
more information on array formats, see Understanding Array Formatted
Data on page 5-15.

Converting Structure Formatted Data to Array Format

If you retrieve data from memory or disk in structure format, you can
convert the resulting structure into array format using the opcstruct2array
function. You pass the structure array to the function, and it will return the
ItemID, Value, Quality, TimeStamp, and EventTime information contained in
that structure array.
The opcstruct2array function is particularly useful when you want to
visualize or analyze time series data without removing it from memory.
Because peekdata only returns structure arrays (due to speed considerations),
you can use opcstruct2array to convert the contents of the structure data
into separate arrays for visualization and analysis purposes.

5-13

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Note You should always retrieve data in numeric or cell array format
whenever you only want to manipulate the time series data. Although the
opcstruct2array function has been designed to use as little memory as
possible, conversion in MATLAB software still requires storage space for both
the structure array and the resulting arrays.
For an example of using opcstruct2array, see Example: Writing a Callback
Function on page 6-17.

5-14

Downloaded from www.Manualslib.com manuals search engine

Understanding Array Formatted Data

Understanding Array Formatted Data

In this section...
Array Content on page 5-15
Conversion of Logged Data to Arrays on page 5-16

Array Content
OPC Toolbox software can return arrays of Value, Quality, and TimeStamp
information from a logging task. You can retrieve arrays from memory using
getdata, or from disk using opcread, by specifying the data type as 'cell'
or any MATLAB numeric array data type, such as 'double' or 'uint32'.
Consult the function reference pages for details on how to specify the data
type.
When you request array formatted data, the toolbox returns arrays of each of
the following elements of the records in memory or on disk:
ItemID A 1-by-nItems list of all item IDs occurring in the structure
array. Each record is searched and all unique item IDs are returned in a
cell array. The order of the item IDs must be used to interpret any of the
Value, Quality, or TimeStamp arrays.
Value An nRecs-by-nItems array of values for each item ID defined in
the ItemID variable, at each time stamp defined by the TimeStamp array.
Each column of the Value array represents the history of values for the
corresponding item in the ItemID array. Each row corresponds to one
record. See Treatment of Missing Data on page 5-16 for information on
how the Value array is populated.
Quality An nRecs-by-nItems cell array of quality strings. Each column
represents the history of qualities for the corresponding item in the ItemID
array. Each row corresponds to the qualities for a particular record. If
a particular item ID was not part of a record (because the item did not
change during that period), the corresponding column in that row is set
to 'Repeat'.
TimeStamp An nRecs-by-nItems array of time stamps for each value in
the Value field. The time stamps are in MATLAB date number format. For

5-15

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

more information on MATLAB date numbers, see the datenum function

help.
EventTime An nRecs-by-1 array of times that the record was received by
OPC Toolbox software (the LocalEventTime field of the record in structure
format). The times are in MATLAB date number format. For more
information on MATLAB date numbers, see the datenum function help.

Conversion of Logged Data to Arrays

When you request array formatted data from getdata or opcread, you must
define the desired data type for the returned Value array. OPC Toolbox
software automatically converts each record of logged data from the items
data type (defined by the DataType property of that item) to the requested
data type.
When converting logged data to arrays, the toolbox must consider two factors
when populating the returned arrays:
A record may not contain information for every item in the logging task.
Treatment of Missing Data on page 5-16 discusses how the toolbox deals
with missing data.
A record may contain an array value for a single item. Such values cannot
easily be converted to a single value of numeric data types. Treatment of
Array Data Values on page 5-17 discusses how the toolbox deals with
this issue.

Treatment of Missing Data

When OPC Toolbox software logs data, each logged record may not contain all
items in the logging task. When converting the data to array format, every
item involved in the logging task must be allocated a value, a quality, and
a time stamp for each record. Therefore, in a logging task there may be
"missing" data for a particular item in a particular record. The toolbox uses
the following rules to determine how to fill the missing entry in each array:
Value When you request the 'cell' array data type, the value used
for the missing entry is an empty double array ([]). When requesting a
numeric data type, the value used for the missing entry is the last value
for that item. If no previous value is known, the equivalent NaN (not a
number) entry is used. For example, if the very first record does not contain

5-16

Downloaded from www.Manualslib.com manuals search engine

Understanding Array Formatted Data

an entry for that item, NaN is used to fill in the missing entry in the first
row of the Value array. The equivalent NaN value for integer and logical
data types is 0.
Quality The missing entry is filled with the specific quality string
'Repeat'.
TimeStamp The time stamp used for the missing entry is the first time
stamp found in that particular record (row).

Treatment of Array Data Values

For each record stored in memory or on disk during a logging task, a single
item may return an array of values. When converting logged data to array
format, each item in each record has only one entry in the Value array
allocated to that record and item.
For the 'cell' data type, OPC Toolbox software is able to store the array
returned as the Value for that element, because a MATLAB cell array is able
to store any data type of any size in each element of the cell array.
For numeric data types, such as 'double' or 'uint32', the resulting Value
array provides space for only a single value. Consequently, if an array value is
found in a logging task, and you have requested a numeric array data type, an
error will be generated. You must use the 'cell' data type or the structure
format to return logged data that contains arrays as values.

5-17

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Working with Different Data Types

In this section...
Conversion Between MATLAB Data Types and COM Variant Data Types
on page 5-18
Conversion of Values Written to an OPC Server on page 5-20
Conversion of Values Read from an OPC Server on page 5-20
Handling Arrays for Item Values on page 5-20

Conversion Between MATLAB Data Types and COM

Variant Data Types
The OPC Data Access Standard uses the Microsoft COM Specification for
communication between the OPC server and OPC client. A significant amount
of the data exchanged between the OPC server and the client is the value from
a server item or the value that a client wants to write to a server item. The
Microsoft COM Specification uses Microsoft Variants to send different data
types between the client and server. This section discusses how OPC Toolbox
software converts MATLAB data types to COM Variants when writing values,
and COM Variants to MATLAB data types when reading values.
OPC servers require all values to be written to server items in COM Variant
format. The server also provides the toolbox with COM Variants when
an items Value property is read or returned by the server. The toolbox
automatically converts between the COM Variant type and MATLAB data
types according to the table shown below.
Table 5-1 Conversion from MATLAB Data Type to COM Variant
Data Type

MATLAB Data
Type

OPC Server
Data Type (COM
Variant Type)

double

VT_R8

single

VT_R4

5-18

Downloaded from www.Manualslib.com manuals search engine

Remarks

Working with Different Data Types

Table 5-1 Conversion from MATLAB Data Type to COM Variant Data
Type (Continued)

MATLAB Data
Type

OPC Server
Data Type (COM
Variant Type)

char

VT_BSTR

logical

VT_BOOL

uint8

VT_UI1

uint16

VT_UI2

uint32

VT_UI4

uint64

VT_UI8

int8

VT_I1

int16

VT_I2

int32

VT_I4

int64

VT_I8

function_handle

N/A

Not allowed

cell

N/A

Not allowed

struct

N/A

Not allowed

object

N/A

Not allowed

N/A

VT_DISPATCH

Not allowed

N/A

VT_BYREF

Not allowed

double

VT_EMPTY

Returns the empty matrix ([])

Remarks

5-19

Downloaded from www.Manualslib.com manuals search engine

Working with OPC Data

Conversion of Values Written to an OPC Server

When you write values to the OPC server using the write or writeasync
function, you can provide any MATLAB data for the write operation. When
you write data to an OPC server, the following data conversions take place:
1 OPC Toolbox software converts the value into the equivalent COM Variant

according to Table 5-1. If any disallowed data type is encountered (for

example, if you attempt to write a MATLAB structure), an error will be
generated.
2 The COM Variant is sent to the OPC server.
3 The OPC server will attempt to convert the COM Variant to the server

items canonical data type, using COM Variant conversion rules. If the
conversion fails, the server will return an error.

Conversion of Values Read from an OPC Server

When an OPC server returns values for a server item to MATLAB, the OPC
server will first convert the value to the COM Variant equivalent of the data
type specified by the daitem objects DataType property. If the conversion
fails, an error message is returned with the value. When OPC Toolbox
software receives the value, the COM Variant is converted to the equivalent
MATLAB data type according to Table 5-1.

Handling Arrays for Item Values

The OPC Specification supports arrays of values being written to a server
item, and read from a server item. However, a specific server item may
not accept an array of values. The behavior of the server in that case is
server-dependent. For example, one server may use only the first value of the
array. Another server may return an error when attempting to write an array
of values to a server item that only supports a scalar value. OPC Toolbox
software is not able to determine if a server item accepts only scalar values.
For all of the data types listed in Table 5-1 that can be converted between
MATLAB and a COM Variant, scalar and array data are permitted by the
toolbox. However, the OPC Specification supports only one-dimensional
arrays of data. Higher dimension MATLAB arrays are flattened into a
one-dimensional vector when writing data to the OPC server.

5-20

Downloaded from www.Manualslib.com manuals search engine

6
Using Events and Callbacks
You can enhance the power and flexibility of your OPC application by using
event callbacks. An event is a specific occurrence that can happen while an
OPC Data Access client object (opcda client object) is connected to an OPC
server. The toolbox defines a set of events that include starting, stopping, or
acquiring records during a logging task, as well as events for asynchronous
reads and writes, data changes, and server shutdown notification.
When a particular event occurs, the toolbox can execute a function that you
specify. This is called a callback. Certain events can result in one or more
callbacks. You can use callbacks to perform processing tasks while your client
object is connected. For example, you can display a message, analyze data, or
perform other tasks. Callbacks are controlled through OPC Toolbox object
properties. Each event type has an associated property. You specify the
function that you want executed as the value of that property.
Example: Using the Default Callback Function on page 6-2
Event Types on page 6-5
Retrieving Event Information on page 6-10
Creating and Executing Callback Functions on page 6-16

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Example: Using the Default Callback Function

In this section...
Overview on page 6-2
Step 1: Create OPC Toolbox Group Objects on page 6-2
Step 2: Configure the Logging Task Properties on page 6-3
Step 3: Configure the Callback Properties on page 6-3
Step 4: Start the Logging Task on page 6-3
Step 5: Clean Up on page 6-4

Overview
To illustrate how to use callbacks, this section presents a simple example that
creates an OPC Toolbox object hierarchy and associates a callback function
with the start event, records acquired event, and stop event of the OPC Data
Access Group object (dagroup object). For information about all the event
callbacks supported by the toolbox, see Event Types on page 6-5.
The example uses the default callback function provided with the toolbox,
opccallback. The default callback function displays the name of the object
along with information about the type of event that occurred and when it
occurred. To learn how to create your own callback functions, see Creating
and Executing Callback Functions on page 6-16.

Step 1: Create OPC Toolbox Group Objects

This example creates a hierarchy of OPC Toolbox objects for the Matrikon
Simulation Server. To run this example on your system, you must have the
Matrikon Simulation Server installed. Alternatively, you can replace the
values used in the creation of the objects with values for a server you can
access.
da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
grp = addgroup(da,'CallbackTest');
itm = additem(grp,{'Random.Real8','Saw-toothed Waves.UInt2'});

6-2

Downloaded from www.Manualslib.com manuals search engine

Example: Using the Default Callback Function

Step 2: Configure the Logging Task Properties

For this example, we log 20 records at 0.5-second intervals.
set(grp,'RecordsToAcquire',20);
set(grp,'UpdateRate',0.5);

Step 3: Configure the Callback Properties

Set the values of three callback properties. The example uses the default
callback function opccallback.
set(grp,'StartFcn',@opccallback)
set(grp,'StopFcn',@opccallback)
set(grp,'RecordsAcquiredFcn',@opccallback)

For this example, specify how often to generate a records acquired event.
set(grp,'RecordsAcquiredFcnCount',5);

Step 4: Start the Logging Task

Start the dagroup object. The object logs 20 records at 0.5-second intervals,
and then stops. With the three callback functions enabled, the object outputs
information about each event as it occurs. The records acquired event occurs
four times for this example.
start(grp)
OPC Start event occurred at local time 18:52:38
Group 'CallbackTest': 0 records acquired.
OPC RecordsAcquired event occurred at local time
Group 'CallbackTest': 5 records acquired.
OPC RecordsAcquired event occurred at local time
Group 'CallbackTest': 10 records acquired.
OPC RecordsAcquired event occurred at local time
Group 'CallbackTest': 15 records acquired.
OPC RecordsAcquired event occurred at local time
Group 'CallbackTest': 20 records acquired.
OPC Stop event occurred at local time 18:52:49
Group 'CallbackTest': 20 records acquired.

18:52:41
18:52:44
18:52:47
18:52:49

6-3

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Step 5: Clean Up
Always remove toolbox objects from memory, and the variables that reference
them, when you no longer need them.
disconnect(da)
delete(da)
clear da grp itm

6-4

Downloaded from www.Manualslib.com manuals search engine

Event Types

Event Types
OPC Toolbox software supports several different types of events. Each event
type has an associated toolbox object property that you can use to specify the
function that executes when the event occurs.
The following table lists the supported event types, the name of the object
property associated with the event, and a brief description of the event,
including the object class associated with the event. For detailed information
about these callback properties, see the reference information for the property.
The toolbox generates a specific set of information for each event and stores
it in an event structure. To learn more about the contents of these event
structures and how to retrieve this information, see Retrieving Event
Information on page 6-10.
Events and Callback Function Properties
Event

Callback Property

Description

Cancel
Async

CancelAsyncFcn

The toolbox generates a cancel async event when

an asynchronous operation is cancelled. You cancel
an asynchronous operation using the cancelasync
function.
When a cancel async event occurs, the
toolbox executes the function specified by the
CancelAsyncFcn property. By default, the toolbox
executes the default callback function for this event,
opccallback, which displays information about the
cancel async event at the MATLAB command line.
Cancel async events occur at the dagroup object
level.

Data
Change

DataChangeFcn

The toolbox generates a data change event when the

server notifies the toolbox that data for a group has
changed. The server will notify the toolbox of data
changes only if the groups Active property is set to
'on' and the Subscription property is set to 'on'.
For more information on controlling data change

6-5

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Events and Callback Function Properties (Continued)

Event

Callback Property

Description
events, see Data Change Events and Subscription
on page 4-12.
When a data change event occurs, the toolbox
executes the function specified by the DataChangeFcn
property.
Data change events occur at the dagroup object level.

Error

ErrorFcn

The toolbox generates an error event when a

run-time error occurs, such as a data type conversion
error or time-out. Run-time errors do not include
configuration errors such as setting an invalid
property value.
When an error event occurs, the toolbox executes
the function specified by the ErrorFcn property. By
default, the toolbox executes the default callback
function for this event, opccallback, which displays
the error message at the MATLAB command line.
Error events occur at the opcda client object level.

Read Async

ReadAsyncFcn

The toolbox generates a read async event when an

asynchronous read operation completes. You execute
an asynchronous read operation using the readasync
function.
When a read async event occurs, the toolbox executes
the function specified by the ReadAsyncFcn property.
By default, the toolbox executes the default callback
function for this event, opccallback, which displays
information about the read async event at the
MATLAB command line.
Read async events occur at the dagroup object level.

6-6

Downloaded from www.Manualslib.com manuals search engine

Event Types

Events and Callback Function Properties (Continued)

Event

Callback Property

Description

Records
Acquired

RecordsAcquiredFcn

The toolbox generates a records acquired event

every time an integer multiple of a specified
number of records have been acquired. You use the
RecordsAcquiredFcnCount property to specify this
number.
When a records acquired event occurs, the
toolbox executes the function specified by the
RecordsAcquiredFcn property.
Records acquired events occur at the dagroup object
level.

Shutdown

ShutDownFcn

The toolbox generates a shutdown event when the

OPC server notifies the client that the server is
about to shut down.
When a shutdown event occurs, the toolbox executes
the function specified by the ShutDownFcn property,
and the client object is then disconnected from the
server. By default, the toolbox executes the default
callback function for this event, opccallback, which
displays information about the shutdown event at
the MATLAB command line.
Shutdown events occur at the opcda client object
level.

6-7

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Events and Callback Function Properties (Continued)

Event

Callback Property

Description

Start

StartFcn

The toolbox generates a start event when an object

is started. You use the start function to start an
object.
Note If an error occurs in the start callback
function, the object does not start.
When a start event occurs, the toolbox executes the
function specified by the StartFcn property.
Start events occur at the dagroup object level.

Stop

StopFcn

The toolbox generates a stop event when the object

stops running. An object stops running when the
stop function is called, or when the specified number
of records is acquired.
When a stop event occurs, the toolbox executes the
function specified by the StopFcn property.
Stop events occur at the dagroup object level.

Timer

TimerFcn

The toolbox generates a timer event when an integer

multiple of a specified amount of time expires. You
use the TimerPeriod property to specify the amount
of time. Time is measured relative to when the opcda
client object is connected.
Note Some timer events might not execute if your
system is significantly slowed or if the TimerPeriod
is set too small.

When a timer event occurs, the toolbox executes the

function specified by the TimerFcn property.

6-8

Downloaded from www.Manualslib.com manuals search engine

Event Types

Events and Callback Function Properties (Continued)

Event

Callback Property

Description
Timer events occur at the opcda client object level.

Write Async

WriteAsyncFcn

The toolbox generates a write async event when

an asynchronous write operation completes. You
execute an asynchronous write operation using the
writeasync function.
When a write async event occurs, the toolbox
executes the function specified by the WriteAsyncFcn
property. By default, the toolbox executes the default
callback function for this event, opccallback, which
displays information about the write async event at
the MATLAB command line.
Write async events occur at the dagroup object level.

6-9

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Retrieving Event Information

In this section...
Event Structures on page 6-10
Example: Accessing Data in the Event Log on page 6-13

Event Structures
Each event has a set of information associated with that event. The
information is generated by the OPC server or the OPC Toolbox software,
and stored in an event structure. This information includes the event type,
the time the event occurred, and other event-specific information. For some
events, the toolbox records event information in the opcda client objects
EventLog property. You can also access the event structure associated with
an event in a callback function.
For information about accessing event information in a callback function, see
Creating and Executing Callback Functions on page 6-16.
An event structure contains two fields: Type and Data. For example, this is
an event structure for a start event.
Type: 'Start'
Data: [1x1 struct]

The Type field is a text string that specifies the event type. For a start event,
this field contains the text string 'Start'.
The Data field is a structure that contains information about the event.
The composition of this structure varies, depending on which type of event
occurred. For details about the information associated with specific events,
see the following sections:
Data Fields for Cancel Async, Data Change, Error, Read Async, and Write
Async Events on page 6-11
Data Fields for Start, Stop, and Records Acquired Events on page 6-12
Data Fields for Shutdown Events on page 6-12

6-10

Downloaded from www.Manualslib.com manuals search engine

Retrieving Event Information

Data Fields for Timer Events on page 6-13

Data Fields for Cancel Async, Data Change, Error, Read Async,
and Write Async Events
For cancel async, data change, error, read async, and write async events, the
Data structure contains these fields.
Field Name

Description

GroupName

The name of the group associated with the event.

LocalEventTime

Absolute time the event occurred, returned in

MATLAB date vector format:
[year month day hour minute seconds]

TransID

The transaction ID for the operation. In the case

of a cancel async event, TransID contains the
transaction ID that was cancelled.

Items

A structure array containing information about

each item in the asynchronous operation. The
cancel async event structure does not contain this
field.

The Items structure array for read async events contains the following fields.
Field Name

Description

ItemID

The item ID for this record in the structure array.

Value

The data value.

Quality

The data quality as a string.

TimeStamp

The time the OPC server updated the value and

quality. The time is returned in MATLAB date
vector format:
[year month day hour minute seconds]

The Items structure array for write async events contains one field: ItemID.

6-11

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

The Items structure array for error events contains the ItemID field and an
Error field, containing a string describing the error that occurred for that
item.

Data Fields for Start, Stop, and Records Acquired Events

For start, stop, and records acquired events, the Data structure contains
these fields.
Field Name

Description

GroupName

The name of the group associated with the event.

LocalEventTime

Absolute time the event occurred, returned in

MATLAB date vector format:
[year month day hour minute seconds]

RecordsAcquired

The total number of records acquired in the current

logging session.

Data Fields for Shutdown Events

For shutdown events, the Data structure contains these fields.
Field Name

Description

LocalEventTime

Absolute time the event occurred, returned in

MATLAB date vector format:
[year month day hour minute seconds]

Reason

6-12

Downloaded from www.Manualslib.com manuals search engine

A string containing the reason the OPC server

provided for shutting down.

Retrieving Event Information

Data Fields for Timer Events

For timer events, the Data structure contains these fields.
Field Name

Description

LocalEventTime

Absolute time the event occurred, returned in

MATLAB date vector format:
[year month day hour minute seconds]

Example: Accessing Data in the Event Log

While an opcda client object is connected, the toolbox stores event information
in the opcda client objects EventLog property. The value of this property
is an array of event structures. Each structure represents one event. For
detailed information about the composition of an event structure for each type
of event, see Event Structures on page 6-10.
The toolbox adds event structures to the EventLog array in the order in which
the events occur. The first event structure reflects the first event recorded,
the second event structure reflects the second event recorded, and so on.
Note Data change events, records acquired events, and timer events are
not included in the EventLog. Event structures for these events (and all the
other events) are available to callback functions. For more information, see
Creating and Executing Callback Functions on page 6-16.
To illustrate the event log, this example creates an OPC Toolbox object
hierarchy, executes a logging task, and then examines the objects EventLog
property:

Step 1: Create the OPC Toolbox Object Hierarchy

This example creates a hierarchy of OPC Toolbox objects for the Matrikon
Simulation Server. To run this example on your system, you must have the
Matrikon Simulation Server installed. Alternatively, you can replace the
values used in the creation of the objects with values for a server you can
access.

6-13

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);
grp = addgroup(da,'CallbackTest');
itm1 = additem(grp,'Triangle Waves.Real8');

Step 2: Start the Logging Task

Start the dagroup object. By default, the object acquires 120 records at
0.5-second intervals, and then stops. Wait for the object to stop logging data.
start(grp)
wait(grp)

Step 3: View the Event Log

Access the EventLog property of the opcda client object. The execution of the
group logging task generated two events: start and stop. Thus the value of
the EventLog property is a 1-by-2 array of event structures.
events = da.EventLog
events =
1x2 struct array with fields:
Type
Data

To list the events that are recorded in the EventLog property, examine the
contents of the Type field.
{events.Type}
ans =
'Start'

'Stop'

To get information about a particular event, access the Data field in that
event structure. The example retrieves information about the stop event.
stopdata = events(2).Data
stopdata =
LocalEventTime: [2004 3 2 21 33 45.8750]
GroupName: 'CallbackTest'
RecordsAcquired: 120

6-14

Downloaded from www.Manualslib.com manuals search engine

Retrieving Event Information

Step 4: Clean Up
Always remove toolbox objects from memory, and the variables that reference
them, when you no longer need them. Deleting the opcda client object also
deletes the group and item objects.
disconnect(da)
delete(da)
clear da grp itm1

6-15

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Creating and Executing Callback Functions

In this section...
Creating Callback Functions on page 6-16
Specifying Callback Functions on page 6-18
Example: Viewing Recently Logged Data on page 6-20

Creating Callback Functions

The power of using event callbacks is that you can perform processing in
response to events. You decide which events with which you want to associate
callbacks, and which functions these callbacks execute.
Note Callback function execution might be delayed if the callback involves a
CPU-intensive task, or if MATLAB software is processing another task.
Callback functions require at least two input arguments:
The OPC Toolbox object
The event structure associated with the event
The function header for this callback function illustrates this basic syntax.
function mycallback(obj,event)

The first argument, obj, is the toolbox object itself. Because the object is
available, you can use in your callback function any of the toolbox functions,
such as getdata, that require the object as an argument. You can also access
all object properties, including the parent and children of the object.
The second argument, event, is the event structure associated with the event.
This event information pertains only to the event that caused the callback
function to execute. For a complete list of supported event types and their
associated event structures, see Event Structures on page 6-10.

6-16

Downloaded from www.Manualslib.com manuals search engine

Creating and Executing Callback Functions

In addition to these two required input arguments, you can also specify
application-specific arguments for your callback function.
Note If you specify input arguments in addition to the object and event
arguments, you must use a cell array when specifying the name of the
function as the value of a callback property. For more information, see
Specifying Callback Functions on page 6-18.

Example: Writing a Callback Function

This example implements a callback function for a records acquired event.
This callback function enables you to monitor the records being acquired by
viewing the most recently acquired records in a plot window.
To implement this function, the callback function acquires the last 60 records
of data (or fewer if not enough data is available in the OPC Toolbox software
engine) and displays the data in a MATLAB figure window. The function also
accesses the event structure passed as an argument to display the time stamp
of the event. The drawnow command in the callback function forces MATLAB
to update the display.
function display_opcdata(obj,event)
numRecords = min(obj.RecordsAvailable, 60);
lastRecords = peekdata(obj,numRecords);
[i, v, q, t, et] = opcstruct2array(lastRecords);
plot(t, v);
isBad = strncmp('Bad', q, 3);
isRep = strncmp('Repeat', q, 6);
hold on
for k=1:length(i)
h = plot(t(isBad(:,k),k), v(isBad(:,k),k), 'o');
set(h,'MarkerEdgeColor','k', 'MarkerFaceColor','r')
h = plot(t(isRep(:,k),k), v(isRep(:,k),k), '*');
set(h,'MarkerEdgeColor',[0.75, 0.75, 0]);
end
axis tight;
set(gca,'YLim',[0, 200]);

6-17

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

datetick('x','keeplimits');
eventTime = event.Data.LocalEventTime;
title(sprintf('Event occured at %s', ...
datestr(eventTime, 13)));
drawnow; % force an update of the figure window
hold off;

To see how this function can be used as a callback, see Example: Viewing
Recently Logged Data on page 6-20.

Specifying Callback Functions

You associate a callback function with a specific event by setting the value of
the OPC Toolbox object property associated with that event. You can specify
the callback function as the value of the property in one of three ways:
Using a Text String to Specify Callback Functions on page 6-18
Using a Cell Array to Specify Callback Functions on page 6-19
Using Function Handles to Specify Callback Functions on page 6-19
The following sections provide more information about each of these options.
Note To access the object or event structure passed to the callback function,
you must specify the function as a cell array or as a function handle.

Using a Text String to Specify Callback Functions

You can specify the callback function as a string. For example, this code
specifies the callback function mycallback as the value of the start event
callback property StartFcn for the group object grp.
grp.StartFcn = 'mycallback';

In this case, the callback is evaluated in the MATLAB workspace.

6-18

Downloaded from www.Manualslib.com manuals search engine

Creating and Executing Callback Functions

Using a Cell Array to Specify Callback Functions

You can specify the callback function as a text string inside a cell array.
For example, this code specifies the callback function mycallback as the value
of the start event callback property StartFcn for the group object grp.
grp.StartFcn = {'mycallback'};

To specify additional parameters, include them as additional elements in

the cell array.
time = datestr(now,0);
grp.StartFcn = {'mycallback',time};

The first two arguments passed to the callback function are still the OPC
Toolbox object (obj) and the event structure (event). Additional arguments
follow these two arguments.

Using Function Handles to Specify Callback Functions

You can specify the callback function as a function handle.
For example, this code specifies the callback function mycallback as the value
of the start event callback property StartFcn for the group object grp.
grp.StartFcn = @mycallback;

To specify additional parameters, include the function handle and the

parameters as elements in the cell array.
time = datestr(now,0);
grp.StartFcn = {@mycallback,time};

If you are executing a local callback function from within a file, you must
specify the callback as a function handle.

6-19

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

Specifying a Toolbox Function as a Callback

In addition to specifying callback functions of your own creation, you can also
specify toolbox functions as callbacks. For example, this code sets the value
of the stop event callback to the start function.
grp.StopFcn = @start;

Disabling Callbacks
If an error occurs in the execution of the callback function, the toolbox disables
the callback and displays a message similar to the following.
start(grp)
??? Error using ==> myrecords_cb
Too many input arguments.
Warning: The RecordsAcquiredFcn callback is being disabled.

To enable a callback that has been disabled, set the value of the property
associated with the callback.

Example: Viewing Recently Logged Data

This example configures an OPC Toolbox object hierarchy and sets the records
acquired event callback function property to the display_opcdata function,
created in Example: Writing a Callback Function on page 6-17.
When run, the example displays the last 60 records of acquired data every
time 5 records have been acquired. Repeat values are highlighted with
magenta circles, and bad values are highlighted with red circles.

Step 1: Create the OPC Toolbox Object Hierarchy

This example creates a hierarchy of OPC Toolbox objects for the Matrikon
Simulation Server. To run this example on your system, you must have the
Matrikon Simulation Server installed. Alternatively, you can replace the
values used in the creation of the objects with values for a server you can
access.
da = opcda('localhost','Matrikon.OPC.Simulation.1');
connect(da);

6-20

Downloaded from www.Manualslib.com manuals search engine

Creating and Executing Callback Functions

grp = addgroup(da,'CallbackTest');
itm1 = additem(grp,'Triangle Waves.Real8');
itm2 = additem(grp,'Saw-toothed Waves.UInt2');

Step 2: Configure Property Values

This example sets the UpdateRate value to 0.2 seconds, and the
RecordsToAcquire property to 200. The example also specifies as the
value of the RecordsAcquiredFcn callback the event callback function
display_opcdata, created in Example: Writing a Callback Function on
page 6-17. The object will execute the RecordsAcquiredFcn every 5 records,
as specified by the value of the RecordsAcquiredFcnCount property.
set(grp,'UpdateRate',0.2);
set(grp,'RecordsToAcquire',200);
set(grp,'RecordsAcquiredFcnCount',5);
set(grp,'RecordsAcquiredFcn',@display_opcdata);

Step 3: Acquire Data

Start the dagroup object. Every time 5 records are acquired, the object
executes the display_opcdata callback function. This callback function
displays the most recently acquired records logged to the memory buffer.
start(grp)
wait(grp)

Step 4: Clean Up
Always remove toolbox objects from memory, and the variables that reference
them, when you no longer need them. Deleting the opcda client object also
deletes the group and item objects.
disconnect(da)
delete(da)
clear da grp itm1 itm2

6-21

Downloaded from www.Manualslib.com manuals search engine

Using Events and Callbacks

6-22

Downloaded from www.Manualslib.com manuals search engine

7
Using the OPC Toolbox
Block Library
OPC Toolbox software includes a Simulink interface called the OPC Toolbox
block library. This chapter describes how to use the blocks of the OPC Toolbox
block library in a Simulink model to communicate with OPC servers.
Overview on page 7-2
Example: Reading and Writing Data from the Matrikon OPC Simulation
Server on page 7-3
Using the OPC Client Manager on page 7-18

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Overview
The OPC Toolbox block library is a tool for sending data from your Simulink
model to an OPC server, or querying an OPC server to receive live data into
your model. You use blocks from the OPC Toolbox block library with blocks
from other Simulink libraries to create models capable of sophisticated OPC
server communications.
The OPC Toolbox block library requires Simulink, a tool for simulating
dynamic systems. Simulink is a model definition environment. Use Simulink
blocks to create a block diagram that represents the computations of your
system or application. Simulink is also a model simulation environment. Run
the block diagram to see how your system behaves. If you are new to Simulink,
read Simulink Getting Started Guide to better understand its functionality.
The best way to learn about the OPC Toolbox block library is to see an
example. Example: Reading and Writing Data from the Matrikon OPC
Simulation Server on page 7-3 provides a simple example. For more detailed
information about the blocks in the OPC Toolbox block library, see Chapter
12, Block Reference.

7-2

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

Example: Reading and Writing Data from the Matrikon

OPC Simulation Server
In this section...
Overview on page 7-3
Step 1: Open the OPC Toolbox Block Library on page 7-4
Step 2: Create a New Model on page 7-5
Step 3: Drag the OPC Toolbox Blocks into the Model on page 7-6
Step 4: Drag Other Blocks to Complete the Model on page 7-7
Step 5: Configure OPC Servers for the Model on page 7-9
Step 6: Specify the Block Parameter Values on page 7-12
Step 7: Connect the Blocks on page 7-15
Step 8: Run the Simulation on page 7-16

Overview
This section provides a step-by-step example to illustrate how to use the OPC
Toolbox block library. The example builds a simple model using the blocks in
the OPC Toolbox block library with blocks from other Simulink libraries.
This example writes a sine wave to the Matrikon OPC Simulation Server, and
reads the data back from the same server. You use the OPC Write block to
send data to the OPC server, and the OPC Read block to read that same
data back into your model.
Note To run the sample code in the following examples, you must have
the Matrikon OPC Simulation Server available on your local machine. For
information on installing this, see Installing the Matrikon OPC Simulation
Server on page 1-18. The code requires only minor changes work with other
servers.

7-3

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Step 1: Open the OPC Toolbox Block Library

To open the OPC Toolbox block library, first start the Simulink Library
Browser. To start the Simulink Library Browser, enter
simulink

at the MATLAB prompt. MATLAB opens the Simulink Library Browser

window. The left pane contains a list of available block libraries in
alphabetical order.
To open the OPC Toolbox block library, click its entry in the tree. When you
open a library, Simulink loads the library and displays its blocks.

Click here
to open the
library.

Selecting the OPC Toolbox Block Library in the Simulink Library Browser

Alternatively, you can open the OPC Toolbox block library by typing
opclib

at the MATLAB command prompt.

7-4

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

Step 2: Create a New Model

To use a block, you must add it to an existing model or create a new model.
1 To create a new model, click the File menu in the Simulink Library

Browser and select New > Model. Simulink opens an empty model
window on the display.

2 Use the Save option to assign the new model a name.

7-5

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Step 3: Drag the OPC Toolbox Blocks into the Model

The OPC Toolbox block library contains four blocks: OPC Configuration,
OPC Quality Parts, OPC Read, and OPC Write. You can use these blocks to
configure and manage connections to servers, to send and receive live data
between your OPC server and your simulation, and to analyze OPC quality.
To use the blocks in a model, click each block in the library and, holding the
mouse button down, drag the block into the model window. For this example,
you need one instance each of the OPC Configuration, OPC Write, and OPC
Read block in your model.

Drag blocks into model.

Dragging OPC Toolbox Blocks into Model Window

7-6

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

Step 4: Drag Other Blocks to Complete the Model

Your model requires three more blocks. One block provides the data sent to
the server; the other two blocks display the data received from the server.
To send a sine wave to the server, you can use the Sine Wave block. To
access the Sine Wave block, expand the Simulink node in the browser tree,
and click the Sources library entry. From the blocks displayed in the right
pane, drag the Sine Wave block into the model and place it to the left of the
OPC Write block.

Drag the Sine Wave block into the model.

Dragging Sine Wave Block into Model Window

You can use the Scope block to show the value received from the server, and a
Display block to view the quality of the item. (You will remove the time stamp
output port in the next step.) To access the Scope block, click the Sinks library
entry in the expanded Simulink node in the browser tree. From the blocks
displayed in the right pane, drag the Scope block into the model and place
it above and to the right of the OPC Read block. Also drag a Display block
into the model and place it below the Scope block.

7-7

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Drag the Display and Scope blocks

into the model.

Dragging Display and Scope Blocks into Model Window

7-8

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

Step 5: Configure OPC Servers for the Model

To communicate with OPC servers from Simulink, you first need to configure
those servers in the model. The OPC Configuration block manages and
configures OPC servers for a Simulink model. Each OPC Read or OPC Write
block uses one server from the configured servers, and defines the items to
read from or write to.
1 Double-click the OPC Configuration block to open its parameters dialog.

7-9

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

2 Click Configure OPC Clients to open the OPC Client Manager.

3 Click Add to open the OPC Server Properties dialog. Specify the ID of the

server as 'Matrikon.OPC.Simulation.1' (or click Select and choose the

server from the list of available OPC servers).

7-10

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

4 Click OK to add the OPC server to the OPC Client Manager.

The Matrikon OPC Simulation Server is now available throughout the

model for reading and writing.
5 Your model will use default values for all other settings in the OPC

Configuration block. Click OK in the OPC Configuration dialog to close

that dialog.

7-11

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Step 6: Specify the Block Parameter Values

You set parameters for the blocks in your model by double-clicking on the
block.
1 Double-click the OPC Write block to open its parameters dialog. The

Matrikon server is automatically selected for you as the OPC client to use
in this block. You need to specify the items for writing.

2 Click Add Items to display a name space browser for the Matrikon OPC

Simulation Server.

7-12

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

3 Expand the Simulation Items node in the name space, then expand the

Bucket Brigade node. Select the Real8 node and click >> to add that item
to the selected items list.

4 Click OK to add the item Bucket Brigade.Real8 to the OPC Write blocks

ItemIDs list.
5 In the OPC Write parameters dialog, click OK to accept the changes and

close the dialog.

6 Double-click the OPC Read block to open its dialog. Add the same item to

the OPC Read block, repeating steps 2-5 that you followed for the OPC
Write block in this section.
7 Set the read mode to 'Synchronous (device)' and the sample time for

the block to 0.2.

7-13

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

8 Also uncheck the 'Show timestamp port' option. This step removes the

time stamp output port from the OPC Read block.

7-14

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

Step 7: Connect the Blocks

Make a connection between the Sine Wave block and the OPC Write block.
When you move the cursor near the output port of the Sine Wave block, the
cursor becomes crosshairs. Click the Sine Wave output port and hold the
mouse button; drag to the input port of the OPC Write block, and release the
button.
In the same way, make a connection between the first output port of the OPC
Read block (labeled V) and the input port of the Scope block. Then connect
the other output port of the OPC Read block (labeled Q) to the input port
of the Display block.
Note that the OPC Write and OPC Read blocks do not directly connect
together within the model. The only communication between them is through
an item on the server, which you defined in Step 5: Configure OPC Servers
for the Model on page 7-9.

7-15

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Step 8: Run the Simulation

Before you run the simulation, double-click the Scope block to open the scope
view.

To run the simulation, click the Start button on the model window toolbar.
Alternatively, you can use the Simulation menu in the model window and
choose the Start option.

The model writes a sine wave to the OPC server, reads back from the server,
and displays the wave in the scope trace. In addition, the quality value is set to
192, which indicates a good quality (see Appendix A, OPC Quality Strings).

7-16

Downloaded from www.Manualslib.com manuals search engine

Example: Reading and Writing Data from the Matrikon OPC Simulation Server

While the simulation is running, the status bar at the bottom of the model
window updates the progress of the simulation, and the sine wave is displayed
in the Scope window.

7-17

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Using the OPC Client Manager

In this section...
Introduction on page 7-18
Adding Clients to the OPC Client Manager on page 7-19
Removing Clients from the OPC Client Manager on page 7-19
Modifying the Server Timeout Value for a Client on page 7-20
Controlling Client/Server Connections on page 7-20

Introduction
The OPC Client Manager displays and manages all clients for a Simulink
model. Using the OPC Client Manager, you associate one or more clients with
a particular model. Each time you use an OPC Read or OPC Write block, you
can then choose the client for that block from the list of configured clients.
By defining a single list of clients in the OPC Client Manager, you enable a
Simulink model to reuse clients among OPC Read and OPC Write blocks.
You access the OPC Client Manager from the parameters dialog of the OPC
Configuration, OPC Read, or OPC Write block, by clicking Configure OPC
Clients. A dialog similar to the following figure appears.

7-18

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Client Manager

Adding Clients to the OPC Client Manager

You add clients to the OPC Client Manager by clicking Add. The following
dialog box appears.

Specify the host in the Host edit box. You can then type the Server ID of the
required server, or use Select to query the host for a list of servers.
Specify the timeout (in seconds) to use when communicating with the server.
When you click OK, the client is added to the OPC Clients list in the OPC
Client Manager. You can now use that client in one or more OPC Read or
OPC Write blocks within that model.

Removing Clients from the OPC Client Manager

To remove a client from the OPC Client Manager, select the client in the OPC
Clients list and click Delete. A confirmation dialog appears. Click Delete to
remove the client from the OPC Client Manager.
If you attempt to remove a client that is referenced by one or more OPC
Toolbox library blocks, you will see the following dialog.

Click Delete to remove all blocks that reference the client you want to delete.

7-19

Downloaded from www.Manualslib.com manuals search engine

Using the OPC Toolbox Block Library

Click Replace to replace the referenced client with another client in the OPC
Client list (this choice is available only if another client is available), and
select the replacement client from the resulting list. Click Cancel to cancel
the delete operation.

Modifying the Server Timeout Value for a Client

Click Edit to modify the timeout property of the selected client. The timeout
value is specified in seconds, and applies to all server operations (connect,
disconnect, read, write).

Controlling Client/Server Connections

OPC Toolbox software automatically attempts to connect a client configured
in the OPC Client Manager to its server. This enables you to browse the
server name space for items, and speeds up the initialization process of
simulating a model.
You can control the clients connection status by highlighting a client in the
OPC Client list and clicking Connect or Disconnect.
The OPC Toolbox block library will automatically reconnect any disconnected
client to its server when you start that model.

7-20

Downloaded from www.Manualslib.com manuals search engine

8
Function Reference
Object Creation and Configuration
(p. 8-2)

Create and configure the objects that

provide access to OPC servers

Server Exploration (p. 8-2)

Explore server name space, tag

properties, and server configuration
information

Data Access (p. 8-3)

Read data from OPC server

synchronously or asynchronously,
or through server-initiated
events; write data to OPC server
synchronously or asynchronously

OPC Data Visualization (p. 8-3)

Visualize live OPC data

Logging and Buffering (p. 8-4)

Log data provided by OPC data

access servers to disk and/or
memory; and read logs

Simulink Support (p. 8-4)

Create Simulink blocks from

MATLAB group objects

Utilities (p. 8-5)

Manage OPC Toolbox objects and

connections to OPC servers; get help
on using OPC Toolbox software

Downloaded from www.Manualslib.com manuals search engine

Function Reference

Object Creation and Configuration

addgroup

Add data access group to opcda

object

additem

Add data access items to dagroup

object

clonegroup

Clone group into new private group

on same client

connect

Connect opcda object to server

copyobj

Make copy of OPC Toolbox object

delete

Remove OPC Toolbox objects from

memory

disconnect

Disconnect opcda object from server

disp

Summary of information for OPC

Toolbox objects

get

OPC Toolbox object properties

isvalid

True for undeleted OPC Toolbox

objects

makepublic

Convert private group into public

group

opcda

Construct OPC data access object

removepublicgroup

Remove public group from server

set

Configure or display OPC Toolbox

object properties

Server Exploration
flatnamespace

Flatten hierarchical OPC name

space

getnamespace

OPC server name space

8-2

Downloaded from www.Manualslib.com manuals search engine

Data Access

opcserverinfo

Version, server, and status

information

serveritemprops

Property information for items in

OPC server name space

serveritems

Query server or name space for fully

qualified item IDs

cancelasync

Cancel asynchronous read and write

operations

read

Read data synchronously from OPC

groups or items

readasync

Read data asynchronously from

group or items

refresh

Read all active items in group

write

Write values to group or items

writeasync

Asynchronously write values to

group or items

Data Access

OPC Data Visualization

trend

Display graphical trend of OPC data

for group

8-3

Downloaded from www.Manualslib.com manuals search engine

Function Reference

Logging and Buffering

flushdata

Remove all logged data records

associated with dagroup object

getdata

Logged records from OPC Toolbox

engine to MATLAB workspace

opcread

Read logged records from disk to

MATLAB workspace

opcstruct2array

Convert OPC data from structure to

array format

opcstruct2timeseries

Convert OPC data from structure to

time series format

peekdata

Preview most recently acquired data

start

Start a logging task

stop

Stop a logging task

wait

Suspend MATLAB execution until

object stops logging

Simulink Support
genslread

Generate Simulink OPC Read block

from MATLAB group object

genslwrite

Generate Simulink OPC Write block

from MATLAB group object

8-4

Downloaded from www.Manualslib.com manuals search engine

Utilities

Utilities
cleareventlog

Clear event log, discarding all events

load

Load OPC Toolbox objects from

MAT-file

obj2mfile

Convert OPC Toolbox object to

MATLAB code

opccallback

Event information for OPC Toolbox

callbacks

opcfind

Find OPC Toolbox objects with

specific properties

opchelp

Help for OPC Toolbox function or

property

opcqid

Construct quality ID from items

quality string

opcqparts

Extract quality parts from OPC

quality ID

opcqstr

Convert OPC quality ID into

readable string

opcregister

Install and register OPC Foundation

Core Components

opcreset

Disconnect and delete all OPC

Toolbox objects

opcsupport

Run OPC Toolbox troubleshooting

utility

opctool

Open OPC Tool GUI

openosf

Open OPC Tool GUI session file

propinfo

Property information for OPC

Toolbox objects

8-5

Downloaded from www.Manualslib.com manuals search engine

Function Reference

save

Save OPC Toolbox objects to

MAT-file

showopcevents

Event log summary for OPC Toolbox

events

8-6

Downloaded from www.Manualslib.com manuals search engine

9
Functions Alphabetical
List

Downloaded from www.Manualslib.com manuals search engine

addgroup

Purpose

Add data access group to opcda object

Syntax

GrpObj = addgroup(DAObj)
GrpObj = addgroup(DAObj,'GName')
GrpObj = addgroup(DAObj,'GName','GrpType')

Description

GrpObj = addgroup(DAObj) adds a group to the opcda object DAObj. A

group is a container for a client to organize and manipulate data items.

Typically, you create different groups to support different update rates,
activation status, callbacks, etc.
GrpObj is a dagroup object. By default, GrpObj has the Active property
set to 'on', GroupType set to 'private', and the Subscription
property set to 'on'.

If DAObj is already connected to the server when addgroup is called, a

group name is requested from the server. If the server does not supply a
group name, or the object is not connected to a server, a unique name
is automatically assigned to GrpObj. The unique name follows the
convention 'groupN' where N is an integer. You can change this name
with the groups Name property.
GrpObj = addgroup(DAObj,'GName') adds a group to the OPC data

access object DAObj with the group name given by 'GName'. The group
name must be unique among other group names within Obj.
GrpObj = addgroup(DAObj,'GName','GrpType') adds a group to
the opcda object DAObj with the group type specified by 'GrpType'.
If 'GrpType' is 'private' (the default) the group is configured to
be private to DAObj, and no other client connected to the OPC server
can access that group. If 'GrpType' is 'public' then a connection
is made to the servers public group named GName. To make a
connection to a public group named GName, that group must exist
on the server as a public group. You create public groups on the
server using the makepublic function. Note that some servers do
not support public groups; you can verify whether a server supports
public groups by running opcserverinfo(DAObj) and checking the
SupportedInterfaces field for the IOPCServerPublicGroups interface.

9-2

Downloaded from www.Manualslib.com manuals search engine

addgroup

You can add items to GrpObj using the additem function, if the group
type is 'private'. For a public group, the items are already defined,
and are automatically created when you connect to the public group
using addgroup.

Examples

Create an opcda client:

da = opcda('localhost', 'Matrikon.OPC.Simulation');

Create a group using a default group name:

grp1 = addgroup(da);

Add another group, providing the name:

grp2 = addgroup(da, 'AddgroupEx');

See Also

additem | opcserverinfo

9-3

Downloaded from www.Manualslib.com manuals search engine

additem

Purpose

Add data access items to dagroup object

Syntax

IObj = additem(GObj,'IName')
IObj = additem(GObj,'IName','DataType')
IObj = additem (GObj,'IName','DataType','Active')

Description

IObj = additem(GObj,'IName') adds items to the group object GObj

with fully qualified item IDs given by IName. The object IObj is the
created item object or objects. You specify IName as a single item ID or

as a cell array of item IDs.

The daitem object provides a connection to a data variable in the
physical device and returns information about the data variable, such
as its value, quality, and time stamp. Note that you cannot add a given
item to the same group more than once. However, you can add the same
item to different groups.
By default, IObj is active; that is, if the groups Subscription property
is on, the items Value, Quality, and TimeStamp properties will be
updated at the groups UpdateRate.
Servers often require item IDs to be specified in the correct case. You
can use the serveritems function to find valid item IDs.
Note You cannot add items to a public group. A public group has a
fixed set of item IDs common to all clients sharing that group. The
GroupType property of a dagroup object indicates the type of group.
IObj = additem(GObj,'IName','DataType') adds items to the group
object GObj with the requested data type given by 'DataType'. You
specify 'DataType' as a cell array of strings, one for each item ID.
'DataType' is the data type in which the items value will be stored in
the MATLAB workspace. The supported data types are 'logical',
'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'single',
'double', 'char', and 'date'. Note that if the requested data type

is rejected by the server, the item is not added. The requested data

9-4

Downloaded from www.Manualslib.com manuals search engine

additem

type is stored in the DataType property. The canonical data type (the
data type used by the server to store the item value) is stored in the
CanonicalDataType property.
IObj = additem (GObj,'IName','DataType','Active') adds items
to the group object GObj with active status given by 'Active'. You
specify 'Active' as a cell array of strings, one for each item ID.
'Active' can be 'on' or 'off'. The active status is stored in the
Active property.

Examples

Create a client and a group:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExAddItem');

Add two items with their canonical data types:

itm = additem(grp, {'Random.Real4', 'Random.Real8'})

Add an item with a 'double' data type:

itmDbl = additem(grp, 'Random.Int2', 'double')

Add an inactive item:

itmInact = additem(grp, 'Random.UInt4', 'double', 'off')

See Also

getnamespace | serveritems

9-5

Downloaded from www.Manualslib.com manuals search engine

cancelasync

Purpose

Cancel asynchronous read and write operations

Syntax

cancelasync(GObj)
cancelasync(GObj,TransID)

Description

cancelasync(GObj) cancels all asynchronous read or write operations

that are in progress for the group object specified by GObj. Note

that this function is asynchronous and does not block the MATLAB
command line.
After cancelasync cancels the in-progress asynchronous operations,
the OPC server generates a cancel async event. If you specify a callback
function file for the CancelAsyncFcn property, the callback function
executes when this event occurs.
cancelasync(GObj,TransID) cancels the asynchronous operation(s),
specified by the transaction ID(s) given by TransID. You can cancel

specific asynchronous requests using this syntax.

Examples

Create a connected client, group, and items:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'CancelAsyncEx');
additem(grp, {'Random.Real8', 'Random.Real4'});

Request an asynchronous read operation and then immediately cancel

that request:
tid = readasync(grp); cancelasync(grp, tid)

See Also

readasync | writeasync

9-6

Downloaded from www.Manualslib.com manuals search engine

cleareventlog

Purpose

Clear event log, discarding all events

Syntax

cleareventlog(DAObj)

Description

cleareventlog(DAObj) clears the event log for opcda object DAObj.

DAObj can be an array of objects. cleareventlog also discards any
events stored in the EventLog property of the objects.

Examples

Create a connected client and configure a group with two items:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ClearEventLogEx');
itm1 = additem(grp, 'Random.Real8');
itm2 = additem(grp, 'Triangle Waves.UInt1');

Run a 10-second logging task, and after 5 seconds perform an

asynchronous read of the group:
set(grp, 'UpdateRate', 1, 'RecordsToAcquire', 10);
start(grp);
pause(5);
tid = readasync(grp);
wait(grp);

Examine the event log size:

el = get(da, 'EventLog')

Clear the event log:

cleareventlog(da)
el2 = get(da, 'EventLog')

9-7

Downloaded from www.Manualslib.com manuals search engine

clonegroup

Purpose

Clone group into new private group on same client

Syntax

NewGObj = clonegroup(GObj,'NewName')

Description

NewGObj = clonegroup(GObj,'NewName') clones the dagroup object

specified by GObj, making a private group NewGObj with name NewName.
NewName must be a unique group name. GObj can be a private group or

a public group.
The new group NewGObj is independent of the original group, but with
the same parent (opcda object) and the same items as that group. All
the group and item properties are duplicated with the exception of the
following:
The Active property is configured to 'off'.
The GroupType property is configured to 'private'.
Not all OPC data access servers support the cloning of groups. To use
this functionality, your server must support public groups. If you try to
clone a group on a server that does not support public groups, an error
is generated. To verify that a server supports public groups, use the
opcserverinfo function on the client connected to that server: Look for
an entry 'IOPCPublicGroups' in the 'SupportedInterfaces' field.
You use clonegroup primarily when you want to create a private
duplicate of a public group that you can then modify. If you want to
create a copy of a group in another client, use the copyobj function.

Examples

Create a fictitious client and configure a group with two items. Do not
connect to the server.
da =
grp1
itm1
itm2

opcda('localhost', 'Dummy.Server');
= addgroup(da, 'OriginalGroup');
= additem(grp1, 'Device1.Item1');
= additem(grp1, 'Device1.Item2');

Clone the group:

9-8

Downloaded from www.Manualslib.com manuals search engine

clonegroup

grp2 = clonegroup(grp1, 'ClonedGroup');

See Also

copyobj | makepublic

9-9

Downloaded from www.Manualslib.com manuals search engine

connect

Purpose

Connect opcda object to server

Syntax

connect(DAObj)

Description

connect(DAObj) connects the opcda object DAObj to the OPC server

that you specified by the Host and ServerID properties. When you
connect DAObj, the Status property takes the value 'connected'. You
can disconnect DAObj from the server with the disconnect function.
When you disconnect DAObj, the Status property takes the value
'disconnected'.

If DAObj is an array of objects and the function cannot connect some

of these objects, it generates a warning message. If the function can
connect none of the objects, it generates an error message.
It is possible to create groups and items before connecting to the server.
However, servers impose restrictions on client group and item names.
Therefore, if you create a group hierarchy and then connect to the
server, connect automatically deletes groups or items that the server
cannot support, and issues a warning message.

Examples

Create a Data Access client and connect to the server:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);

See Also

disconnect

9-10

Downloaded from www.Manualslib.com manuals search engine

copyobj

Purpose

Make copy of OPC Toolbox object

Syntax

NewObj = copyobj(Obj)
NewObj = copyobj(Obj, ParentObj)

Description

NewObj = copyobj(Obj) makes a copy of all the objects in Obj, and

returns them in NewObj. Obj can be a scalar OPC Toolbox object, or a

vector of toolbox objects.

NewObj = copyobj(Obj, ParentObj) makes a copy of the objects in
Obj inside the parent object ParentObj. ParentObj must be a valid
scalar parent object for Obj. If any objects in Obj cannot be created in
ParentObj, a warning will be generated.

A copied toolbox object contains new versions of all children, their

children, and any parents that are required to construct that object. A
copied object is different from its parent object in the following ways:
The values of read-only properties will not be copied to the new
object. For example, if an object is saved with a Status property
value of 'connected', the object will be recreated with a Status
property value of 'disconnected' (the default value). You can use
propinfo to determine if a property is read-only. Specifically, a
connected opcda object is copied in the disconnected state, and a copy
of a logging dagroup object is not reset to the logging state.
A copied dagroup object that has records in memory from a logging
session is copied without those records.

Examples

Create a connected Data Access client with a group containing an item:

da1 = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da1);
grp1 = addgroup(da1, 'CopyobjEx');
itm1 = additem(grp1, 'Random.Real8');

Copy the client object. This also copies the group and item objects.
da2 = copyobj(da1);

9-11

Downloaded from www.Manualslib.com manuals search engine

copyobj

grp2 = get(da2, 'Group')

Change the first groups name, and note that the second groups name
is unchanged:
set(grp1, 'Name', 'NewGroupName');
get(grp2, 'Name')

See Also

obj2mfile | propinfo

9-12

Downloaded from www.Manualslib.com manuals search engine

delete

Purpose

Remove OPC Toolbox objects from memory

Syntax

delete(Obj)

Description

delete(Obj) removes the OPC Toolbox object Obj from memory. Obj

can be an array of objects. A deleted object becomes invalid and you

should remove references to that object from the workspace with the
clear command. Deleting an object that contains children (groups or
items) also deletes these children, so you should remove references to
these children.
If multiple references to a toolbox object exist in the workspace, then
deleting one object invalidates the remaining references.
If Obj is an opcda object connected to the server, delete disconnects
and deletes the object.

Examples

Delete a group and its children from memory:

da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da,'DeleteEx');
itm = additem(grp,'Random.Real4');
r = read(grp)
delete(grp);
% deletes itm as well
clear grp itm

See Also

disconnect | isvalid

9-13

Downloaded from www.Manualslib.com manuals search engine

disconnect

Purpose

Disconnect opcda object from server

Syntax

disconnect(DAObj)

Description

disconnect(DAObj) disconnects the opcda object DAObj from the

server. DAObj can be an array of objects.

If the disconnection from the server was successful, the function sets the
DAObj property Status value to 'disconnected'. You can reconnect
DAObj to the server with the connect function.
If DAObj is an array of objects and the function cannot disconnect some
of the objects from the server, it disconnects the remaining objects in
the array and issues a warning. If the function can disconnect none of
the objects from their server, it generates an error.

Examples

Create a Data Access client and connect to the server:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
get(da, 'Status')

Disconnect from the server:

disconnect(da);
get(da, 'Status')

See Also

connect | propinfo

9-14

Downloaded from www.Manualslib.com manuals search engine

disp

Purpose

Summary of information for OPC Toolbox objects

Syntax

Obj
disp(Obj)

Description

Obj or disp(Obj) displays summary information for OPC Toolbox

object Obj.

If Obj is an array of objects, disp outputs a table of summary

information about the objects in the array.
In addition to the syntax shown above, you can display summary
information for Obj by excluding the semicolon when
Creating a toolbox object, using the opcda, addgroup, or additem
functions
Configuring property values using dot notation

Examples

Display the summary of a data access client:

da = opcda('localhost', 'My.Server.1')
da =
Summary of OPC Data Access Client Object: localhost/My.Server.1
Server Parameters
Host
: localhost
ServerID : My.Server.1
Status
: disconnected
Timeout
: 10 seconds
Object Parameters
Group
: 0-by-1 dagroup object
Event Log : 0 of 1000 events

9-15

Downloaded from www.Manualslib.com manuals search engine

disp

Display the summary information for an array of data access clients:

da2 = opcda('localhost', 'My.Second.Server.1');
[da da2]
OPC Data Access Object Array:
Index:
1
2

See Also

Status:
disconnected
disconnected

addgroup | additem | opcda

9-16

Downloaded from www.Manualslib.com manuals search engine

Name:
localhost/My.Server.1
localhost/My.Second.Server.1

flatnamespace

Purpose

Flatten hierarchical OPC name space

Syntax

FNS = flatnamespace(NS)

Description

FNS = flatnamespace(NS) flattens the hierarchical name space NS,

by recursively removing all information in the Nodes fields of NS and
placing that information into additional entries in the root structure of
FNS. You obtain a hierarchical name space using the 'hierarchical'
flag in getnamespace.

Examples

Retrieve the name space for the Matrikon Simulation Server, and then
flatten the name space:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
hierNS = getnamespace(da)
flatNS = flatnamespace(hierNS)

See Also

getnamespace | serveritems

9-17

Downloaded from www.Manualslib.com manuals search engine

flushdata

Purpose

Remove all logged data records associated with dagroup object

Syntax

flushdata(GObj)

Description

flushdata(GObj) removes all records associated with the dagroup

object GObj from the OPC Toolbox engine, and sets RecordsAvailable
to 0 for that object.
GObj can be a scalar dagroup object, or a vector of dagroup objects.

Examples

Create a connected client and configure a group with two items:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ClearEventLogEx');
itm1 = additem(grp, 'Random.Real8');

Acquire 10 records using a logging task:

set(grp, 'UpdateRate', 0.5, 'RecordsToAcquire', 10);
start(grp);
wait(grp);

Examine the records available:

recordCount1 = get(grp, 'RecordsAvailable')

Flush all data from the client:

flushdata(grp)
recordCount2 = get(grp, 'RecordsAvailable')

See Also

getdata | peekdata | start | stop

9-18

Downloaded from www.Manualslib.com manuals search engine

genslread

Purpose

Generate Simulink OPC Read block from MATLAB group object

Syntax

BlkPath = genslread(GrpObj)
BlkPath = genslread(GrpObj, DestSys)

Description

BlkPath = genslread(GrpObj) generates an OPC Read block from the

dagroup object GrpObj, and places the block in a new Simulink model.

The OPC Read block has the same name, update rate, and items as
GrpObj. If all items in GrpObj have the same data type, the OPC Read
blocks Value port indicates that data type. BlkPath indicates the full
path to the new OPC Read block.
BlkPath = genslread(GrpObj, DestSys) generates the OPC Read
block and places it into the system defined by DestSys. DestSys must

be a model name or a path to a subsystem block. The OPC Read block

automatically takes a location that attempts to minimize overlap of
lines and blocks, however, the block might appear over an existing
annotation.

Examples

Create a group object with two items, and then construct an OPC Read
block from the group:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
% Set update rate to 2 seconds:
grp.UpdateRate = 2;
% Construct OPC Read block:
blkPath = genslread(grp)

See Also

genslwrite

9-19

Downloaded from www.Manualslib.com manuals search engine

genslwrite

Purpose

Generate Simulink OPC Write block from MATLAB group object

Syntax

BlkPath = genslwrite(GrpObj)
BlkPath = genslwriteGrpObj, DestSys)

Description

BlkPath = genslwrite(GrpObj) generates an OPC Write block from

the dagroup object GrpObj, and places the block in a new Simulink
model. The generated OPC Write block has the same name, update
rate, and items as GrpObj. BlkPath indicates the full path to the new
OPC Write block.
BlkPath = genslwriteGrpObj, DestSys) generates the OPC Write
block and places it into the system defined by DestSys. DestSys must
be a model name or a path to a subsystem block. The OPC Write block
automatically takes a location that attempts to minimize overlap of
lines and blocks, however, the block might appear over an existing
annotation.

Examples

Create a group object with two items, and then construct an OPC Write
block from the group:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
% Set update rate to 2 seconds:
grp.UpdateRate = 2;
% Construct OPC Write block:
blkPath = genslwrite(grp)

See Also

genslread

9-20

Downloaded from www.Manualslib.com manuals search engine

get

Purpose

OPC Toolbox object properties

Syntax

Val = get(Obj,'PropName')
get(Obj)
Val = get(Obj)

Description

Val = get(Obj,'PropName') returns the value Val of the property

specified by PropName for the OPC Toolbox object Obj.

If PropName is a cell array of strings containing property names, get

returns a 1-by-N cell array of values, where N is the length of PropName.
If Obj is a vector of toolbox objects, Val is an M-by-N cell array of
property values where M is equal to the length of Obj and N is equal to
the number of properties requested.
get(Obj) displays all property names and their current values for the
toolbox object Obj.
Val = get(Obj) returns a structure, Val, where each field name is the
name of a property of Obj containing the value of that property. If Obj
is an array of toolbox objects, Val is an M-by-1 structure array.

Examples

Obtain the values of the Status and Group properties of an opcda

object, and then display all the properties of the object:
da = opcda('localhost','Dummy.Server');
get(da, {'Status','Group'})
out = get(da,'Status')
get(da)

See Also

opchelp | propinfo | set

9-21

Downloaded from www.Manualslib.com manuals search engine

getdata

Purpose

Logged records from OPC Toolbox engine to MATLAB workspace

Syntax

S = getdata(GObj)
S = getdata(GObj, NRec)
TSCell = getdata(GObj, 'timeseries')
TSCell = getdata(GObj, NRec, 'timeseries')
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj,
'DataType')
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, NRec,
'DataType')

Description

S = getdata(GObj) returns the number of records specified in the

RecordsToAcquire property of dagroup object GObj, from the OPC
Toolbox software engine. GObj must be a scalar dagroup object.
S is an NRec-by-1 structure array, where NRec is the number of records
returned. S contains the fields 'LocalEventTime' and 'Items'.
LocalEventTime is a date vector corresponding to the local event time
for that record. Items is an NItems-by-1 structure array containing the

fields shown below.

Field Name

Description

ItemID

The fully qualified tag name, as a string.

Value

The data value. The data type is defined by the items

DataType property.

Quality

The data quality, as a string. See Appendix A, OPC

Quality Strings for a description of quality strings.

TimeStamp

The time the value was changed, as a date vector.

S = getdata(GObj, NRec) retrieves the first NRec records from the

toolbox engine.
TSCell = getdata(GObj, 'timeseries') and
TSCell = getdata(GObj, NRec, 'timeseries') assign the data

received from the toolbox engine to a cell array of time series objects.
TSCell contains as many time series objects as there are items in the

9-22

Downloaded from www.Manualslib.com manuals search engine

getdata

group, with the name of each time series object set to the item ID. The
quality value stored in the time series object is offset from the quality
value returned by the OPC server by 128. The quality strings displayed
by each is the same. Because each record logged might not contain
information for every item, the time series objects have only as many
data points as there are records containing information about that
particular item ID.
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj,
'DataType') and
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, NRec,
'DataType') assign the data retrieved from the toolbox engine to
separate arrays. Valid data types are 'double', 'single', 'int8',
'int16', 'int32', 'uint8', 'uint16', 'uint32', 'logical',
'currency', 'date', and 'cell'.
ItmID is a 1-by-NItem cell array of item names.
Val is an NRec-by-NItem array of values with the data type specified. If
a data type of cell is specified, then Val is a cell array containing data
in the returned data type for each item. Otherwise, Val is a numeric

array of the specified data type.

Note 'DataType' must be set to 'cell' when retrieving records
containing strings or arrays of values.
Qual is an NRec-by-NItem array of quality strings for each value in Val.
TStamp is an NRec-by-NItem array of MATLAB date numbers
representing the time when the relevant value and quality were stored
on the OPC server.
ETime is an NRec-by-1 array of MATLAB date numbers, corresponding

to the local event time for each record.

Each record logged may not contain information for every item returned,
since data for that item may not have changed from the previous

9-23

Downloaded from www.Manualslib.com manuals search engine

getdata

update. When data is returned as a numeric matrix, the missing item

columns for that record are filled as follows.
Argument

Behavior for Missing Items

Val

The corresponding value entry is set to the previous

value of that item, or to NaN if there is no previous
value.

Qual

The corresponding quality entry is set to 'Repeat'.

TStamp

The corresponding time stamp entry is set to the first

valid time stamp for that record.

getdata is a blocking function that returns execution control to the

MATLAB workspace when one of the following conditions is met:

The requested number of records becomes available.
The logging operation is automatically stopped by the engine. If
fewer records are available than the number requested, a warning is
generated and all available records are returned.
You issue Ctrl+C. The logging task does not stop, and no data is
removed from the toolbox engine.
When getdata completes, the objects RecordsAvailable property is
reduced by the number of records returned by getdata.

Examples

Configure and start a logging task for 60 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'memory', 'RecordsToAcquire', 60);
start(grp);

9-24

Downloaded from www.Manualslib.com manuals search engine

getdata

Retrieve the first two records into a structure. This operation waits for
at least two records:
s = getdata(grp, 2)

Retrieve all the remaining data into a double array and plot it with a
legend:
[itmID, val, qual, tStamp] = getdata(grp, 'double');
plot(tStamp(:,1), val(:,1), tStamp(:,2), val(:,2));
legend(itmID);
datetick x keeplimits

See Also

flushdata | peekdata | start | stop

9-25

Downloaded from www.Manualslib.com manuals search engine

getnamespace

Purpose

OPC server name space

Syntax

S = getnamespace(DAObj)
S = getnamespace(DAObj, 'Filter1',Val1,'Filter2',Val2, ...)

Description

S = getnamespace(DAObj) returns the entire name space of the

server associated with the opcda object specified by DAObj. S is a

recursive structure array representing the name space of the server.

Each element of S is a node in the name space. S contains the fields
Name, FullyQualifiedID, NodeType, and Nodes. The Name field is a
descriptive name; FullyQualifiedID is the fully qualified ItemID of
that node; NodeType defines the node as a 'branch' node (containing
other nodes) or 'leaf' node (containing no other nodes); and Nodes is
a structure array with the same fields as S, representing the nodes
contained in this branch of the name space.
Use flatnamespace to flatten the hierarchical name space.
S = getnamespace(DAObj, 'Filter1',Val1,'Filter2',Val2, ...)

allows you to filter the retrieved name space based on a number of

available browse filters. Available filters are described in the following
table:
BrowseFilter

Description

'StartItemID'

Specify the FullyQualifiedID of a branch node,

as a string. Only nodes contained in that branch
node will be returned. Some OPC servers do not
support partial name space retrieval based on this
option: An error is generated if you attempt to use
the 'StartItemID' browse filter on such a server.

'Depth'

Specify the depth of the name space that you want

returned. A 'Depth' value of 1 returns only the
nodes contained in the starting position. A 'Depth'
value of 2 returns the nodes contained in the
starting position and all of their nodes. A 'Depth'
value of Inf returns all nodes. When combined
with the 'StartItemID' filter, the 'Depth' filter

9-26

Downloaded from www.Manualslib.com manuals search engine

getnamespace

BrowseFilter

Description
provides a useful way to investigate a name server
hierarchy one layer at a time.

'AccessRights' Restricts the search to leaf nodes with particular

access right characteristics. Specify 'read' to

return nodes that include the read access right,

and 'write' to return nodes that include the write
access right. An empty string ('') returns nodes
with any access rights. Note that branch nodes
will still be returned in the name space, in order
to contain the leaf nodes that have the requested
access rights.
'DataType'

Examples

Restricts the search to nodes with a particular

canonical data type. Valid data types are 'double',
'single', 'int8', 'int16', 'int32', 'uint8',
'uint16', 'uint32', 'logical', 'currency', and
'date'. Use the 'DataType' filter to find server
items with a specific data type, such as 'double'
or 'date'. Note that branch nodes will still be
returned in the name space, in order to contain the
leaf nodes that have the required data type.

Get the entire name space for the Matrikon Simulation Server on the
local host:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
nsFull = getnamespace(da)

Get only the first level of the name space:

nsPart = getnamespace(da, 'Depth', 1)

Add the nodes contained in the first branch of the name space to the
existing structure:

9-27

Downloaded from www.Manualslib.com manuals search engine

getnamespace

nsPart(1).Nodes = getnamespace(da, ...

'StartItemID', nsPart(1).Name, ...
'Depth', 1);

See Also

additem | flatnamespace | serveritems

9-28

Downloaded from www.Manualslib.com manuals search engine

isvalid

Purpose

True for undeleted OPC Toolbox objects

Syntax

A = isvalid(Obj)

Description

A = isvalid(Obj) returns a logical array, A, that contains false where

the elements of Obj are deleted OPC Toolbox objects and true where
the elements of Obj are valid objects.

Use the clear command to clear an invalid toolbox object from the
workspace.

Examples

Create two valid OPC data access objects, and then delete one to make
it invalid:
da(1) = opcda('localhost','Dummy.ServerA');
da(2) = opcda('localhost','Dummy.ServerB');
out1 = isvalid(da)
% Delete the first object and show it is invalid:
delete(da(1))
out2 = isvalid(da)
% Delete the second object and clear the object array:
clear da

See Also

delete | opchelp

9-29

Downloaded from www.Manualslib.com manuals search engine

load

Purpose

Load OPC Toolbox objects from MAT-file

Syntax

load FileName
load FileName Obj1 Obj2 ...
S = load('FileName','Obj1','Obj2',...)

Description

load FileName returns all variables from the MAT-file FileName into

the MATLAB workspace.

load FileName Obj1 Obj2 ... returns the specified OPC Toolbox
objects, Obj1, Obj2, ... from the MAT-file FileName into the MATLAB

workspace.
S = load('FileName','Obj1','Obj2',...) returns the structure S
with the specified toolbox objects Obj1, Obj2, ... from the MAT-file
FileName, instead of directly loading the toolbox objects into the
workspace. The field names in S match the names of the retrieved
toolbox objects. If you specify no objects, load returns all variables

from the MAT-file.

When you load an object, its read-only properties initially take their
default values. For example, the Status property value of an opcda
object is 'disconnected'. Use propinfo to determine if a property
is read-only.

Examples

Assume the example on the save reference page saved the group object
grp in the file mygroup. Load the group object from mygroup, and create
a reference to the parent client:
load mygroup
da = grp.Parent;

See Also

opchelp | propinfo | save

9-30

Downloaded from www.Manualslib.com manuals search engine

makepublic

Purpose

Convert private group into public group

Syntax

makepublic(GObj)

Description

makepublic(GObj) makes the dagroup object GObj public. Public

groups allow you to share data configuration information across
multiple OPC clients. Use the GroupType property to check whether a
group is public.

Public groups on a server cannot have the same name. If you attempt to
call makepublic on a private group with the same name as an existing
public group, you get an error.
After you make a group public, you cannot add items to that group or
delete items from that group. You must ensure that a group contains
the required items before making the group public.
Not all OPC data access servers support public groups. If you try to
make a public group on a server that does not support public groups,
you get an error. To verify that a server supports public groups, use the
opcserverinfo function on the client connected to that server: Look for
an entry 'IOPCPublicGroups' in the 'SupportedInterfaces' field.
Use the clonegroup function to create a private group from a public
group.

Examples

Create a group on a local server and make the group public:

da = opcda('localhost', 'Dummy.Server');
connect(da);
grp = addgroup(da, 'MakepublicEx');
itm1 = additem(grp, 'Device1.Item1');
itm2 = additem(grp, 'Device1.Item2');
makepublic(grp);

See Also

clonegroup | opcserverinfo

9-31

Downloaded from www.Manualslib.com manuals search engine

obj2mfile

Purpose

Convert OPC Toolbox object to MATLAB code

Syntax

obj2mfile(DAObj,'FileName')
obj2mfile(DAObj,'FileName','Syntax')
obj2mfile(DAObj,'FileName','Mode')
obj2mfile(DAObj,'FileName','Syntax','Mode')

Description

obj2mfile(DAObj,'FileName') converts the opcda object DAObj to the

equivalent MATLAB code using the set syntax and saves the MATLAB
code to a file specified by FileName. If an extension is not specified, the
.m extension is used. Only those properties that are not set to their
default values are written to FileName.
obj2mfile(DAObj,'FileName','Syntax') converts the OPC Toolbox
object to the equivalent MATLAB code using the specified 'Syntax' and
saves the code to the file, FileName. 'Syntax' can be either 'set' or
'dot'. By default, 'set' is used.
obj2mfile(DAObj,'FileName','Mode') and
obj2mfile(DAObj,'FileName','Syntax','Mode') save the equivalent
MATLAB code for all properties if 'Mode' is 'all', and save only
the properties that are not set to their default values if 'Mode' is
'modified'. By default, 'modified' is used.

If DAObjs UserData is not empty or if any of the callback properties are

set to a cell array of values or to a function handle, the data stored
in those properties is written to a MAT-file when the toolbox object
is converted and saved. The MAT-file has the same name as the file
containing the toolbox object code, but with a different extension.
The values of read-only properties will not be restored. For example,
if an object is saved with a Status property value of 'connected', the
object will be recreated with a Status property value of 'disconnected'
(the default value). You can use propinfo to determine if a property
is read-only.
To recreate DAObj, type the name of the file that you previously created
with obj2mfile.

9-32

Downloaded from www.Manualslib.com manuals search engine

obj2mfile

Examples

Create a client with a group and an item, then save that client to disk:
da = opcda('localhost','Dummy.Server');
set(da, 'Tag', 'myopcTag','Timeout',300);
grp = addgroup(da, 'TestGroup');
itm = additem(grp, 'Dummy.Tag1');
obj2mfile(da, 'myopc.m','dot','all');

Recreate the client under a different name:

copyOfDA = myopc;

See Also

opchelp | propinfo

9-33

Downloaded from www.Manualslib.com manuals search engine

opccallback

Purpose

Event information for OPC Toolbox callbacks

Syntax

opccallback(Obj,Event)

Description

opccallback(Obj,Event) displays a message in the MATLAB

Command Window that contains information about an OPC Toolbox
event. The message includes the type of event, the time the event
occurred, and the related data for that event.
Obj is the object associated with the event. Event is a structure that
contains the Type and Data fields. Type is the event type. Data is a

structure containing event-specific information.

opccallback is an example callback function. Use this callback function

as a template for writing your own callback function. By default,

@opccallback is the value for the ReadAsyncFcn, WriteAsyncFcn, and
CancelAsyncFcn properties of a dagroup object, and for the ErrorFcn
and ShutDownFcn properties of an opcda object.

See Also

showopcevents

9-34

Downloaded from www.Manualslib.com manuals search engine

opcda

Purpose

Construct OPC data access object

Syntax

Obj = opcda('Host','ServerID')
Obj = opcda('Host','ServerID','P1',V1,'P2',V2,...)

Description

Obj = opcda('Host','ServerID') constructs an OPC data access

(opcda) object, Obj, for the host specified by Host and the OPC server
ID specified by ServerID. When you construct Obj, its initial Status
property value is 'disconnected'. To communicate with the server,
you must connect Obj to the server with the connect function.
Obj = opcda('Host','ServerID','P1',V1,'P2',V2,...) constructs
an OPC data access object, Obj, for the host specified by Host and the
OPC server ID specified by ServerID, applying the specified property

values. If you specify an invalid property name or value, the function

does not create an object.
Note that the property name/property value pairs can be any format
that the set function supports, i.e., parameter-value string pairs,
structures, and parameter-value cell array pairs.
At any time, you can view a complete listing of OPC Toolbox functions
and properties with the opchelp function.

Examples

Create an opcda client for a local server:

daObj1 = opcda('localhost', 'Dummy.Server.ID');

Create an opcda client for a remote server:

daObj2 = opcda('ServerHost1', 'OPCServer.ID');

See Also

connect | opchelp | set

9-35

Downloaded from www.Manualslib.com manuals search engine

opcfind

Purpose

Find OPC Toolbox objects with specific properties

Syntax

Out = opcfind
Out = opcfind('P1',V1,'P2',V2,...)
Out = opcfind(S)

Description

Out = opcfind returns a cell array, Out, of all existing OPC Toolbox

objects.
returns a cell array, Out, of
toolbox objects whose property values match those passed as property
name/property value pairs, P1, V1, P2, V2, etc.

Out = opcfind('P1',V1,'P2',V2,...)

Out = opcfind(S) returns a cell array, Out, of toolbox objects whose

property values match those defined in structure S. The field names of S
are object property names and the field values of S are the requested

property values.

Examples

Create some OPC Toolbox objects:

da1 = opcda('localhost','Dummy.ServerA');
da2 = opcda('localhost','Dummy.ServerB');
set(da1, 'Tag','myopcTag', 'Timeout',300);
grp = addgroup(da2, 'TestGroup');
itm = additem(grp, {'Dummy.Tag1', 'Dummy.Tag2'});

Find all OPC Toolbox objects:

allObjCell = opcfind;

Find all objects with the Tag 'myopcTag':

myOPC = opcfind('Tag', 'myopcTag')

9-36

Downloaded from www.Manualslib.com manuals search engine

opcfind

Find all daitem objects:

itmCell = opcfind('Type', 'daitem')

See Also

delete

9-37

Downloaded from www.Manualslib.com manuals search engine

opchelp

Purpose

Help for OPC Toolbox function or property

Syntax

opchelp
opchelp('Name')
Out = opchelp('Name')
opchelp(Obj)
opchelp(Obj,'Name')
Out = opchelp(Obj,'Name')

Description

opchelp displays a complete listing of OPC Toolbox software functions

with a brief description of each function.
opchelp('Name') displays online help for the function or property,
Name. If Name is an OPC Toolbox class, a complete listing of the functions

and properties for that class is displayed with a brief description of

each. The online help for the object constructor for that class is also
displayed. If Name is an OPC Toolbox class with the .m extension, then
only the online help for the object constructor is displayed.
You can display object-specific function information by specifying Name
to be object/function. For example, to display the online help for the
data access objects connect function, Name would be 'opcda/connect'.
You can display object-specific property information by specifying Name
to be object.property. For example, to display the online help for the
data access objects Status property, Name would be 'opcda.Status'.
Out = opchelp('Name') returns the help text to the string Out.
opchelp(Obj) displays a complete listing of functions and properties
for the OPC Toolbox object Obj, along with the online help for the

objects constructor.
opchelp(Obj,'Name') displays the help for function or property, Name,
for the toolbox object Obj.
Out = opchelp(Obj,'Name') returns the help text to the string Out.

When displaying property help in the command window, the names in

the See also section that contain all uppercase letters are function

9-38

Downloaded from www.Manualslib.com manuals search engine

opchelp

names. The names that contain a mixture of uppercase and lowercase

letters are property names.
When displaying function help, the See also section contains only
function names.

Examples

Display all OPC Toolbox functions and a brief description of each

function:
opchelp

Display help on the opcda constructor:

daHelp = opchelp('opcda')

Display help on the OPC Toolbox set function:

opchelp set

Display help on the opcda objects disconnect function:

opchelp opcda/disconnect

Create an opcda object and queries help information on that object. The
objects Timeout and Status properties are also queried.
da = opcda('localhost','Matrikon.OPC.Simulation');
opchelp(da)
timeoutHelp = opchelp(da,'Timeout');
opchelp(da,'Status');

See Also

propinfo

9-39

Downloaded from www.Manualslib.com manuals search engine

opcqid

Purpose

Construct quality ID from items quality string

Syntax

QualityID = opcqid(QualityStr)

Description

QualityID = opcqid(QualityStr) returns the quality ID, which is

a number between 0 and 255, corresponding to the specified quality

string. The quality string must be in the form 'Major Quality:
Quality Sub-status (Limit Status)'.
If QualityStr is a cell array of quality strings, QualityID will be a
matrix having the same size as QualityStr.
For more information on quality values, see Appendix A, OPC Quality
Strings.

Examples

Construct the quality ID from the quality string of the item

Random.Real8 on the Matrikon OPC Simulation Server:
da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da)
grp = addgroup(da);
itm = additem(grp, 'Random.Real8');
qualityID = opcqid(itm.Quality)

See Also

get | opcqstr

9-40

Downloaded from www.Manualslib.com manuals search engine

opcqparts

Purpose

Extract quality parts from OPC quality ID

Syntax

[MajorQual, Substatus, Limit, Vendor] = opcqparts(QualityID)

Description

[MajorQual, Substatus, Limit, Vendor] =

opcqparts(QualityID) extracts the major quality, the quality

substatus, the limit status, and the vendor-specific quality information

fields, given the daitem object QualityID property value.
The QualityID is a double value ranging from 0 to 65535, made
up of four parts. The high 8 bits of the QualityID represent the
vendor-specific quality information. The low 8 bits are arranged as
QQSSSSLL, where QQ represents the major quality, SSSS represents the
quality substatus, and LL represents the limit status.
For more information on quality values, see Appendix A, OPC Quality
Strings.

Examples

Extract the major quality, substatus, and limit status of the item
Random.Qualities on the Matrikon OPC Simulation Server:
da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da)
grp = addgroup(da);
itm = additem(grp, 'Random.Qualities');
[quality, substatus, limit] = opcqparts(itm.QualityID)

See Also

get | opcqstr

9-41

Downloaded from www.Manualslib.com manuals search engine

opcqstr

Purpose

Convert OPC quality ID into readable string

Syntax

QualityStr = opcqstr(QualityID)

Description

QualityStr = opcqstr(QualityID) constructs a quality string from a

quality ID, stored in the QualityID property of a daitem object. The
string is of the form 'Major Quality: Quality Substatus: Limit
Status'. The Limit Status part is omitted if the limit status is set
to Not Limited. For information on each of the quality parts, see
opcqparts.

If QualityID is specified as a vector or matrix of quality IDs, then

QualityStr will be a cell array having the same size as QualityID.
For more information on quality values, see Appendix A, OPC Quality
Strings.

Examples

Construct the quality string from the quality ID of the item

Random.Qualities on a Matrikon OPC Simulation Server:
da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da)
grp = addgroup(da);
itm = additem(grp, 'Random.Qualities');
qualitystr = opcqstr(itm.QualityID)

See Also

get | opcqid | opcqparts

9-42

Downloaded from www.Manualslib.com manuals search engine

opcread

Purpose

Read logged records from disk to MATLAB workspace

Syntax

S = OPCREAD('LogFileName')
S =
opcread('LogFileName','PropertyName','PropertyValue',...)
TSCell = opcread('LogFileName', 'DataType', 'timeseries')
[I,V,Q,TS,ET] = opcread('LogFileName',
'DataType', DType,...)

Description

S = OPCREAD('LogFileName') returns all available records from the

OPC log file named LogFileName. If no extension is specified as part of
LogFileName, then .olf is used.
S is an NRec-by-1 structure array, where NRec is the number of records
returned. S contains the fields 'LocalEventTime' and 'Items'.
LocalEventTime is a date vector corresponding to the local event time
for that record. Items is an NItems-by-1 structure array containing
the fields show below.

Field Name

Description

ItemID

The fully qualified item ID, as a string.

Value

The data value. The data type is dependent on the

original Items DataType property.

Quality

The data quality, as a string.

TimeStamp

The time the value was changed, as a date vector.

S =
opcread('LogFileName','PropertyName','PropertyValue',...)

limits the data read from the specified OPC log file based on the
properties and values provided. Valid property names and property
values are defined in the table below.

9-43

Downloaded from www.Manualslib.com manuals search engine

opcread

Property
Name

Property Value

'Records'

Specify the required records as [startRec endRec].

If no records fall within those bounds, opcread
returns empty outputs.

'Dates'

Specify the date range for records as [startDt

endDt]. The dates must be in MATLAB date
number format. If no records fall within those
bounds, opcread returns empty outputs.

'ItemIDs'

Specify the required item IDs as a string or cell

array of strings. If no records match the required
ItemIDs, OPCREAD returns empty outputs.

TSCell = opcread('LogFileName', 'DataType', 'timeseries')

assigns the data received from the OPC log file to a cell array of time
series objects. TSCell contains as many time series objects as there
are items in the group, with the name of each time series object set to
the item ID. The quality value stored in the time series object is offset
from the quality value returned by the OPC server by 128. The quality
strings displayed by each is the same. Because each record logged might
not contain information for every item, the time series objects have
only as many data points as there are records containing information
about that particular item ID.
[I,V,Q,TS,ET] = opcread('LogFileName', 'DataType',
DType,...) assigns the data retrieved from the OPC log file to
separate arrays. Valid data types for DType are 'double', 'single',
'int8', 'int16', 'int32', 'uint8', 'uint16', 'uint32', 'logical',
'currency', 'date', and 'cell'.
I is a 1-by-NItem cell array of item names.
V is an NRec-by-NItem array of values with the data type specified. If
a data type of 'cell' is specified, V is a cell array containing data in
the returned data type for each item. Otherwise, V is a numeric array
of the specified data type.

9-44

Downloaded from www.Manualslib.com manuals search engine

opcread

Note DType must be set to 'cell' when retrieving records containing

strings or arrays of values.
Q is an NRec-by-NItem array of quality strings for each value in V.
TS is an NRec-by-NItem array of MATLAB date numbers representing

the time when the relevant value and quality were stored on the OPC
server.
ET is an NRec-by-1 array of MATLAB date numbers, corresponding to

the local event time for each record.

Each record logged may not contain information for every item returned,
since data for that item may not have changed from the previous
update. When data is returned as a numeric matrix, the missing item
columns for that record are filled as follows.

Examples

The corresponding value entry is set to the previous value

of that item, or to NaN if there is no previous value.

The corresponding quality entry is set to 'Repeat'.

TS

The corresponding time stamp entry is set to the first valid

time stamp for that record.

Configure and start a logging task. Wait for the task to complete:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'disk', 'RecordsToAcquire', 30);
set(grp, 'LogFileName', 'ExOPCREAD.olf');
start(grp);
wait(grp);

9-45

Downloaded from www.Manualslib.com manuals search engine

opcread

Retrieve the first two records into a structure:

s = opcread('ExOPCREAD.olf', 'Records', [1, 2]);

Retrieve all the data and plot it with a legend:

[itmID, val, qual, tStamp] = opcread('ExOPCREAD.olf', ...
'DataType', 'double');
plot(tStamp(:,1),val(:,1), tStamp(:,2),val(:,2));
legend(itmID);
datetick x keeplimits

See Also

flushdata | getdata | peekdata | start | stop

9-46

Downloaded from www.Manualslib.com manuals search engine

opcregister

Purpose

Install and register OPC Foundation Core Components

Syntax

opcregister
opcregister('repair')
opcregister('remove')
opcregister(..., '-silent')

Description

opcregister installs the OPC Foundation Core Components so that

OPC Toolbox software is able to communicate with OPC servers.

opcregister('repair') repairs an existing OPC Foundation Core

Components installation. Use this option if you are experiencing

problems querying hosts with the opcserverinfo function.
opcregister('remove') removes all OPC Foundation Core Components

from your workstation. Use this option if you no longer wish to access
any servers using OPC.
opcregister(..., '-silent') runs the selected option without

prompting you for confirmation, and without showing any progress

dialog. Note that your machine might be restarted without prompting
you if you choose this option. If you are concerned about restarting your
machine, do not use the '-silent' option.
Note You must clear any OPC Toolbox objects that you have previously
created in this MATLAB session before you can run opcregister. If
you attempt to run opcregister and OPC Toolbox objects already exist,
an error is generated. Use opcreset to clear objects from the MATLAB
session.
OPC Foundation Core Components are redistributed under license from
the OPC Foundation, http://www.opcfoundation.org.

See Also

opcreset

9-47

Downloaded from www.Manualslib.com manuals search engine

opcreset

Purpose

Disconnect and delete all OPC Toolbox objects

Syntax

opcreset
opcreset -force

Description

opcreset disconnects and deletes all OPC Toolbox objects. This

command flushes any data stored in the buffer, cancels all asynchronous
operations, and closes any open log files.
You cannot reconnect a toolbox object to the server after you delete the
object. Therefore, you should remove these objects from the workspace
with the clear function.
Note that you cannot call opcreset if an opctool session is open, or
if Simulink models containing OPC Toolbox blocks are open. Close
all opctool sessions and all open Simulink models containing OPC
Toolbox blocks before calling opcreset.
opcreset -force closes all open opctool sessions and all Simulink
models containing OPC Toolbox blocks, without prompting to save
those sessions and models. If you use the -force option, you lose any
unsaved changes to those sessions and models. Use the -force option
only as a last resort.

Examples

Create an opcda object, and add a group to that object. Then delete
the OPC Toolbox objects using opcreset, and clear all variables from
the workspace.
da = opcda('localhost','Dummy.Server');
grp = addgroup(da);
opcreset; % Deletes all objects
% Clear the variables
clear da grp
opcfind

See Also

clear | delete | opcfind | opctool

9-48

Downloaded from www.Manualslib.com manuals search engine

opcserverinfo

Purpose

Version, server, and status information

Syntax

Out = opcserverinfo
Out = opcserverinfo('Host')
Out = opcserverinfo(DAObj)

Description

Out = opcserverinfo returns a structure, Out, that contains

information about OPC Toolbox and MATLAB software, including

product version numbers.
Out = opcserverinfo('Host') returns a structure, Out, that contains

OPC server information associated with the host name or IP address

specified by Host. The information includes the ServerID you can use
to create a client associated with that server, and other information
about each server.
Out = opcserverinfo(DAObj) returns a structure, Out, that contains
about the server associated with the opcda object DAObj.

information
DAObj must
information
information

Examples

be a scalar, and must be connected to the server. The

includes the current server status, as well as time
related to the server.

Retrieve information about servers installed on the local machine:

opcserverinfo('localhost')

Retrieve information about the Matrikon Simulation Server installed

on the local host:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
matrikonInfo = opcserverinfo(da)

See Also

connect | opcda

9-49

Downloaded from www.Manualslib.com manuals search engine

opcstruct2array

Purpose

Convert OPC data from structure to array format

Syntax

[ItmID,Val,Qual,TStamp,EvtTime] = opcstruct2array(S)
[ItmID,Val,Qual,TStamp,EvtTime] = opcstruct2array(S,
'DataType')

Description

[ItmID,Val,Qual,TStamp,EvtTime] = opcstruct2array(S) converts

the OPC data structure S into separate arrays for the item ID, value,
quality, time stamp, and event time. S must be a structure as returned
by the getdata and opcread functions. S must contain the fields
LocalEventTime and Items. The Items field of S must contain the fields
ItemID, Value, Quality, and TimeStamp.
ItmID is a 1-by-nItm cell array containing the item IDs of all unique
items found in the ItemID field of the Items structures in S.
Val is an nRec-by-nItm array of doubles containing the value of each
item in ItmID, at each time specified by TStamp.
Qual is an nRec-by-nItm cell array of strings containing the quality
of each value in Val.
TStamp is an nRec-by-nItm array of doubles containing the time stamp
for each value in Val.
EvtTime is nRec-by-1 array of doubles containing the local time each
data change event occurred.

Each row of Val represents data from one record received by OPC
Toolbox software at the corresponding entry in EvtTime, while each
column of Val represents the time series for the corresponding item
ID in ItmID.
[ItmID,Val,Qual,TStamp,EvtTime] = opcstruct2array(S,'DataType')

uses the data type specified by the string 'DataType' for the value
array. Valid data types are 'double', 'single', 'int8', 'int16',
'int32', 'uint8', 'uint16', 'uint32', 'logical', 'currency',
'date', and 'cell'.

9-50

Downloaded from www.Manualslib.com manuals search engine

opcstruct2array

Examples

Configure and start a logging task for 30 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'memory', 'UpdateRate', 0.5, ...
'RecordsToAcquire', 60);
start(grp);
wait(grp);

Retrieve the records into a structure:

s = getdata(grp);

Convert the structure into a double array and plot it with a legend:
[itmID, val, qual, tStamp] = opcstruct2array(s, 'double');
plot(tStamp(:,1), val(:,1), tStamp(:,2), val(:,2));
legend(itmID);
datetick x keeplimits

See Also

getdata | opcread

9-51

Downloaded from www.Manualslib.com manuals search engine

opcstruct2timeseries

Purpose

Convert OPC data from structure to time series format

Syntax

TS = opcstruct2timeseries(S)

Description

TS = opcstruct2timeseries(S) converts the OPC data structure S

into a cell array of time series objects. S must be a structure in the
format that the getdata and opcread functions return. S must contain
the fields LocalEventTime and Items. The Items field of S must contain
the fields ItemID, Value, Quality, and TimeStamp.

The cell array TS contains as many time series objects as there are
unique item IDs in the data structure, with the name of each time
series object indicating the item ID. The time series object contains the
quality, although this value is offset by 128 from the quality value that
the OPC server returns. However, the quality strings are the same.
Because each logged record might not contain information for every
item, the time series objects have only as many data points as there are
records containing information about that particular item ID.

Examples

Configure and start a logging task for 30 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'memory', 'UpdateRate', 0.5, ...
'RecordsToAcquire', 60);
start(grp);
wait(grp);

Retrieve the records into a structure:

s = getdata(grp);

Convert the structure into time series objects and plot each separately:
ts = opcstruct2timeseries(s);

9-52

Downloaded from www.Manualslib.com manuals search engine

opcstruct2timeseries

subplot(2,1,1); plot(ts{1});
subplot(2,1,2); plot(ts{2});

See Also

getdata | opcread | opcstruct2array | timeseries

9-53

Downloaded from www.Manualslib.com manuals search engine

opcsupport

Purpose

Run OPC Toolbox troubleshooting utility

Syntax

opcsupport
opcsupport('HostName')
opcsupport('HostName','FileName')

Description

opcsupport returns diagnostic information for all OPC servers

installed on the local machine, and saves the output to the text file
opcsupport.txt in the current directory.
opcsupport('HostName') returns diagnostic information for the OPC
servers installed on the host named HostName, and saves the output to
the text file opcsupport.txt in the current directory.
opcsupport('HostName','FileName') returns diagnostic information
for the host named HostName, and saves the results to the text file
FileName in the current directory.

Examples

Get diagnostic information for OPC servers on the local machine and
save the information to file opcsupport.txt:
opcsupport

Get diagnostic information for OPC servers on the host named area1
and save the information to file opcsupport.txt:
opcsupport('area1')

Get diagnostic information for OPC servers on the host named area1
and save the information to file myfile.txt:
opcsupport('area1','myfile.txt')

See Also

opcda | opcserverinfo

9-54

Downloaded from www.Manualslib.com manuals search engine

opctool

Purpose

Open OPC Tool GUI

Syntax

opctool
opctool(SessionName)

Description

opctool opens the OPC Tool graphical user interface (GUI). The OPC

Tool GUI allows you to graphically browse the contents of an OPC

server, view server item properties, and create and configure OPC
Toolbox clients, groups and items. With OPC Tool you can also read
and write OPC data, configure and start a logging session, and export
logged data to the workspace.
If you use OPC Tool to configure clients, groups, and items, you can
export these to the workspace, a MAT-file, or an OPC Session File that
you can import into the GUI later.
opctool(SessionName) opens the OPC Tool GUI and loads a previously
saved OPC Session File, SessionName. If you do not specify a file
extension as part of SessionName, .osf is the default.

See Also

openosf

9-55

Downloaded from www.Manualslib.com manuals search engine

openosf

Purpose

Open OPC Tool GUI session file

Syntax

openosf('Name.osf')

Description

openosf('Name.osf') opens the OPC Tool GUI and loads the session
from the session file Name.osf. Specifying the .osf extension is
optional. Name.osf must exist on the MATLAB path, or you must

specify the full path to the file.

This function facilitates opening .osf files from the file browser window.

See Also

opctool | open

9-56

Downloaded from www.Manualslib.com manuals search engine

peekdata

Purpose

Preview most recently acquired data

Syntax

S = peekdata(GObj, NRec)

Description

S = peekdata(GObj, NRec) returns the NRec most recently acquired

records for the dagroup object, GObj, without removing those records
from the OPC Toolbox software engine. GObj must be a scalar dagroup
object. S is a structure array containing data for each record, in the
same format as the structure returned by getdata.

If NRec is greater than the number of records currently available, a

warning will be generated and all available records will be returned.
You use peekdata when you want to return logged data but you
do not want to remove the data from the buffer. The objects
RecordsAvailable property value will not be affected by the number
of samples returned by peekdata.
peekdata is a non-blocking function that immediately returns records
and execution control to the MATLAB workspace.

Examples

Configure and start a logging task for 60 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'memory');
set(grp, 'RecordsToAcquire', 60);
start(grp);

Wait for 2 seconds and peek at the two most recent records:
pause(2);
s = peekdata(grp, 2)
s.Items(1).Value

9-57

Downloaded from www.Manualslib.com manuals search engine

peekdata

See Also

flushdata | getdata | start | stop

9-58

Downloaded from www.Manualslib.com manuals search engine

propinfo

Purpose

Property information for OPC Toolbox objects

Syntax

Out = propinfo(Obj)
Out = propinfo(Obj,'PropName')

Description

Out = propinfo(Obj) returns a structure array, Out, with field names

given by the property names for Obj. Each property name in Out
contains a structure with the fields shown below.

Field Name

Description

Type

Data type of the property. Possible values are

any', 'callback', 'double', and 'string'.

Constraint

Type of constraint on the property value. Possible

values are 'bounded, 'callback', 'enum', and
'none'.

ConstraintValue List of valid string values or a range of valid values

DefaultValue

Default value for the property

ReadOnly

Condition under which a property is read-only:

'always' Property cannot be configured.
'whileConnected' Property cannot be
configured while Status is set to 'connected'.
'whileLogging' Property cannot be
configured while Logging is set to 'on'.
'never' Property can be configured at any
time.

Out = propinfo(Obj,'PropName') returns a structure array, Out,

for the property specified by PropName. If PropName is a cell array of

strings, a cell array of structures is returned for each property.

9-59

Downloaded from www.Manualslib.com manuals search engine

propinfo

Examples

See Also

da = opcda('localhost','Dummy.Server');
allInfo = propinfo(da)
serverIDInfo = propinfo(da,'ServerID')
opchelp

9-60

Downloaded from www.Manualslib.com manuals search engine

read

Purpose

Read data synchronously from OPC groups or items

Syntax

S
S
S
S

Description

S = read(GObj) and S = read(Iobj) read data for all the items

contained in the dagroup object, GObj, or for the vector of daitem
objects, IObj. The data is read from the OPC servers cache. S is a

=
=
=
=

read(GObj)
read(Iobj)
read(GObj,'Source')
read(IObj,'Source')

structure array containing data for each item in the following fields:
Field
Name

Description

Type

ItemID

Fully qualified item name

string

Value

Value

double,
string

Quality

Quality of the value

string

TimeStamp

The time that the value and quality

was obtained by the device (if this
is available), or the time the server
updated or validated the value and
quality in its cache

Date vector

Error

Error message

string

You can synchronously read from the cache only if the Active property
is set to 'on' for both the item and the group that contains the item.
A warning is issued if any of the objects passed to read are inactive.
An inactive item is still returned in S, but the Quality is set to 'BAD:
Out of Service'.
S = read(GObj,'Source') and S = read(IObj,'Source') read data
from the source specified by 'Source'. 'Source' can be 'cache' or
'device'. If 'Source' is 'device', data is returned directly from the
device. If 'Source' is 'cache', data is returned from the OPC servers

9-61

Downloaded from www.Manualslib.com manuals search engine

read

cache, which contains a copy of the device data. Note that the Active
property is ignored when reading from 'device'. Note also, that
reading data from the device can be slow.
When a read operation succeeds, the Value, Quality, and Timestamp
properties of the associated items are updated to reflect the values
obtained from the read operation.

Examples

Configure a client and a group and item, for the Matrikon Simulation
Server. Set the update rate for this group to prevent frequent cache
updates:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExRead');
set(grp, 'UpdateRate', 20);
itm = additem(grp, 'Random.Real8');

Read twice from the cache, noting that the values are the same each
time:
v1 = read(grp)
v2 = read(grp)

Now read twice from the device, noting that the value updates each
time:
v3 = read(grp, 'device')
v4 = read(grp, 'device')

See Also

readasync | refresh | write | writeasync

9-62

Downloaded from www.Manualslib.com manuals search engine

readasync

Purpose

Read data asynchronously from group or items

Syntax

TransID = readasync(GObj)
TransID = readasync(IObj)

Description

TransID = readasync(GObj) and TransID = readasync(IObj)

asynchronously read data for all the items contained in the dagroup
object, GObj, or for the vector of daitem objects specified by IObj.
TransID is a unique transaction ID for the asynchronous request.

For asynchronous reads, data is always read from the device, not from
the server cache. The Active property is ignored for asynchronous
reads.
When the read operation completes, a read async event is generated by
the server. If a callback function file is specified for the ReadAsyncFcn
property, that function executes when the event is generated.
You can cancel an in-progress asynchronous request using cancelasync.
When a readasync operation succeeds, the Value, Quality, and
Timestamp properties of the associated items are updated to reflect the
values obtained from the read operation.

Examples

Configure a client, group, and item, for the Matrikon Simulation Server:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExReadAsync');
set(grp, 'UpdateRate', 20);
itm = additem(grp, 'Random.Real8');

Perform two asynchronous read operations:

tid1 = readasync(grp)
tid2 = readasync(grp, 'device')

9-63

Downloaded from www.Manualslib.com manuals search engine

readasync

Examine the event log:

pause(2)
disp('Event log:')
showopcevents(da)

See Also

cancelasync | read | refresh | write | writeasync

9-64

Downloaded from www.Manualslib.com manuals search engine

refresh

Purpose

Read all active items in group

Syntax

refresh(GObj)
refresh(GObj,'Source')

Description

refresh(GObj) asynchronously reads data for all active items contained

in the dagroup object specified by GObj. Items whose Active property is
set to 'off' will not be read. GObj can be an array of group objects. The
data is read from the OPC servers cache. You can use refresh only if
the Active property is set to 'on' for GObj.

When the refresh operation completes, a DataChange event is

generated by the server. If a callback function file is specified for the
DataChangeFcn property, then the function executes when the event is
generated.
refresh is a special case of subscription that forces a DataChange event
for all active items even if the data has not changed. Note that refresh
ignores the Subscription property.
refresh(GObj,'Source') asynchronously reads data from the source
specified by 'Source', which can be 'cache' or 'device'. If 'Source'
is 'device', data is returned directly from the device. If 'Source'
is 'cache', data is returned from the OPC servers cache. Note that

reading data from the device can be slow.

Examples

Configure a client, group, and item, for the Matrikon Simulation Server:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExRefresh');
itm = additem(grp, 'Random.Real8');

Turn off subscription for the group and add a DataChangeFcn callback:
set(grp, 'Subscription', 'off');
set(grp, 'DataChangeFcn', 'disp(grp.Item)')

9-65

Downloaded from www.Manualslib.com manuals search engine

refresh

Call refresh to get group and item updates:

refresh(grp)
refresh(grp)

See Also

read | readasync | write | writeasync

9-66

Downloaded from www.Manualslib.com manuals search engine

removepublicgroup

Purpose

Remove public group from server

Syntax

removepublicgroup(DAObj,'PublicGroupName')

Description

removepublicgroup(DAObj,'PublicGroupName') removes the public

group PublicGroupName from the server that DAObj is connected to.
DAObj must be a connected opcda object.

If the public group has clients using that group, removepublicgroup

issues a warning; then it removes the group from the server only when
all clients have stopped using that group. No additional clients can
connect to that group after you call removepublicgroup.
Not all OPC data access servers support public groups. If you try to
make a public group on a server that does not support public groups,
you get an error. To verify that a server supports public groups, use the
opcserverinfo function on the client connected to that server: Look for
an entry 'IOPCPublicGroups' in the 'SupportedInterfaces' field.

Examples

Connect to the server Dummy.Server and remove the public group

named PGroup:
da = opcda('localhost', 'Dummy.Server');
connect(da);
removepublicgroup(da, 'PGroup');

See Also

addgroup | makepublic

9-67

Downloaded from www.Manualslib.com manuals search engine

save

Purpose

Save OPC Toolbox objects to MAT-file

Syntax

save FileName
save FileName Obj1 Obj2 ...

Description

save FileName saves all variables in the MATLAB workspace to

the specified MAT-file, FileName. If an extension is not specified for
FileName, then a .MAT extension is used.
save FileName Obj1 Obj2 ... saves OPC Toolbox objects, Obj1,
Obj2, ... to the specified MAT-file, FileName. If an extension is not
specified for FileName, then a .MAT extension is used.
save can be used in the functional form as well as the command form
shown above. When using the functional form, you must specify the file
name and toolbox objects as strings.

Any data associated with the toolbox object will not be stored in the
MAT-file. The data can be brought into the MATLAB workspace with
getdata and then saved to the MAT-file using a separate variable name.
The load command is used to return variables from the MAT-file to the
MATLAB workspace. Values for read-only properties will be restored to
their default values upon loading. For example, the Status property for
an opcda object will be restored to 'disconnected'. You use propinfo
to determine if a property is read-only.

Examples

Create a connected client and configure a group with two items. Then
save the group.
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ClearEventLogEx');
itm1 = additem(grp, 'Random.Real8');
save mygroup grp

See Also

getdata | load | opchelp | propinfo

9-68

Downloaded from www.Manualslib.com manuals search engine

serveritemprops

Purpose

Property information for items in OPC server name space

Syntax

S = serveritemprops(DAObj,ItemID)
S = serveritemprops(DAObj,ItemID,PropID)

Description

S = serveritemprops(DAObj,ItemID) returns all property

information for the OPC server items specified by ItemID. ItemID is a
single, fully qualified ItemID, specified as a string. DAObj is an opcda
object connected to the OPC server. S is a structure array with the

following fields:
Field Name

Description

PropID

The property number

PropDescription

The property description

PropValue

The property value

The number of properties returned by the server may be different for

different ItemIDs.
Item properties include the items canonical data type, limits,
description, current value, etc.
S = serveritemprops(DAObj,ItemID,PropID) returns property
information for the property IDs contained in PropID. PropID is a vector
of integers. If PropID contains IDs that do not exist for that property, a

warning is issued and any remaining property information is returned.

Note This function is not intended to read large amounts of data.
Instead, it is intended to allow you to easily browse and read small
amounts of data specific to a particular ItemID.
For a complete list of Property IDs defined by the OPC Foundation,
consult Appendix B, OPC Server Item Properties.

9-69

Downloaded from www.Manualslib.com manuals search engine

serveritemprops

Examples

Find the properties of the Matrikon Simulation Server Random.Real4

tag:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
p = serveritemprops(da, 'Random.Real4');

Read the first property to see the items canonical data type:
p(1)

Read the third property to see the items quality:

p(3)

See Also

serveritems

9-70

Downloaded from www.Manualslib.com manuals search engine

serveritems

Purpose

Query server or name space for fully qualified item IDs

Syntax

FQID
FQID
FQID
...)
FQID
FQID

Description

= serveritems(DAObj,ItemID)
= serveritems(DAObj)
= serveritems(DAObj, 'Filter1',Val1,'Filter2',Val2,
= serveritems(NS)
= serveritems(NS,ItemID)

FQID = serveritems(DAObj,ItemID) returns a cell array of all fully

qualified item IDs matching ItemID that are found on the OPC server
defined by DAObj. DAObj must be a connected opcda object. ItemID is a
partial string to search for, and can contain the wildcard character '*'.
FQID is a string or cell array of strings. You can use FQID in a call to
additem to construct daitem objects.
FQID = serveritems(DAObj) returns all fully qualified item IDs on the
OPC server associated with DAObj.
FQID = serveritems(DAObj, 'Filter1',Val1,'Filter2',Val2,
...) allows you to filter the retrieved name space based on a number of

available browse filters. Available filters are described in the following

table:
Browse Filter

Description

'StartItemID'

Specify the FullyQualifiedID of a branch node,

as a string. Only nodes contained in that branch
node will be returned. Some OPC servers do not
support partial name space retrieval based on this
option: An error is generated if you attempt to use
the 'StartItemID' browse filter on such a server.

'Depth'

Specify the depth of the name space that you want

returned. A 'Depth' value of 1 returns only the
nodes contained in the starting position. A 'Depth'
value of 2 returns the nodes contained in the

9-71

Downloaded from www.Manualslib.com manuals search engine

serveritems

Browse Filter

Description
starting position and all of their nodes. A 'Depth'
value of Inf returns all nodes.

'AccessRights' Restricts the search to leaf nodes with particular

access right characteristics. Specify 'read' to

return nodes that include the read access right,

and 'write' to return nodes that include the write
access right. An empty string ('') returns nodes
with any access rights.
'DataType'

Restricts the search to nodes with a particular

canonical data type. Valid data types are 'double',
'single', 'int8', 'int16', 'int32', 'uint8',
'uint16', 'uint32', 'logical', 'currency', and
'date'. Use the 'DataType' filter to find server
items with a specific data type, such as 'double'
or 'date'.

FQID = serveritems(NS) and FQID = serveritems(NS,ItemID)

search the name space structure defined by NS, rather than querying
the OPC server. NS is the result of a call to getnamespace in either

hierarchical or flat format.

Note that some servers may return item IDs that cannot be created on
that server. These item IDs are usually branches of the OPC server
name space.
You use the results of a call to serveritems in a call to serveritemprops
to return the property information for items in the OPC server name
space. The properties of the items in the server name space include the
server items canonical data type, limits, description, current value, etc.

Examples

Create a client for the Matrikon Simulation Server and connect to the
server:
da = opcda('localhost', 'Matrikon.OPC.Simulation');connect(da);

9-72

Downloaded from www.Manualslib.com manuals search engine

serveritems

Find all item IDs in the Matrikon Server containing the word 'Real':
realItmIDs = serveritems(da, '*Real*'):

Add all items in the Random node to a group:

grp = addgroup(da, 'ServerItemsEx');
itm = additem(grp, serveritems(da, 'Random.*'));

See Also

getnamespace | serveritemprops

9-73

Downloaded from www.Manualslib.com manuals search engine

set

Purpose

Configure or display OPC Toolbox object properties

Syntax

set(Obj)
Prop = set(Obj)
set(Obj,'PropertyName')
Prop = set(Obj,'PropertyName')
set(Obj,'PropertyName',PropertyValue)
set(Obj,S)
set(Obj,PN,PV)
set(Obj,'PropName1',PropValue1,'PropName2',PropValue2,...)

Description

set(Obj) displays property names and any enumerated values for all
configurable properties of OPC Toolbox object Obj. Obj must be a single
toolbox object.
Prop = set(Obj) returns all property names and their possible values
for object Obj. Obj must be a single object. The return value, Prop, is a
structure whose field names are the property names of Obj, and whose

values are cell arrays of possible property values or empty cell arrays if
the property does not have a finite set of possible string values.
set(Obj,'PropertyName') displays the possible values for the specified
property, PropertyName, of toolbox object Obj. Obj must be a single

object.
Prop = set(Obj,'PropertyName') returns the possible values for the
specified property, PropertyName, of object Obj. The returned array,
Prop, is a cell array of possible value strings or an empty cell array if
the property does not have a finite set of possible string values.
set(Obj,'PropertyName',PropertyValue) sets the value,
PropertyValue, of the specified property, PropertyName, for object
Obj. Obj can be a vector of toolbox objects, in which case set sets the

property values for all the objects specified.

Note that if Obj is connected to an OPC server, configuring
server-specific properties such as UpdateRate and DeadbandPercent
might be time consuming.

9-74

Downloaded from www.Manualslib.com manuals search engine

set

set(Obj,S) where S is a structure whose field names are object

property names, sets the properties named in each field name to the
values contained in the structure.
set(Obj,PN,PV) sets the properties specified in the cell array of strings,
PN, to the corresponding values in the cell array PV, for all objects
specified in Obj. The cell array PN must be a vector, but the cell array
PV can be M-by-N, where M is equal to length(Obj) and N is equal to
length(PN), so that each object will be updated with a different set of
values for the list of property names contained in PN.
set(Obj,'PropName1',PropValue1,'PropName2',PropValue2,...)

sets multiple property values with a single statement.

Note that it is permissible to use param-value string pairs, structures,
and param-value cell array pairs in the same call to set.

Examples

Create an opcda object and add a group to that object:

da = opcda('localhost','Dummy.Server');
grp = addgroup(da,'SetExample');

Set the opcda objects Timeout to 300 seconds and restrict the event
log to 2000 entries:
set(da,'Timeout',300,'EventLogMax',2000);

Set multiple properties using cell array pairs:

set(da,{'Name','ServerID'},{'My Opcda object','OPC.Server.1'});

Set the groups name:

set(grp,'Name','myopcgroup');

9-75

Downloaded from www.Manualslib.com manuals search engine

set

Query the permissible values for the groups Subscription property:

set(grp,'Subscription')

See Also

get | opchelp | propinfo

9-76

Downloaded from www.Manualslib.com manuals search engine

showopcevents

Purpose

Event log summary for OPC Toolbox events

Syntax

showopcevents(DAObj)
showopcevents(DAObj,Index)
showopcevents(Struct)
showopcevents(Struct,Index)

Description

showopcevents(DAObj) displays a summary of the event log for the

opcda object specified by DAObj.
showopcevents(DAObj,Index) displays a summary of the events
with index of Index. Index can be the numerical index, a string, or
a cell array of strings that specifies the type of event. Valid events
are CancelAsync, Error, ReadAsync, Shutdown, Start, Stop, and
WriteAsync.
showopcevents(Struct) and showopcevents(Struct,Index) display
a summary of the events with index of Index for the event structure,
Struct. You can obtain an event structure from the objects EventLog
property.

The display summary includes the event type, the local time the event
occurred, and additional event-specific information.

Examples

Configure a logging task for the Matrikon Simulation Server, then

display the event log to find timing information for the logging task:
da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da)
grp = addgroup(da);
set(grp, 'RecordsToAcquire',10);
itm = additem(grp,'Bucket Brigade.Real8');
start(grp);
wait(grp);
showopcevents(da);

See Also

opccallback

9-77

Downloaded from www.Manualslib.com manuals search engine

start

Purpose

Start a logging task

Syntax

start(GObj)

Description

start(GObj) starts a data logging task for GObj. GObj can be a scalar
dagroup object, or a vector of dagroup objects. A dagroup object must
be active and contain at least one item for start to succeed.

When logging is started, GObj performs the following operations:

1 Generates a Start event, and executes the StartFcn callback.
2 If Subscription is 'off', sets Subscription to 'on' and issues

a warning.
3 Removes all records associated with the object from the OPC Toolbox

software engine.
4 Sets RecordsAcquired and RecordsAvailable to 0.
5 Sets the Logging property to 'on'.

The Start event is logged to the EventLog.

GObj will stop logging when a stop command is issued, or when
RecordsAcquired reaches RecordsToAcquire.

Examples

Configure and start a logging task for 30 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'StartEx');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-toothed Waves.UInt16');
set(grp, 'LoggingMode', 'memory', 'UpdateRate', 0.5, ...
'RecordsToAcquire', 60);
start(grp);

9-78

Downloaded from www.Manualslib.com manuals search engine

start

Wait for the logging task to finish, then retrieve the records into a
double array and plot the data with a legend:
wait(grp);
[itmID, val, qual, tStamp] = getdata(grp, 'double');
plot(tStamp(:,1), val(:,1), tStamp(:,2), val(:,2));
legend(itmID);
datetick x keeplimits

See Also

flushdata | getdata | peekdata | stop | wait

9-79

Downloaded from www.Manualslib.com manuals search engine

stop

Purpose

Stop a logging task

Syntax

stop(GObj)

Description

stop(GObj) stops all logging tasks associated with the dagroup object
GObj. GObj can be a dagroup object or a vector of dagroup objects. When
the function stops a logging task, it sets the objects Logging property
value to 'Off', and triggers execution of the objects StopFcn callback.

A dagroup object also stops running when the logging task has acquired
all the requested records. This occurs when RecordsAcquired equals
RecordsToAcquire.
The objects EventLog property records the Stop event.

Examples

Configure and start a logging task for 30 seconds of data:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCREAD');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');
set(grp, 'LoggingMode', 'memory', 'UpdateRate', 0.5, ...
'RecordsToAcquire', 60);
start(grp);

Stop the logging task after 5 seconds:

wait(5);
stop(grp);

See Also

start | wait

9-80

Downloaded from www.Manualslib.com manuals search engine

trend

Purpose

Display graphical trend of OPC data for group

Syntax

H = trend(GObj)
H = trend(GObj, 'PropertyName', PropertyValue,...)

Description

H = trend(GObj) displays the newest 100 points of live data for the
items defined in the dagroup object GObj in the current axes. GObj must
be an active group containing one or more items. The handles to the
created Handle Graphics objects are returned in H.

All the items are displayed in the same axes, with no scaling. New data
is displayed on the far right of the axes, and oldest data is displayed on
the left. If no old data exists (such as at the beginning of a plot), the
axes are empty. The Handle Graphics objects (including the axis limits)
are updated with new data whenever the group object receives a Data
Change event from the OPC server.
H = trend(GObj, 'PropertyName', PropertyValue,...) allows you

to pass additional property/value pairs to specify additional properties

of the created plots. Special property/value pairs are listed in the
following table. If any property is not in this list, that property/value
pair is passed on to the created Handle Graphics objects.
Property Name

Description

Default

DisplayTime

Defines the number of seconds of

history to display in the plot.

100*gObj.UpdateRate

Parent

Defines the parent axes objects in

which to display the trends. The
value can be a scalar, or a vector the
same length as the number of items
in GObj. If the value is a vector,
each items value is displayed in the
respective axes object.

Current axes

9-81

Downloaded from www.Manualslib.com manuals search engine

trend

Property Name

Description

Default

PlotType

Defines the plot types for each

item. Valid plot types are 'line',
'stairs', and 'stem'. The value
can be a scalar, or a cell array the
same length as the number of items
in GObj. If the value is a cell array of
strings, each items plot type is set to
the respective plot type in the value
array.

'line'

DateFormat

Sets the display format for the x-axis

of all axes objects into which data
is plotted. DateFormat must be one
of the date formats recognized by
datetick.

'HH:MM:SS'

BufferTime

Defines the number of seconds of

history to store for all items. Setting
this value to a number greater than
the value of DisplayTime allows you
to pause the trend (by setting the
Subscription property of the group
to 'off') and panning the axes in
question.

10*DisplayTime

You can fix the axes y-limits to a particular value by using the YLim
property of the axes containing your visualized data. For example, to
set the limits of the y-axis to the instrument range reported by the OPC
server, use the following code:
props = serveritemprops(da, itmName, 102:103);
set(gca, 'YLim', [props.PropValue]);

If you add items to a group that currently has an active trend, the item
is not shown. Call trend again to include that item in the trend view. (If
you set the hold state of the axes to 'on', when you call trend, existing
trend objects are reused, without destroying their current view.)

9-82

Downloaded from www.Manualslib.com manuals search engine

trend

If you delete an item from a group that currently has an active trend,
the trend display shows no data for that item, and the items trend
eventually disappears off the graph.
This function overwrites the following properties of the group object:
The DataChangeFcn property is set to update the axes with new
data whenever it is received from the OPC server. If there is an
existing DataChangeFcn callback, the trend functionality overwrites
the callback.
The Subscription property is configured to 'on' to receive Data
Change events from the OPC server. You can change Subscription
to 'off' after calling trend, in which case the trend stops updating
until you set Subscription back to 'on' or issue a readasync
command.

Examples

Configure a group with two items:

da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExOPCTREND');
itm1 = additem(grp, 'Triangle Waves.Real8');
itm2 = additem(grp, 'Saw-Toothed Waves.Int2');

Create a trend showing the last two minutes of data in two separate
axes:
ax1 = subplot(2,1,1);
ax2 = subplot(2,1,2);
trend(grp, 'DisplayTime', 120, 'Parent', [ax1, ax2]);

See Also

datetick | hold

9-83

Downloaded from www.Manualslib.com manuals search engine

wait

Purpose

Suspend MATLAB execution until object stops logging

Syntax

wait(GObj)
wait(GObj, TSec)

Description

wait(GObj) suspends MATLAB execution until the group object GObj

has stopped logging. GObj must be a scalar dagroup object.
wait(GObj, TSec) will wait at most TSec seconds for GObj to stop
logging. If the group object is still logging when the timeout value is
exceeded, an error message is generated.

The wait function can be useful when you want to guarantee that data
is logged before another task is performed.
You can press Ctrl+C to interrupt the wait function. An error message
will be generated, and control will return to the MATLAB command
window.

Examples

Log 60 seconds of data at 1-second intervals from the Matrikon

Simulation Servers Random.Real8 and Random.UInt4 tags. Display a
message indicating that the acquisition is complete, then retrieve and
plot the data:
da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da)
grp = addgroup(da,'WaitExample');
itm = additem(grp, {'Random.Real8','Random.UInt4'});
set(grp, 'RecordsToAcquire',60, 'UpdateRate',1);
start(grp);
wait(grp)
disp('Acquisition complete');
[itmID,v,q,t]=getdata(grp, 'double');
plot(t(:,1),v(:,1), t(:,2), v(:,2));
legend(itmID);

See Also

getdata | start | stop

9-84

Downloaded from www.Manualslib.com manuals search engine

write

Purpose

Write values to group or items

Syntax

write(GObj,Values)
write(IObj,Values)

Description

write(GObj,Values) writes values to all the items contained in the

dagroup object GObj. Values is a cell array of values--one for each item.

To ensure that a specific value is written to the correct item object, you
should construct the Values cell array based on the order of the items
returned by the Item property.
write(IObj,Values) writes values to all the items contained in the
vector of daitem objects specified by IObj.

The data types of the values do not need to match the canonical data
type of the associated items. However an error is returned if a data type
conversion cannot be performed.
Because the values are written to the device, this operation might be
slow. The function does not return until it verifies that the device has
actually accepted or rejected the data.
Note The behavior of an OPC server when writing NaN to an item is
server-dependent. If you attempt to write NaN to an OPC server, the
value might be silently ignored by the OPC server. That is, the server
might not generate any events in response to writing NaN to an item.

Examples

Configure a client, group, and items for the Matrikon Simulation Server:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'ExWrite');
itm = additem(grp, {'Bucket Brigade.Real8', ...
'Bucket Brigade.String'});

9-85

Downloaded from www.Manualslib.com manuals search engine

write

Read and write values to/from the items:

write(grp, {23, 'Hello World!'})
r = read(grp)
write(itm(1), 15)
r2 = read(itm(1))

See Also

read | readasync | refresh | | writeasync

9-86

Downloaded from www.Manualslib.com manuals search engine

writeasync

Purpose

Asynchronously write values to group or items

Syntax

TransID = writeasync(GObj,Values)
TransID = writeasync(IObj,Values)

Description

TransID = writeasync(GObj,Values) asynchronously writes values

to all the items contained in the dagroup object GObj. Values is a cell
array of values and is the same size as the number of items in GObj.
TransID is a unique transaction ID for the asynchronous request.
TransID = writeasync(IObj,Values) asynchronously writes values to
all the items contained in the vector of daitem objects specified by IObj.

To ensure that a specific value is written to the correct item object, you
should construct the Values cell array based on the order of the items
returned by the Item property. Because the values are written to the
device, this operation might be time consuming.
The data types of the values do not need to match the canonical data
type of the associated items. If a data type conversion cannot be
performed, a warning is issued.
When the asynchronous write operation completes, a write async event
is generated by the server. If a callback function file is specified for the
WriteAsyncFcn property, then the function executes when the event is
generated.
Note The behavior of an OPC server when writing NaN to an item is
server-dependent. If you attempt to write NaN to an OPC server, the
value might be silently ignored by the OPC server. That is, the server
might not generate any events in response to writing NaN to an item.

Examples

Configure a client, group, and items, for the Matrikon Simulation

Server:
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);

9-87

Downloaded from www.Manualslib.com manuals search engine

writeasync

grp = addgroup(da, 'ExWrite');

itm = additem(grp, {'Bucket Brigade.Real8', ...
'Bucket Brigade.String'});

Configure the WriteAsyncFcn callback to read from the group:

grp.WriteAsyncFcn = 'r=read(grp,''device'')';

Write values asynchronously to the group:

writeasync(grp, {123.456, 'MATLAB is great!'})

See Also

cancelasync | read | readasync | refresh | write

9-88

Downloaded from www.Manualslib.com manuals search engine

10
Property Reference
OPC Data Access Client Object
Properties (p. 10-2)

Information and behavior of opcda

client object

Data Access Group Object Properties

(p. 10-4)

Information and behavior of opcda

group object

Data Access Item Object Properties

(p. 10-7)

Information and behavior of opcda

item object

Downloaded from www.Manualslib.com manuals search engine

10

Property Reference

OPC Data Access Client Object Properties

General Properties (p. 10-2)

Basic information about client object

Callback Function and Event

Properties (p. 10-2)

Information about object event and

callback behavior

Server Connection Properties

(p. 10-3)

Information about object connections

General Properties
Group

Data Access Group objects contained

by client

Name

Descriptive name for OPC Toolbox

object

Tag

Label to associate with OPC Toolbox

object

Type

OPC Toolbox object type

UserData

Data to associate with OPC Toolbox

object

Callback Function and Event Properties

ErrorFcn

Callback function file to execute

when error event occurs

EventLog

Event information log

EventLogMax

Maximum number of events to store

in event log

ShutDownFcn

Callback function file to execute

when OPC server shuts down

TimerFcn

Callback function file to execute

when predefined period passes

TimerPeriod

Period between timer events

10-2

Downloaded from www.Manualslib.com manuals search engine

OPC Data Access Client Object Properties

Server Connection Properties

Host

DNS name or IP address of server

ServerID

Server identity

Status

Status of connection to OPC server

Timeout

Maximum time to wait for

completion of instruction to
server

10-3

Downloaded from www.Manualslib.com manuals search engine

10

Property Reference

Data Access Group Object Properties

General Properties (p. 10-4)

Basic information about group object

Callback Function and Event

Properties (p. 10-4)

Information about object event and

callback behavior

Subscription and Logging Properties

(p. 10-5)

Information about object logging,

records, and subscription

General Properties
GroupType

Public status of dagroup object

Item

Data Access Item objects contained

by group

Name

Descriptive name for OPC Toolbox

object

Parent

OPC Toolbox object that contains

dagroup or daitem object

Tag

Label to associate with OPC Toolbox

object

TimeBias

Time bias of group

Type

OPC Toolbox object type

UserData

Data to associate with OPC Toolbox

object

Callback Function and Event Properties

CancelAsyncFcn

Callback function file to execute

when asynchronous operation is
canceled

DataChangeFcn

Callback function file to execute

when data change event occurs

10-4

Downloaded from www.Manualslib.com manuals search engine

Data Access Group Object Properties

ReadAsyncFcn

Callback function file to execute

when asynchronous read completes

RecordsAcquiredFcn

Callback function file to execute

when RecordsAcquired event occurs

RecordsAcquiredFcnCount

Number of records to acquire before

RecordsAcquired event occurs

StartFcn

Callback function file to execute

immediately before logging starts

StopFcn

Callback function file to execute

immediately after logging stops

WriteAsyncFcn

Callback function file to execute

when asynchronous write completes

Subscription and Logging Properties

Active

Group or item activation state

DeadbandPercent

Percentage change in item value

that causes subscription callback

LogFileName

Name of disk file to which logged

data is written

Logging

Status of data logging

LoggingMode

Specify destination for logged data

LogToDiskMode

Method of disk file handling for

logged data

RecordsAcquired

Number of records acquired

RecordsAvailable

Number of records available in OPC

Toolbox engine

RecordsToAcquire

Number of records to acquire for

logging session

10-5

Downloaded from www.Manualslib.com manuals search engine

10

Property Reference

Subscription

Enable server update when data

changes

UpdateRate

Rate, in seconds, at which

subscription callbacks occur

10-6

Downloaded from www.Manualslib.com manuals search engine

Data Access Item Object Properties

Data Access Item Object Properties

General Properties (p. 10-7)

Basic information about item object

Data Properties (p. 10-7)

Information about item data

General Properties
AccessRights

Inherent nature of access to item

Active

Group or item activation state

ItemID

Fully qualified ID on OPC server

Parent

OPC Toolbox object that contains

dagroup or daitem object

ScanRate

Fastest possible data update rate

Tag

Label to associate with OPC Toolbox

object

Type

OPC Toolbox object type

UserData

Data to associate with OPC Toolbox

object

Data Properties
CanonicalDataType

Servers data type for item

DataType

Client items data type

Quality

Quality of data value as string

QualityID

Quality of data value as 16-bit

integer

TimeStamp

Time when item was last read

Value

Item value

10-7

Downloaded from www.Manualslib.com manuals search engine

10

Property Reference

10-8

Downloaded from www.Manualslib.com manuals search engine

11
Properties Alphabetical
List

Downloaded from www.Manualslib.com manuals search engine

AccessRights

Purpose

Inherent nature of access to item

Description

AccessRights represents the servers ability to access a single OPC data

item. The property value can be 'read', 'write', or 'read/write'.
If AccessRights is 'read', you can read the server items value. If
AccessRights is 'write', you can write values to the server item. If
AccessRights is 'read/write', you can read and change the server

items value. If you attempt a read or write operation on an item that

does not have the required access rights, the server may return an error.

Characteristics Access

Read-only

Applies to

daitem

Data type

string

Values

[ 'read' | 'read/write' | 'write' ]

The value is set by the server when an item is

created.

See Also

Functions
read, readasync, refresh, write, writeasync

Properties
Subscription

11-2

Downloaded from www.Manualslib.com manuals search engine

Active

Purpose

Group or item activation state

Description

Active can be 'on' or 'off'. If Active is 'on', the OPC server will
return data for the group or item when requested by the read function
or when the corresponding data items change (subscriptions). If Active
is 'off', the OPC server will not return information about the group

or item.
By default, Active is set to 'on' when you create a dagroup or daitem
object. Set Active to 'off' when you are temporarily not interested
in that daitem or dagroup objects values. You configure Active for
both dagroup and daitem objects. Changing the state of the group does
not change the state of the items.
The activation state of a dagroup or daitem object affects reads and
subscriptions, and depends on whether the data is obtained from the
cache or from the device. The active state of a group or item affects
operations as follows.
Operation

Source

Active State

read

Cache

Both group and items must be active.

Inactive items in active groups, and all
items in inactive groups, return bad
quality.

read

Device

Active is ignored.

write

N/A

Active is ignored.

Subscription N/A

readasync

N/A

Both group and items must be active.

Inactive items in active groups, and all
items in inactive groups, return bad
quality.
Active is ignored.

A transition from 'off' to 'on' results in a change in quality, and

causes a subscription callback for the item or items affected. Changing
the Active state from 'on' to 'off' will cause a change in quality but

11-3

Downloaded from www.Manualslib.com manuals search engine

Active

will not cause a callback since by definition callbacks do not occur for
inactive items.
You enable subscription callbacks with the Subscription property.
Use the DataChangeFcn property to specify a callback function file to
execute when a data change event occurs.

Characteristics Access

See Also

Read/write

Applies to

dagroup, daitem

Data type

string

Values

[ 'off' | {'on'} ]

Functions
read, readasync, refresh

Properties
DataChangeFcn, Subscription

11-4

Downloaded from www.Manualslib.com manuals search engine

CancelAsyncFcn

Purpose

Callback function file to execute when asynchronous operation is

canceled

Description

You configure CancelAsyncFcn to execute a callback function file when

a cancel async event occurs. A cancel async event occurs after an
asynchronous read or write operation is canceled.
When a cancel async event occurs, the function specified in
CancelAsyncFcn is passed two parameters: Obj and EventInfo. Obj
is the object associated with the event, and EventInfo is an event
structure containing the fields Type and Data. The Type field is set to
'CancelAsync'. The Data field contains a structure with the fields
shown below.
Field Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred.

TransID

The transaction ID of the canceled read or write

asynchronous operation.

GroupName

The group name.

Cancel async event information is stored in the EventLog property.

Characteristics Access

Read/write

Applies to

dagroup

Data type

String, function handle, or cell array

Values

The default value is @opccallback.

11-5

Downloaded from www.Manualslib.com manuals search engine

CancelAsyncFcn

See Also

Functions
cancelasync, opccallback, readasync, writeasync

Properties
EventLog

11-6

Downloaded from www.Manualslib.com manuals search engine

CanonicalDataType

Purpose

Servers data type for item

Description

CanonicalDataType indicates the data type of the item as stored on

the OPC server. The MATLAB supported data types are as for the
DataType property.
You can specify that the items value is stored in the daitem object
using a data type that differs from the canonical data type, by
setting the DataType property of the item to a value different from
CanonicalDataType. Translation between the CanonicalDataType
and the DataType is automatic.
Refer to the DataType property reference for a listing of the COM
Variant data types and their equivalent MATLAB data types.

Characteristics Access

See Also

Read-only

Applies to

daitem

Data type

string

Values

The default value is determined when the item

is created.

Functions
additem

Properties
DataType

11-7

Downloaded from www.Manualslib.com manuals search engine

DataChangeFcn

Purpose

Callback function file to execute when data change event occurs

Description

You configure DataChangeFcn to execute a callback function file when a

data change event occurs. A data change event occurs for subscribed
active items within an active group when the value or quality of the item
has changed. The events will happen no faster than the time specified
for the UpdateRate property of the group. The DeadbandPercent
property is used to determine what percentage change in the value or
quality initiates the callback. A data change event is only generated
when both the Active and Subscription properties are 'on'.
When a data change event occurs, the function specified in
DataChangeFcn is passed two parameters: Obj and EventInfo. Obj
is the object associated with the event, and EventInfo is an event
structure containing the fields Type and Data. The Type field is set
to 'DataChange'. The Data field contains a structure with the fields
defined below.
Field Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred

TransID

0, or the Refresh transaction ID if the data change

event was generated by refresh

GroupName

The group name

Items

A structure containing information about each

item whose value or quality updated

The Items structure contains the fields defined below.

Field Name

Description

ItemID

The item name

Value

The data value

TimeStamp

The time, as a MATLAB date vector, that the

servers cache was updated

11-8

Downloaded from www.Manualslib.com manuals search engine

DataChangeFcn

Data change event information is not stored in the EventLog property

Characteristics Access

See Also

Read/write

Applies to

dagroup

Data type

string, function handle, or cell array

Values

The default value is an empty matrix ([]).

Functions
opccallback, refresh

Properties
Active, DeadbandPercent, Subscription, UpdateRate

11-9

Downloaded from www.Manualslib.com manuals search engine

DataType

Purpose

Client items data type

Description

DataType indicates the data type of the item as stored in the daitem

object in the MATLAB workspace. You can specify the data type when
the item is created using the additem function. If you do not specify
a data type, or if the requested data type is rejected by the server,
the canonical (native) data type is used. If the client associated with
the item is not connected, the data type is set to 'unknown' until the
client is connected.
The OPC server uses this data type to store the item value. The
CanonicalDataType property of a daitem object provides information
on the canonical data type of that item on the server.
OPC communication uses COM Variant data types to send information
between the server and client. These are automatically translated to
an equivalent MATLAB data type for the COM Variant types defined
below. Any data type not included in this list is returned as 'unknown'.
OPC Toolbox
Data Type

COM Data Type

MATLAB Data Type

double

VT_R8

double

char

VT_BSTR

char

single

VT_R4

single

uint8

VT_UI1

uint8

uint16

VT_UI2

uint16

uint32

VT_UI4

uint32

uint64

VT_UI8

uint64

int8

VT_I1

int8

int16

VT_I2

int16

int32

VT_I4

int32

int64

VT_I8

int64

11-10

Downloaded from www.Manualslib.com manuals search engine

DataType

OPC Toolbox
Data Type

COM Data Type

MATLAB Data Type

currency

VT_CY

double

date

VT_DATE

double

logical

VT_BOOL

logical

double

VT_EMPTY

Empty array ([])

Characteristics Access

See Also

Read-only while logging

Applies to

daitem

Data type

string

Values

[{'unknown'} | 'double' | 'char' |

'single' | 'uint8' | 'uint16' | 'uint32'
| 'uint64' | 'int8' | 'int16' | 'int32'
| 'int64' | 'currency' | 'date' |
'logical']

Functions
additem

Properties
CanonicalDataType

11-11

Downloaded from www.Manualslib.com manuals search engine

DeadbandPercent

Purpose

Percentage change in item value that causes subscription callback

Description

You configure DeadbandPercent to a value between 0 and 100. The

default value is 0, which specifies that any value change will update the
OPC servers cache. A non-zero value results in the cache value being
updated only if the difference between the cached value and the current
value of the item exceeds
DeadbandPercent * (High EU - Low EU) / 100

The DeadbandPercent property only affects items that have an

analogue data type and 'High EU' and 'Low EU' properties defined
(Property IDs 102 and 103 respectively). You can query data types and
item properties using serveritemprops.
Note OPC servers may not implement the DeadbandPercent property
behavior, even for values that have High EU and Low EU properties
defined. For servers that do not support DeadbandPercent, an error will
be generated if you attempt to set the DeadbandPercent property to a
value other than 0.
DeadbandPercent is applied group wide for all analog daitem

objects, and is used to prevent noisy signals from updating the client
unnecessarily.

Characteristics Access

Read/write

Applies to

dagroup

Data type

double

Values

Any value from 0 to 100, inclusive. The default

value is 0.

11-12

Downloaded from www.Manualslib.com manuals search engine

DeadbandPercent

See Also

Functions
serveritemprops

Properties
Active, Subscription, UpdateRate

11-13

Downloaded from www.Manualslib.com manuals search engine

ErrorFcn

Purpose

Callback function file to execute when error event occurs

Description

You configure ErrorFcn to execute a callback function file when an

error event occurs. An error event is generated when an asynchronous
transaction fails. For example, an asynchronous read on items that
cannot be read generates an error event. An error event is not generated
for configuration errors such as setting an invalid property value, nor
for synchronous read and write operations.
When an Error event occurs, the function specified in ErrorFcn is
passed two parameters: Obj and EventInfo. Obj is the object associated
with the event, and EventInfo is an event structure containing the
fields Type and Data. The Type field is set to 'Error'. The Data field
contains a structure with the following fields:
Field Name

Description

LocalEventTime The local time (as a date vector) the event occurred.
TransID

The transaction ID associated with the event.

GroupName

The group name.

Items

A structure containing information on each item

that generated an error during that transaction.

The Items structure array contains the following fields:

Field Name

Description

ItemID

The item name.

Error

The error message.

The default value for ErrorFcn is @opccallback.

Note that error event information is also stored in the EventLog
property.

11-14

Downloaded from www.Manualslib.com manuals search engine

ErrorFcn

Characteristics Access

See Also

Read/write

Applies to

opcda

Data type

string, function handle, or cell array

Values

@opccallback is the default callback function.

Functions
opccallback, showopcevents

Properties
EventLog, Timeout

11-15

Downloaded from www.Manualslib.com manuals search engine

EventLog

Purpose

Event information log

Description

EventLog contains a structure array that stores information related to

OPC Toolbox software events. Every element in the structure array

corresponds to an event.
Each element in the EventLog structure contains the fields Type
and Data. The Type value can be 'WriteAsync', 'ReadAsync',
'CancelAsync', 'Shutdown', 'Start', 'Stop', or 'Error'.
Data stores event-specific information as a structure. For information
on the fields contained in Data, refer to the associated callback

property reference pages. For example, to find information on the fields

contained in Data for a Start event, refer to the StartFcn property.
You specify the maximum number of events to store with the
EventLogMax property.
Note that some events are not stored in the EventLog. If you want to
store these events, you must specify a callback for that event.
You can execute a callback function when an event occurs by specifying
a function for the associated callback property. For example, to
execute a callback when a read async event is generated, you use the
ReadAsyncFcn property.
If the event log is full (the number of events in the log equals the value
of the EventLogMax property) and a new event is received, the oldest
event is removed to make space for the new event. You clear the event
log using the cleareventlog function.

Characteristics Access

Read-only

Applies to

opcda

Data type

Structure array

Values

The default value is an empty matrix ([]).

11-16

Downloaded from www.Manualslib.com manuals search engine

EventLog

Examples

The following example creates a client and configures a group with two
items. A 30-second logging task is run, and after 10 seconds the item
values are read. When the logging task stops, the event log is retrieved
and examined.
da = opcda('localhost', 'Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da, 'EvtLogExample');
itm1 = additem(grp, 'Random.Real8');
itm2 = additem(grp, 'Triangle Waves.UInt1');
set(grp, 'UpdateRate', 1, 'RecordsToAcquire', 30);
start(grp);
pause(10);
tid = readasync(grp);
wait(grp);
el = get(da, 'EventLog')
el = get(da, 'EventLog')
el =
1x3 struct array with fields:
Type
Data

Now examine the first event, which is the start event.

el(1)
ans =
Type: 'Start'
Data: [1x1 struct]

The Data field contains the following information.

el(1).Data
ans =
LocalEventTime: [2004 1 13 16 16 25.1790]
GroupName: 'EvtLogExample'
RecordsAcquired: 0

11-17

Downloaded from www.Manualslib.com manuals search engine

EventLog

The second event is a ReadAsync event. Examine the Data structure

and the first element of the Items structure.
el(2)
ans =
Type: 'ReadAsync'
Data: [1x1 struct]
el(2).Data
ans =
LocalEventTime:
TransID:
GroupName:
Items:

[2004 1 13 16 16 35.2100]
2
'EvtLogExample'
[2x1 struct]

el(2).Data.Items(1)
ans =
ItemID: 'Random.Real8'
Value: 2.4619e+003
Quality: 'Good: Non-specific'
TimeStamp: [2004 1 13 16 16 35.1870]

See Also

Functions
cleareventlog, start

Properties
CancelAsyncFcn, DataChangeFcn, EventLogMax, ErrorFcn,
ReadAsyncFcn, StartFcn, StopFcn, WriteAsyncFcn

11-18

Downloaded from www.Manualslib.com manuals search engine

EventLogMax

Purpose

Maximum number of events to store in event log

Description

If the event log is full (the number of events in the log equals the value
of the EventLogMax property) and a new event is received, the oldest
event is removed to make space for the new event. You clear the event
log using the cleareventlog function.
By default, EventLogMax is set to 1000. To continually store events,
specify a value of Inf. To store no events, specify a value of 0. If
EventLogMax is reduced to a value less than the number of existing
events in the event log, the oldest events are removed until the number
of events is equal to EventLogMax.

Characteristics Access

See Also

Read/write

Applies to

opcda

Data type

double

Values

Any integer in the range [0 Inf]. The default value

is 1000.

Functions
cleareventlog

Properties
EventLog

11-19

Downloaded from www.Manualslib.com manuals search engine

Group

Purpose

Data Access Group objects contained by client

Description

Group is a vector of dagroup objects contained by the opcda object.

Group is initially an empty vector. The size of Group increases as you
add groups with the addgroup function, and decreases as you remove
groups with the delete function.

Characteristics Access

See Also

Read-only

Applies to

opcda

Data type

dagroup array

Values

The default value is an empty array ([]).

Functions
addgroup, delete

11-20

Downloaded from www.Manualslib.com manuals search engine

GroupType

Purpose

Public status of dagroup object

Description

GroupType indicates whether a group is private or public. A private

group is local to the opcda client, and other clients must create their

own private groups. A public group is available from the server for any
other OPC client on the network.

Characteristics Access

See Also

Read-only

Applies to

dagroup

Data type

string

Values

[ {'private'} | 'public' ]

Functions
addgroup

11-21

Downloaded from www.Manualslib.com manuals search engine

Host

Purpose

DNS name or IP address of server

Description

Host is the name or IP address of the machine hosting the OPC server.

If you specify the host using an IP address, no name resolution is

performed on that address.

Characteristics Access

See Also

Read-only while connected

Applies to

opcda

Data type

string

Values

The value is configured when the object is created.

Functions
opcda

Properties
ServerID

11-22

Downloaded from www.Manualslib.com manuals search engine

Item

Purpose

Data Access Item objects contained by group

Description

Item is a vector of daitem objects contained by the dagroup object. Item

is initially an empty vector. The size of Item increases as you add
items with the additem function, and decreases as you remove items
with the delete function.

Characteristics Access

Example

Read-only

Applies to

dagroup

Data type

daitem

Values

The default value is an empty matrix ([]).

This example creates a fictitious client, adds a group and two items.
da = opcda('localhost', 'Dummy.Server');
grp = addgroup(da, 'MyGroup');
itm1 = additem(grp, 'Item.Name.1');
itm2 = additem(grp, 'Item.Name.2');
allItems = grp.Item

If one of the items is deleted, the Item property is updated to reflect this.
delete(itm2);
newItems = grp.Item

See Also

Functions
additem, delete

11-23

Downloaded from www.Manualslib.com manuals search engine

ItemID

Purpose

Fully qualified ID on OPC server

Description

ItemID is the fully qualified ID of the data item on the OPC server. The
server uses the ItemID to return the appropriate data from the servers

cache, or to read and send data to a specific device or location.

You obtain valid ItemID values for a particular server by querying that
servers name space using the getnamespace or serveritems functions.

Characteristics Access

See Also

Read-only while connected

Applies to

daitem

Data type

string

Values

The default value is set during creation.

Functions
additem, getnamespace, serveritems

11-24

Downloaded from www.Manualslib.com manuals search engine

LogFileName

Purpose

Name of disk file to which logged data is written

Description

When you start a logging operation using the start function, and
the LoggingMode property is set to 'disk' or 'disk&memory', then
DataChange events (records) are logged to a disk file with the name
specified by LogFileName. You may specify any value for LogFileName
as long as it conforms to the operating system file naming conventions.
If no extension is specified as part of LogFileName, then .olf is used.
If a log file with the same name as LogFileName already exists when
logging is started, the LogToDiskMode property is used to determine
whether to overwrite the existing file, append records to that file, or
create an indexed file based on LogFileName.
The log file is an ASCII file in comma-separated variable format,
arranged as follows:
DataChange: LocalEventTime
ItemID1, Value1, Quality1, TimeStamp1
ItemID2, Value2, Quality2, TimeStamp2
...
ItemIDN, ValueN, QualityN, TimeStampN
DataChange: <LocalEventTime>
ItemID1, Value1, Quality1, TimeStamp1
ItemID2, Value2, Quality2, TimeStamp2
...
ItemIDN, ValueN, QualityN, TimeStampN
...

Characteristics Access

Read-only while logging

Applies to

dagroup

Data type

string

Values

The default value is 'opcdatalog.olf'.

11-25

Downloaded from www.Manualslib.com manuals search engine

LogFileName

See Also

Functions
start

Properties
LoggingMode, LogToDiskMode

11-26

Downloaded from www.Manualslib.com manuals search engine

Logging

Purpose

Status of data logging

Description

Logging is automatically set to 'on' when you issue a start command.

Logging is automatically set to 'off' when you issue a stop command,

or when the requested number of records is logged. You specify the

number of records to log with the RecordsToAcquire property.
When Logging is 'on', each DataChange event (a record) is stored to
disk or to memory (the buffer) as defined by the LoggingMode property.

Characteristics Access

See Also

Read-only

Applies to

dagroup

Data type

string

Values

[ {'off'} | 'on' ]

Functions
start, stop, wait

Properties
LoggingMode, RecordsToAcquire

11-27

Downloaded from www.Manualslib.com manuals search engine

LoggingMode

Purpose

Specify destination for logged data

Description

LoggingMode can be set to 'disk', 'memory', or 'disk&memory'. If

LoggingMode is set to 'disk', DataChange events (records) are stored
to a disk file as specified by LogFileName. If LoggingMode is set to
'memory', records are stored to memory (the buffer). If LoggingMode is
set to 'disk&memory', records are stored to memory and to a disk file.
LoggingMode defaults to 'memory'.

The disk file or memory buffer contains data logged from the time you
issue the start command, until the time you issue a stop command or
the number of records specified by the RecordsToAcquire property has
been logged. Each DataChange event constitutes one record, containing
one or more items. Only items that change value or quality are included
in a DataChange event. The logged data includes the ItemID, Value,
TimeStamp, and Quality for each item that changed.
Note that when you issue a refresh command while the toolbox is
logging, the results of that operation are included in the log, since a
refresh forces a DataChange event on the OPC server.
You extract data from memory with the getdata function. You can
return the data stored in a log file to the MATLAB workspace with
the opcread function.

Characteristics Access

Read-only while logging

Applies to

dagroup

Data type

string

Values

[ 'disk' | 'disk&memory' | {'memory'} ]

11-28

Downloaded from www.Manualslib.com manuals search engine

LoggingMode

See Also

Functions
getdata, opcread, refresh, start, stop

Properties
LogFileName, RecordsToAcquire

11-29

Downloaded from www.Manualslib.com manuals search engine

LogToDiskMode

Purpose

Method of disk file handling for logged data

Description

LogToDiskMode can be set to 'append', 'overwrite' or 'index'. If

LogToDiskMode is set to 'append', then data for a logged session is

added to any data that already exists in the log file when logging
is started using the start command. If LogToDiskMode is set to
'overwrite', then the log file is overwritten each time start is called.
If LogToDiskMode is set to 'index', then a different disk file is created
each time start is called, according to the following rules:
1 The first log file name attempted is specified by the initial value of

LogFileName.
2 If the attempted file name exists, then a numeric identifier is

added to the value of LogFileName. For example, if LogFileName

is initially specified as 'groupRlog.olf', then groupRlog.olf is
the first attempted file, groupRlog01.olf is the second file name,
and so on. If the LogFileName already contains numbers as the
last characters in the file name, then that number is incremented
to create the new log file name. For example, if the LogFileName
is specified as 'groupLog003.olf', then the next file name would
be 'groupLog004.olf'.
3 The actual file name used is the first file name that does not exist. In

this way, each consecutive logging operation is written to a different

file, and no previous data is lost.
Separate dagroup objects are logged to separate files. If two dagroup
objects have the same value for LogFileName, then attempting to log
data from both objects simultaneously will result in the second object
failing during the start operation.

11-30

Downloaded from www.Manualslib.com manuals search engine

LogToDiskMode

Characteristics

See Also

Access

Read-only while logging

Applies to

dagroup

Data type

string

Values

[ 'append' | {'index'} | 'overwrite' ]

Functions
start

Properties
LogFileName, Logging, LoggingMode

11-31

Downloaded from www.Manualslib.com manuals search engine

Name

Purpose

Descriptive name for OPC Toolbox object

Description

The default object creation behavior is to automatically assign a name

to all objects. For the opcda object, Name follows the naming scheme
'Host/ServerID'. For the dagroup object, if a name is not specified
upon creation, the name returned by the OPC server is used, or a unique
name is automatically assigned to the group. Automatically assigned
group names follow the naming scheme 'groupN' where N is an integer.
You can change the Name of an object at any time. The Name can be any
string, and is used for display and identification purposes only.

Characteristics Access

See Also

Read/write

Applies to

opcda, dagroup

Data type

string

Values

The default value is defined at object creation time.

Functions
opcda, addgroup

Properties
Host, ItemID, ServerID

11-32

Downloaded from www.Manualslib.com manuals search engine

Parent

Purpose

OPC Toolbox object that contains dagroup or daitem object

Description

For dagroup objects, Parent indicates the opcda object that contains
the group. For daitem objects, Parent indicates the dagroup object
that contains the daitem object.

Characteristics Access

See Also

Read-only

Applies to

dagroup, daitem

Data type

Type of parent object

Values

The value is defined at object creation time.

Properties
Group, Item

11-33

Downloaded from www.Manualslib.com manuals search engine

Quality

Purpose

Quality of data value as string

Description

Quality indicates the quality of the daitem objects Value property as

a string. You can use the Quality property to determine if a value

is useful or not.
The Quality string is made up of a major quality string, a substatus
string, and an optional limit status string, arranged in the format
'Major: Substatus: Limit status'. The limit status part is
omitted if the value is not limited. The major quality can be one of
the following values:
Value

Description

Bad

The value is not useful for reasons indicated by

the Substatus.

Good

The value is of good quality.

Uncertain

The quality of the value is uncertain for reasons

indicated by the Substatus.

For a list of substatus and limit status values and their interpretations,
consult Appendix A, OPC Quality Strings.
Quality is updated when you perform a read operation using read or
readasync, or when a subscription callback occurs. Quality is also
returned during a synchronous read operation.

Characteristics Access

Read-only

Applies to

daitem

Data type

string

Values

The default value is 'Bad:

11-34

Downloaded from www.Manualslib.com manuals search engine

Out of Service'.

Quality

See Also

Functions
read, readasync, refresh

Properties
QualityID, Subscription, TimeStamp, UpdateRate, Value

11-35

Downloaded from www.Manualslib.com manuals search engine

QualityID

Purpose

Quality of data value as 16-bit integer

Description

QualityID is a numeric indication of the quality of the daitem objects

data value.
QualityID is a number ranging from 0 to 65535, made up of four
parts. The high 8 bits of the QualityID represent the vendor-specific
quality information. The low 8 bits are arranged as QQSSSSLL, where
QQ represents the major quality, SSSS represents the quality substatus,
and LL represents the limit status.

You use the opcqparts function to extract the four quality fields from
the QualityID value. Alternatively, you can use the bit-wise functions
to extract the fields you are interested in. For example, to extract
the major quality, you can bit-wise AND the QualityID with 192 (the
decimal equivalent of binary 11000000) using the bitand function, and
shift the result 6 bits to the right using the bitshift function.
You use the opcqstr function to obtain the string equivalent of the four
quality fields from the QualityID value.
For more information on quality values, see Appendix A, OPC Quality
Strings.
QualityID is updated when you perform a read operation using read or
readasync, or when a subscription callback occurs.

Characteristics Access

Read-only

Applies to

daitem

Data type

double

Values

An integer from 0 to 65535. The default value

is 28 (representing the quality 'Bad: Out of
Service').

11-36

Downloaded from www.Manualslib.com manuals search engine

QualityID

See Also

Functions
bitand, bitshift, opcqparts, opcqstr, read, readasync, refresh

Properties
Quality, Value

11-37

Downloaded from www.Manualslib.com manuals search engine

ReadAsyncFcn

Purpose

Callback function file to execute when asynchronous read completes

Description

You configure ReadAsyncFcn to execute a callback function file

when an asynchronous read operation completes. You execute an
asynchronous read with the readasync function. A read async event
occurs immediately after the data is returned by the server to the
MATLAB workspace.
When a read async event occurs, the function specified in ReadAsyncFcn
is passed two parameters: Obj and EventInfo. Obj is the object
associated with the event, and EventInfo is an event structure
containing the fields Type and Data. The Type field is set to
'ReadAsync'. The Data field contains a structure with the fields
defined below.
FIeld Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred.

TransID

The transaction ID for the asynchronous read

operation.

GroupName

The group name.

Items

A structure containing information about each

item whose value or quality updated.

The Items structure contains the fields defined below.

FIeld Name

Description

ItemID

The item name.

Value

The data value.

TimeStamp

The time, as a MATLAB date vector, that the

servers cache was updated.

Read async event information is stored in the EventLog property.

11-38

Downloaded from www.Manualslib.com manuals search engine

ReadAsyncFcn

Characteristics Access

See Also

Read/write

Applies to

dagroup

Data type

string, function handle, or cell array

Values

The default value is @opccallback.

Functions
opccallback, readasync

Properties
EventLog

11-39

Downloaded from www.Manualslib.com manuals search engine

RecordsAcquired

Purpose

Number of records acquired

Description

RecordsAcquired is continuously updated to reflect the number of

records acquired since the start function was called. When you issue a
start command, the group object resets the value of RecordsAcquired
to 0 and flushes the memory buffer.

To find out how many records are available in the buffer, use
the RecordsAvailable property. You can also configure the
RecordsAcquiredFcn to generate an event each time a particular
number of records have been acquired.

Characteristics Access

See Also

Read-only

Applies to

dagroup

Data type

double

Values

The default value is 0.

Functions
start

Properties
Logging, RecordsAcquiredFcn, RecordsAvailable

11-40

Downloaded from www.Manualslib.com manuals search engine

RecordsAcquiredFcn

Purpose

Callback function file to execute when RecordsAcquired event occurs

Description

You configure RecordsAcquiredFcn to execute a callback function file

when a records acquired event is generated. A records acquired event is
generated each time the RecordsAcquired property reaches a multiple
of RecordsAcquiredFcnCount.
When a records acquired event occurs, the function specified in
RecordsAcquiredFcn is passed two parameters: Obj and EventInfo.
Obj is the object associated with the event, and EventInfo is an event
structure containing the fields Type and Data. The Type field is set
to 'RecordsAcquired'. The Data field contains a structure with the
fields defined below.
FIeld Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred

GroupName

The group name

RecordsAcquired

The number of records acquired in the current

logging session at the time the event occurred

Records acquired event information is not stored in the EventLog

property.

Characteristics Access

Read/write

Applies to

dagroup

Data type

String, function handle, or cell array

Values

The default value is an empty matrix ([]).

11-41

Downloaded from www.Manualslib.com manuals search engine

RecordsAcquiredFcn

See Also

Functions
start

Properties
EventLog, RecordsAcquired, RecordsAcquiredFcnCount

11-42

Downloaded from www.Manualslib.com manuals search engine

RecordsAcquiredFcnCount

Purpose

Number of records to acquire before RecordsAcquired event occurs

Description

A records acquired event is generated each time the number of records

acquired reaches a multiple of RecordsAcquiredFcnCount.

Characteristics Access

See Also

Read-only while logging

Applies to

dagroup

Data type

double

Values

Any integer in the range [0 Inf]. The default

value is 20.

Properties
RecordsAcquired, RecordsAcquiredFcn

11-43

Downloaded from www.Manualslib.com manuals search engine

RecordsAvailable

Purpose

Number of records available in OPC Toolbox engine

Description

RecordsAvailable indicates the number of records that are available

in the OPC Toolbox software engine. When you extract records from the
engine with the getdata function, the RecordsAvailable value reduces
by the number of records extracted. RecordsAvailable is reset to 0 and
the toolbox engine is cleared when you issue a start command.
Use the RecordsAcquired property to find out how many records have
been acquired since the start command was issued.

Characteristics Access

See Also

Read-only

Applies to

dagroup

Data type

double

Values

Any integer in the range [0 Inf]. The default

value is 0.

Functions
getdata, start

Properties
RecordsAcquired, RecordsToAcquire

11-44

Downloaded from www.Manualslib.com manuals search engine

RecordsToAcquire

Purpose

Number of records to acquire for logging session

Description

RecordsToAcquire specifies the number of records that must be

acquired before the engine automatically stops logging. When

RecordsAcquired reaches RecordsToAcquire, the Logging property is
set to 'off', and no more records are logged.

To continuously log records, specify a value of Inf.

Characteristics Access

See Also

Read-only while logging

Applies to

dagroup

Data type

double

Values

Any integer in the range [0 Inf]. The default

value is 120.

Properties
Logging, RecordsAvailable

11-45

Downloaded from www.Manualslib.com manuals search engine

ScanRate

Purpose

Fastest possible data update rate

Description

ScanRate describes the fastest possible rate at which a server can

update an item. The default value is 0, which indicates that the scan

rate is not known. Note that the scan rate may not be attainable by the
server due to network load, server load and other factors.

Characteristics Access

See Also

Read-only while logging

Applies to

dagroup

Data type

double

Values

The value is set by the server when a daitem object

is created or when you connect to the server.

Properties
UpdateRate

11-46

Downloaded from www.Manualslib.com manuals search engine

ServerID

Purpose

Server identity

Description

ServerID is the COM style program ID that the opcda object connects

to. The program ID is normally defined during installation of the OPC

server.
You use opcserverinfo to find a list of available servers and their
Server IDs.

Characteristics Access

See Also

Read-only while connected

Applies to

opcda

Data type

string

Values

The default value is specified during object creation.

Functions
opcda, opcserverinfo

Properties
Host

11-47

Downloaded from www.Manualslib.com manuals search engine

ShutDownFcn

Purpose

Callback function file to execute when OPC server shuts down

Description

You configure ShutDownFcn to execute a callback function file when the

OPC server shuts down. Prior to calling the ShutDownFcn callback, the
Status property of the opcda object is changed to 'disconnected'.
When a shutdown event occurs, the function specified in ShutDownFcn is
passed two parameters: Obj and EventInfo. Obj is the object associated
with the event, and EventInfo is an event structure containing the
fields Type and Data. The Type field is set to 'Shutdown'. The Data
field contains a structure with the following fields.
FIeld Name

Description

LocalEventTime

The time the event occurred, as a MATLAB date

vector.

Reason

The reason for the server shutdown.

Shutdown event information is stored in the EventLog property.

Characteristics Access

See Also

Read/write

Applies to

opcda

Data type

string, function handle, or cell array

Values

The default value is @opccallback.

Functions
opccallback

Properties
EventLog

11-48

Downloaded from www.Manualslib.com manuals search engine

StartFcn

Purpose

Callback function file to execute immediately before logging starts

Description

You configure StartFcn to execute a callback function file when all

prelogging steps have been completed. You start logging by calling the
start function. A start event occurs immediately before Logging is
set to 'on'.
When a start event occurs, the function specified in StartFcn is passed
two parameters: Obj and EventInfo. Obj is the object associated with
the event, and EventInfo is an event structure containing the fields
Type and Data. The Type field is set to 'Start'. The Data field contains
a structure with the fields given below.
FIeld Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred.

GroupName

The group name.

RecordsAcquired The number of records acquired in the current

logging session at the time the event occurred.

Start event information is stored in the EventLog property.

Characteristics Access

See Also

Read/write

Applies to

dagroup

Data type

string, function handle, or cell array

Values

The default value is an empty matrix ([]).

Functions
start

Properties
EventLog, Logging

11-49

Downloaded from www.Manualslib.com manuals search engine

Status

Purpose

Status of connection to OPC server

Description

Status can be 'disconnected' or 'connected'. You connect an opcda

object with the connect function and disconnect with the disconnect
function. If the opcda object is connected to a server and the server
shuts down, the Status property will be set to 'disconnected'.

Characteristics Access

See Also

Read-only

Applies to

opcda

Data type

string

Values

[ {'disconnected'} | 'connected' ]

Functions
connect, disconnect

Properties
ShutDownFcn

11-50

Downloaded from www.Manualslib.com manuals search engine

StopFcn

Purpose

Callback function file to execute immediately after logging stops

Description

You configure StopFcn to execute a callback function file when logging

has stopped. Logging stops when you issue a stop command, or when
the RecordsAcquired value reaches RecordsToAcquire.
When a stop event occurs, the function specified in StopFcn is passed
two parameters: Obj and EventInfo. Obj is the object associated with
the event, and EventInfo is an event structure containing the fields
Type and Data. The Type field is set to 'Stop'. The Data field contains
a structure with the fields given below.
FIeld Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred.

GroupName

The group name.

RecordsAcquired

The number of records acquired in the current

logging session at the time the event occurred.

Stop event information is stored in the EventLog property.

Characteristics Access

See Also

Read/write

Applies to

dagroup

Data type

string, function handle, or cell array

Values

The default value is an empty matrix ([]).

Functions
stop

Properties
EventLog, RecordsAcquired, RecordsToAcquire

11-51

Downloaded from www.Manualslib.com manuals search engine

Subscription

Purpose

Enable server update when data changes

Description

Subscription can be 'on' or 'off'. If Subscription is 'on', server

update notification is enabled for the group. The update occurs when
the server cache quality or value of the data associated with a daitem
object contained by the dagroup object changes. In order for the server
cache to be updated, the percent change in the item value must also be
greater than the value specified for the DeadbandPercent property.
A Subscription value of 'on' instructs the server to issue data change
events when items in the group are updated by the server. Additionally,
if an callback function file is specified for the DataChangeFcn property,
that function executes. If Subscription is 'off', the server might
still update item values and/or quality information, but no data change
event is generated.
Note that the refresh function is a special case of subscription, where
refresh forces a data change event for all active items.

Characteristics Access

See Also

Read/write

Applies to

dagroup

Data type

string

Values

[ 'off' | {'on'} ]

Functions
read, readasync, refresh

Properties
Active, DataChangeFcn, DeadbandPercent, UpdateRate

11-52

Downloaded from www.Manualslib.com manuals search engine

Tag

Purpose

Label to associate with OPC Toolbox object

Description

You configure Tag to be a string value that uniquely identifies an OPC

Toolbox object.
Tag is particularly useful when constructing programs that would
otherwise need to define the toolbox object as a global variable, or pass
the object as an argument between callback routines. You can return a
toolbox object with the opcfind function by specifying the Tag property
value.

Characteristics Access

See Also

Read/write

Applies to

dagroup, daitem, opcda

Data type

string

Values

The default value is an empty string ('').

Functions
opcfind

11-53

Downloaded from www.Manualslib.com manuals search engine

TimeBias

Purpose

Time bias of group

Description

TimeBias indicates the time difference between the server and client

machines. In some cases the data may have been collected by a device
operating in a time zone other than that of the client. Then it will be
useful to know what the time of the device was at the time the data was
collected (e.g., to determine what shift was on duty at the time).
The time is specified in minutes and can be positive or negative.

Characteristics Access

See Also

Read-only

Applies to

dagroup

Data type

double

Values

The default value is 0.

Properties
TimeStamp

11-54

Downloaded from www.Manualslib.com manuals search engine

Timeout

Purpose

Maximum time to wait for completion of instruction to server

Description

You configure Timeout to be the maximum time, in seconds, to wait for

completion of a synchronous read or a synchronous write operation.
If a time-out occurs, the read or write operation aborts. The default
value is 10.
You can use Timeout to abort functions that block access to the
MATLAB command line.
For asynchronous read or write operations, Timeout specifies the time
to wait for the server to acknowledge the request. It does not limit the
time for the instruction to be completed by the server.

Characteristics Access

See Also

Read/write

Applies to

opcda

Data type

double

Values

Any value in the range [0 Inf]. The default

value is 10.

Functions
read, readasync, write, writeasync

11-55

Downloaded from www.Manualslib.com manuals search engine

TimerFcn

Purpose

Callback function file to execute when predefined period passes

Description

You configure TimerFcn to execute a callback function file when a timer

event occurs. A timer event occurs when the time specified by the
TimerPeriod property passes. Timer events are only generated when
the Status property is set to 'connected'. Timer events will stop being
generated when the objects Status is set to 'disconnected', either by
a disconnect function call, or when the server shuts down.
Some timer events may not be processed if your system is significantly
slowed or if the TimerPeriod value is too small. Timer event
information is not stored in the EventLog property.

Characteristics Access

See Also

Read/write

Applies to

opcda

Data type

string, function handle, or cell array

Values

The default value is an empty matrix ([]).

Functions
connect, disconnect

Properties
TimerPeriod

11-56

Downloaded from www.Manualslib.com manuals search engine

TimerPeriod

Purpose

Period between timer events

Description

TimerPeriod specifies the time, in seconds, that must pass before the
callback function specified by TimerFcn is called.

Some timer events may not be processed if your system is significantly

slowed or if the TimerPeriod value is too small.

Characteristics Access

See Also

Read only while logging

Applies to

opcda

Data type

double

Values

Any value in the range [0.001 Inf]. The default

value is 10.

Functions
connect, disconnect

Properties
TimerFcn

11-57

Downloaded from www.Manualslib.com manuals search engine

TimeStamp

Purpose

Time when item was last read

Description

TimeStamp indicates the time when the Value and Quality properties

were obtained by the device (if this is available) or the time the server
updated or validated Value and Quality in its cache. TimeStamp is
updated when you perform an asynchronous or synchronous read
operation or when a subscription callback occurs.
TimeStamp is stored as a MATLAB date vector. You convert date
vectors to date strings with the datestr function, and to MATLAB date
numbers with the datenum function.

Characteristics Access

See Also

Read-only

Applies to

daitem

Data type

MATLAB date vector

Values

The default value is an empty matrix ([]).

Functions
datestr, datenum, datevec, read, readasync, refresh

Properties
Quality, Subscription, UpdateRate, Value

11-58

Downloaded from www.Manualslib.com manuals search engine

Type

Purpose

OPC Toolbox object type

Description

Type indicates the type of the object. The OPC Toolbox object types
are 'opcda', 'dagroup', and 'daitem'. Once an object is created, the
value of Type is automatically defined, and cannot be changed.

You can identify OPC Toolbox objects of a given type using the opcfind
function and the Type value.

Characteristics Access

See Also

Read-only

Applies to

dagroup, daitem, opcda

Data type

string

Values

The value is set during object creation.

Functions
opcfind

11-59

Downloaded from www.Manualslib.com manuals search engine

UpdateRate

Purpose

Rate, in seconds, at which subscription callbacks occur

Description

UpdateRate specifies the rate, in seconds, at which subscription

callbacks occur. Therefore, UpdateRate determines how often the

cached data can be updated and how often data change events can
occur. Consequently, UpdateRate also controls the rate at which data is
logged. You start logging data change events with the start function.
Data change events can occur only for active items in an active group.
Additionally, subscription must be enabled for the group.
Note that servers can select an update rate that differs from the
requested value. If this occurs, UpdateRate is automatically updated
with the returned value. By specifying an update rate of 0, updates
will occur as soon as new information becomes available for the
daitem object. New information is considered to be a change in the
Quality property or a change in the data Value that exceeds the
DeadbandPercent property value.

Characteristics Access

See Also

Read-only while logging

Applies to

dagroup

Data type

double

Values

Any value greater than or equal to 0. The default

value is 0.5.

Functions
start

Properties
Active, DeadbandPercent, Subscription

11-60

Downloaded from www.Manualslib.com manuals search engine

UserData

Purpose

Data to associate with OPC Toolbox object

Description

You configure UserData to store data that you want to associate with
an OPC Toolbox object. The object does not use this data directly, but
you can access it using the get function.

Characteristics Access

See Also

Read/write

Applies to

dagroup, daitem, opcda

Data type

Any MATLAB data type

Values

The default value is an empty matrix ([]).

Properties
Tag

11-61

Downloaded from www.Manualslib.com manuals search engine

Value

Purpose

Item value

Description

Value indicates the value that was last obtained from the OPC server
for the item defined by the ItemID property. The data type of the value
is given by the DataType property.

The value returned from the server may be different from the value of
the device to which the ItemID refers, if the DeadbandPercent for the
daitem objects parent group is not zero. The value is also updated
only periodically, based on the parent groups Active and UpdateRate
properties.
You determine the validity of Value by checking the Quality property
for the item.
Value is updated when you perform an asynchronous or synchronous

read operation or when a subscription callback occurs.

Characteristics Access

See Also

Read-only

Applies to

daitem

Data type

Any MATLAB data type

Values

The default value is an empty matrix ([]).

Functions
read, readasync, refresh

Properties
Active, DataType, DeadbandPercent, Quality, Subscription,
TimeStamp, UpdateRate

11-62

Downloaded from www.Manualslib.com manuals search engine

WriteAsyncFcn

Purpose

Callback function file to execute when asynchronous write completes

Description

You configure WriteAsyncFcn to execute a callback function file

when an asynchronous write operation completes. You execute an
asynchronous write with the writeasync function. A write async event
occurs immediately after the server notifies the client that data has
written to the device.
When a write async event occurs, the function specified in
WriteAsyncFcn is passed two parameters: Obj and EventInfo. Obj
is the object associated with the event, and EventInfo is an event
structure containing the fields Type and Data. The Type field is set
to 'WriteAsync'. The Data field contains a structure with the fields
defined below.
FIeld Name

Description

LocalEventTime

The time, as a MATLAB date vector, that the

event occurred.

TransID

The transaction ID for the asynchronous write

operation.
GroupName

The group name.

Items

A structure containing information about each

item whose value or quality was written.

The Items structure contains the fields defined below.

FIeld Name

Description

ItemID

The item name.

Write async event information is stored in the EventLog property.

11-63

Downloaded from www.Manualslib.com manuals search engine

WriteAsyncFcn

Characteristics

See Also

Access

Read/write

Applies to

dagroup

Data type

string, function handle, or cell array

Values

The default value is @opccallback.

Functions
opccallback, writeasync

Properties
EventLog

11-64

Downloaded from www.Manualslib.com manuals search engine

12
Block Reference

Downloaded from www.Manualslib.com manuals search engine

OPC Configuration

Purpose

Configure OPC clients to use in model, pseudo real-time control options,

and behavior in response to OPC errors and events

Library

OPC Toolbox

Description

The OPC Configuration block defines the OPC clients to be used in a

model, configures pseudo real-time behavior for the model, and defines
behavior for OPC errors and events.
The block has no input ports. One optional output port displays the
model latency (time spent waiting in each simulation step to achieve
pseudo real-time behavior).
You cannot place more than one OPC Configuration block in a model. If
you attempt to do so, an error message appears, and the second OPC
Configuration block becomes disabled.

12-2

Downloaded from www.Manualslib.com manuals search engine

OPC Configuration

Dialog
Box

Configure OPC Clients

Opens the OPC Client Manager for this model. Each model has a
list of clients associated with it. These clients are used during the
simulation to read or write data to an OPC server. See Using the
OPC Client Manager on page 7-18 for more information.
Error control
Defines actions that Simulink software must take when
OPC-specific errors and events are encountered. The available
actions are to produce an error and stop the simulation, produce a
warning and continue the simulation, or ignore the error or event.
The following table describes each error or event.

12-3

Downloaded from www.Manualslib.com manuals search engine

OPC Configuration

Error/Event

Description

Default

Items not available

on server

Defines the behavior for

items that are specified
in a Read or Write
block but do not exist
on the server when the
simulation starts.

error

Read/write errors

Defines the behavior

when a read or write
operation fails.

warn

Server unavailable

Defines the behavior

when the client cannot
connect to the OPC
server, or when the
server sends a shutdown
event to the client.

error

Pseudo real-time
violation

Defines the behavior

when the simulation
runs slower than
real time. See the
Pseudo real-time
simulation options for
more information.

warn

Pseudo real-time simulation

Allows you to configure options for running the simulation in
pseudo real time. When Enable pseudo real-time simulation
is checked, the model execution time matches the system clock as
closely as possible by slowing down the simulation appropriately.
The Speedup setting determines how many times faster than the
system clock the simulation runs. For example, a setting of 2
means that a 10-second simulation will take 5 seconds to complete.
Note that the real-time control settings do not guarantee real-time
behavior. If the model runs slower than real time, a pseudo

12-4

Downloaded from www.Manualslib.com manuals search engine

OPC Configuration

real-time latency violation error occurs. You can control how

Simulink responds to a pseudo real-time latency violation using
the settings in the Error control pane. You can also output
the model latency using the Show pseudo real-time latency
port setting.
Show pseudo real-time latency port
When checked, the pseudo real-time latency (in seconds) is output
from the block. Pseudo real-time latency is the time spent waiting
for the system clock during each step. If this value is negative, the
simulation runs slower than real time, and the behavior defined
in the Pseudo real-time violation setting determines the action
that Simulink takes.

See Also

OPC Read, OPC Write

12-5

Downloaded from www.Manualslib.com manuals search engine

OPC Quality Parts

Purpose

Convert OPC quality ID into vendor, major, minor, and limit status

Library

OPC Toolbox

Description

The OPC Quality Parts block converts an OPC quality ID vector into
four parts: the vendor status, major quality, quality substatus, and limit
status. The Quality port of an OPC Read block generates quality IDs.
For more information on quality parts, see Appendix A, OPC Quality
Strings.

See Also

OPC Read

12-6

Downloaded from www.Manualslib.com manuals search engine

OPC Read

Purpose

Read data from OPC server

Library

OPC Toolbox

Description

The OPC Read block reads data from one or more items on an OPC
server. The read operation takes place synchronously (from the cache or
from the device) or asynchronously (from the device).
The block outputs the values (V) of the requested items in the first
output, and optionally outputs the quality IDs (Q) and the time stamps
(T) associated with each data value in additional outputs. The time
stamp may be output as a serial date number (real-world time), or as the
number of seconds from the start of the simulation (simulation time).
The V,Q,T triple presented at the output ports is the last known data
for each of the items read by the block. Use the time stamp output to
determine when a sample last changed.
Note You must have an OPC Configuration block in your model to use
the OPC Read block. You cannot open the OPC Read dialog without
first including an OPC Configuration block in the model.

12-7

Downloaded from www.Manualslib.com manuals search engine

OPC Read

Dialog
Box

Import from Workspace

Allows you to import settings for the OPC Read block from a
dagroup object in the base workspace. The client, item IDs, and
sample time are updated based on the properties of the imported
group. The Value port data type is also set if all items in the
group have the same DataType property.
Client
Defines the OPC client associated with this block. You can add
additional clients to the list using Configure OPC Clients. For

12-8

Downloaded from www.Manualslib.com manuals search engine

OPC Read

more information, see Using the OPC Client Manager on page

7-18.
Item IDs
Shows the items to be read from the specified server. You can
add items to the list using Add Items, or delete items using
Delete. You can reorder the items in the list using Move Up
or Move Down. The order of the items determines the order of
their values in the block outputs.
Read mode
Defines the read mode for this block. Available options
are Asynchronous, Synchronous (cache), or Synchronous
(device). Synchronous reads have slightly more overhead than
asynchronous reads, but they are generally more reliable than
asynchronous reads.
Sample time
Defines the sample time for the block. For synchronous reads,
data is read from the server at the specified sample time. For
asynchronous reads, the sample time setting defines the update
rate for data change events.
Value port data type
Defines the data type for the value output. The OPC server is
responsible for converting all data to the required type.
Note For items with a Canonical Data Type of logical, the OPC
Read block will output -1 for signed data types, or the maximum
value for unsigned data types, when the item value is "true". A
value of 0 is output when the item value is "false".
Show quality port
When checked, the quality IDs of all the items are output in the
second port as a vector of unsigned 16-bit integers. Use the OPC
Quality Parts block to separate the quality ID into component
parts.

12-9

Downloaded from www.Manualslib.com manuals search engine

OPC Read

Show timestamp port

When checked, the timestamps for each of the items are output in
the last port as a vector of doubles. You choose whether to output
the timestamps as Seconds since start (i.e., simulation time) or
as Serial date numbers (i.e., real-world time).

See Also

OPC Configuration, OPC Quality Parts, OPC Write

12-10

Downloaded from www.Manualslib.com manuals search engine

OPC Write

Purpose

Write data to OPC server

Library

OPC Toolbox

Description

The OPC Write block writes data to one or more items on an OPC server.
The write operation takes place synchronously or asynchronously.
Each element of the input vector is written to the corresponding item in
the Item ID list defined for the OPC Write block.
Note You must have an OPC Configuration block in your model to use
the OPC Write block. You cannot open the OPC Write dialog without
first including an OPC Configuration block in the model.

Dialog
Box

12-11

Downloaded from www.Manualslib.com manuals search engine

OPC Write

Import from Workspace

Allows you to import settings for the OPC Write block from a
dagroup object in the base workspace. The client, item IDs, and
sample time are updated based on the properties of the imported
group.
Client
Defines the OPC client associated with this block. You can add
clients to the list using Configure OPC Clients. For more
information, see Using the OPC Client Manager on page 7-18.
ItemIDs
Shows the items to be written to the specified server. You can
add items to the list using Add Items, or delete items using
Delete. You can reorder the items in the list using Move Up or
Move Down. Each element of the input port is written to the
corresponding item in the list.
Write mode
Defines the write mode for this block. Available options are
Asynchronous and Synchronous. Synchronous writes have
slightly more overhead than asynchronous writes, but they are
generally more reliable than asynchronous writes.
Sample time
Defines the sample time for the block. Data is written to the
server at the specified sample time. You can specify 0 for
continuous mode, or -1 to inherit the sample time of the block
connected to the input of the OPC Write block.

See Also

OPC Configuration, OPC Read

12-12

Downloaded from www.Manualslib.com manuals search engine

A
OPC Quality Strings
OPC Toolbox software uses specific quality values defined by the OPC
Foundation, based on a major quality value, a substatus for that major quality
value, and a limit status indicating how the value is limited. This appendix
describes the standard quality strings defined by the OPC Foundation that are
used in the toolbox, and describes any special extensions that the toolbox uses.
An OPC quality value is a number ranging from 0 to 65535, made up of four
parts. The high 8 bits of the quality value represent the vendor-specific
quality information. The low 8 bits are arranged as QQSSSSLL, where QQ
represents the major quality, SSSS represents the quality substatus, and LL
represents the limit status.
The following sections describe the OPC quality values and strings associated
with each quality part.
Major Quality on page A-2
Quality Substatus on page A-3
Limit Status on page A-6
For more information on OPC quality strings, see the Quality property
reference page. The quality of an item is also stored in native value format
in the QualityID property of the daitem object.

Downloaded from www.Manualslib.com manuals search engine

OPC Quality Strings

Major Quality
OPC Toolbox software uses the following major quality values and strings.
The major quality is contained in bits 7 and 8 of the quality value.
Major Quality Strings Used in OPC Toolbox Software

Value

Quality
String

Bad

The value is not useful for the reason indicated by

the substatus. The table Bad Quality Substatus
Strings on page A-5 contains information about the
substatus for bad quality.

Uncertain

The quality of the value is uncertain for reasons

indicated by the substatus. The table Uncertain
Quality Substatus Strings on page A-3 contains
information about the substatus for uncertain
quality.

Good

The quality of the value is good. The table Good

Quality Substatus Strings on page A-3 contains
information about the substatus for good quality.

N/A

Repeat

The value is repeated from a previous known value

for this item. This toolbox-specific value occurs only
in data returned from getdata or opcread, when you
request array formatted values.

A-2

Downloaded from www.Manualslib.com manuals search engine

Description

Quality Substatus

Quality Substatus
Each major quality status has an additional substatus that describes the
quality of the value in more detail. The following tables describe the quality
substatus for each major quality.
Good Quality Substatus Strings on page A-3
Uncertain Quality Substatus Strings on page A-3
Bad Quality Substatus Strings on page A-5
Good Quality Substatus Strings
Value

Substatus String

Description

Non-specific

The value is good. There are no

special conditions.

Local Override

The value has been overridden.

Typically, this means that the device
has been disconnected from the OPC
server (either physically, or through
software) and a manually entered
value has been forced.

Uncertain Quality Substatus Strings

Value

Substatus String

Description

Non-Specific

The server has not published a

specific reason why the value is
uncertain.

Last Usable Value

Whatever was writing the data

value has stopped doing so. The
returned value should be regarded
as "stale." Note that this quality
value differs from 'Bad: Last
Known Value' in that the "bad"
quality is associated specifically
with a detectable communications

A-3

Downloaded from www.Manualslib.com manuals search engine

OPC Quality Strings

Uncertain Quality Substatus Strings (Continued)

Value

Substatus String

Description
error. The 'Uncertain: Last
Usable Value' string is associated
with the failure of some external
source to "put" something into the
value within an acceptable period of
time. You can examine the age of the
value using the TimeStamp property
associated with this quality.

Sensor Not Accurate

Either the value has pegged at one

of the sensor limits, or the sensor
is otherwise known to be out of
calibration via some form of internal
diagnostics.

Engineering Units
Exceeded

The returned value is outside the

limits defined for this value. Note
that this substatus does not imply
that the value is pegged at some
upper limit. The value may exceed
the engineering units even further
in future updates.

Sub-Normal

The value is derived from multiple

sources and has less than the
required number of good sources.

A-4

Downloaded from www.Manualslib.com manuals search engine

Quality Substatus

Bad Quality Substatus Strings

Value

Substatus String

Description

Non-Specific

The value is bad but no specific

reason is known.

Configuration Error

There is some server-specific

problem with the configuration.
For example, the item in question
is deleted from the running server
configuration.

Not Connected

The input is required to be logically

connected to something, but is not
connected. This quality may reflect
that no value is available at this
time, possibly because the data
source has not yet provided one.

Device Failure

A device failure has been detected.

Sensor Failure

A sensor failure has been detected.

Last Known Value

Communication between the device

and the server has failed. However,
the last known value is available.
Note that the age of the last known
value can be determined from the
TimeStamp property.

Comm Failure

Communication between the device

and server has failed. There is no
last known value available.

Out of Service

The Active state of the item or

group containing the item is set to
off. This quality is also used to
indicate that the item is not being
updated by the server for some
reason.

A-5

Downloaded from www.Manualslib.com manuals search engine

OPC Quality Strings

Limit Status
The limit status is not dependent on the major quality and substatus parts of
a quality value.
The following table lists the limit status values and strings used in OPC
Toolbox software.
Value

Limit Status String

Description

Not Limited

The value is free to move. Note that

when the limit status has this value,
it is omitted from any quality string
in the toolbox.

Low Limited

The value is fixed at some lower

limit.

High Limited

The value is fixed at some upper

limit.

Constant

The value is a constant and cannot

change.

A-6

Downloaded from www.Manualslib.com manuals search engine

B
OPC Server Item Properties
All server items defined in an OPC server name space have associated
properties that describe that server item in more detail. The properties
defined by the OPC Foundation are described in this appendix, under the
following sections.
Understanding OPC Server Item Properties on page B-2
OPC Specific Properties on page B-3
OPC Recommended Properties on page B-4
For more information on querying OPC server item properties, consult the
help for serveritemprops.

Downloaded from www.Manualslib.com manuals search engine

OPC Server Item Properties

Understanding OPC Server Item Properties

Every item defined by an OPC server has specific attributes, or properties,
that describe that server item in more detail. These properties include the
current Value, Quality and TimeStamp for the server item, plus additional
properties that a server may require in order to determine the quality of
a value, or to decide whether to generate a DataChange event for groups
that have a nonzero DeadbandPercent value. Exposure of the server item
properties to a client is intended to provide a client with more information
on a specific item, and is not intended to provide efficient access to large
amounts of data. Rather, you should use the read function to read data from
a large number of server items.
Each property is identified by a Property ID, or PropID, which is an integer
value. The OPC Data Access Specification defines three sets of these
properties, based on their PropID.
OPC Item Property Sets
Set Name

ID Range

Description

OPC Specific

1-99

Information directly related to the OPC

server for that item.

OPC
Recommended

100-4999

Additional information which is

commonly associated with items, such as
ranges of valid values, alarm limits, etc.

Vendor Specific

5000 or
greater

Specific properties defined by an OPC

server vendor. Since these vary from
vendor to vendor, the actual descriptions
are not presented in this appendix.

Each of the property sets defined by the OPC Foundation is presented in

the following sections.
Note OPC servers must implement the OPC specific properties. However, the
recommended properties are not mandatory, and an OPC server could provide
any subset of the recommended properties, or none of them.

B-2

Downloaded from www.Manualslib.com manuals search engine

OPC Specific Properties

OPC Specific Properties

OPC Specific Properties
PropID

Description

Item Canonical DataType

The data type of the item as stored on the OPC server.
This property is also exposed in the CanonicalDataType
property of the daitem object.

Item Value
The value that was last obtained from the OPC server
for the item. This property is the same as the Value
property of the daitem object. Querying this property
behaves like a read operation from the device.

Item Quality
The quality of the items Value property. This property
is the same as the Quality property of the daitem object.
Querying this property behaves like a read operation
from the device.

Item Timestamp
The time that the Value and Quality was obtained by
the device (if this is available) or the time the server
updated or validated the Value and Quality in its cache.
This property is the same as the TimeStamp property of
the daitem object. Querying this property behaves like a
read operation from the device.

Item Access Rights

The ability of the server to read or write data to this item.

Server Scan Rate

Represents the fastest rate at which the server could
obtain data from the underlying data source. The
accuracy of this value could be affected by system load
and other factors, and is not a guaranteed rate.

7-99

Reserved for future use

B-3

Downloaded from www.Manualslib.com manuals search engine

OPC Server Item Properties

OPC Recommended Properties

The Recommended Properties are divided into the following tables.
Recommended Properties Related to the Item Value on page B-4
Recommended Properties Related to Operator Displays on page B-5
Recommended Properties Related to Alarm and Condition Values on page
B-6
Recommended Properties Related to the Item Value
PropID

Description

100

EU Units
The engineering units for this item.

101

Item Description
A description of the item.

102

High EU
Present only for analog data. Represents the highest
value likely to be obtained in normal operation. Also
used by servers that support non-zero DeadbandPercent
values for a group.

103

Low EU
Present only for analog data. Represents the lowest
value likely to be obtained in normal operation. Also
used by servers that support non-zero DeadbandPercent
values for a group.

104

High Instrument Range

Represents the highest value that can be returned by the
instrument.

105

Low Instrument Range

Represents the highest value that can be returned by the
instrument.

B-4

Downloaded from www.Manualslib.com manuals search engine

OPC Recommended Properties

Recommended Properties Related to the Item Value (Continued)

PropID

Description

106

Contact Close Label

Present only for discrete data. Represents a string to
be associated with this contact when it is in the closed
(non-zero) state.

107

Contact Open Label

Present only for discrete data. Represents a string to be
associated with this contact when it is in the open (zero)
state.

108

Item Timezone
The difference in minutes between the items UTC
Timestamp and the local time in which the item value
was obtained. OPC Toolbox software does not use this
property to adjust time stamps for an item.

109-199

Reserved for future use.

Recommended Properties Related to Operator Displays

PropID

Description

200

Default Display
The name of an operator display associated with this
item.

201

Current Foreground Color

The COLORREF in which the item should be displayed.

202

Current Background Color

The COLORREF in which the item should be displayed.

203

Current Blink
Defines whether a display of this item should blink.

204

BMP File
Bitmap file associated with this item.

205

Sound File
.WAV or .MID file associated with this item.

B-5

Downloaded from www.Manualslib.com manuals search engine

OPC Server Item Properties

Recommended Properties Related to Operator Displays (Continued)

PropID

Description

206

HTML File
URL reference for this item.

207

AVI File
Video file associated with this item.

208-299

Reserved for future OPC use.

Recommended Properties Related to Alarm and Condition Values

PropID

Description

300

Condition Status
The current alarm condition status associated with the
item.

301

Alarm Quick Help

A short text string providing a brief set of instructions for
the operator to follow when this alarm occurs.

302

Alarm Area List

An array of strings indicating the plant or alarm areas
which include this item.

303

Primary Alarm Area

A string indicating the primary plant or alarm area
including this item.

304

Condition Logic
An arbitrary string describing the test being performed.

305

Limit Exceeded
For multistate alarms, the condition exceeded.

306

Deadband

307

HiHi Limit

308

Hi Limit

309

Lo Limit

B-6

Downloaded from www.Manualslib.com manuals search engine

OPC Recommended Properties

Recommended Properties Related to Alarm and Condition Values

(Continued)
PropID

Description

310

LoLo Limit

311

Rate of Change Limit

312

Deviation Limit

313-4999

Reserved for future OPC use.

B-7

Downloaded from www.Manualslib.com manuals search engine

OPC Server Item Properties

B-8

Downloaded from www.Manualslib.com manuals search engine

Index
A
Index

AccessRights property 11-2

Active property 11-3

data change events 4-13

Active status
daitem object 3-7
addgroup function 9-2
additem function 9-4
array formatted data
description 5-15
missing data 5-16
asynchronous read 4-5
multiple values 4-10
asynchronous write
using 4-7

definition 6-5
information returned 6-11
cancelasync function 9-6
CancelAsyncFcn property 11-5
Canonical Datatype 2-16
CanonicalDataType property 11-7
cleareventlog function 9-7
Client object 1-6
clonegroup function 9-8
COM Variant 3-6
COM Variants
converting to MATLAB data types 5-18
connect function 9-10
copyobj function 9-11

D
B
blocks
OPC Configuration 12-2
OPC Quality Parts 12-6
OPC Read 12-7
OPC Write 12-11
using the OPC Toolbox block library 7-1

C
callback 6-1
callback functions
as text string 6-18
creating 6-16
enabling and disabling 6-20
specifying 6-18
specifying as cell array 6-19
specifying as function handle 6-19
callback properties
list of 6-5
cancel async event
cancelasync function 9-6
CancelAsyncFcn property 11-5

dagroup object 1-6

creating 3-2
example 2-12
using 3-5
viewing summary 3-3
daitem object 1-6
Active status 3-7
creating 3-5
example 2-17
disabling 4-14
using 3-8
viewing summary 3-7
data change event
DataChangeFcn property 11-8
forcing 4-14
information returned 6-11
notification 4-12
OPC data returned 5-5
processing 4-15
UpdateRate property 11-60
using callback 4-15
data conversion
read operations 5-20

Index-1

Downloaded from www.Manualslib.com manuals search engine

Index

write operations 5-20

data type 5-18
conversion during write 4-6
converting to COM Variants 5-18
specifying at creation 3-6
DataChangeFcn property 11-8
data change event response 4-16
DataType property 11-10
DCOM 1-28
configuring 1-11
DeadbandPercent property 11-12
effect on logging 4-21
delete function 9-13
disconnect function 9-14
disconnected client
building hierarchy 3-8
disp function 9-15

additem 9-4

by category 8-1
cancelasync 9-6
cleareventlog 9-7
clonegroup 9-8
connect 9-10
copyobj 9-11
delete 9-13
disconnect 9-14
disp 9-15
flatnamespace 9-17
flushdata 9-18
genslread 9-19
genslwrite 9-20
get 9-21
getdata 9-22
getnamespace 9-26

getting help 1-9

E
error event
definition 6-6
information returned 6-11
ErrorFcn property 11-14
event structures 6-10
EventLog property 11-16
retrieving information from 6-13
EventLogMax property 11-19
events
retrieving event information 6-10
types of 6-5

F
flatnamespace function 9-17
flushdata function 9-18

frames acquired events

example 6-21
functions
addgroup 9-2

Index-2

Downloaded from www.Manualslib.com manuals search engine

isvalid 9-29
load 9-30
makepublic 9-31
obj2mfile 9-32
opccallback 9-34
opcda 9-35
opcfind 9-36
opchelp 9-38
opcqid 9-40
opcqparts 9-41
opcqstr 9-42
opcread 9-43
opcregister 9-47
opcreset 9-48
opcserverinfo 9-49
opcstruct2array 9-50
opcstruct2timeseries 9-52
opcsupport 9-54
opctool 9-55
openosf 9-56
peekdata 9-57
propinfo 9-59

Index

read 9-61
readasync 9-63
refresh 9-65
removepublicgroup 9-67
save 9-68
serveritemprops 9-69
serveritems 9-71
set 9-74
showopcevents 9-77
start 9-78
stop 9-80
trend 9-81
wait 9-84
write 9-85
writeasync 9-87

item ID
daitem object 1-6
OPC server name spaces 1-4
server item 1-5
item object 1-6
item properties B-1
Item property 11-23
ItemID property 11-24

L
load function 9-30
LogFileName property 11-25

help
on functions 1-9
Host property 11-22
hostname 2-4

controlling log destination 4-22

logged data
array format 5-15
converting to arrays 5-16
structure format 5-12
logging 4-17
callbacks 4-23
characteristics 4-17
configuring 4-20
destination 4-22
duration of 4-21
example 4-18
monitoring progress 4-24
retrieving data 4-26
starting 4-24
stopping 4-25
Logging property 11-27
monitoring progress of logging task 4-24
LoggingMode property 11-28
controlling log destination 4-22
LogToDiskMode property 11-30
controlling log destination 4-22

G
genslread function 9-19
genslwrite function 9-20
get function 9-21
getdata function 9-22

logging OPC server data 4-27

getnamespace function 9-26
group name 3-3
Group object 1-6
Group property 11-20
GroupType property 11-21

inactive items
read operation 4-4
isvalid function 9-29

makepublic function 9-31

Matrikon OPC Simulation Server

Index-3

Downloaded from www.Manualslib.com manuals search engine

Index

installing 1-18

N
Name property 11-32

name space 1-4

flat 1-5
hierarchical 1-5

O
obj2mfile function 9-32

object properties
getting information about 3-19
setting 3-20
special read only modes 3-22
viewing all values 3-18
viewing settable 3-21
viewing specific value 3-19
object vectors
constructing 3-10
definition 3-9
limitations 3-10
read and write 4-8
using 3-12
OPC
about 1-3
OPC Configuration block 12-2
OPC Data Access client 1-6
OPC Data Access Group 1-6
OPC Data Access Item 1-6
OPC Foundation Core Components 1-10
OPC GUI
Logging Pane 2-24
OPC item properties B-1
OPC Quality Parts block 12-6
OPC quality strings A-1
OPC Read block 12-7
OPC recommended properties B-4
OPC server ProgId 1-6

Index-4

Downloaded from www.Manualslib.com manuals search engine

OPC specific properties B-3

OPC Toolbox block library
using 7-1
OPC Toolbox objects 3-1
configuring 3-17
deleting 3-23
loading 3-25
saving 3-25
server relationship 1-7
OPC Toolbox Objects toolbar 2-10
OPC Toolbox software
basic procedure 2-2
OPC Write block 12-11
opccallback function 9-34
read operations 4-5
using default callback function 6-2
opcda client object
connecting 2-10
creating 2-6
opcda function 9-35
opcda object 1-6
opcfind function 9-36
using 3-25
opchelp function 9-38
opcqid function 9-40
opcqparts function 9-41
opcqstr function 9-42
opcread function 9-43
filtering retrieved data 4-28
opcregister function 9-47
opcreset function 9-48
opcserverinfo function 9-49
opcstruct2array function 9-50
opcstruct2timeseries function 9-52
opcsupport function 9-54
opctool

example 2-3
opctool function 9-55
openosf function 9-56

Index

Subscription 11-52
Tag 11-53
TimeBias 11-54
Timeout 11-55
TimerFcn 11-56
TimerPeriod 11-57
TimeStamp 11-58
Type 11-59
UpdateRate 11-60
UserData 11-61
Value 11-62
WriteAsyncFcn 11-63

Parent property 11-33

peekdata function 9-57

properties
AccessRights 11-2
Active 11-3

by category 10-1
CancelAsyncFcn 11-5
CanonicalDataType 11-7
DataChangeFcn 11-8
DataType 11-10
DeadbandPercent 11-12
ErrorFcn 11-14
EventLog 11-16
EventLogMax 11-19
Group 11-20
GroupType 11-21
Host 11-22
Item 11-23
ItemID 11-24
LogFileName 11-25
Logging 11-27
LoggingMode 11-28
LogToDiskMode 11-30
Name 11-32
Parent 11-33
Quality 11-34
QualityID 11-36
ReadAsyncFcn 11-38
RecordsAcquired 11-40
RecordsAcquiredFcn 11-41
RecordsAcquiredFcnCount 11-43
RecordsAvailable 11-44
RecordsToAcquire 11-45
ScanRate 11-46
ServerID 11-47
ShutDownFcn 11-48
StartFcn 11-49
Status 11-50
StopFcn 11-51

property ID 1-26
propinfo function 9-59

Q
Quality property 11-34
QualityID property 11-36

R
read async event
definition 6-6
information returned 6-11
readasync function 9-63
ReadAsyncFcn property 11-38
using read operations 4-5
read function 9-61
read operation
asynchronous 4-5
synchronous 4-2
read-only
whileConnected 3-22
whileLogging 3-22
whilePublic 3-22
readasync function 5-4 9-63
ReadAsyncFcn property 11-38
records acquired event
configuring logging callbacks 4-23

Index-5

Downloaded from www.Manualslib.com manuals search engine

Index

definition 6-7
information returned 6-12
RecordsAcquiredFcn property 11-41
RecordsAcquiredFcnCount property 11-43
RecordsAcquired property 11-40
monitoring progress of logging task 4-24
RecordsAcquiredFcn property 11-41
RecordsAcquiredFcnCount property 11-43
RecordsAvailable property 11-44
monitoring progress of logging task 4-25
RecordsToAcquire property 11-45
effect on logging 4-21
refresh function 9-65
using 4-14
removepublicgroup function 9-67

S
save function 9-68
ScanRate property 11-46

server ID
allocation 2-4
definition 1-4
determining 1-19
server item 3-2
server name space
browsing 1-23
browsing graphically 2-14
view flat 2-15
view hierarchical 2-14
server tag 1-5
ServerID property 11-47
serveritemprops function 9-69
serveritems function 9-71
set function 9-74
showopcevents function 9-77
shutdown event 11-48
definition 6-7
information returned 6-12
ShutDownFcn property 11-48

Index-6

Downloaded from www.Manualslib.com manuals search engine

start event
configuring logging callbacks 4-23
definition 6-8
information returned 6-12
StartFcn property 11-49
start function 9-78
StartFcn property 11-49
Status property 11-50
stop event
configuring logging callbacks 4-23
definition 6-8
information returned 6-12
StopFcn property 11-51
stop function 9-80
StopFcn property 11-51
structure formatted data
converting to arrays 5-13
example of using 5-8
returned from logging 5-12
understanding 5-8
when to use 5-13
subscription 4-12
Subscription property 11-52
data change events 4-13
synchronous read 4-2
inactive items 4-4
Synchronous read
multiple values 4-9
synchronous write
using 4-6
system requirements
OPC Toolbox software 1-8

T
tag 2-13
Tag property 11-53
TimeBias property 11-54
Timeout property 11-55
timer event

Index

definition 6-9
information returned 6-13
TimerFcn property 11-56
TimerPeriod property 11-57
TimeStamp property 11-58
transaction ID
from read 4-5
from write 4-7
trend function 9-81
troubleshooting 1-28
Type property 11-59

U
UpdateRate property 11-60

data change events 4-13

effect on logging 4-21
UserData property 11-61

V
Value property 11-62

W
wait function 9-84

write async event

definition 6-9
information returned 6-11
writeasync function 9-87
WriteAsyncFcn property 11-63
write function 9-85
write operation
asynchronous 4-7
multiple values 4-10
synchronous 4-6
writeasync function 9-87
WriteAsyncFcn property 11-63

Index-7

Downloaded from www.Manualslib.com manuals search engine