Industrial Communication 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
any MATLAB® numeric array data type, such as
'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-
nItemslist 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.
nItemsarray of values for each item ID defined in the
ItemIDvariable, at each time stamp defined by the
TimeStamparray. Each column of the
Valuearray represents the history of values for the corresponding item in the
ItemIDarray. Each row corresponds to one record. See Treatment of Missing Data for information on how the
Valuearray is populated.
nItemscell array of character vectors. Each column represents the history of qualities for the corresponding item in the
ItemIDarray. 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
nItemsarray of time stamps for each value in the
Valuefield. The time stamps are in MATLAB date number format. For more information on MATLAB date numbers, see the
nRecs-by-1 array of times that the record was received by the toolbox (the
LocalEventTimefield of the record in structure format). The times are in MATLAB date number format. For more information on MATLAB date numbers, see the
Conversion of Logged Data to Arrays
When you request array-formatted data from
opcread, you must define the desired data type for the
Value array. Industrial Communication Toolbox automatically converts each record of logged data from the item's 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 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 discusses how the toolbox deals with this issue.
Treatment of Missing Data
When the toolbox 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 an entry for that item,
NaNis used to fill in the missing entry in the first row of the
Valuearray. The equivalent
NaNvalue for integer and logical data types is
Quality— The missing entry is filled with the specific quality of
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
array allocated to that record and item.
'cell' data type, the toolbox 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
'uint32', the resulting
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.