piar_summary

This function calculates the Archive function specified by the code parameter from Archive data for the time between the passed starting and ending times inclusive. Pctgood returns the percentage of the given time that the point was good. A digital point always returns zero percent good.

Bad data are ignored in the calculation. See Usage Notes for behavior specific to the Archive function parameter, code.

C format

int32 piar_summary(

int32 pt,

int32 PIPTR *time1

int32 PIPTR *time2,

float PIPTR *rval,

float PIPTR *pctgood,

int32 code );

Returns

>0

System error

Success

-1

Bad point number

-104

Invalid code

-105

Last time not after first time or time < 0

-106

No good data for this point for this time

-120

Invalid code for the currently connected server.

Arguments

pt (passed)

Point number

time1 (passed, returned)

Starting time stamp, returned with the time of the determined minimum or maximum value or range value

time2 (passed, returned)

Ending time stamp, returned with the time of the range value

rval (returned)

Calculated engineering value

pctgood (returned)

Percent of time Archive value was good

code (passed)

Archive function to execute (average, minimum, maximum, etc.)

Usage Notes

The codes to be used when calling the piar_summary function are defined in piapi.h as:

#define ARCTOTAL 0

#define ARCMINIMUM 1

#define ARCMAXIMUM 2

#define ARCSTDEV 3

#define ARCRANGE 4

#define ARCAVERAGE 5

#define ARCMEAN 6

The time-based total calculated by piar_summary is converted to a total for the entire time range and if some of the data are bad, the calculated total is divided by the fraction of the time period for which there were good values. If the engineering units for the point do not match default time units for the system, the resulting value must be properly adjusted using a conversion factor.

piar_summary returns the minimum value in the time period between the starting and ending times, inclusive. The time of the minimum value is returned in time1.

piar_summary returns the maximum value in the time period between the starting and ending times, inclusive. The time of the maximum value is returned in time1.

The standard deviation calculation uses the first good value as a standard value. Each value is subtracted from the standard value to minimize round off problems resulting from the difference of the two running sums. The standard deviation is a time-weighted calculation.

To retrieve the range in the given time period, piar_summary calculates the difference between the maximum and the minimum values. The time of the minimum is returned in time1 and the time of the maximum is returned in time2.

The average calculated by piar_summary is time-weighted.

The mean calculated by piar_summary is the arithmetic mean.

Enabling Operational Intelligence