04 Perfeq

Chapter 4
Performance Equations Subsystem

Performance Equations (PEs) allow for the programming of complex calculations using data from the PI System. These calculations may include: Heat and material balances Unit performance Real-time cost accounting Real-time yield accounting Grade-based costing Batch summary
Configuring Performance Equations

To configure a Performance Equation: 1. Create a point with a point source defined in pipeschd.bat (default point source is C) to store the results of the performance equation. 2. Put the equation in the points extended descriptor. 3. Schedule the equation to be evaluated by Performance Equation (PE) Scheduler.
Totalizer vs. Performance Equations

The PI Totalizer is a separate subsystem that makes it easier to carry out certain types of performance equations. These mathematical calculations include totals, averages, minimum and maximum values, ranges, medians and standard deviations.
May 1998 55
Chapter 4
Performance Equations
Furthermore, the Totalizer is able to count the number of events and find the time of events such as digital points. To create totalizer points, see the totalizer chapter in this manual.
Calculated Points
Calculated points are PI points that take their data from a periodic calculation. By default, the point source of a calculated point is C. The performance equation associated with the calculated point is specified in the Extended Descriptor attribute in the point database. Like any other point, a calculated point can be used in other calculations, graphed in trend displays and included in reports.
Performance Equation Syntax

The performance equation syntax may consist of operands, arithmetic operators, built-in functions, and if-then-else structures. The equation can also include PI points with snapshot or archive values. The pipetest utility is used to test the syntax of a performance equation at point configuration time.
The Performance Equation (PE) Scheduler

The PE Scheduler or pipeschd is a subsystem that does the PE calculations. The frequency at which the equations are evaluated is determined by the scan class, which is specified for the calculated point in the Location4 attribute in the point database.
PIPE Steam Module

The Pipe-Steam module is used to calculate the thermodynamic properties of steam within Performance Equations. This is a separately licensed product embedded in the Performance Equation evaluator.
Configuration of Calculated Points

The following attributes have special significance when creating a point that uses performance equations. Table 4-1 Attribute Requirements for Calculated Points
56
OSI Software, Inc.
Attribut e PtClass
Requirement This must be classic
PointSou Maps PE Scheduler to the point rce Location 4 ExDesc Scan ExcDev Shutdow n Scan class specifier Performance equation Equation evaluated if not zero Exception reporting parameter Marker inserted in archive at shutdown
PtClass
The point class for calculated points must be classic.
PointSource
Calculated points must define their PointSource attribute to match the /ps= entry in the pipeschd startup script. This point source is normally C. It can be changed to any other alphanumeric character as long as the /ps= specification and the pointsource attribute of the calculated point match.
Location4
All calculated points have a Location4 value selecting their scan class, 1..n. Location4 must be a positive non-zero integer. The number indicates the relative position of the /f= parameter in the PE scheduler startup script. See the explanation in "Startup Script" on page 77.
ExDesc
The text for the equation for the calculated point goes into the extended descriptor (ExDesc) field. This field also determines the type of scheduling and is not limited to a specific length. If the equation text contains a comma (,), the entire string must be enclosed in double quotes (") to help piconfig to interpret it as a single field. If the equation text begins with the single quote character (), the entire string must be enclosed in double quotes (") or
PI Data Archive for Windows NT and UNIX 57
Chapter 4
parentheses. The double quotes will cause piconfig to process the entire field as a unit. The parentheses become part of the expression. If the expression also has internal quoted strings, each quote character needs to be 'escaped' by preceding it with another quote. These are the same rules used by Excel to save and read text files in the standard, comma-separated value format. Alternatively, the field separator may be redefined to use another character. See the example in the Piconfig chapter. The rules for quotes and commas discussed here apply to the text as input to piconfig. This is a common text file convention for field oriented data, such as Microsoft Excel comma-separated value format. An easy way to deal with this form is to write PEs in Excel. In the cell, you may enter only the internal commas and single quotes around strings. Excel will add the others when the file is saved as _.CSV, and reverse the process when reading them in. Values calculated by expressions are subject to exception reporting logic before being sent to the snapshot table.
Scan
The Scan attribute should be set to 1. If it is set to 0, no calculations will take place and no values will be generated.
ExcDev
If a new calculated result is within ExcDev of the value last sent to the snapshot, it will not be transmitted. This means that the new value, and the time of its calculation, will not be visible. The exception reporting time parameters, ExcMin and ExcMax, also work as they do in other interfaces.
Shutdown
Performance Equations will not be calculated if PI is not running. Therefore the Shutdown attribute should be set to 1 so that a shutdown event will be inserted to mark this situation. See the PI System Databases chapter for more information about configuring this Point Database attribute. Note that this will not detect if the PE Scheduler stops independent of the PI System.
58
OSI Software, Inc.
Summary of Point Database Attributes

The following attributes have their normal meanings for directing archive and display operations:
Archiving CompMin Descriptor ExDesc Tag Shutdown CompDev Compress DisplayDig Zero Typical CompMax Conversion PtClass Span Step
The following attributes do not apply to PI calculated points:

Location1 Location5 UserReal1 InstrumentTa g Location2 UserInt1 UserReal2 SquareRoot Location3 UserInt2 EventTag
Performance Equation Syntax

An equation is a collection of elements that give a desired result. In an equation, operands (tag names, constants, and numeric values) are acted on by operators.
Operands
Operands are numbers, tag names, timestamps, strings, or functions.
Numbers
In performance equations, numeric values are processed as floating point numbers. Some examples are
125 125. .125 0.125 Note: Scientific notation is not supported.
PI Data Archive for Windows NT and UNIX
59
Chapter 4
Tagnames
Tagnames are used in performance equations to represent values from the Snapshot. They are also used as arguments for functions that get data from the Archive. Tagnames must be delimited by single quotes. A performance equation will not compile if a point cannot be found in the system. Some examples are:
sinusoid cdm158
If a tagname is used in an expression, the evaluator gets the points value at the current time. These following examples are equivalent:
3 3 3 3 + + + + sinusoid TagVal(sinusoid) TagVal(sinusoid, *) TagVal(sinusoid,ParseTime(*))
If a tagname is used as a function argument, the evaluator handles the tagname according to what the function expects from the argument. If the function expects a tagname, the name is passed directly to the function. If the function expects any other data type, the name is translated into its current value.
Strings
Strings are sequences of any printable characters enclosed in double quotes. Some examples are
This is a string sinusoid 14-Dec-97
Notice that character strings may look like a tagname or a timestamp as in the second and third examples above. The difference is that a character string is enclosed in double quotes rather than single quotes.
60
OSI Software, Inc.
Timestamps
Timestamps represent a particular day and time. The standard PI 3 time formats are recognized and must be enclosed in single quotes. These standard formats are given in Appendix A. Some examples of absolute timestamps are as follows.
* 14-Dec-97 11-Nov-96 2:00:00.0001 T
Caution should be used in choosing the correct timestamp format for the PEs. Some absolute timestamps are evaluation at execution time while other timestamps are evaluated at compile time.
Function Expressions
A function call is a reference to a built-in function. Functions are not case sensitive. Functions may have one or more arguments, as required by each formula. Argument expressions, if present, are enclosed in parenthesis following the function name. If there are several arguments, they are separated by commas. Here are some examples of functions:
Max(3, 5, 12.6, sinusoid) PrevEvent(sy;arc001, *-2h, *) Sqr(Abs(TagMax(tag, y, t))) Log(if tag=2 then .5 else .5)
Relative Time Expressions

Relative time expressions are of the form +/- a number of days, hours, minutes, or seconds and must be enclosed in single quotes. These expressions are converted to a number of seconds and do not imply any special processing for clock or calendar events such as daylight savings time boundaries. If intervals based on local clock times are required, use Noon( ) and Bod( ) functions to achieve the desired result.
Digital State Values

Digital state values consist of a state set specifier and a state number within that set. Each set has a list of text names for the states. To set a digital point, an expression may result in either a number (the offset) or a string containing the state name.
Chapter 4
The value of a digital point may be compared to a string in an expression. For example, if the text Run in the state set for
digital point PumpStatTag, then the following expression is valid:
If PumpStatTag <> run then 1 else 0
Operators
Operators consist of prefix operators, infix operators, and if thenelse. When the operators consist of letters (such as AND), lowercase letters are considered the same as the corresponding uppercase letters.
Prefix Operators
A prefix operator appears to the left of its operand, e.g.,"- x". Table 4-2 Prefix Operators
Operator not Meaning Negation Complementati on
Infix Operators
An infix operator appears between its two operands, e.g., "x+5". Table 4-3 Infix Operators
Operator + * / ^ < = > <= <> >= mod and or
62
Meaning Addition Subtraction Multiplication Division Raise to a power Less than Equal to Greater than Less than or equal to Not equal to Greater than or equal to Modulus Conjunction Inclusive disjunction
OSI Software, Inc.
Operator in .. in ( )
Meaning Membership in range Membership in discrete set
The mod operator returns the remainder after its left operand is divided by its right operand. For example, 17 mod 3 equals 2. The and operator returns 1 if both operands are nonzero; otherwise it returns zero. The or operator returns 1 if either operand is nonzero; otherwise it returns zero. The in .. operator returns 1 if true and 0 if false. The in .. operator can be used with functions that return digital states and uses the offset within the digital state set for comparison. The digital states must all be in the same digital state set. Lexical comparisons are made with character strings.
Note: The use of the in operator with functions that return digital states and character strings is not supported for this release.
A relational operator (one of <, =, >, <=, <>, and >= ) returns a value of 0 for false or 1.0 for true. These operators may be used to compare numbers, timestamps, time periods, or character strings. You may compare values of dissimilar types without error; for instance, you may compare a character string to a number or a timestamp to a time period. Here are some examples.
* + 5 y 3 12 / 3.6 x and (not y) 5 in 0 .. 10 40 in (TagVal(siusoid), TagVal(sinusoid, t), TagVal(sinusoid, y)) digitaltag in TagVal(digitaltag, y) in TagVal(digitaltag, t) 'SI:NUSOID' = "shutdown" "Fred" < "Frederick"
ifthenelse
The ifthenelse operator is a compound operator whose operands are used as follows:
if expr0 then expr1 else expr2
Chapter 4
where expr0, expr1, and expr2 are expressions. If expr0 is true (nonzero), this operator returns the value of expr1; it returns the value of expr2 if expr0 is false (zero). Here are some examples:
if tag1 < 50 then overlimit else good if tag1= 1 then Sin(tag2) else if tag1= 2 then Cos(tag2) else Tan(tag2) if tag3<> shutdown then (if tag1 > tag2 then tag1 else tag2) else error * + (if tag2 = 0 then 3600 else 0) Note: You must include the if and the then and the else. Nested operations are supported.
Operator Priority
Operators are executed in order of priority, from highest to lowest. Within the same priority, operators are executed from left-to-right or right-to-left, depending on the operator. See the following table: Table 4-4 Operator Priority
Operator -(prefix) ^ * / mod + < = > <= <> >= in .. in( ) not and or Priority 9 (done first) 8 7 6 5 4 3 2 1 (done last) Order L-R R-L L-R L-R L-R L-R L-R L-R L-R
Parentheses Parentheses may be used anywhere to affect the order of calculation. Regardless of operator priority, operations within parentheses are evaluated before operations outside those parentheses. For example, (2+3) * 5 equals 25, while 2 + 3 * 5 equals 17.
64
OSI Software, Inc.
Calculating with Time

Time can be expressed as a timestamp or time period. Arithmetic operations are allowed on time values.
Timestamps
A timestamp is an absolute date and time. To obtain a timestamp, you may specify a timestamp string in single quotes, or one of the built-in functions that returns a timestamp:
'12-Jun-91' * NextEvent('tag1', *)
Be careful using timestamp strings in expressions which are not full date and time. For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out, they default to the current date. Time fields default to 00. The following timestamps are examples of these types of timestamps.
8:00:00 0:00:00.0000 12:00:00 25
These timestamps are converted into absolute timestamps at the time at which the equations are compiled. The first three examples will be the 8am, midnight, and noon, on the day that the equations were compiled. The last example will be midnight on the 25th of the month that the equation was compiled. Instead, timestamps that are calculated at runtime should be used.
Bod(*)+ +8h Bod(*) Noon(*) Bom(*)+ +24d
In addition, ParseTime( ) can also be used for these type of timestamps because ParseTime is a function that is evaluated at runtime.
ParseTime(8:00:00) ParseTime(0:00:00.0000) ParseTime(12:00:00) ParseTime(25)
65
Chapter 4
Periods
A period is a space of time. To obtain a period, one may use built-in functions that return a period, such as TimeEq or take the difference between two timestamps:
y-t TimeEq('tag1','14-Dec-97', *,0.0)
Relative time stamps are periods when they are additions and subtractions to an absolute time. They reference a period only when used in a built-in function that requires a start time and an end time. The following are examples of the use of relative time stamp:
14-Dec-97 + +1h TimeEq('tag1','14-Dec-97', +1h,0.0) PctGood('tag1',-1h,14-Dec-97,0.0)
Relative time stamps alone are not periods. If no reference time is provided the relative time stamp is converted into an absolute time stamp using the default as January 1, 1970 Universal Coordinate Time (UTC). This is the start for archive timestamps in PI for NT and UNIX. Therefore a relative time that includes a subtraction and has no reference (e.g., -1h) would result in adverse behavior. For further details, refer to the chapter on PI Time Conversions in Volume II of the documentation.
Comparisons
One can perform all comparisons, including in, on timestamps and time periods.
*+20m >= *+300s prevevent('tag1') > tag1
The following example may seem to be a comparison utilizing relative time stamps.
20m >= 300s
In fact, these relative timestamps are first converted into absolute timestamps and then used in the comparison.
Arithmetic Operations
One can perform certain arithmetic operations on times. The following table shows the valid operations and their results,
66 OSI Software, Inc.
where N represents a number, T represents a timestamp, and P represents a period. Table 4-5 Valid Arithmetic Operations in Performance Equations
Opera tor + Express ion T+ P T+ N P+T P+N P+P N+T N+P - (infix) T - P T-N T-T P-N P-P * P*N N*P / P/P P/N N/P mod T mod P T mod N P mod P (prefix ) P mod N -P Res ult T T T P P T P T T P P P P P N P N P P P P P Example * + +3h * + 10 +3h + * (t- y) + 10 (t- y) + (t-y) 10 + * 10 + (t-y) * +3h * - 10 t y (t- y) - 10 (t- *) - (t-y) (t y) * 5 5 * (+1d +1h) (t- *) / (t-y) (t- *) / 2 2 / (t- *) * mod *-t * mod 2 (*-y)mod (*-t) (*-y) mod 3 -(*-y)
Note: The use of T mod P currently returns a T. The timestamp returned is the result of T mod P added to January 1, 1970 Universal Coordinate Time (UTC).
Type Compatibility and Error Checking

The performance equation evaluator can handle several kinds of data. However, it can seldom use one data type where another is expected. For example, you cannot add two character strings, or multiply two timestamps together. The built-in functions may require particular data types for particular arguments.
Chapter 4
The data types we recognize are: Number Character string Tagname Timestamp Period
These have all been described. Every variable has one of these data types; every function returns one of these data types.
Digital States
The performance equation evaluator considers digital states to be the same as character strings. A Digital or String PI point always returns a character string value. A Real or Integer PI point's data type may vary. It will be a number or a character string, depending on circumstances.
Error Values
When the performance equation evaluator cannot perform a calculation, it returns an error value. Error values propagate through most calculations. For example, an error value plus one is an error value. Exceptions to this rule are the Concat and BadVal functions, and comparison operators. These all treat error values as character strings.
Type Checking
At compile (parse) time, we check type compatibility as far as possible. This lets us catch errors, such as trying to add a number to a character string. To check for compile time errors, in Windows NT check to pipc.log file located in the \pipc\dat\ directory. For UNIX check the pipeschd.log file located in \pi\log directory. However, not all errors can be detected at compile time. The expression
sinusoid / 2.0
works well if sinusoid has a numeric value, but if sinusoid is equal to "shutdown" this operation cannot be performed. At compile time, we always allow you to specify a point name, or a variable or function that returns a point value, wherever a
number or character string is expected. At run time, if the data type is correct, the calculation works properly; otherwise, there is a warning message, and the faulty operation returns an error value. Comparisons Comparisons are an exception to this rule. Every comparison is valid, regardless of its operand types. Operands of different types are unordered; that is, they are not less than, greater than, or equal to one another. All comparisons of unordered operands are false (yield zero) except for <>, which is true (yields 1).
Pipetest Utility
The pipetest utility is used to test performance equation syntax. It accepts a single performance equation per line. Each equation is immediately compiled and evaluated. The utility is limited to equations that are 512 characters or less. However, the PEs are not limited to 512 characters. The utility can not be use to test dynamic response functions. The pipetest utility is located in the under the pi\adm directory. It can operate interactively or take its input from a file. For more information, see the following examples: Interactive Mode Example The pipetest utility can be run interactivly from a Command Prompt window. The following examples can be tested within the utility.
If not BadVal(sinusoid) then ((sinusoid 50)^2)/25 else 0 If PctGood(sinusoid,y,t)>90 then TagAvg(sinusoid,y,t) else 0 TimeLT(sinusoid ,y ,t , TagVal(sinusoid,*))
The first expression checks for a bad value of the point sinusoid and then does a calculation. The second expression checks if the percent good of the point sinusoid from midnight yesterday to midnight today is greater than 90 percent then calculates the average for that time period. The final example
Chapter 4
finds the total time that the point sinusoid has a value less than the current value of that point.
Figure 4-1 Interactive pipetest utility session File Input Example The same performance equations can be placed in a file. The file name is passed on command line using the f switch. In this example, an input file named pescript.dat contains the performance equations.
70
OSI Software, Inc.
Figure 4-2 Input file, pescript.dat, with performance equations
Figure 4-3 Evaluated result of each input line Each input line in turn is echoed and the evaluated result is displayed.
71
Chapter 4
PE Scheduler
Overview
The PE Scheduler is a UNIINT-based program designed in conformance with the PI Instrument and Computer Interfacing Standard. The PE Scheduler will evaluate the performance equation specified for all points that have a point source specified in pipeschd.bat (default point souce is C). Table 4-6 Features of PE Scheduler
Supported Features Sign-up for Updates Exception Reporting PI-API Support Vendor Software Required Fail-over Multiple instances Maximum Point Count Yes Yes PE Scheduler must run on home node No No Yes Unlimited
Scheduling
The type of scheduling determines when a performance equation will be evaluated. Two types of are supported: clock scheduling (based on scan class) and event-based scheduling (based on an input equation becoming true).
Clock Scheduling
Clock scheduling evaluates the equation at fixed intervals. Two attributes, period and offset, determine when to evaluate the equation. The period specifies the interval between calculations and the offset specifies the time since midnight to start the calculation. Specifying the offset is optional. Scan classes are defined in the file pipeschd.bat for NT or pipeschd.sh for UNIX:
/f=hh:mm:ss,hh:mm:ss
where the first hh:mm:ss is the time interval, the second is the time offset. To create a scan class that calculates once per hour starting on the hour (0 offset), use this:
72
OSI Software, Inc.
/f=01:00:00,00:00:00
To create a scan class that calculates once per 8 hour shift starting at 7 a.m. use this:
/f=08:00:00,07:00:00
A particular scan class is mapped to a point by specifying its position in Location4. The first scan class defined is specified by 1; the second scan class defined is specified by 2; etc. Building Clock-Scheduled Calculation Points The easiest way to build points is using the PI TagConfigurator tool described in the PI System Management Tools chapter in Volume II of this documentation. The following example creates a point in scan class 1 by defining 4 point attributes and leaving the rest of the attributes as defaults. The PI TagConfigurator tool builds a point sinsq, whose archive values will be derived from the equation specified in the ExDesc (extended descriptor). Note that the equation includes the snapshot of the point sinusoid.
Figure 4-4 Example that creates a point in scan class 1 Alternatively, the following script can be used in piconfig.
@table pipoint @ptclass classic @mode create,t @istru tag, exdesc, pointsource, location4 sinsq,"(( sinusoid - 50 ) ^ 2 ) /25",C,1
Chapter 4
Performance Equations @mode list
Performance Considerations Although the only limit in the number of performance equations is the number points available to the system, there are practical limits on the performance of the PE scheduler. It is possible for the PE Scheduler to get overloaded. If a scan class is more then one scan period behind, it will skip the calculation in order to catch up. To check if PE Scheduler is skipping calculations, look at the pipc.log file located in the pipc\dat directory for Windows NT or pipeschd.log located in the pi\log directory for UNIX.
Figure 4-5 Sample pipc.log file in the pipc\dat directory To improve system performance, the offset attribute could be utilized. For example, by using offset times of 10 seconds, 20 seconds, 30 seconds, and so forth, a set of five-minute calculations can be divided into thirty sub-groups to even out the system loading. Equation Evaluation Order Equations in the same scan class are processed 'in parallel'. To force equations to be evaluated in a specific sequence, you must use the scan class offset. If two calculations are evaluated at the
same period and offset, there is no way to determine which calculation is done first. To ensure a particular processing order, assign PE points to scan classes that have different offsets.
Event Scheduling
Points may be calculated in response to an update event on a single other point. The only events considered by the event scheduler are Snapshot events. Out of order events bypass the Snapshot and thus are not considered by the event scheduler. Interface events that are filtered out by exception reporting are also not considered by the event scheduler. To specify event scheduling, include a clause in the extended descriptor attribute of the form event = tag. If event scheduling is specified, the scan classes are ignored. The following is an example of the event scheduled equation created in the PI-TagConfigurator.
Figure 4-6 Sample of event-scheduled equation created in PI-TagConfigurator The event clause is separated from the expression by a comma. When a comma (,) is included in the extended descriptor, the entire string must be enclosed in double quotes (") to help piconfig to interpret it as a single field.
@table pipoint @mode edit @istru tag, exdesc sinsq,"event = sinusoid, 50 ) ^ 2 ) /25" @mode list
(( sinusoid -
75
Chapter 4
Limitations and Attributes

In both the clock and event-based scheduling methods, there is a set limit on the number of characters that can be used for the extended descriptor. In the PI-TagConfigurator the limit is 4096 characters and in piconfig the limit is set at 1024 characters. To extend the limit in piconfig add the command @linelen NNNN where NNNN is the new limit length in the piconfig session before creating or editing the PE calculation point. The PE Scheduler does not support string points but built-in function calls to string points are supported. Exception filtering is done on calculated points according to the exception specifications defined by the point attributes ExcMin, ExcMax, ExcDev, and ExcDevPercent. Compression filtering is done on calculated points according to the compression specifications defined by the point attributes CompMin, CompMax, CompDev, and CompDevPercent. Function calls that access the archive such as functions to obtain point attributes and functions that allow for previous timestamps or periods incur larger loads and may slow the performance of the system. Hence a rule of thumb would be to try and create performance equations that read snapshot values. Another idea would be to utilize the totalizer instead of creating a performance equation when possible because the totalizer signs up for exceptions and reads snapshot values instead of accessing the archive.
Multiple Instances of the Performance Equation Scheduler

Any expression that contains an archive call may take a very long time to evaluate. During archive shifts or times of high client use, a single evaluation may take several minutes. An instance of Pipeschd that evaluates any archive functions cannot be counted on for critical real-time results. Instead, multiple instances of the Pipeschd can be run simultaneously. The main reason to do this is if there are real time scan classes that do not get processed in a timely manner due to slower scan classes. Pipeschd will complete one scan class before processing the next. To run multiple instances, make multiple copies of the pipesched.bat file. Each instance should be assigned a different point source in the pipesched.bat file.
PE Scheduler Installation
The PE Scheduler is installed with the rest of the PI system. It consists of the executable (pipeschd.eXE on NT or pipeschd on UNIX) and the startup script (pipeschd.bat on NT or pipeschd.sh on UNIX). These files are located in the PI/bin/ directory.
Startup Script
The PE Scheduler program is normally started automatically by the PI startup script. The PI startup script starts up the PI server processes which includes the PE Scheduler. The PE Scheduler startup script starts the PE Scheduler, passing it configuration parameters as shown. The following is an NT example of the PE Scheduler startup script. On Windows NT the PE Scheduler is normally started as an NT service, which allows it to be run in the background, independent of any particular login session.
rem rem $Archive: /PI/3.2/subsystems/pipeschd/pipeschd.bat $ Rem $Log: /PI/3.2/subsystems/pipeschd/pipeschd.bat $ rem rem rem 3 8/19/97 12:16p Jonrem rem Changes to reflect starting from bin dirrem rem rem Interactive PI PE Scheduler Startup rem ..\bin\pipeschd /ps=C /Q /host=localhost:5450 /f=00:00:30 /f=00:00:05
The following is a UNIX example of the PE Scheduler startup script.

#!/bin/sh # # pipeschd.sh # ./pipeschd /Q /ps=C /ec=24 /f=00:00:30 /f=00:00:05 \ /host=localhost:5450 > ../log/pipeschd.log 2>&1 & #
where:
Chapter 4
Performance Equations /ps=C
specifies the point source,

/f=00:00:30
defines the scan frequency for scan class 1 and

/f=00:00:05
defines the scan frequency for scan class 2.

/host=
specifies the PI home node. The PE scheduler must run on the home node, thus:
/host =localhost:5450
Defining Scan Classes

The position within the startup command line defines the scan classes; that is, the first /f= refers to scan class 1, the second /f= refers to scan class 2, etc. Simply add more /f= parameters to define more scan classes. The calculated point is assigned to a scan class using the Location4 attribute. For example, if Location4 is set to 2, the PE will be evaluated every 5 seconds.
Shutdown
The PE Scheduler program is normally shutdown automatically by the PI Server shutdown script. On NT, pisrvstop.bat stops all PI subsystems (including the PE Scheduler). The subsystem may be started or stopped independent of the PI System. To do this on NT, use the Control Panel Services dialog box. On UNIX, pistop.sh stops all PI subsystems (including the PE Scheduler). PI Scheduler may be started or stopped independent of the PI System. To do this on UNIX, use the ps command to determine the process id, and the then use the kill command to stop the process:
$ ps -aef | grep pipeschd piadmin 25688 1 1 Sep 14 ? 35:22 ./pipeschd /Q /ps=C /ec=24 /f=00: $ kill -2 25688
78
OSI Software, Inc.
Examples of Performance Equations

This section provides some helpful hints and examples on writing performance equations. The calculation points are where the performance equation resides and are created using the PITagConfigurator or in piconfig. Examples of creating a calculation point are given in PE Scheduler section of the chapter.
Hints
Use the BadVal function to check to see if the value to be evaluated is bad before carrying out a calculation. Use the PctGood function to check if the amount of data that is good is within an acceptable level. Remember to place the performance equation in the exdesc (extended descriptor). Remember to escape anything that requires double quotes with double quotes. Cascade calculations that occur in the same scan class using offsets. Be careful using ambiguous timestamps. Check the log file pipc.log in the pipc\dat directory for Windows NT or pipeschd.log in pi\log for UNIX to see if there are errors in the equations during compilation. Use the pipetest utility to see if equation is syntactically correct. Set rescode=4 for stair step point.
Totalization of Digital Point Example

In this example, the goal is to obtain the total of the number of times a point goes into a digital state for the month. Accumulator is the performance equation point. OnOffSwitch is the digital point that uses a digital state set with two digital states: ON and OFF.
79
Chapter 4
Performance Equation
If day(*)=1 and day(PrevEvent(Accumulator, *))<>1 then 0 else if PrevVal(OnOffSwitch, *) <> ON and OnOffSwitch = ON then 'Accumulator' +1 else 'Accumulator'
This performance equation checks that if it is the first of the month and that the last event did not occur on the first of the month. If it is the first of the month, Accumulator resets. Otherwise if the previous value of OnOffSwitch is not the digital state OFF and the current value is ON then Accumulator increments.
TagTot Example
In this example, the goal is to use the TagTot function to obtain a total on a point that has engineering units other than the default per day. RateTag has engineering units of gallons per hour and the objective is to get the number of gallons for the previous day. Performance Equation for TagTot
If PctGood(RateTag, y, t)>85 then TagTot(RateTag, y, t)*24 else Bad Total
First, the performance equation checks the percent of good values starting from midnight yesterday to midnight of the current day. If the percentage is greater than 85 then a total of RateTag is calculated for that given period. The total is multiplied by 24 hours per day to obtain the units of gallons. If the percentage is less than or equal to 85 then the digital state of Bad Total is given. In this example, although the RateTag would have an integer or real PointType, digital states only in the System digital state set are allowed.
TagMax vs. Max Example

In this example, the objective is to obtain the maximum of a point for the month. One method for doing this is the TagMax function, shown in the next paragraph. An alternative method, also shown below, uses the Max function.
80
OSI Software, Inc.
Performance Equation for TagMax

If Day(*)=1 and Day(PrevEvent(RateTag, *))<>1 then TagMax(RateTag, Bom(PrevEvent(RateTag, *)), Bom(*)-+1s) else No Result
The performance equation first checks that it is the beginning of the month and then finds the maximum of RateTag from the prior month up to one second before the beginning of the current month. Notice that the beginning of the month function Bom was not used to check for the first of the month. The reason for this is that an expression like:
Bom(*)= *
is not as accurate as the expression used in the performance equation because the current time of the scan may not exactly equal the beginning of the month. Also the TagMax function may use too many resources accessing the archive for data of the previous month and slow down the system. Performance Equations for Max
If Day(*)=1 and Day(PrevEvent(RateTag, *))<>1 then Max(TagZero(RateTag), RateTag) else Max(RateTag, MaxTag)
This performance equation has the tagname of MaxTag and compares the point to be maximized RateTag to the current maximum in MaxTag. If the current time is the first of the month, MaxTag is reset by comparing the maximum between the current value of RateTag to the tagzero of RateTag. This version of obtaining a maximum makes only one archive call as opposed to archive calls to obtain one month of data.
Built-in Functions
Built-in Functios for Performance Equations are described individually on the following pages.
Arguments
A tagname may be used in any argument where a number or character string is called for. The point is evaluated as if it had been written TagVal(tag), which is the same as TagVal(tag, '*' ).
Chapter 4
This gets the points value at the current time for the calculation. If the argument calls for a number, but the points value is a digital state when the function is evaluated, a run-time error is generated.
Table of Built-in Functions

The built-in functions can be grouped in several categories as shown in the table below: Table 4-7 Built-in Functions for Performance Equations
Function Name Type Transcende Asin ntal Acos functions Atn Atn2 Cos Cosh Exp Log Log10 Sin Sinh Sqr Tanh Tan Aggregate Avg functions Max Median Min PStDev SStDev Total Other math Abs functions Frac Int Poly Round Sgn Trunc
82
Meaning Arc sine Arc cosine Arc tangent Arc tangent (two arguments) Cosine Hyperbolic cosine Exponential Natural logarithm Common logarithm Sine Hyperbolic sine Square root Hyperbolic tangent Tangent Average Maximum Median selector Minimum Population standard deviation Sample standard deviation Sum Absolute value Fractional part of number Integer part of number Evaluate polynomial Round to nearest unit Numerical sign Truncate to next smaller unit
OSI Software, Inc.
Function Name Type Miscellaneo Badval us functions Concat
Meaning See if a value is bad (not a number or time)
Archive retrieval
Archive search
Concatenate two or more strings Curve Gets value of a curve DigState Get digital state from a string StateNo Get the code number of a digital state Tagbad See if a point has an abnormal state NextEven Time of a points next archive t event NextVal Points next value after a time PrevEvent Time of a points previous archive event PrevVal Points previous value before a time TagVal Points value at a time FindEq Timestamp when point value FindGE FindGT FindLE FindLT FindNE TimeEq TimeGE TimeGT TimeLE TimeLT TimeNE Timestamp when point value Timestamp when point value Timestamp when point value Timestamp when point value Timestamp when point value Total period when point value Total period when point value Total period when point value Total period when point value Total period when point < value Total period when point value Percent of good time in a period Range of minimum to
83
Archive statistics
PctGood Range
Chapter 4
Performance Equations Function Type Name StDev TagAvg TagMax TagMin TagTot TagDesc TagEU Meaning maximum value Time-weighted standard deviation Time-weighted average Maximum value in a period Minimum value in a period Time integral over a period Get a points descriptor
Point attributes
Time functions
Get a points engineering unit string TagExDes Get a points extended c descriptor TagName Get a points name TagSourc Get a points point source e character TagSpan Get a points span TagType Get a points type character TagTypVa Get a points typical value l TagZero Get a points zero value Bod Timestamp for beginning of the day for given timestamp Bom Timestamp for beginning of the month for given timestamp Day Day of the month from a timestamp DaySec Seconds since midnight from timestamp Fonm Timestamp for first of the next month for given timestamp Hour Hour from a timestamp Minute Minute from a timestamp Month Month from a timestamp Noon Timestamp for local noon of day of a timestamp ParseTim Convert character string to e time Second Second from a timestamp Weekday Day of the week from a timestamp Year Year from a timestamp Yearday Day of the year from a
OSI Software, Inc.
84
Function Type Dynamic Response
Name Arma Delay MedianFil t Impulse
Meaning timestamp Dynamic response from Auto Regressive Moving Average model Introduces time delay Selects the median value of time series Dynamic response characterized by impulse response shape
Abs
Return the absolute value of an integer or real number. Format
Abs(x)
Arguments x Must be an integer or real number. Returns The absolute value of x. Exceptions If x is not an integer or real number, returns an error value. Examples
Abs(1) Abs(-2.2) Abs(tag1) Abs(tag1- tag2)
85
Chapter 4
Acos
Return the inverse (or arc) cosine of an integer or real number. The inverse cosine of x is the angle in radians whose cosine is equal to x. Format
Acos(x)
Arguments x Must be a real number between -1.0 and 1.0, inclusive. Returns The inverse cosine of x, in radians. Exceptions If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value. Examples
Acos(1-.5) Acos(-.5) If tag1 < 1 and tag1 > -1 then Acos(tag1)else 0
Arma
Calculate dynamic response for Auto Regressive Moving average model. Format
Arma( In, RunFlag, ( a1, a2, aN ),( b0, b1, b2, bN ) )
Arguments The denominator and numerator coefficient series are enclosed in parenthesis with a comma between the two. There must be
only one more term (b0) in the numerator than denominator. Both In and RunFlag may be any expression that evaluates to a number. In Input signal. RunFlag Non-zero enables filter to run. a1,a2, Coefficients of past output terms. b0, b1,b2 Coefficients of the present and past input terms of the model. Returns The next output value in time series response to past and present input. ut = a1 * ut-1 + a2 * ut-2 + + an * ut-n + b0 * yt + b1 * yt-1 + b2 * yt-2 + + bn * yt-n Where ut is model output at time t, now. ut-1 is output one sample interval in the past. yt is the input signal at time t. If RunFlag expression result is 0, the model is reset. Depending on the number of coefficients used, Arma stores the inputs and outputs until an evaluation of the model is available. For example, in
Arma( input_tag, 1, ( 0. ,1)( 1, -1 ,1))
Arma will store two previous values of the input and output. Hence when the point is first created, no good results will be given until two prior values of the input have been stored. From then on, the two most current previous values will be stored. Exceptions Arma will give different results depending on which type of scheduling is used. In scan class scheduling, the interval between time series values depends on the scan class and gives values at evenly spaced time intervals. On the other hand, event based scheduling is dependent on a trigger from another point. If the exception deviation is not zero, the intervals for events will be not be evenly spaced in time and hence Arma will give results
Chapter 4
that are not trustworthy. Arma is not supported in the pipetest utility or in PI DataLink. If the input point is not a real number or integer Arma will return an error. Examples Derivative Integration Second order filter
Arma( input_tag, 1, ( 0. )( 1, -1 )) Arma( input_tag, 1, ( 1. )( .05, 0. )) Arma( input_tag, 1, (.25,.25) ,(.1,.25,.15 ))
I n p u t S ig n a l
b0
a1
O u tp u t
b1

b2 a2

b3
...
a3
...
bn an
Figure 4-7 Block Diagram of ARMA Calculation Function
Asin
Return the inverse (or arc) sine of a number. The inverse sine of x is the angle in radians whose sine is equal to x.
88
OSI Software, Inc.
Format
Asin(x)
Arguments x Must be a real number between -1.0 and 1.0, inclusive. Returns The inverse sine of x, in radians. Exceptions If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value. Examples
Asin(TagVal(tag1,y)) Asin(-0.5) Asin(tag1)
Atn
Return the inverse (or arc) tangent of an integer or real number. The inverse tangent of x is the angle in radians whose tangent is equal to x. Format
Atn(x)
Arguments x Must be an integer or real number. Returns The inverse tangent of x, in radians.
89
Chapter 4
Exceptions If x is not an integer or real number, returns an error value. Examples

Atn(1) Atn(-2.2) Atn(tag1) Atn(tag1- tag2)
Atn2
Calculate the inverse (or arc) tangent of a pair of numbers, which represent a point on the plane. If you draw a line between the point whose Cartesian coordinates are (y, x) and the origin, the angle between that line and the x-axis is the inverse tangent of (y, x). Format
Atn2(y, x)
Arguments y Must be an integer or real number. x Must be an integer or real number. Returns The inverse tangent of (y, x), in radians. Exceptions If x or y is not an integer or real number, returns an error value. Examples
Atn2(TagVal(tag1,y),TagVal(tag1, y))
Atn2(1,1) Atn2(tag1, tag2)
Avg
Return the average of two or more arguments, or of all the elements in an array. Format
Avg(x1, x2, ..., xn)
Arguments X1...Xn May be numbers, timestamps, or time periods, but all must be the same data type. Returns The average of the arguments. The result is the same data type as the operands. Exceptions Arguments whose run-time values are character strings or digital states are not included in the average. If all values are character strings or digital states, Avg returns an error value. Examples
Avg(TagVal(tag1,y),TagVal(tag1, y),1,2) Avg(y, t, 14-Dec-97, 14 8:00) Avg(tag1, tag2)
Badval
Test a value to see if it is bad. For real and integer points, a bad value is a digital state value. For digital points, a bad value is a digital state value outside its own digital state set.
91
Chapter 4
Format
Badval(x)
Arguments x A value to be tested. Returns 1 if the value is bad 0 otherwise. Exceptions Returns 1 for blob points. Returns 0 for character strings. Examples
BadVal(tag1) BadVal(digitaltag) BadVal(TagVal(stringtag, 14-Dec-97 8:00:00))
Bod
Gets the timestamp for midnight at the start of a day. Format
Bod(time)
Arguments time timestamp. Returns timestamp for the start of the day. Exceptions None.
92
OSI Software, Inc.
Usage Note This function is useful for establishing a time at a unique clock time independent of the length of particular days. See also Bom( ), Bonm( ), and Noon( ). Examples
Bod(*) Bod(y) Bod(FindEq(tag1, 14-Dec-97, +17d,50))
Bom
Gets the timestamp for midnight at the beginning of the month. Format
Bod(time)
Arguments time timestamp. Returns timestamp for the start of the month. Exceptions None. Usage Note This function is useful for establishing a time at a unique clock time independent of the length of particular days. See also Bod( ), Bonm( ), and Noon( ). Examples
Bom(*) Bom(PrevEvent(tag, *)) Bom(FindEq(tag1, 14-Dec-97, +17d,50))
Chapter 4
Call
Call a user-written FORTRAN or C function. Call is not supported in this release.
Concat
Concatenate two or more strings. Format
Concat(s1, s2, ..., sn)
Arguments S1...Sn Must be character strings, or expressions yielding character strings. Returns The character strings, concatenated together. This function does not insert blanks between its arguments. If you need blanks, you must add them yourself. Exceptions Any argument that is not a string is replaced by an error value.
Note: Expressions yielding character strings is not supported in this release.
Examples
Concat(shut, down)
94
OSI Software, Inc.
Cos
Return the trigonometric cosine of an integer or real number. Format
Cos(x)
Arguments x Must be an integer or real number, which represents an angle in radians. Returns The cosine of x. Exceptions If x is not an integer or real number, returns an error value. Examples
Cos(tag1) Cos(1) Cos(1.1)
Cosh
Return the hyperbolic cosine of an integer or real number. Format
Cosh(x)
Arguments x Must be an integer or real number. Returns The hyperbolic cosine of x.

Chapter 4
Exceptions If x is not an integer or real number, returns an error value. Examples

Cosh(tag1) Cosh(.9) Cosh(1)
Curve
Returns the y value of a curve given the x value. Format
Curve( x, (x1,y1) (x2,y2) (xn,yn) )
Arguments x Expression evaluating to a number. x1, y1 The first point on the curve. The xis and yis are numeric constants evaluated at compile time. The values set for xis must be in assending order. Returns Returns the y value on the curve corresponding to the value of x. Linear interpolation is used between points defining the curve. If the value of x is less than x1 then y1 is returned and if it is greater than xn, yn is returned. The points are assumed to be ordered in the x direction from smallest to largest. Exceptions If the value of x is not an integer or real number, an error value is returned. Examples
curve(tag1, (0,100) (100,0) )
96
//inverter
OSI Software, Inc.
curve(tag3, (25,25) (75,75) )
//limiter
Day
Extract the day of the month from a timestamp. Format
Day(time)
Arguments Time A timestamp. Returns The day of the month of time, in the range 131. Exceptions None. Examples
Day(*) Day(t) Day(FindGt(tag1, *-30d, *,50))
DaySec
Extract the number of seconds since midnight from a timestamp. Format
DaySec(time)
Arguments Time A timestamp.
97
Chapter 4
Returns The number of seconds of time since midnight, in the range 0 86399. Exceptions None. Usage Note This function is the same as the time ( ) function in the PI 2.x Performance Equation package. For example, if the current time is 8:30 AM, DaySec('*') returns 30600. Examples
DaySec(*) DaySec(t) DaySec(FindGt(tag1, *-30d, *,50))
Delay
Delay line, the output tracks the input. For use in real time calculations, e.g., in Pesched, this function may be a better choice than Prevevent( ). Format
Delay( x, RunFlag, N )
Arguments x Input signal. RunFlag Non-zero enables filter to run. N Length of the delay, integer.
98
OSI Software, Inc.
Returns The input signal delayed by N calculation intervals. For scan class scheduling, the calculation interval is based on the scan class. For event based scheduling, the calculation interval will be dependent on the trigger and the exception deviation. Exceptions Delay is not supported in the pipetest utility or in PI DataLink. If the input point is not a real number or integer Delay will return an error. Examples
Delay(tag1,1,2)
DigState
Translate a character string representing a digital state into its corresponding digital state. Format
DigState(s1,x)
Arguments s1 A character string representing a digital state. x (optional) A digital point in which the character string represents a digital state. If omitted, defaults to system digital state set. Returns A digital state Exceptions If the character string does not represent a digital state in the digital state set of the reference digital point, returns an error. If
Chapter 4
digital point is omitted and character string does not represent a digital state in the system state set then, error is returned. Examples
DisState(digitalstring, digitaltag) StateNo(DigState(digitalstring, digitaltag))
Exp
Return the exponential of an integer or real number. This is the number ex, where e = 2.7182818... Format
Exp(x)
Arguments x Must be an integer or real number. Returns The exponential of x. Exceptions If x is not an integer or real number, returns an error value. Examples
Exp(tag1) Exp(TagVal(tag1,14-Dec-97)) Exp(11)
FindEq
Find the first time, within a range, when a point is equal to a given value.
100
OSI Software, Inc.
Format
FindEq(tag, starttime, endtime, value)
Arguments Tag A tagname enclosed in single quotes. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for. Returns The timestamp closest to starttime, within the given range, for which the point was equal to the given value. Exceptions If the point was never equal to the given value, FindEq returns an error value. Usage Note FindEq looks for an archive event that is exactly equal to the given value. It does not interpolate between values. If there is no archive event with the desired value, FindEq will not find it. Therefore, you should not use FindEq to look for a threshold crossing for a real-valued point. Examples
FindEq(tag1, t, *,40.0) FindEq(digitaltag, -1d, *, TagVal(digitaltag, 14-Dec-97)) FindEq(digitaltag, 14-Dec-97, *, On) PI Data Archive for Windows NT and UNIX 101
Chapter 4
FindGE
Find the first or last time, within a range, when a point is greater than or equal to a given value. Format
FindGE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for. Returns The timestamp closest to starttime, within the given range, for which the point was greater than or equal to the given value. Exceptions If the point was always less than the given value, FindGE returns an error value. Usage Note FindGE interpolates between archive events, if necessary, to find the value it is looking for.
102
OSI Software, Inc.
Examples
FindGE(tag1, t, *,40.0) FindGE(digitaltag, -1d, *, TagVal(digitaltag, 14-Dec-97)) FindGE(tag1, -1d, *,tag2)
FindGT
Find the first time, within a range, when a point is greater than a given value. Format
FindGT(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for. Returns The timestamp closest to starttime, within the given range, for which the point was greater than the given value. Exceptions If the point was never greater than the given value, FindGT returns an error value.
Chapter 4
Usage Note FindGT interpolates between archive events, if necessary, to find the value it is looking for. Examples
FindGT(tag1, t, *,40.0) FindGT(tag1, -1d, *,40.0) FindGT(digitaltag, -1d, *, TagVal(digitaltag, y))
FindLE
Find the first time, within a range, when a point is less than or equal to a given value. Format
FindLE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for. Returns The timestamp closest to starttime, within the given range, for which the point was less than or equal to the given value.
Exceptions If the point was always greater than the given value, FindLE returns an error value. Usage Note FindLE interpolates between archive events, if necessary, to find the value it is looking for. Examples
FindLE(tag1, t, *,40.0) FindLE(tag1, -3600, *,40.0) FindLE(tag1, Saturday, *,40.0)
FindLT
Find the first time, within a range, when a point is less than a given value. Format
FindLT(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for.
105
Chapter 4
Returns The timestamp closest to starttime, within the given range, for which the point was less than the given value. Exceptions If the point was never less than the given value, FindLT returns an error value. Usage Note FindLT interpolates between archive events, if necessary, to find the value it is looking for. Examples
FindLT(tag1, t, 3600,40.0) FindLT(tag1, -1h, *,40.0) FindLT(tag1, 14-Dec-97 01:00:00.0001, *,40.0)
FindNE
Find the first time, within a range, when a point is unequal to a given value. Format
FindNE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp.
106
OSI Software, Inc.
Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time may be earlier than starttime; if so, the range is searched backwards. Value Must be an integer or real number or digital state (character string), the value to search for. Returns The timestamp closest to starttime, within the given range, for which the point was unequal to the given value. Exceptions If the point was always equal to the given value, FindNE returns an error value. Examples
FindNE(tag1, y, *,40.0) FindNE(tag1, 14-Dec-97, *,40.0) FindNE(tag1, 14-Dec-97, Monday,40.0)
Fonm
Gets the timestamp for midnight at the beginning of the next month. Format
Fonm(time)
Arguments Time Timestamp. Returns Timestamp for the start of the next month.
Chapter 4
Exceptions None. Usage Note This function is useful for establishing a time at a unique clock time independent of the length of particular days. See also Bod( ), Bom( ), and Noon( ). Examples
Fonm(*) Fonm(y) Fonm(FindEq(tag1, 14-Dec-97, +17d,50))
Frac
Returns the fractional part of a real number. Returns 0 for integers. Format
Frac(x)
Arguments x Must be an integer or real number. Returns The fractional part of x. Exceptions If x is not an integer or real number, returns an error value. Usage Note By definition, Int(x) + Frac(x) = x.
108
OSI Software, Inc.
Examples
Frac(tag1) Frac(1.1) Frac(TagVal(tag1, 14-Dec97))
Hour
Extract the hour from a timestamp. Format
Hour(time)
Arguments Time A timestamp. Returns The hour of time, in the range 023. Exceptions None. Examples
Hour(*) Hour(Saturday) Hour(t)
Impulse
Dynamic response specified by the impulse response. Format
Impulse(x, RunFlag, i1,i2 )
109
Chapter 4
Arguments x Input signal. RunFlag Non-zero enables filter to run. i1, i2, Unit impulse response specifying dynamic model, text sequence of numbers. Returns Dynamic model output as function of time. u(t)=i1*u(t-1) +i2*u(t-2)+ Where u(t) is the current output and u(t-1) is the output one sample interval in the past. Exceptions Impulse will give different results depending on which type of scheduling is used. In scan-class scheduling, the interval between time series values depends on the scan class and gives values at evenly spaced time intervals. On the other hand, event-based scheduling is dependent on a trigger from another point. If the exception deviation is not zero, the intervals for events will be not be evenly spaced in time and hence Impulse will give results that are not trustworthy. Impulse is not supported in the pipetest utility or in PI-DataLink. If the input point is not a real number or integer, Impulse will return an error. Examples
Impulse(tag1,1,1,1,1)
Int
Return the integer part of an integer or real number.
110
OSI Software, Inc.
Format
Int(x)
Arguments x Must be an integer or real number. Returns The integer part of x. Exceptions If x is not an integer or real number, returns an error value. Examples
Int(tag1) Int(1) Int(2.1)
Log
Return the natural (base-e = 2.7182818...) logarithm of an integer or real number. Format
Log(x)
Arguments x Must be an integer or real number greater than zero. Returns The natural logarithm of x. Exceptions If x is zero or negative, or not a number, returns an error value.
Chapter 4
Examples
Log(*) Log(14) Log(TagVal(tag1, 14-Dec-97))
Log10
Return the common (base-10) logarithm of an integer or real number. Format
Log10(x)
Arguments x Must be an integer or real number greater than zero. Returns The common logarithm of x. Exceptions If x is zero or negative, or not a number, returns an error value. Examples
Log10(*) Log10(14) Log10(TagVal(tag1, 14-Dec-97))
Max
Return the maximum of two or more arguments. Format
Max(x1, x2, ..., xn)
112
OSI Software, Inc.
Arguments X1...Xn May be numbers, timestamps, or time periods, but all must be the same. Returns The maximum of the arguments. The result has the same data type as the arguments. Exceptions Arguments whose run-time values are digital states are ignored. If all values are digital states, Max returns an error value. Examples
Max(*, y, Saturday) Max(14, tag1, 14.5, TagVal(tag2,14-Dec97)) Max(*-*-h, t-y, TimeEq(tag1, y, t,50))
Median
Return the median (middle) value of three or more arguments. Format
Median(x1, x2, ..., xn)
Arguments x1...xn May be only integers, real numbers, timestamps, or time periods, but all arguments must be the same data type. Returns The median value of the input signal as sampled over the previous number of evaluations. This is a very effective noise rejection filter.
Chapter 4
Exceptions Arguments whose run-time values are digital states are ignored. Median must have greater than two arguments that evaluate to non digital states otherewise, Median returns an error value. Usage Note Median allows for mixed integer and real data types. Median follows the data type of the first argument. Hence if the first argument is a point that evaluates to an integer then all the other entries will be converted to integers by truncation (not by rounding). Examples
Median(*, y, Saturday) Median(14, tag1, 14.5, TagVal(tag2,14-Dec97)) Median(*-*-1h, t-y, TimeEq(tag1, y, t,50))
MedianFilt
Return the median value of the last specified number of values of a time series. Format
MedianFilt( X, runflag, number )
Arguments X Input signal, but be a number. RunFlag Non-zero enables filter to run. The number of series elements to be considered. A numeric constant greater or equal to 3.
114
OSI Software, Inc.
Returns The maximum of the arguments. The result has the same data type as the arguments. Exceptions Arguments whose run-time values are digital states are ignored. MedianFilt is not supported in the pipetest utility or in PI DataLink. If all values are digital states, Medianfilt returns an error value. Examples
MedianFilt(tag1,1,3)
Min
Return the minimum of two or more arguments. Format
Min(x1, x2, ..., xn)
Arguments X1...Xn May be numbers, timestamps, or time periods, but all must be the same. Returns The minimum of the arguments. The result has the same data type as the arguments. Exceptions Arguments whose run-time values are digital states are ignored. If all values are digital states, Min returns an error value. Examples
Min(*, y, Saturday)
Chapter 4
Performance Equations Min(14, tag1, 14.5, TagVal(tag2,14-Dec97)) Min(*-*-1h, t-y, TimeEq(tag1, y, t,50))
Minute
Extract the minute from a timestamp. Format
Minute(time)
Arguments Time A timestamp. Returns The minute of time, in the range 059. Exceptions None. Examples
Minute(*) Minute(1) Minute(*-1h)
Month
Extract the month from a timestamp. Format
Month(time)
116
OSI Software, Inc.
Arguments Time A timestamp. Returns The month of time, in the range 112. Exceptions None. Examples
Month(*) Month(1) Month(*-1h)
NextEvent
Find the time of a points next archive event after a given time. Format
NextEvent(tag, time)
Arguments Tag A tagname. Time A timestamp. Returns The timestamp of the next archive event for tag after time. Exceptions If point has no archive data after time, returns an error value.
Chapter 4
Examples
NextEvent(tag1,*) NextEvent(digitaltag, *)
NextVal
Find the value of a points next archive event after a given time. Format
NextVal(tag, time)
Arguments Tag A tagname. Time A timestamp. Returns The value of the next archive event for tag after time. Exceptions If point has no archive data after time, returns an error value. Examples
NextVal(tag1,*-1h) NextVal(digitaltag, 14-Dec-97)
Noon
A timestamp for noon on the day of a given timestamp. Format
Noon(time)
118
OSI Software, Inc.
Arguments Time A timestamp. Returns A timestamp corresponding to noon of the day of the input timestamp. Exceptions None. Usage Note This function is useful for establishing a unique clock time independent of the length of particular days. See also Bod( ), Bom( ), and Bonm( ). Examples
Noon(*) Noon(14-Dec-97)
ParseTime
Translate a PI time string to a timestamp. Format
ParseTime(s)
Arguments s Must be a character string in PI time format. Either absolute or relative time may be specified. Returns The timestamp corresponding to s.
Chapter 4
Exceptions If s is not a character string, or if there is a syntax error, returns an error value. Usage Note There is no difference between ParseTime("14-Nov-92") and the timestamp expression '14-Nov-92', except that the ParseTime call definitely takes more time. This is because the timestamp expression (enclosed in single quotes) is evaluated at compile time, not run time. If you write ParseTime('14-Nov-92') (using single quotes, not double quotes) the parser will detect an error, because the expression in single quotes is already translated to a timestamp at compile time. The expression ParseTime(":12:00:00") is not the same as the timestamp expression ':12:00:00'. The ParseTime expression is evaluated at runtime and translated using '*' as the relative time base, while the timestamp expression is evaluated at compile time and uses the time the expression is parsed as the relative time base. Examples
ParseTime(14-Dec-97) ParseTime(t)
PctGood
Find the time percentage, over a given range, when a points archived values are good (not digital states). Format
PctGood(tag, starttime, endtime)
Arguments Tag A tagname.
120
OSI Software, Inc.
Starttime Must be a timestamp, the beginning of the time range to search. Endtime Must be a timestamp, greater than starttime; the end of the time range to search. Returns An integer or real number from 0.0 to 100.0: the percentage of the given time when the point had good values. Exceptions For a digital point, PctGood always returns error . Examples
PctGood(tag1, y,*) PctGood(tag1, -1h, *)
Poly
2 n Evaluate the polynomial c0 + c1 x + c2 x +... + cn x .
Format
Poly(x, c0, ..., cn)
Arguments x The variable. It must be an integer or real number. C0...Cn The coefficients. There must be at least one coefficient. All must be numbers. Returns The value of the polynomial.
121
Chapter 4
Exceptions If x or any coefficient is not an integer or real number, Poly returns an error value. Examples
Poly(tag1,1,1)
PrevEvent
Find the time of a points previous archive event before a given time. Format
PrevEvent(tag, time)
Arguments Tag A tagname. Time A timestamp. Returns The timestamp of the previous archive event for tag before time. Exceptions If point has no archive data before time, returns an error value. Examples
PrevEvent(tag1, *) PrevEvent(tag1,14-Dec-97)
PrevVal
Find the value of a points previous archive event before a given time.
Format
PrevVal(tag, time)
Arguments Tag A tagname. Time A timestamp. Returns The value of the previous archive event for tag before time. Exceptions If point has no archive data before time, returns an error value. Examples
PrevVal(tag1, *) PrevVal(tag1,14-Dec-97)
PStDev
Return the standard deviation of two or more arguments, where those arguments represent the whole population. The standard deviation of a population x1...xn is
( x )
i
n
where is the mean of the arguments, i.e., xi / n. Format
PStDev(x1, x2, ..., xn)
123
Chapter 4
Arguments X1...Xn May be numbers, timestamps, or time periods, but all must be the same. Returns The standard deviation of the arguments. If the arguments are numbers, the result is a number; if the arguments are timestamps or time periods, the result is a time period. Exceptions Arguments whose run-time values are digital states are ignored. If all values are digital states, PStDev returns an error value. Usage Note This function should not be used for most purposes. Sstdev calculates the standard deviation of a sample, and should normally be used. Examples
PStDev(tag1, ) PStDev(*,14-Dec-97, y) PStDev(*-y,14-Dec-97-*, -1h)
Range
Find the difference between a points maximum and minimum values during a given time, according to values stored in the archive. Format
Range(tag, starttime, endtime, pctgood)
124
OSI Software, Inc.
Arguments Tag A tagname. This point should represent a continuous variable. Starttime Must be a timestamp, the beginning of the time range to search. Endtime Must be a timestamp, greater than starttime; the end of the time range to search. PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The difference between the points maximum and minimum values during the given time. Exceptions If the point has no good values or the pctgood minimum is not reached in the given time range, returns an error value. Caution The OverRangeStat and UnderRangeStat digital states are not taken into account when calculating this value. Examples
Range(tag1, y, *) Range(tag1,-1h, y) Range(tag1,y, +1h,70)
Round
Round a number or time to the nearest unit.
125
Chapter 4
Format
Round(x, unit)
Arguments x Must be an integer or real number, timestamp, or time period. Unit (optional) The size of the unit to round to. If x is a number, unit must be a number. If x is a timestamp or time period, unit must be a time period. If unit is omitted, Round rounds to the nearest integer (for a number) or second (for a time period). Returns The nearest value to x which is an integer multiple of unit. Returns the same data type as x. For more information, see the examples below. Exceptions If x is a string, or if unit is of the wrong data type, returns an error value. Examples
Expression Round(12.499) Round(12.500) Round(12.8, 10) Round(14-Dec-97 11:47, +1h) Round(18:47 15:00,+1h) Value 12.0 13.0 10.0 14-DEC-97 12:00 10800 Comments Round to nearest integer Half a unit rounds up Round to nearest ten Round to nearest hour (returns timestamp) Round period to nearest hour (returns period in seconds)
Note: Round to the nearest day results in a timestamp of the closest day in UTC time and not local time.
Usage Note If x is a time, and unit is omitted, this routine has no effect, as times are only accurate to one second.
Second
Extract the second from a timestamp. Format
Second(time)
Arguments Time A timestamp. Returns The second of time, in the range 059. Exceptions None. Examples
Second(*) Second(y) Second(*-1h)
Sgn
Return a representation of the numerical sign of a number. Format
Sgn(x)
127
Chapter 4
Arguments x Must be an integer or real number. Returns -1 0 1 Exceptions If x is not an integer or real number, returns an error value. Examples
Sgn(tag1) Sgn(1) Sgn(0)
if x < 0. if x = 0. if x > 0.
Sin
Return the trigonometric sine of a number. Format
Sin(x)
Arguments x Must be an integer or real number, which represents an angle in radians. Returns The sine of x. Exceptions If x is not a number, returns an error value.
128
OSI Software, Inc.
Examples
Sin(tag1) Sin(1) Sin(1.1)
Sinh
Return the hyperbolic sine of a number. Format
Sinh(x)
Arguments x Must be an integer or real number. Returns The hyperbolic sine of x. Exceptions If x is not a number, returns an error value. Examples
Sinh(tag1) Sinh(1) Sinh(0.9)
Sqr
Return the square root of a number. Format
Sqr(x)
129
Chapter 4
Arguments x Must be an integer or real number greater than or equal to zero. Returns The square root of x. Exceptions If x is negative, or is not a number, returns an error value. Examples
Sqr(tag1) Sqr(2) Sqr(2.1)
SStDev
Return the standard deviation of two or more arguments, where those arguments represent a sample of a larger population. The standard deviation of a sample x1...xn is equal to
( x )
i
n1
where is the sample mean, i.e., xi / n. Format

SStDev(x1, x2, ..., xn)
Arguments X1...Xn May be numbers, timestamps, or time periods, but all must be the same.
130
OSI Software, Inc.
Returns The sample standard deviation of the arguments. If the arguments are numbers, the result is a number; if they are timestamps or time periods, the result is a time period. Exceptions Arguments whose run-time values are digital states are ignored. If there are not at least two numeric values, SStDev returns a zero. Usage Note In the rare case where you have the entire population, rather than a sample, you may wish to use the function PStDev instead of this. Examples
SStDev(tag1, tag2, TagVal(tag1, y)) SStDev(y, t, 14-Dec-97) SStDev(1, 2, 1.1)
StateNo
Translate a digital state into its corresponding state number. Format
StateNo(DigState)
Arguments DigState A digital state value. This may be the value of a digital point or a character string that is the name of a digital state.
Note: The use of character strings is currently not supported.
Returns The offset into the digital state set corresponding to DigState.
131
Chapter 4
Exceptions If a point is passed as DigState that is not a digital point, returns an error value. If a character string is passed as DigState that does not appear in the digital state table, returns an error value. Usage Note A digital state may appear more than once in the Digital State Table. In this case, the value that StateNo returns may vary. If DigState is the value of a digital point, StateNo returns a code number appropriate for that point. If DigState is a character string, StateNo searches all digital state sets in the digital state table starting with set zero (the system set) and returns the offset into the first set in which the state is found. Examples
StateNo(digitaltag) StateNo(TagVal(digitaltag, *-1h)
StDev
Find the time-weighted standard deviation of a point over a given time, according to values stored in the archive. Format
StDev(tag, starttime, endtime, pctgood)
Arguments Tag A tagname. This point must represent a continuous variable. Starttime Must be a timestamp, the beginning of the time range to search. Endtime Must be a timestamp, greater than starttime; the end of the time range to search.
132
OSI Software, Inc.
PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The points time-weighted standard deviation over the given time. Exceptions If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error value. Caution If the point has few good archive values during the time period, this functions result may not be trustworthy. Use the PctGood function to find out what percentage of the values is good. Examples
StDev(tag1, y, *) StDev(tag1, 14-Dec-97, +1d,85) StDev(tag1, 14-Dec-97, 15-Dec-97)
TagAvg
Find the time-weighted average value of a point over a given time, according to values stored in the archive. Format
TagAvg(tag, starttime, endtime, pctgood)
Arguments Tag A tagname. This point must represent a continuous variable. Starttime Must be a timestamp, the beginning of the time range to search.
Chapter 4
Endtime Must be a timestamp, greater than starttime; the end of the time range to search. PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The points time-weighted average value over the given time. Exceptions If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error value. Caution If the point has few good archive values during the time period, this functions result may not be trustworthy. Use the PctGood function to find out what percentage of the values are good. Examples
TagAvg(tag1, y, *) TagAvg(tag1, 14-Dec-97, +1d,70) TagAvg(tag1, 14-Dec-97, 15-Dec-97)
TagBad
Test if a point has an abnormal state at a given time. If the points type is r or i, any digital state is abnormal. If the point is type d, the states that are defined for that point are normal; all others are abnormal. Format
Tagbad(tag, time)
134
OSI Software, Inc.
Arguments Tag A tagname. Time A timestamp. Returns 0 if the point's state at time is normal, 1 if it is abnormal. Exceptions If point does not exist, or has no archived value at time, returns an error value. Usage Note Badval can test any value or expression; TagBad can only test a point. Examples
TagBad(tag1, *) TagBad(digitaltag, 14-Dec-97) TagBad(tag1, y)
TagDesc
Get a points descriptor from the point data base. Format
TagDesc(tag)
Arguments Tag A tagname. Returns The points descriptor.

Chapter 4
Exceptions If point does not exist, returns an error value. Examples

TagDesc(tag1) TagDesc(digitaltag)
TagEU
Get a points engineering unit string from the point data base. Format
TagEU(tag)
Arguments Tag A tagname. Returns The points engineering units. Exceptions If point does not exist, returns an error value. Examples
TagDesc(tag1)
TagExDesc
Get a points extended descriptor from the point data base. Format
TagExDesc(tag)
136
OSI Software, Inc.
Arguments Tag A tagname. Returns The points extended descriptor. Exceptions If point does not exist, returns an error value. Examples
TagEU(tag1)
TagMax
Find the maximum value of a point during a given time, according to values stored in the archive. Format
TagMax(tag, starttime, endtime, pctgood)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime.
137
Chapter 4
PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The points maximum value during the given time. Exceptions If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error value. Caution The OverRange digital state is not taken into account when calculating this value. Examples
TagMax(tag1, y, *) TagMax(tag1, -1h, *,95) TagMax(tag1, 14-Dec-97, +1h)
TagMin
Find the minimum value of a point during a given time, according to values stored in the archive. Format
TagMin(tag, starttime, endtime, pctgood)
Arguments Tag A tagname. This point should represent a continuous variable. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp.
138
OSI Software, Inc.
Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. A time later than starttime. PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The points minimum value during the given time. Exceptions If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error value. Caution The UnderRange digital state is not taken into account when calculating this value. Examples
TagMin(tag1, y, *) TagMin(tag1, -1h, *,90) TagMin(tag1, 14-Dec-97, +1h)
TagName
Get a points name from the point data base. Format
TagName(tag)
139
Chapter 4
Returns The points name including delimiters, a character string up to 12 characters long. Exceptions If point does not exist, returns an error value. Examples
TagName(tag1)
TagSource
Get a points point source character from the point data base. Format
TagSource(tag)
Arguments Tag A tagname. Returns The points point source character. Exceptions If point does not exist, returns an error value. Examples
TagSource(tag1)
TagSpan
Get a points span from the point data base.
140
OSI Software, Inc.
Format
TagSpan(tag)
Arguments Tag A tagname. Returns The points span. If the points type is Digital this is an integer whose value is the number of digital states defined for the point. Examples
TagSpan(tag1) TagSpan(digitaltag)
TagTot
Find the totalized value (time integral) of a point over a given time, according to values stored in the archive. Format
TagTot(tag, starttime, endtime, pctgood)
Arguments Tag A tagname. This point must represent a continuous process flow. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime.
141
Chapter 4
PctGood (optional) Minimum time percentage over the given time range, that the points archived values must good. Returns The points totalized value over the given time. Exceptions If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error value. Caution If the point has few good archive values during the time period, this functions result may not be trustworthy. Use the PctGood function to find out what percentage of the values are good. Usage Note The system chooses a scale factor such that the integral will be correct only if the flow is expressed in units per day. If the flow is expressed in units per hour, or per some other time unit, you must multiply this result by a conversion factor. The conversion factor equals the number of actual flow time units in a day. For instance, if you totalize a point measured in gallons per minute, you must multiply the result of TagTot by 1440 to get the answer in gallons. This conversion factor is not related to the time period you are totalizing over; it is strictly a function of the points engineering units. Some PI sites have the default total period configured to be perhour rather than per-day. If you are at one of these sites, your conversion factor will differ. Examples
TagTot(tag1, y, *) TagTot(tag1, -1h, *,85) TagTot(tag1, 14-Dec-97, +1h)
142
OSI Software, Inc.
TagType
Get a points type character (i, r, or d) from the point data base. Format
TagType(tag)
Arguments Tag A tagname. Returns The points type character. Exceptions If point does not exist, returns an error value. Examples
TagType(tag1) TagType(digitaltag)
TagTypVal
Get a points typical value from the point data base. Format
TagTypVal(tag)
143
Chapter 4
Returns The points typical value. If the points type is R or I, this is a number; if the points type is D, this is a digital state (character string). Exceptions If point does not exist, returns an error value. Examples
TagTypVal(tag1) TagTypVal(digitaltag)
TagVal
Find a points archive value at a given time. Format
TagVal(tag, time)
Arguments Tag A tagname. Time (optional) A timestamp. If you omit this argument, '*' is used. Returns The archived value of tag at time. This value is interpolated unless the point has resolution code 4. Exceptions If point does not exist, or has no archived value at time, returns an error value. Examples
TagVal(tag1)
TagVal(digitaltag) TagVal(tag1,*)
TagZero
Get a points zero value from the point data base. Format
TagZero(tag)
Arguments Tag A tagname. Returns The points zero value. If the points type is R or I, this is a number; if the points type is D, this is a digital state (character string). Exceptions If point does not exist, returns an error value. Examples
TagZero(tag1) TagSpan(digitaltag)
Tan
Return the trigonometric tangent of a number. Format
Tan(x)
145
Chapter 4
Arguments x Must be an integer or real number, which represents an angle in radians. Returns The tangent of x. Exceptions If x is not a number, returns an error value. Examples
Tan(tag1) Tan(1) Tan(1.1)
Tanh
Return the hyperbolic tangent of a number. Format
Tanh(x)
Arguments x Must be an integer or real number. Returns The hyperbolic tangent of x. Exceptions If x is not a number, returns an error value. Examples
Tanh(tag1)
Tanh(1) Tanh(1.1)
TimeEq
Find the total time, within a range, when a point is equal to a given value. Format
TimeEq(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime. Value Must be an integer or real number or digital state (character string); the value to search for. Returns The time period within the given range, for which the point was exactly equal to the given value. Exceptions None. Examples
TimeEq(tag1, t, *,40.0)
Chapter 4
Performance Equations TimeEq(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeEq(digitaltag, 14-Dec-97, *, On)
TimeGE
Find the total time, within a range, when a point is greater than or equal to a given value. Format
TimeGE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime. Value Must be an integer or real number or digital state (character string); the value to search for. Returns The time period within the given range, for which the point was greater than or equal to the given value. Exceptions None.
148
OSI Software, Inc.
Usage Note TimeGE interpolates between archive events, if necessary, to find the times when the point crossed the given value. Examples
TimeGE(tag1, t, *,40.0) TimeGE(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeGE(digitaltag, 14-Dec-97, *, On)
TimeGT
Find the total time, within a range, when a point is greater than a given value. Format
TimeGT(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime. Value Must be an integer or real number or digital state (character string); the value to search for. Returns The time period within the given range, for which the point was greater than the given value.
Chapter 4
Exceptions None. Usage Note TimeGT ( ) interpolates between archive events, if necessary, to find the times when the point crossed the given value. Examples
TimeGT(tag1, t, *,40.0) TimeGT(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeGT(digitaltag, 14-Dec-97, *, On)
TimeLE
Find the total time, within a range, when a point is less than or equal to a given value. Format
TimeLE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime. Value Must be an integer or real number or digital state (character string); the value to search for.
150
OSI Software, Inc.
Returns The time period within the given range, for which the point was less than or equal to the given value. Exceptions None. Usage Note TimeLE interpolates between archive events, if necessary, to find the times when the point crossed the given value. Examples
TimeLE(tag1, t, *,40.0) TimeLE(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeLE(digitaltag, 14-Dec-97, *, On)
TimeLT
Find the total time, within a range, when a point is less than a given value. Format
TimeLT(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp. Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime.
Chapter 4
Value Must be an integer or real number or digital state (character string); the value to search for. Returns The time period within the given range, for which the point was less than the given value. Exceptions None. Usage Note TimeLT interpolates between archive events, if necessary, to find the times when the point crossed the given value. Examples
TimeLT(tag1, t, *,40.0) TimeLT(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeLTdigitaltag, 14-Dec-97, *, On)
TimeNE
Find the total time, within a range, when a point is unequal to a given value. Format
TimeNE(tag, starttime, endtime, value)
Arguments Tag A tagname. Starttime Beginning of the time range to search; timestamp or time relative to endtime if endtime is a timestamp.
Endtime End of the time range to search, timestamp or time relative to starttime if starttime is a timestamp. This time must be after starttime. Value Must be an integer or real number or digital state (character string); the value to search for. Returns The time period within the given range, for which the point was unequal to the given value. Exceptions None. Examples
TimeNE(tag1, t, *,40.0) TimeNE(digitaltag, -1d, *,TagVal(digitaltag, 14-Dec-97)) TimeNE(digitaltag, 14-Dec-97, *, On)
Total
Return the sum of two or more arguments. Format
Total(x1, x2, ..., xn)
Arguments X1...Xn May be numbers or time periods, but all must be the same. Returns The total of the arguments. The result has the same data type as the arguments.
Chapter 4
Exceptions Arguments whose run-time values are digital states are not included in the total. If all values are digital states, Total returns an error value. Examples
Total(tag1, tag2, TagVal(tag1, y),40.0) Total(t-y, +1h)
Trunc
Truncate a number or time to the next lower unit. Format
Trunc(x, unit)
Arguments x Must be an integer or real number, timestamp, or time period. Unit (optional) The size of the unit to truncate to. If x is a number, unit must be a number. If x is a timestamp or time period, unit must be a time period. If unit is omitted, Trunc truncates to the next lower integer (for a number) or second (for a time period). Returns The largest value smaller than x which is an integer multiple of unit. Returns the same data type as x. For more information, see the examples below. Exceptions If x is a string, or if unit is of the wrong data type, returns an error value.
154
OSI Software, Inc.
Examples
Expression Trunc(12.999) Trunc(18.75, 10) Trunc(14-Dec-97 11:47,+1h) Trunc(18:47 15:00,+1h) Value 12.0 10.0 14-DEC-97 11:00 7200 Comments Truncate to next lower integer Truncate to next lower ten Truncate to next lower hout Truncate period to next lower hour (returns period in seconds)
Note: Trunc to the next lower day results in a timestamp of the next lower day in UTC time and not local time.
Usage Note If x is a time, and unit is omitted, this routine has no effect, as times are only accurate to one second.
Weekday
Extract the day of the week from a timestamp. Format
Weekday(time)
Arguments Time A timestamp. Returns The day of the week of time, in the range 17, where 1 represents Sunday. Exceptions None.
Chapter 4
Examples
Weekday(*) Weekday(t)
Year
Extract the year from a timestamp. Format
Year(time)
Arguments Time A timestamp. Returns The year of time, in the range 1970present. Exceptions None. Examples
Year(*) Year(t)
Yearday
Extract the day of the year from a timestamp. The day of the year (also known as a Julian day) is an integer ranging from 1 to 366, where 1 represents January 1. Format
Yearday(time)
156
OSI Software, Inc.
Arguments Time A timestamp. Returns The day of the year of time, in the range 1366, where 1 represents January 1. Exceptions None. Examples
Yearday(*) Yearday(t)
PIPE Steam Functions

The PIPE-STEAM module makes available functions that calculate the thermodynamic properties of steam within Performance Equations. This is a separately licensed product embedded in the Performance Equation evaluator. This section briefly lists the functions. For a more detail description of the functionality of the PIPE Steam Functions, please refer to the PIPE Steam Table Manual. The functions are converted from the software distribution of ASME's Steam Tables, 6th Edition. Both English units and SI units are supported. The following table lists the functions available. Table 4-8 PI Steam Table Functions
Nam e tsat p hsat p ssat p vsat p Function Description Saturation temperature as a function of pressure. Saturation enthalpy as a function of pressure. Saturation entropy as a function of pressure. Saturation vapor specific volume as a function of pressure.
157
Chapter 4
Performance Equations Nam e psat t hsat t ssat t vsat t vpt vptl vph vps hpt hptl hps spt sptl sph tph tps xph xps hpx spx Function Description Saturation pressure as a function of temperature. Saturation enthalpy as a function of temperature. Saturation entropy as a function of temperature. Saturation vapor specific volume as a function of temperature. Vapor specific volume as a function of pressure and temperature. (for saturated and super heated steam) Water specific volume as a function of pressure and temperature. Vapor specific volume as a function of pressure and enthalpy. (for wet and dry steam) Vapor specific volume as a function of pressure and entropy. (for wet and dry steam) Enthalpy as a function of pressure and temperature. (for saturated and super heated steam) Liquid enthalpy as a function of pressure and temperature. (for water) Enthalpy as a function of pressure and entropy. (for wet and dry steam) Entropy as a function of pressure and temperature.(for saturated and super heated steam) Liquid entropy as a function of pressure and temperature. (for water) Entropy as a function of pressure and enthalpy. (for wet and dry steam) Temperature as a function of enthalpy and pressure. (for wet and dry steam) Temperature as a function of entropy and pressure. (for wet and dry steam) Steam quality(vapor fraction) as a function of enthalpy and pressure. (for wet steam). Steam quality(vapor fraction) as a function of entropy and pressure. (for wet steam). Enthalpy as a function of pressure and steam quality. (for wet steam) Entropy as a function of pressure and steam quality. (for wet steam)
158
OSI Software, Inc.
Engineering Units
The engineering units for the variables in the steam functions are listed below:
Variable s Tempera ture Pressure Volume Enthalpy Entropy Sym bol T P V H S English units degree F psia ft3/lbm BTU/lbm BTU/lbm/R SI units degree C kpa cc/g J/g J/g/K Conversion factor (From Eng to SI) (T - 32) / 1.8 6.894757 62.42796 2.326 4.1868
PIPE Steam Function Formats

Function names indicate engineering units and the calculation performed. The names are STMENG_XXX for English units and STMSI_XXX for SI units.
159
Chapter 4
The following table lists all of the available functions and their arguments. All arguments and normal return values are real numbers.
English Units StmEng_TsatP(P) StmEng_HsatP(P) StmEng_SsatP(P) StmEng_VsatP(P) StmEng_PsatT(T) StmEng_HsatT(T) StmEng_SsatT(T) StmEng_VsatT(T) StmEng_VPT(P, T) StmEng_VPTL(P, T) StmEng_VPH(P, H) StmEng_VPS(P, S) StmEng_HPT(P, T) StmEng_HPTL(P, T) StmEng_HPS(P, S) StmEng_SPT(P, T) StmEng_SPTL(P, T) StmEng_SPH(P, H) StmEng_TPH(P, H) StmEng_TPS(P, S) StmEng_XPH(P, H) StmEng_XPS(P, S) StmEng_HPX(P, X) StmEng_SPX(P, X) SI Units StmSI_HsatP(P) StmSI_SsatP(P) StmSI_VsatP(P) StmSI_HsatT(T) StmSI_SsatT(T) StmSI_VsatT(T) StmSI_VPT(P, T) StmSI_VPTL(P, T) StmSI_VPH(P, H) StmSI_VPS(P, S) StmSI_HPT(P, T) StmSI_HPTL(P, T) StmSI_HPS(P, S) StmSI_SPT(P, T) StmSI_SPTL(P, T) StmSI_SPH(P, H) StmSI_TPH(P, H) StmSI_TPS(P, S) StmSI_XPH(P, H) StmSI_XPS(P, S) StmSI_HPX(P, X) StmSI_SPX(P, X)
In case of error, the formulas return the following digital states:

Digital State BADINPUT INPOUTRANG E NOTCONVER GE BADNARG Explanation Input are not numeric data type. Input condition out of computation range Calculation failed to converge in iterative loop. Wrong number of arguments
160
OSI Software, Inc.
PEs for NT and UNIX Differ from PEs for OpenVMS

There are differences between OpenVMS (PI 2.x) and the NT and UNIX (PI 3.x) versions of the performance equations.
Natural Scheduling
Natural scheduling is not supported in PI 3.x. Instead, one can configure the scheduler to calculate when a specified point receives a new value. The event point itself can be a calculated point.
CurTime
The built-in function CurTime ( ) is still supported; however, it may be replaced by *. The following equations are PI 2.x examples.
"tagavg('sinusoid',ParseTime(*-1h),CurTime)" "if pctgood('sinusoid', ParseTime(*-1h), CurTime) > 95 then tagtot('sinusoid', ParseTime(*-1h), CurTime)*24 else 0"
The same syntax may be used in PI 3.x or replaced with these equivalent PI 3.x equations:
"tagavg('sinusoid','*-1h','*')" "if pctgood('sinusoid','*-1h','*') > 95 then tagtot('sinusoid','*-1h','*')*24 else 0"
ParseTime
The built-in function ParseTime ( ) is still supported; however, PI time syntax can be directly embedded as arguments to functions using single quotes. For example, PI 2.x requires this construction to do a ramping totalization that resets daily at 7 a.m.:
if parsetime("*") > parsetime("t+7h") then tagtot('sinusoid',parsetime("t+7h"),parsetim e("*")) else tagtot('sinusoid', parsetime("y+7h"), parsetime("*"))
With the current syntax you can avoid the ParseTime and use this:
Chapter 4
Performance Equations if '*' > 't+7h' then tagtot('sinusoid','t+7h','*') else tagtot('sinusoid','y+7h','*')
Pipetest Utility
PI 3.x has an added utility to check the performance equation syntax before applying it in the PE Scheduler.
BadVal and TagBad

In PI 2.x BadVal( ) and TagBad( ) always returned abnormal if any point is in any digital state. In PI 3.x these function returned abnormal if the real or integer points returned digital states and if digital points returned digital states that are not in its digital state table.
Time Conversion Operators

The PI 2.x postfix time conversion operators (s, m, h, and d) are no longer needed or supported. These operators convert numeric expressions into time periods that then, for example, can be added to a timestamp. An example of this in PI 2.x is
(sinusoid + 7) s + CurTime
The equivalent PI 3.x syntax is

sinusoid + 7 + *
PI 3.x will convert numbers to seconds when they are added to or subtracted from timestamps. In this example, sinusoid and 7 are numbers. They are converted automatically to seconds when added to * because * is a timestamp. It is also important to note the difference between the relative time expressions using (s, m, h, and d) as opposed to postfix operators. These relative time expressions are used within the timestamp that is enclosed in single quotes and do not convert numeric expressions to time periods. Relative time expression syntax is still supported and is given in Appendix A.
Time Functions
In PI 2.x the time conversion operators are required to convert the time functions (TimeGT, TimeLT, TimeEq, TimeGE, and TimeLE). to a time period. Here is the PI 2.x syntax:
timegt('sinusoid',curtime-8h,curtime,50)/1s
In PI 3.x, the time conversion is automatic, so the syntax looks like this:
timegt('sinusoid','*-8h','*',50)
In PI 3.x the time conversion operator syntax is not supported.
Double Quotes
Words that normally are enclosed in double quotes require special handling if they appear in a performance equation that is itself enclosed by double quotes. Typically these are strings like digital states and time intervals used in the ParseTime function. In order for the embedded double quotes to be interpreted correctly, place two double quotes in the place where a single double quote normally appears. For example, the PI 2.x performance equation syntax permits these uses:
timeeq('CDM158',curtime-8h, curtime, "manual")/1m
The PI 3.x performance equations are normally enclosed in double quotes so they require this:
"timeeq('CDM158','*-8h','*',""manual"")"
Time Periods
In PI 3.x, the concept of time period has been loosened. The difference between two timestamps is now simply a number of seconds. For example,
'*'-'*-1h
returns a time period of 3600 seconds. A number can be added to a timestamp to produce another timestamp. The number is automatically converted into seconds when combined with a timestamp. For example,
'y'+2
results in a timestamp that is 2 seconds greater than midnight yesterday. In PI 2.x, when passing. a starttime and an endtime to a function, a time period could not be used in place of a
Chapter 4
timestamp. In PI 3.x, these parameters can be passed as two timestamps or as one timestamp (for either start or end of period) and the appropriate time period. Hence the following equations are equivalent.
TagAvg(sinusoid,'t-1h,t) TagAvg(sinusoid,'t-1h,3600) TagAvg(sinusoid,-3600,t)
Required Time Parameters

For some built-in functions, previously optional time parameters are now required. This applies to the functions: Day ( ), Daysec ( ), Hour ( ), Month ( ), Minute ( ), NextEvent ( ), NextValue ( ), PrevEvent ( ), PrevValue ( ), Second ( ), TagBad( ), Weekday ( ), Year ( ), and Yearday ( ). For example, the following PI 2.x equations are equivalent
NextEvent(sinusoid) NextEvent(sinusoid,curtime) NextEvent(sinusoid,ParseTime(*))
The first example above omits the timestamp; in PI 3.x the timestamp argument is required:
NextEvent(sinusoid, *)
Digital State Comparisons

The functions TimeGT( ), TimeGE ( ),TimeLT ( ),TimeLE ( ), FindGT( ), FindGE( ), FindLT( ), and FindLE( ) now accept digital state (character strings). The comparisons are made based on the offset of the digital state table for the point.
Additional PI 3.x Functions

PI 3.x supports some functions that did not exist in PI 2.x.
Real Time Functions

PI 3.x supports the real-time filter functions that did not exist in PI 2.x. Arma ( ) is a function that can be used to define sophisticated linear filters. Delay ( ) is a real time delay line.
Impulse ( ) can be used for simple linear models. MedianFilt ( ) is a useful signal noise filter. These new real time filter functions work in the PE Scheduler but are not supported by the pipetest utility or PI-DataLink.
Other Functions
PI 3.x also provides other added functions that did not exist in PI-2.x. Bod ( ) gives the timestamp of beginning of the day of the selected timestamp given in the argument. Bom ( ) gives the timestamp of midnight at beginning of the month of the selected timestamp given in the argument. Fonm ( ) gives the timestamp of midnight at beginning of the month of the selected timestamp given in the argument. Curve( ) returns the y value of a curve given the x value Median ( ), is a signal selector function like Max ( ) and Min ( ) that takes the median of three or more values. Noon ( ) gives the timestamp of noon of the selected timestamp given by the argument. DigState( ) returns the digital state for a given string.
Functions Not Supported in PI 3.x

The built-in functions Runtime( ), Tagroc( ) and Tageps( ) are no longer supported.
PE Library
Linkage to user-supplied, compiled functions (pelibrary) is not supported. The event-based scheduler no longer supports expressions as triggers. Triggers are now based on one point.
165

04 Perfeq

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

04 Perfeq

Uploaded by

Copyright:

Available Formats

Chapter 4

Performance Equations Subsystem

Configuring Performance Equations

Totalizer vs. Performance Equations

Performance Equation Syntax

The Performance Equation (PE) Scheduler

PIPE Steam Module

Configuration of Calculated Points

OSI Software, Inc.

Requirement This must be classic

OSI Software, Inc.

Summary of Point Database Attributes

The following attributes do not apply to PI calculated points:

Performance Equation Syntax

PI Data Archive for Windows NT and UNIX

OSI Software, Inc.

Relative Time Expressions

Digital State Values

Meaning Membership in range Membership in discrete set

OSI Software, Inc.

Calculating with Time

PI Data Archive for Windows NT and UNIX

Type Compatibility and Error Checking

OSI Software, Inc.

Figure 4-2 Input file, pescript.dat, with performance equations

PI Data Archive for Windows NT and UNIX

OSI Software, Inc.

Performance Equations @mode list

Limitations and Attributes

Multiple Instances of the Performance Equation Scheduler

The following is a UNIX example of the PE Scheduler startup script.

Performance Equations /ps=C

specifies the point source,

defines the scan frequency for scan class 1 and

defines the scan frequency for scan class 2.

Defining Scan Classes

OSI Software, Inc.

Examples of Performance Equations

Totalization of Digital Point Example

PI Data Archive for Windows NT and UNIX

TagMax vs. Max Example

OSI Software, Inc.

Performance Equation for TagMax

Table of Built-in Functions

Function Name Type Miscellaneo Badval us functions Concat

Meaning See if a value is bad (not a number or time)

PI Data Archive for Windows NT and UNIX

Function Type Dynamic Response

Name Arma Delay MedianFil t Impulse

PI Data Archive for Windows NT and UNIX

OSI Software, Inc.

PI Data Archive for Windows NT and UNIX

Exceptions If x is not an integer or real number, returns an error value. Examples

Atn2(1,1) Atn2(tag1, tag2)

PI Data Archive for Windows NT and UNIX

OSI Software, Inc.

OSI Software, Inc.

Arguments x Must be an integer or real number. Returns The hyperbolic cosine of x.

Exceptions If x is not an integer or real number, returns an error value. Examples

curve(tag3, (25,25) (75,75) )

Arguments Time A timestamp.

PI Data Archive for Windows NT and UNIX

Performance Equations TimeEq(digitaltag, -1d, ,TagVal(digitaltag, 14-Dec-97)) TimeEq(digitaltag, 14-Dec-97, , On)

Performance Equations if '' > 't+7h' then tagtot('sinusoid','t+7h','') else tagtot('sinusoid','y+7h','*')