pisn_getsnapshotx

This function returns the most recent event from the PI System snapshot for a single point.

Visual Basic format

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

C format

int32 PIPROC pisn_getsnapshotx(

int32 ptnum,

float64 PIPTR *drval,

int32 PIPTR *ival,

void PIPTR *bval,

uint32 PIPTR *bsize,

int32 PIPTR *istat,

int16  PIPTR *flags,

PITIMESTAMP PIPTR *timestamp);

Returns

>0

System error

0

Success

-1

Point not found

-991

Not implemented

-998

Memory allocation error

-15010

Value truncated

 

Arguments

ptnum (passed)

PI point number.

drval (modified)

Floating-point value in engineering units.

ival (modified)

Integer value in engineering units.

bval (modified)

Pointer to string or byte array buffer.

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

timestamp (modified)

Timestamp of the value.

Usage Notes

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