piar_getarcvaluex

This function returns a single value from the PI Data Archive. Full status information and sub-second timestamp are included.

The mode argument determines how the data value is found:

 1 Value before given date and time
 2 Value after given date and time
 3 Interpolated value at exact date and time
 4 Either interpolated or previous value

See the Usage Notes below for details.

Visual Basic format

Declare Function piar_getarcvaluex Lib "piapi32.dll" (
ByVal PtNum&,
ByVal arcMode&,
drVal As Any,
iVal&,
bVal As Any,
bSize&,
iStat&,
Flags%,
time0 As PITimeStamp) As Long

C format

int32 PIPROC piar_getarcvaluex(
int32 ptnum,
int32 mode,
float64 PIPTR *drval,
int32 PIPTR *ival,
void PIPTR *bval,
uint32 PIPTR *bsize,
int32 PIPTR *istat,
int16 PIPTR *flags,
PITIMESTAMP PIPTR *time);

Returns

>0

System error

Success

-1

Point not found

-983

Invalid mode

-991

Not implemented

-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.

mode (passed)

Retrieval mode (see Usage Notes).

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 numerical points, the digital state code indicating status of the value.

flags (modified)

Data quality flag mask.

time (passed, modified)

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

Usage Notes

For C language programming, the following codes defined in piapi.h can be used when calling piar_getarcvaluex. These are the same mode codes as are used by piar_value:

#define ARCVALUEBEFORE  1

#define ARCVALUEAFTER  2

#define ARCVALUEINTERP  3

#define ARCVALUECODE  4

When communicating with a PI System for Windows NT and UNIX, mode ARCVALUECODE is identical to mode ARCVALUEINTERP. However, points with the step point attribute set will return the previous value and it's associated timestamp.

When communicating with a PI System for OpenVMS, mode ARCVALUECODE will return the first value before the passed timestamp for a point with a resolution code of 4, and an interpolated value for all other resolution codes.

For string points, the ARCVALUEINTERP mode returns the previous value.

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 real, ival will contain an integer truncation. If the point is integer, 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