pisn_putsnapshotx

This function adds a new event to the PI System Snapshot. Note that all arguments are passed by reference, even though they are not modified by the function. Check Usage Notes below to determine how the passed data is interpreted by PI.

Visual Basic format

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

C format

int32 PIPROC pisn_putsnapshotx(
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

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

-30200

No data provided

 

Arguments

ptnum (passed)

PI point number.

drval (passed)

Floating-point value in engineering units. This value will be sent to PI as a floating point value if bval is NULL.

ival (passed)

Integer value in engineering units. This value will be sent to PI if bval is NULL, and drval is NULL.

bval (passed)

Pointer to string or byte array buffer. If non-NULL, this buffer will be sent to PI.

bsize (passed)

If positive, length in bytes of the buffer passed as bval, not including the null termination character. If zero, this function will measure the string length using the C language run-time library function strlen.

istat (passed)

For digital points, the point value. No other values need be passed. For numerical points, the digital state code indicating status of the value.

flags (passed)

Data quality flag mask.

timestamp (passed)

Timestamp of the value. If NULL, use the current time without subseconds.

Usage Notes

This function uses the following rules to determine which data value to send data to PI:

· If bval is non-NULL, a string/byte value will be sent to PI.

· If bval is NULL and drval is non-NULL, a floating point value will be sent to PI.

· If bval and drval are NULL, and ival is non-NULL, an integer value will be sent to PI.

· If all arguments are passed as NULL, this function returns -30200, which means that no data values were provided to PI.

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 library 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_putsnapshot call fails and returns an error of -15011.

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

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

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.

Enabling Operational Intelligence