getdata

Retrieve logged records from OPC Toolbox engine to MATLAB workspace

Syntax

S = getdata(GObj)
S = getdata(GObj, NRec)
TSCell = getdata(GObj, 'timeseries')
TSCell = getdata(GObj, NRec, 'timeseries')
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, 'DataType')
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, NRec, 'DataType')

Description

S = getdata(GObj) returns the number of records specified in the RecordsToAcquire property of dagroup object GObj, from the OPC Toolbox™ software engine. GObj must be a scalar dagroup object.

S is an NRec-by-1 structure array, where NRec is the number of records returned. S contains the fields 'LocalEventTime' and 'Items'. LocalEventTime is a date vector corresponding to the local event time for that record. Items is an NItems-by-1 structure array containing the fields shown below.

Field Name

Description

ItemID

The fully qualified tag name, as a string.

Value

The data value. The data type is defined by the item's DataType property.

Quality

The data quality, as a string. See OPC Quality Strings for a description of quality strings.

TimeStamp

The time the value was changed, as a date vector.

S = getdata(GObj, NRec) retrieves the first NRec records from the toolbox engine.

TSCell = getdata(GObj, 'timeseries') and
TSCell = getdata(GObj, NRec, 'timeseries') assign the data received from the toolbox engine to a cell array of time series objects. TSCell contains as many time series objects as there are items in the group, with the name of each time series object set to the item ID. The quality value stored in the time series object is offset from the quality value returned by the OPC server by 128. The quality strings displayed by each is the same. Because each record logged might not contain information for every item, the time series objects have only as many data points as there are records containing information about that particular item ID.

[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, 'DataType') and
[ItmID, Val, Qual, TStamp, ETime] = getdata(GObj, NRec, 'DataType') assign the data retrieved from the toolbox engine to separate arrays. Valid data types are 'double', 'single', 'int8', 'int16', 'int32', 'uint8', 'uint16', 'uint32', 'logical', 'currency', 'date', and 'cell'.

ItmID is a 1-by-NItem cell array of item names.

Val is an NRec-by-NItem array of values with the data type specified. If a data type of 'cell'is specified, then Val is a cell array containing data in the returned data type for each item. Otherwise, Val is a numeric array of the specified data type.

    Note   'DataType' must be set to 'cell' when retrieving records containing strings or arrays of values.

Qual is an NRec-by-NItem array of quality strings for each value in Val.

TStamp is an NRec-by-NItem array of MATLAB® date numbers representing the time when the relevant value and quality were stored on the OPC server.

ETime is an NRec-by-1 array of MATLAB date numbers, corresponding to the local event time for each record.

Each record logged may not contain information for every item returned, since data for that item may not have changed from the previous update. When data is returned as a numeric matrix, the missing item columns for that record are filled as follows.

Argument

Behavior for Missing Items

Val

The corresponding value entry is set to the previous value of that item, or to NaN if there is no previous value.

Qual

The corresponding quality entry is set to 'Repeat'.

TStamp

The corresponding time stamp entry is set to the first valid time stamp for that record.

getdata is a blocking function that returns execution control to the MATLAB workspace when one of the following conditions is met:

  • The requested number of records becomes available.

  • The logging operation is automatically stopped by the engine. If fewer records are available than the number requested, a warning is generated and all available records are returned.

  • You issue Ctrl+C. The logging task does not stop, and no data is removed from the toolbox engine.

When getdata completes, the object's RecordsAvailable property is reduced by the number of records returned by getdata.

Examples

Configure and start a logging task for 60 seconds of data:

da = opcda('localhost','Matrikon.OPC.Simulation');
connect(da);
grp = addgroup(da,'ExOPCREAD');
itm1 = additem(grp,'Triangle Waves.Real8');
itm2 = additem(grp,'Saw-Toothed Waves.Int2');
grp.LoggingMode = 'memory';
grp.RecordsToAcquire = 60;
start(grp);

Retrieve the first two records into a structure. This operation waits for at least two records:

s = getdata(grp,2)

Retrieve all the remaining data into a double array and plot it with a legend:

[itmID, val, qual, tStamp] = getdata(grp,'double');
plot(tStamp(:,1), val(:,1), tStamp(:,2), val(:,2));
legend(itmID);
datetick x keeplimits
Was this topic helpful?