piar_getarcvaluesfilterx

This function returns either compressed or evenly spaced values from the PI Data Archive. When passing a filter expression, if sequential events fail the filter, only one Filtered (-244) status is returned for the sequence.

Visual Basic format

Declare Function piar_getarcvaluesfilterx Lib "piapi32.dll" (
ByVal PtNum&,
ByVal Mode&,
Count&,
drVal As Any,
iVal&,
bVal As Any,
bSize&,
iStat&,
Flags%,
time0 As PITimeStamp,
time1 As PITimeStamp,
ByVal Expr$,
ByVal FuncCode&) As Long

C format

int32 PIPROC piar_getarcvaluesx(
int32 ptnum,
int32 arcmode,
int32 PIPTR *count,
float64 PIPTR *drval,
int32 PIPTR *ival,
void PIPTR *bval,
uint32 PIPTR *bsize,
int32 PIPTR *istat,
int16 PIPTR *flags,
PITIMESTAMP PIPTR *time0,
PITIMESTAMP PIPTR *time1,
char PIPTR *expression,
int32 funccode);

Returns

100

All values have been returned (PI_NOMOREVALUES)

>0

System error

Success

-1

Point not found

-982

Invalid funccode

-983

Invalid arcmode

-991

Not implemented

-992

Invalid bsize

-993

Invalid count

-998

Memory allocation error

-11032

No events after passed eventid

-11033

No events before passed eventid

-11049

Invalid timestamp

-15010

Value truncated

Arguments

ptnum (passed)

PI point number.

arcmode (passed)

Archive mode code. Supported values are:

ARCflag_comp for compressed data, and
ARCflag_even for evenly spaced data.

ARCflag_time for values at the specified array of times.

These values are defined in the include file pidefs.h. Filter reporting modifiers ARCflag_filter and ARCflag_mark may also be used in conjunction with ARCflag_comp, ARCflag_even, or ARCflag_time. That is, if you want to get filtered, compressed data, use an arcmode value that is the sum of ARCflag_comp and ARCflag_filter. The ARCflag_mark specification returns filtered values marked as "Filtered" while ARCflag_filter omits filtered values.

count (passed, modified)

When passed, the total number of values requested. When returned, the number of values found.

drval (modified)

Floating-point value in engineering units.

ival (modified)

Integer value in engineering units.

bval (modified)

Pointer to string or byte array buffer without a terminating null.

bsize (passed, modified)

When passed, contains the length of the buffer passed as bval. When returned, contains the number of bytes returned (or available to return if the buffer is too small). For strings, the returned size does not include the null termination character.

istat (modified)

For digital points, the point value. For all other point types, the digital state code indicating status of the value.

flags (modified)

Data quality flag mask.

time0 (passed)

Start time or array of times.

time1 (passed, modified)

When passed, the end time. When returned, timestamp of the value.

expression (passed)

The filter expression or a NULL pointer.

funccode (passed)

Code indicating type of call. Three values are possible:

GETFIRST: obtains data from the PI System and returns the first data value.
GETNEXT returns the next data value.
GETSAME: returns the same data value as returned by the last call using GETNEXT or GETFIRST.

Usage Notes

A call using the function code GETFIRST must be made first, otherwise PI_NOMOREVALUES will be returned.

The arguments ptnum, arcmode and time0 are used by PI only when the function code is GETFIRST. For mode ARCflag_time, time0 must be an array of times at which values are desired.

If time0 is earlier than time1, data will be returned moving forward in time. If time0 is later than time1, data will be returned moving backwards in time.

The caller need not pass valid pointers for all of the defined arguments. If any of the data values are not needed, pass NULL in the argument list.

If the point value is numeric, drval and ival will both be populated. If the point is a real point, ival will contain an integer truncation. If the point is an integer point, drval will contain a floating point copy of the value.

For a values returned in bval, if the function returns –15010 indicating truncation of the data in bval, the bval buffer is filled with as much of the requested data as possible (bsize bytes). Also, bsize is set to the required buffer size.

It is not necessary to pass a buffer pointer as bval. If this is the case, and the PI point is a string point, then bsize will be set to the number of bytes available to return, not including a null termination character for strings. The return value in this case will be –15010.

Note This technique can be used to determine the length of the string before retrieving it.

This function does not null-terminate a string. You must use the returned bsize value to assign the null in your program.

Enabling Operational Intelligence