Main Content

opcda Properties

(To be removed) Configure OPC DA client

Support for the OPC Data Access (DA) standard will be removed in a future release. Instead use OPC Unified Architecture (UA). See Version History.

Use the properties of the opcda client object to access server connection parameters and specify other high level behaviors.

General Settings

expand all

This property is read-only.

EventLog contains a structure array that stores information related to Industrial Communication 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.

Example

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

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: [2004 1 13 16 16 35.2100]
           TransID: 2
         GroupName: 'EvtLogExample'
             Items: [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]

Data Types: struct

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.

Example: 1000

Data Types: double

This property is read-only.

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.

This property is read-only.

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.

Data Types: char

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 character vector, and is used for display and identification purposes only.

Data Types: char

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.

Use opcserverinfo to find a list of available servers and their server IDs.

Data Types: char

This property is read-only.

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 is set to 'disconnected'.

Example: 'connected'

Data Types: char

You configure Tag to be a character vector value that uniquely identifies an OPC 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.

Data Types: char

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 timeout occurs, the read or write operation aborts. You can set the property to any value in the range [0 Inf]. 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.

Example: 60

Data Types: double

This property is read-only.

Type indicates the type of the object. The OPC 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 objects of a given type using the opcfind function and the Type value.

Example: 'opcda'

Data Types: char

You can configure UserData to store data that you want to associate with an OPC object. The object does not use this data directly, but you can access it using the get function.

Callback Function Settings

expand all

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.

Example: @opccallback

Data Types: char | cell | function_handle

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.

Example: @opccallback

Data Types: char | cell | function_handle

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 object's 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.

Example: @timercallback

Data Types: char | cell | function_handle

TimerPeriod specifies the time, in seconds, that must pass before the callback function specified by TimerFcn is called. The setting can be any value in the range [0.001 Inf]. The default value is 10.

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

Example: 1

Data Types: double

Version History

Introduced before R2006a

expand all

See Also

Properties

Functions