Learn more about OPC Toolbox

Understanding Array Formatted Data

On this page…
Array Content Conversion of Logged Data to Arrays

Array Content

OPC 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 — An nRecs-by-nItems array of values for each item ID defined in the ItemID variable, at each time stamp defined by the TimeStamp array. Each column of the Value array represents the history of values for the corresponding item in the ItemID array. Each row corresponds to one record. See Treatment of Missing Data for information on how the Value array is populated.

• Quality — An nRecs-by-nItems cell array of quality strings. Each column represents the history of qualities for the corresponding item in the ItemID 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 — An nRecs-by-nItems array of time stamps for each value in the Value field. The time stamps are in MATLAB date number format. For more information on MATLAB date numbers, see the datenum function help.

• EventTime — An nRecs-by-1 array of times that the record was received by OPC Toolbox software (the LocalEventTime field of the record in structure format). The times are in MATLAB date number format. For more information on MATLAB date numbers, see the datenum function help.

Back to Top

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. OPC Toolbox software 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 OPC Toolbox software 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, NaN is used to fill in the missing entry in the first row of the Value array. The equivalent NaN value for integer and logical data types is 0.

• Quality — The missing entry is filled with the specific quality string '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, OPC Toolbox software 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.

Back to Top

Working with Structure Formatted Data

Working with Different Data Types

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS