Main Content

daitem Properties

(Not recommended) Configure OPC daitem object

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

Use the properties of the daitem object to examine item values, quality, timestamps, types, and so on.

General Settings

expand all

This property is read-only.

AccessRights represents the server’s ability to access a single OPC data item. The property value can be 'read', 'write', or 'read/write', with the following effects:

  • 'read' — You can read the server item's value.

  • 'write' — You can write values to the server item.

  • 'read/write' — You can read and change the server item's value. If you attempt a read or write operation on an item that does not have the required access rights, the server might return an error.

The value is set by the server when an item is created.

Example: 'read'

Data Types: char

This property is read-only.

CanonicalDataType indicates the data type of the item as stored on the OPC server. The MATLAB® supported data types are indicated in the DataType property.

You can specify that the item's 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.

Data Types: char

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

currency

VT_CY

double

date

VT_DATE

double

logical

VT_BOOL

logical

double

VT_EMPTY

Empty array ([])

Example: 'double'

Data Types: char

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 server's 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 server's name space using the getnamespace or serveritems functions.

Data Types: char

This property is read-only.

For daitem objects, Parent indicates the dagroup object that contains the daitem object.

Data Types: DA group object

This property is read-only.

Quality indicates the quality of the daitem object’s Value property as a character vector. You can use the Quality property to determine if a value is useful or not.

The Quality is made up of a major quality, a substatus, and an optional limit status, arranged as a character vector 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.

The default value is 'Bad: Out of Service'.

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, see OPC Quality.

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.

Example: 'Bad: Out of Service'

Data Types: char

This property is read-only.

QualityID is a numeric indication of the quality of the daitem object's 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 four quality fields from the QualityID value.

For more information, see OPC Quality.

QualityID is updated when you perform a read operation using read or readasync, or when a subscription callback occurs.

Example: 28

Data Types: double

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 might not be attainable by the server due to network load, server load, and other factors.

The value is initially set by the server when a daitem object is created or when you connect to the server.

Data Types: double

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.

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 can convert date vectors to date character vectors with the datestr function, and to MATLAB date numbers with the datenum function.

Data Types: date vector

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

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.

This property is read-only.

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 object's parent group is not zero. The value is also updated only periodically, based on the parent group's 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.

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

Version History

Introduced before R2006a

expand all

See Also

Properties

Functions