pisn_sendexceptionq

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:

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.

C format

LPQERRORS pisn_sendexceptionq(

int32 pt,

char type,

float PIPTR * oldval,

int16 PIPTR * oldstat,

int32 PIPTR * oldtime,

float PIPTR * prevval,

int16 PIPTR * prevstat,

int32 PIPTR * prevtime,

float newval,

int16 newstat,

int32 newtime,

float excdeveng,

int16 excmin,

int16 excmax,

int32 PIPTR * count);

Returns

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 */

}PIPTR *LPQERRORS;

typedef struct qerror

{

  int32 point;

  int32 error;

}PIPTR *LPQERROR;

syserror

  >0  System error

  0  Success

numbpterrs

  Number of points in error list

point

  Point in error

error

  -1  Point does not exist

  -8  Time is after the current time or less than 0

  -9  Illegal status or integer value

Arguments

pt (passed)

Point number

type (passed)

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

newval (passed)

New value

newstat (passed)

New status

newtime (passed)

Time stamp of new value or 0 for current time

excdeveng (passed)

Exception deviation in engineering units

excmin (passed)

Exception minimum time in seconds

excmax (passed)

Exception maximum time in seconds

count (returned)

Number of values sent to pi: 0,1, or 2

Usage Notes

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.

Enabling Operational Intelligence