Getpidata

Purpose

Uses the current PI connection to construct a DSO from 'taglist'.

Synopsis

[pidso, warnlog] = getpidata(taglist,startdate,enddate,options)

Description

This function requires the PI SDK (developer kit) be installed. If only taglist is submitted and or date inputs are empty then a "snapshot" of the data is returned. Date inputs can be any PI supported value.

Inputs

• taglist = Cell array of strings containing tags to query or excel file with one column of tag names.

• startdate = Start date/time to query or excel file with 2 columns (start and end dates). Each row will indicate a unique start/end and will be appended according to appenddir option setting.

• endtdate = End date/time to query.

Outputs

• pidso = dataset object of queried values or (if rawdata = 'on') a 1xn structure array with the following fields:

.tagname

.time

.value

NOTE:With DSO returned queries, timestamps are returned in the .axisscale field. Matlab adjusted timestamps are reported in .axisscale{1,1}. The original UTC timestamps are reported in .axisscale{1,2}.

Options

options = structure array with the following fields:

• tagsearch: [ {'off'} | 'on' ] Show PI tag search gui.

• interpolate: [ {'interval'} | 'total' ] Governs interpolate settings.

'interval' is the time between data points in seconds.

'total' is the total number of points to retrieve.

• interpolateval: {60} Default is interval if 60 seconds.

• timeout: {10} Seconds to wait for server to return for each column of data.

• savefile: {} File name to save output to.

• diplaywarnings: [ 'off' | {'on'} ] Show warning at command line after calculation.

• timecorrection: {0} Time in seconds to be added when converting PI timestamps to Matlab time.

• rawdata: [ {'off'} | 'on' ] Retrieve PI "compressed data" (actual Archive events) for given taglist. This will not use any interpolation and because data will likely be of different length, the result will be returned in a structure, not a dso.

• userservertime: [ 'off' | {'on'} | local] Governs how to convert Matlab timestamps (axisscale{1,1}). 'on' creates timestamps with timezone settings (e.g., daylight savings rules) applied. If set to 'off' then server time is used with no timezone rules applied. If set to 'local', local timezone is applied.

• appenddir: [ {'mode 1'} | 'mode 3'] Mode to append to when using multiple time range inputs.

• lengthmatch: [ 'min' | {'max'} | 'stretch' | 'fixed' ] Defines how slabs should be concatenated (used only when appenddir = 'mode 3'):

'min' truncates all slabs to the shortest slab length.

'max' adds NaN's to the end of each slab to match the longest slab length.

'stretch' interpolates all slabs to match the length of the FIRST read slab.

'fixed' either truncates or infills all slabs to match a specific length specified in targetlength, below.

All modes can also be adapted to match a minimum or maximum length using the "targetlength" option, below.

• targetlength: [] Optional target length (used only when appenddir = 'mode 3'). A non-empty value will be used in place of the default length defined by the lengthmatch option. If lengthmatch is 'min', this option defines the MAXIMUM length slab to allow. If lengthmatch is 'max', this option defines the MINIMUM length slab to allow. If lengthmatch is 'stretch', this option defines the target length. If lengthmatch is 'fixed' then this option defines the target length.

Examples

>> dso = getpidata('tagnames.xls','y-2d','t',options);

>> dso = getpidata('tagnames.xls','dates.xls',options);

>> dso = getpidata({'SINUSOID' 'BA:PHASE.1' 'BA:TEMP.1'},'y-2d','t',options);

See Also

builddbstr, piconnectgui, querydb