This function sends exception reports to the pi Snapshot queue. If the queue is full, this function will also send all values in the queue to the PI home node and return a list of any point errors. This is the recommended method of putting instrument or other real-time data into pi if large data rates are expected.
This function determines if the passed, new value is an exception. An exception is a value that satisfies one of these criteria:
The time between the new value and the last exception is greater than the maximum exception time for the point.
The time between the new value and the last exception is greater than the minimum exception time for the point and the difference between the new value and the last exception is greater than the exception deviation for the point.
If it is an exception, it sends the previous value if that value has a different time stamp than the last exception (oldvalue). It always sends the new value when there is an exception.
This routine moves the new value to the previous value. If there is an exception, it also moves the new value to the old value. If newtime is passed as 0, the current server time is used.
The passed parameters are given the recommended data types for program storage. For example, the exception minimum and maximum times should be short (16 bit) rather than char or long. The time variables must be long (32 bit) variables.
float PIPTR * oldval,
int16 PIPTR * oldstat,
int32 PIPTR * oldtime,
float PIPTR * prevval,
int16 PIPTR * prevstat,
int32 PIPTR * prevtime,
int32 PIPTR * count);
LPQERRORS type, which is a pointer to a qerrors structure as defined in piapi.h. The structure contains the system error and a list of point errors, if any. The structure and typedef are as follows:
typedef struct qerrors
int32 syserror; /* current system errors */
int32 numbpterrs;/* number of individual pt errors */
struct qerror qerr[MAXPUTSNAP];
/* list of points in error */
typedef struct qerror
>0 System error
Number of points in error list
Point in error
-1 Point does not exist
-8 Time is after the current time or less than 0
-9 Illegal status or integer value
pi point type (R, I, or D)
oldval (passed, returned)
Value of last exception
oldstat (passed, returned)
Status of last exception
oldtime (passed, returned)
Time stamp of last exception
prevval (passed, returned)
Value of last scan
prevstat (passed, returned)
Status of last scan
prevtime (passed, returned)
Time stamp of last scan
Time stamp of new value or 0 for current time
Exception deviation in engineering units
Exception minimum time in seconds
Exception maximum time in seconds
Number of values sent to pi: 0,1, or 2
The error structure will only be set after the network call has been made. The list of individual point errors will be in the same order they were added to the queue. If no point errors were encountered, this list will be empty.
The same structure is used for each queue call, thus it is advisable to process the return information or copy the structure before making another queue call.
The local queue size is different depending on whether you are communicating with a PI2 or PI3 server. For PI2 servers, the queue size is 36. For PI3 servers, the size is 255. This means unless you call pisn_flushputsnapq, the API will send more values less frequently to a PI3 server.