pisn_getsnapshotsx

This function returns snapshot values for several points.

Visual Basic format

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

C format

int32 PIPROC pisn_getsnapshotsx(

int32 PIPTR *ptnums,

int32 PIPTR *count_ptnum,

float64 PIPTR *drval,

int32 PIPTR *ival,

void PIPTR *bval,

uint32 PIPTR *bsize,

int32 PIPTR *istat,

int16 PIPTR *flags,

PITIMESTAMP PIPTR *timestamp,

int32 PIPTR *errors,

int32 funccode);

Returns

100

All values have been returned

>0

System error

0

Success

-1

Point not found

-982

Invalid funccode

-991

Not implemented

-992

Bad length for bval

-998

Memory allocation error

-15010

Value truncated

 

Arguments

ptnums (passed)

Array of PI point numbers.

count_ptnum (passed, modified)

When passed, indicates the number of values in the array ptnums. When returned, indicates the PI point number whose snapshot value is returned.

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

PI snapshot time.

errors (modified)

Retrieval status code, corresponding to the value retrieved. This status codes indicates the success or failure of retrieving the snapshot value from PI. A status code of 0 indicates a successful retrieval.

funccode (passed)

Code indicating type of call. Three values are possible:

GETFIRST: obtains data from the PI System and returns data for the first PI point.
GETNEXT returns data for the next PI point.
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 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 error code is –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 error code in this case will be –15010.

Note This technique can be used to determine the length of the string before retrieving it. After allocating a sufficiently large buffer, you can recall this function using the function code GETSAME.

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

The archive call is limited to 16,375 events on 16-bit platforms.

Enabling Operational Intelligence