PercentTrue Method (IPICalculation interface)

              

 

This method evaluates the passed boolean expression over the passed time range. The passed time range is first divided into a number of calculation periods. The method then computes the percentage of time the passed expression evaluates to true over each of the periods. The method returns a PIValues collection containing these results. The format of this returned collection is described under Remarks below.

The caller can also control how often the expression is evaluated during the computation of the Percent True results. This flexibility allows the user to manage the trade-off between accuracy and execution time. Higher accuracy typically imposes a heavier load on the server. In the extreme cases, this may impact other applications from accessing the server.

Syntax

object.PercentTrue StartTime, EndTime, CalculationDuration, Expression, SampleType, SampleInterval, asynchStatus

The object placeholder is an object that evaluates to a reference to an IPICalculation interface.  This interface can be obtained from a Server object.

 

The PercentTrue method syntax has these parts:

Part

Description

object

An object expression that evaluates to an IPICalculation interface.

StartTime

A Variant containing the start time of the evaluation period. See the Settings section for allowable values. The StartTime, EndTime and CalculationDuration arguments together determine the number of calculation periods and the starting and ending times of each period. See the Remarks section for how the calculation periods are determined.

EndTime

A Variant containing the end time of the evaluation period. See the Settings section for allowable values.

CalculationDuration A Variant containing the length of calculation period. See the Settings section for allowable values and the Remarks section for usage.

Expression

A string containing the expression to be evaluated.  The syntax for the expression follows the Performance Equation syntax as described in the server documentation.

SampleType

A value from the FilterSampleTypeConstants enumeration. See the Settings section for allowable values. Together with the SampleInterval argument, SampleType determines how often the expression is evaluated. See the Remarks section for usage. The default value for SampleType is fstExpRecordedValues.

SampleInterval

A Variant containing the time interval at which the evaluation is performed within the specified time range.  See the Settings section for allowable values. If SampleType is specified as fstPIPointRecordedValues or fstExpRecordedValues , this argument is ignored. 

AsynchStatus

A PIAsynchStatus object for launching an asynchronous call, determining the progress of, or canceling a lengthy call. [Optional]

 


Settings

The possible values in the variant for StartTime and EndTime are:

 

The possible values for CalculationDuration are:

 

The possible values for SampleType are:

Setting Description
fstExpRecordedValues Sampling / evaluation is done based on the actual times of all tag values in the filter expression saved in the archive. Archive events are retrieved for all the tags in the expression over the passed time range. The expression is then evaluated at each of the timestamps of these retrieved events. The result of each evaluation is assumed to hold until the next evaluation, i.e. same as step attribute is true. This sampling algorithm is sometimes referred to as natural or event-based. The SampleInterval argument is ignored when fstExpRecordedvalues is selected for SampleType. fstExpRecordedvalues is the default SampleType setting for the PercentTrue method.
fstInterval Sampling / evaluation is done based on a passed interval (SampleInterval).  This is sometimes referred to as evenly-spaced evaluation. This option is currently NOT IMPLEMENTED for the PercentTrue method.
fstPIPointRecordedValues This option is the same as fstExpRecordedValues for the PercentTrue method.
fstExpRecValWithMinSampTime This option is the same as fstExpRecordedValues with the additional requirement that the evaluation interval has to be less than or equal to the passed interval (SampleInterval). Therefore, the number of evaluations using this option will always be more or the same as the number of evaluations using the fstExpRecordedValues option or fstInterval option with the same SampleInterval. This option is NOT IMPLEMENTED for PI 2 server.
fstAutoDetectChange With this option, the server tries to determine the times the expression result changes (true to false, false to true) to within the passed accuracy (SampleInterval) in the most efficient manner. First the expression is evaluated using the event-based algorithm (see fstExpRecordedValues discussion above), resulting in a time series of boolean events. Within this boolean events collection, whenever there is a boolean value change, the server further narrows down the interval until the interval is less than or equal to the passed SampleInterval. This option is currently NOT IMPLEMENTED.

 

 

The possible values for SampleInterval are:

 

 

Remarks

Specifying Calculation Intervals

Given the StartTime, EndTime and Duration, this function generates a number of contiguous calculation time periods where the computation results are returned according to the following rules:

1.  When the Duration argument is specified as a string, the way the calculation interval is determined depends on the server type and the interval type.

Against a PI2.x server, wall clock rules based on client machine time zone are used to determine the interval length for all interval types.

Against a PI3.x server, intervals specified in "seconds", "minutes" and "hours" are interpreted as evenly spaced UTC time intervals. The rest of the interval types are interpreted using wall clock rules. Wall clock rules are time zone dependent. If the StartTime and EndTime arguments are specified as PITimeFormat objects, the wall clock rules of the PITimeZoneInfo of the passed PITimeFormat object are used to determine the calculation intervals. Otherwise, wall clock rules based on the client machine time zone are used. For example, against a PI 3 server, Duration of "24h" means using an evenly spaced 24 UTC hour interval for each calculation. On the other hand, for a StartTime of April 1, 2003, EndTime of April 10, 2003 and Duration of "1d", the calculation will be performed for nine one calendar day periods, with the sixth period covering only 23 UTC hours because of Daylight Savings Time change. 

2.  When the specified StartTime is earlier than the EndTime, the resulting PIValues collection will be indexed in time ascending direction. If the StartTime is more recent than the EndTime, the resulting PIValues collection will be indexed in time descending direction. Using the example in rule 1, reversing the StartTime and EndTime, the result PIValues collection will be generated in descending time order, starting with April 9 period and ending with the April 1 period.

3.  When positive Duration is specified, the function starts at the earliest time (i.e. the smaller of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in ascending time direction to generate the calculation periods. Therefore, if the StartTime is more recent than the EndTime, the function starts at the EndTime, otherwise, the function starts at the StartTime. The function stops at the closest interval to the latest time (i.e. the larger of the StartTime and the EndTime argument) but does not go beyond the it. 

4.  For negative Duration, the function starts at the latest time (i.e. the larger of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in descending time direction to generate the calculation periods. Therefore, if the StartTime is more recent than the EndTime, the function starts at the StartTime, otherwise, the function starts at the EndTime. The function stops at the closest interval to the earliest time (i.e. the smaller of the StartTime and the EndTime argument) but does not go beyond the it. 

Note that the order of the PIValues still obeys rule 2 where the results index order reflects the start and end time specification.

Rules 2, 3 and 4 apply to Duration specified in string as well as numeric format. The determination of the calculation interval and results index order from the Start/End time and Duration specifications are demonstrated in the following table:

 

  Time Ascending Time Descending Time Ascending with negative Duration Time Descending with negative Duration
StartTime

Y

T

Y T
EndTime

T

Y

T Y
Duration

5h

5h

-5h -5h
Period for PIValues(1) 12a.m. to 5a.m. 3p.m. to 8p.m. 4a.m. to 9a.m. 7p.m. to 12p.m.
Period for PIvalues(2) 5a.m. to 10a.m. 10a.m. to 3p.m. 9a.m. to 2p.m. 2p.m. to 7p.m.
Period for PIvalues(3) 10a.m. to 3p.m. 5a.m. to 10a.m. 2p.m. to 7p.m. 9a.m. to 2p.m.
Period for last PIvalue 3p.m. to 8p.m. 12a.m. to 5a.m. 7p.m. to 12p.m. 4a.m. to 9a.m.

 

SampleType and SampleInterval Usage:

The PercentTrue result is computed by summing up intervals where the passed expression is evaluated to true. The arguments SampleType and SampleInterval are used to determine expression evaluation intervals as discussed in the table below. More frequent expression evaluations leads to more accurate result but increases server load. Therefore, care must be taken to avoid overloading the server by specifying too fine a calculation granularity.

 

FilterSampleTypeConstant

Server Support

Usage

fstExpRecordedValues All versions This is the default option for this method. This option is the most efficient in getting accurate result. Expressions using only digital tags will get exact answers with this option. However, for calculation covering a large time range, the server may have to evaluate the expression a large number of times if there are lots of data in the archive.
fstInterval Not supported on any Server now. With this option, the server evaluates the expression at evenly spaced intervals (SampleInterval). This option may not be efficient in getting accurate result, i.e. evaluating expression at time stamp where data are not changing. But since user can specify the evaluation interval, user has better control of number of evaluation vs. desired accuracy. Hence, this option is ideal for getting a quick estimate for a large time period with limited expression evaluation.
fstPIPointRecordedValues All versions Same as fstExpRecordedValues for the PercentTrue method
fstExpRecValWithMinSampTime PI 3.x and above This option allows the user to get more accurate answer than the fstExpRecordedValues option by evaluating the expression more frequently. Normally, this option is only necessary if the expression involves comparison of analog tag values. Also, the PI 3 server limits SampleInterval to between 1/100 and 1/10000 of the calculation period. PIAPI uses this option for PI 3.x servers.
fstAutoDetectChange Not supported on any Server now. This option allows the user to get more accurate answer than the fstExpRecordedValues option but is more efficient than the fstExpRecValWithMinSampTime option. The user can also specify the accuracy directly in the SampleInterval argument.

 

Calculation Result Format

The PercentTrue can compute the expression true percentage over multiple calculation periods. The result for each calculation period is put into the value field of a PIValue object. All the PIValue objects are assembled into a PIValues collection as the return object. The timestamp of each PIValue object is assigned to the start time of the calculation period. The start time of the calculation period is always the earliest time of the period even when the StartTime and the EndTime arguments are specified in reversed time order.

The ValueAttributes of each of the PIValue contains additional information about the calculation result in the period. The start time and the end time of the calculation period are stored as NameValue item EarliestTime and MostRecentTime. If there is problem when the server computes the result, the PIValue.value will contain a variant with VT_ERROR type and the full error description is put into the NameValue item of ErrDescription.

 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error

Description

E_INVALIDARG Some of the function argument are not valid.
E_NOTIMPL This combination of the function arguments is not implemented at current PISDK version or not supported by this version of the PI Server.
PISDK_E_ERRCONVINPUT Problem converting input arguments to PI Server calling arguments.
E_ACCESSDENIED No read access to PI Server
PISDK_E_INVPEEXPR Invalid Expression Syntax
PISDK_E_PERUNTIMEERROR Expression evaluation runtime error
PISDK_E_DATENOTONLINE Archive not online for specified time range
PISDK_E_CALCFAILED Other calculation error from the PI Server
PISDK_E_ERRCONVOUTPUT Error converting PI Server result to PISDK result format
Enabling Operational Intelligence