pisn_sendexceptionqx

This function adds a new event to the PI System snapshot if it passes the exception test. The exception test is designed to eliminate events that are not significantly different from previous events. The exception test algorithm is described in the usage notes below. The PI_EVENT structure should contain the value type as well as the data value. The queueing flag determines whether or not events are sent when each pisn_sendexceptionqx call is made or cached in an internal array and sent as an array of events.

C format

int32 PIPROC pisn_sendexceptionqx(
int32 pt,
PI_EVENT PIPTR *oldvalue,
PI_EVENT PIPTR *prevvalue,
PI_EVENT
newvalue,
float64 excdeveng,
float64 excmin,
float64 excmax,
int32 PIPTR *count,
pibool queueing,
int32 PIPTR *numbpterrs,
QERROR PIPTR *qerrs );

Returns

>0

System error

Success

-991

Not implemented

-30000

Success, but some points had errors

-30200

No data provided

 

Arguments

pt (passed)

PI point number.

oldvalue (passed,modified)

Last value which passed the exception test. The structure is listed below in the Usage Notes.

prevvalue (passed,modified)

Last value to be tested for exception. If the last test was true, this will be the same as oldvalue. The structure is listed below in the Usage Notes.

newvalue (passed)

New value to be tested for exception.

excdeveng (passed)

Exception deviation in engineering units used in the exception test.

excmin (passed)

Exception minimum time in seconds used in the exception test.

excmax (passed)

Exception maximum time in seconds used in the exception test.

count (modified)

Number of values sent to the snapshot.

queueing (passed)

Flag indicating whether this value should be queued. FALSE causes a putsnapshotx call without queueing and TRUE will cause snapshots to be stored until a PINet message is full or a pisn_flushputsnapqx is issued.

numbpterrs (modified)

The number of point errors for the queued data.

qerrs (modified)

An array of size 192 of QERROR structures allocated by the calling program.

Usage Notes

The standard exception reporting algorithm is used to add values to the snapshot. When

  1. the difference between oldvalue and newvalue exceeds excdeveng ,
  2. the difference between the timestamp of oldvalue and newvalue exceeds excmax ,
  3. or a change in digital state occurs,
newvalue is added to the snapshot. However, if the time between oldvalue and newvalue does not exceed excmin, newvalue is not sent. If prevvalue has a timestamp greater than oldvalue, prevvalue and newvalue are both sent to the snapshot (count is returned as 2, otherwise count is returned as 1). For out of order data values newvalue is sent and prevvalue is not updated (refer to the Data Archive manual for details on setting excdeveng, excmax, excmin).

The PI value type, which is part of the structure, is used to select which structure member contains the data to be used. If a string is entered in bval of the new value, the previous and old values must have previously allocated the maximum expected number of bytes. The bsize parameter will not be changed by this function so that the number of bytes allocated for the buffer will always be available for each exception test.

An internal data queue for the extended snapshot values is enabled by passing queuing = 1. See the pisn_flushputsnapqx function call for an explanation of snapshot queueing.

typedef struct {
PIvaluetype typex;
float64 drval;
int32 ival;
void *bval;/* Set to NULL if not used. */
uint32 bsize;
int32 istat;
int16 flags;
PITIMESTAMP timestamp;
} PI_EVENT;

Enabling Operational Intelligence