Main Content

dagroup Properties

(To be removed) Configure OPC dagroup object

expand all in page

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 dagroup object to control reading, writing, logging, and so on.

General Settings

expand all

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 server's 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 (1)

The DeadbandPercent property affects only items that have an analog 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 might 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 is 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.

Example: 10

Data Types: double

This property is read-only.

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 other OPC clients on the network.

Example: 'private'

Data Types: char

This property is read-only.

Item is a vector of daitem objects contained in 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.

Data Types: daitem

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

This property is read-only.

For dagroup objects, Parent indicates the opcda client object that contains the group.

Data Types: DA client object

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

This property is read-only.

TimeBias indicates the time difference between the server and client machines. In some cases the data might have been collected by a device operating in a time zone other than that of the client. Then it is useful to know what the time of the device was when the data was collected (e.g., to determine what shift was on duty at the time).

The time is indicated in minutes, and can be positive or negative.

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: 'dagroup'

Data Types: char

UpdateRate specifies the rate, in seconds, at which subscription callbacks occur. This 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.

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.

Example: 1.0

Data Types: double

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 CancelAsyncFcn to execute a callback function 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.

Example: @opccallback

Data Types: char | cell | function_handle

You configure DataChangeFcn to execute a callback function 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 server's cache was updated

Data change event information is not stored in the EventLog property

Example: @readNewData

Data Types: char | cell | function_handle

You configure ReadAsyncFcn to execute a callback function 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 server's cache was updated.

Read async event information is stored in the EventLog property.

Example: @opccallback

Data Types: char | cell | function_handle

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.

Example: @readNewRecords

Data Types: char | cell | function_handle

A records acquired event is generated each time the number of records acquired reaches a multiple of RecordsAcquiredFcnCount.

Example: 20

Data Types: double

You configure StartFcn to execute a callback function 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.

Example: @opcLogStart

Data Types: char | cell | function_handle

You configure StopFcn to execute a callback function 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.

Example: @opcLogStop

Data Types: char | cell | function_handle

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.

Example: @opccallback

Data Types: char | cell | function_handle

Subscription and Logging Settings

expand all

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 the dagroup object. Set Active to 'off' when you are temporarily not interested in that daitem or dagroup object's 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

Both group and items must be active. Inactive items in active groups, and all items in inactive groups, return bad quality.

readasync

N/A

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 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.

Example: 'on'

Data Types: char

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 can 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
...

Example: 'opcdatalog.olf'

Data Types: char

This property is read-only.

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.

Example: 'on'

Data Types: char

LoggingMode can be set to 'disk', 'memory', or 'disk&memory', with the following effects:

  • 'disk' — DataChange events (records) are stored to the disk file specified by LogFileName.

  • 'memory' (default) — Records are stored to memory (the buffer).

  • 'disk&memory' — Records are stored to memory and to a disk file.

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.

Example: 'disk'

Data Types: char

LogToDiskMode can be set to 'append', 'overwrite', or 'index', with the following effects:

  • 'append' — 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.

  • 'overwrite' — The log file is overwritten each time start is called.

  • 'index' (default) — 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 results in the second object failing during the start operation.

Example: 'append'

Data Types: char

This property is read-only.

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.

Example: 20

Data Types: double

This property is read-only.

RecordsAvailable indicates the number of records that are available in the Industrial Communication 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.

Example: 20

Data Types: double

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.

Example: 480

Data Types: double

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 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.

Example: 'on'

Data Types: char

Version History

Introduced before R2006a

expand all

See Also

Properties

Functions