piar_getarcvaluesx

This function returns either compressed or evenly spaced values from the PI Data Archive.

Visual Basic format

Declare Function piar_getarcvaluesx Lib "piapi32.dll" (
ByVal PtNum&,
ByVal arcMode&,
Count&,
drVal As Any,
iVal&,
bVal As Any,
bSize&,
iStat&,
Flags%,
time0 As PITimeStamp,
time1 As PITimeStamp,
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,
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.

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.

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 arguments are not needed, pass NULL in the argument list for C/C++ code or vbNullString for Visual Basic code.

If the point value is numeric (floating point and integer values), drval and ival will both be populated if provided, or if only one of the agruments is provided that argument will 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 values returned in bval (string and blob types), the function will return –15010 if the bval argument is NULL or smaller than the number of bytes returned by the server. This indicates truncation of the data in bval and the bval buffer will be filled with as much of the requested data as possible (the passed bsize bytes). Also, bsize is modified to return 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