Array-Formatted Data
Array Content
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 '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
— AnnRecs
-by-nItems
array of values for each item ID defined in theItemID
variable, at each time stamp defined by theTimeStamp
array. Each column of theValue
array represents the history of values for the corresponding item in theItemID
array. Each row corresponds to one record. See Treatment of Missing Data for information on how theValue
array is populated.Quality
— AnnRecs
-by-nItems
cell array of character vectors. Each column represents the history of qualities for the corresponding item in theItemID
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
— AnnRecs
-by-nItems
array of time stamps for each value in theValue
field. The time stamps are in MATLAB date number format. For more information on MATLAB date numbers, see thedatenum
function help.EventTime
— AnnRecs
-by-1 array of times that the record was received by the toolbox (theLocalEventTime
field of the record in structure format). The times are in MATLAB date number format. For more information on MATLAB date numbers, see thedatenum
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. 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 equivalentNaN
(not a number) entry is used. For example, if the very first record does not contain an entry for that item,NaN
is used to fill in the missing entry in the first row of theValue
array. The equivalentNaN
value for integer and logical data types is0
.Quality
— The missing entry is filled with the specific quality of'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, 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 '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.