pisn_putsnapshotsx

This function adds an array of new events to the PI System snapshot. The function accepts several arrays in the argument list, but not all are used. Check Usage Notes below to determine how the passed data is interpreted by PI.

Visual Basic format

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

C format

int32 PIPROC pisn_putsnapshotsx(
int32 count,
int32 *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);

Returns

>0

System error

Success

-1

Point not found

-991

Not implemented

-998

Memory allocation error

-10702

STATE Not Found

-15011

Unusable string value passed for numeric point

-15014

PIvalue Type or PIstring is Not Integer

-15017

PIvalue Type is Not Allowed For This Call

-30000

Success, but some points had errors

-30200

No data provided

 

Arguments

count (passed)

Number of values to send to PI.

ptnum (passed)

Array of PI point numbers.

drval (passed)

Array of floating-point values in engineering units. Values from this array will be sent to PI as floating point values if bval is NULL.

ival (passed)

Array of integer values in engineering units. Values from this array will be sent to PI if bval is NULL, and drval is NULL.

bval (passed)

Array of pointers to strings or byte array buffers. If non-NULL, this array of buffers will be sent to PI.

bsize (passed)

Array of buffer lengths. If NULL, or if a given entry in the array is zero, this function will measure the string length using the C language run-time library function strlen.

istat (passed)

Array of digital state codes. For digital points, these are point values. No other values need be passed. For numerical points, these are digital state codes indicating status of the value. If NULL is passed, all values will receive a status code indicating good data.

flags (passed)

Array of data quality flag masks.

timestamp (passed)

Array of value timestamps. If NULL, use the current time without subseconds; all values will receive the same timestamp.

errors (modified)

Array of status codes for adding values to PI corresponding to the array of point numbers passed to the function

Usage Notes

All arrays passed to this function must have an array dimension of at least count.

This function will normally interpret a single data array along with the digital state code array, unless the digital state array is passed alone. All values will be sent to PI as the same data type; the PI System Snapshot may reject values that cannot be stored due to data type mismatch. These are the steps this function will take to determine which array to send:

If bval is non-NULL and bsize is a positive, then bsize is taken to be the string or byte array length. If bsize is passed as zero, this function will determine the string length using the C run-time function strlen.

If a string is passed to a numeric point, PI will attempt to read a number from the string. If this is not possible, PI will attempt to interpret the string as a digital state string. If this is not possible, the pisn_putsnapshots call will returns an error code of -15011 in the corresponding position in the errors array.

For inserting values into PI for digital points, the istat array must be passed. All other arrays should not be passed; they will be ignored.

If you are adding a data value to a digital point using an offset value of zero, you must pass the istat array and must not pass other arrays. Passing other arrays would cause pisn_putsnapshotsx to interpret the istat values as good, and will attempt to send strings or numeric values.

If a digital state string is passed to a string-valued point, it will be added to the snapshot as a string value, not as a digital state. To put digital state codes into PI for string-valued points, you must pass the appropriate digital state code as istat.

If a value for a point was successfully added to PI, its entry in the errors array will be zero.

For 16 bit platforms, the maximum number of events that may be sent is 2047.

Enabling Operational Intelligence