PI ACE 2010 R2 User Guide For Visual Basic 6 en

PI ACE 2010 R2
User Guide for Visual Basic 6

OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia Perth, Australia

OSIsoft Europe GmbH Frankfurt, Germany
OSIsoft Asia Pte Ltd. Singapore
OSIsoft Canada ULC Montreal & Calgary, Canada
OSIsoft, LLC Representative Office Shanghai, Peoples Republic of China
OSIsoft Japan KK Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil
PI ACE 2010 R2 User Guide for Visual Basic 6

Copyright: 1998-2011 OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical,
photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT
Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI
ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of
OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Version: 1.2.50
Published: 3/9/2011
Table of Contents
Chapter 1 Introduction ..................................................................................................................1
Features .............................................................................................................................1
Components .......................................................................................................................2
Structure of ACE Modules..................................................................................................3
Configuration and System Requirements ..........................................................................3
Installation ..........................................................................................................................5
Types of Scheduling...........................................................................................................5
Equation Ordering ..............................................................................................................6
Message Logs ....................................................................................................................7
High Availability ..................................................................................................................7
Documentation Overview ...................................................................................................7
Chapter 2 Tutorial Examples ........................................................................................................9

Example 1 - Email Notification ...........................................................................................9
Example 2 - Calling External Functions ...........................................................................14
Example 3 - Write Once, Apply to Many ..........................................................................16
Chapter 3 ACE Scheduler ...........................................................................................................21

Execution of ACE Modules ..............................................................................................21
Clock Differences between ACE and PI Servers .............................................................22
Resource Constraint.........................................................................................................22
Tag and Alias Name Changes .........................................................................................23
Security ............................................................................................................................24
Chapter 4 ACE Wizard.................................................................................................................25

Add-In Menu and Toolbar ................................................................................................25
Creating New ACE Modules ............................................................................................27
Editing ACE Modules .......................................................................................................37
Debugging ACE Modules.................................................................................................37
Testing ACE Modules.......................................................................................................37
Registering ACE Modules ................................................................................................41
Chapter 5 ACE Manager..............................................................................................................45

ACE Manager GUI ...........................................................................................................46
Server Menu.....................................................................................................................47
Executable Menu..............................................................................................................50
Module Menu....................................................................................................................51
Context Menu ...................................................................................................................55
Tag Menu .........................................................................................................................61
PI ACE 2010 R2 User Guide for Visual Basic 6 iii

Table of Contents
Chapter 6 Advanced Topics .......................................................................................................63

Caching Server.................................................................................................................63
Recalculation....................................................................................................................64
Setting up Redundant Schedulers ...................................................................................66
User-Defined Functions in Visual Basic 6 ........................................................................66
In-process COM Servers..................................................................................................67
Out-of-process COM Servers...........................................................................................67
Retrieving Last Snapshot Value or Last Archive Value ...................................................68
Output Tag Timestamp.....................................................................................................68
Specification of Timestamp Argument .............................................................................68
PI System Backup and Connection..................................................................................69
Security ............................................................................................................................69
Running ACE on a Cluster ...............................................................................................69
Testing a Running ACE Module.......................................................................................70
Chapter 7 ACE Library Functions ..............................................................................................71

Timestamp........................................................................................................................71
Error Handling ..................................................................................................................72
PIACEPoint Methods and Properties ...............................................................................72
Static (or Shared) Functions ............................................................................................94
Chapter 8 Troubleshooting.......................................................................................................111
ACE Scheduler Does Not Start ......................................................................................111
ACE Context Is Not Running..........................................................................................112
No Data Written To PI Tag.............................................................................................113
Skipped Calculations......................................................................................................113
Incorrect Output Timestamp...........................................................................................113
Cannot Find Error Messages .........................................................................................114
ACE Calculations Take Excessive Amount of CPU.......................................................114
Appendix A Differences between ACE for VB6 (ACE 1.x) and ACE for VB.NET (ACE 2.x)117
Upgrading ACE Modules from VB6 to VB.NET .............................................................118
Appendix B Technical Support and Resources .....................................................................121
Index ............................................................................................................................................125
iv
Chapter 1
Introduction
PI Advanced Computing Engine (ACE) allows programming of complex calculations (for
example, heat and material balances, data reconciliation, real-time cost accounting, and batch
summary), communication applications (for example, alarming, emailing, and paging), data
transfer programs, and just about any other application that does not require user intervention.
ACE can be used in either the Microsoft Visual Basic 6 (VB6) or the Microsoft Visual Basic
.NET (VB.NET) development environment. Because of the significant differences in the
integrated development environments (IDEs) for VB6 and for VB.NET 2005/2008/2010,
OSIsoft provides two versions of ACE: ACE for Visual Basic 6 (ACE 1.x) and ACE for
Visual Basic .NET (ACE 2.x). The 1.x and 2.x nomenclature is retained for consistency with
usage in earlier releases of ACE. This manual discusses features of ACE 1.x only. For details
on ACE for VB.NET, see PI ACE User Guide for Visual Basic .NET. For more information,
see Differences Between ACE for VB 6 and ACE for VB .NET (page 117).
Features
The main features for the PI Advanced Computing Engine (ACE) are as follows:
To implement complex calculations (for example, iterative solutions, data and time
manipulation, and numerically solving ordinary or partial differential equations)
To provide a fault-tolerant and redundant architecture.
To retrieve data from, and send results to, PI tags or to other systems.
To apply one set of equations to multiple units or processes.
To provide various scheduling features: clock, natural, event, equation ordering, and
graceful degradation under resource limitations (CPU loading).
To use multiple PI tags from multiple PI Servers in calculations.
To provide the ability to use the previous snapshot value for a PI tag (instead of the
previous archive value) in calculations.
To allow documentation or comments with a set of equations.
To allow clamping and bad-value substitution of inputs and outputs.
To provide the ability to call COM and .NET objects and a library of user-written
functions.
To provide the ability to test and debug equations.
To provide the ability to make different users responsible for different groups of
equations.
PI ACE 2010 R2 User Guide for Visual Basic 6 1

Introduction
To provide the ability to migrate from PI 2 and PI 3 performance equations.

To provide the ability to monitor performance of individual equations.
To provide robustness, including trapping floating-point errors and avoiding repetitive
message logs.
To expose calculations via a Web service.
To allow automatic recalculation when past data are changed.
To manually recalculate an ACE Context.
Components
A set of calculations (or more generally instructions) is implemented in a Visual Basic COM
class, which is referred to as an ACE Module. The components of ACE 1.x that develop,
monitor, manipulate, and execute ACE Modules are:
ACE Wizard (page 25)
ACE Manager (page 45)
ACE Scheduler (page 21)
Figure 1-1 ACE Components and Their Common Data
The ACE Wizard is a Visual Basic add-in to help users build and test ACE Modules quickly,
the ACE Manager lets users monitor and change various properties of ACE Modules, and the
ACE Scheduler executes ACE Modules in a timely manner and handles updates and
abnormal behavior. The structural information for ACE Modules is stored in the PI Module
Database. While the ACE Scheduler and the .exe files for all ACE Modules need to be on
the same computer, the ACE Wizard, the ACE Manager, the ACE Scheduler, and the PI
Server that stores the ACE structural information may be on different computers.
2
Structure of ACE Modules
Structure of ACE Modules

The overall structure of the ACE Modules is shown in Figure 1-2. All the ACE Modules
developed with Visual Basic 6 are listed under the ACE Executables tree in the PI Module
Database (PI MDB).
Figure 1-2 Structure of ACE Modules
Each ACE Module developed with ACE 1.x corresponds to a class in a Visual Basic 6
ActiveX Exe project (that is, out-of-process COM server). The project is referred to as ACE
Executable. ACE Executables may be developed and maintained by different users. Each
ACE Executable can contain multiple ACE Modules. Each ACE Module can be run in
different contexts (that is, ACE Contexts). For example, if identical calculations need to be
carried out for reactor #1 and reactor #2, then only one set of equations needs to be developed
and maintained but it may be run in two different contexts. This would greatly facilitate the
development and maintenance of calculations for similar units or processes.
The maximum number of ACE Executables may be limited by the computer resources. Each
ACE Executable runs in its own process and thus is independent of other ACE Executables.
This design is useful for ACE 1.x calculations when some calculations are time-intensive but
infrequent (for example, it takes five minutes to carry out the calculations and it is calculated
once every ten minutes) and others are quick but frequent (for example, it takes 0.1 second to
carry out the calculations and it is calculated once every 10 seconds). By placing them in two
different ACE Executables, both types of calculations can be executed in a timely manner.
Configuration and System Requirements

ACE consists of the following components: ACE Wizard, ACE Manager, and ACE
Scheduler. The components of ACE can be installed on different computers. In order to
develop/run ACE Modules, a PI Server version 3.3 or higher is required to store the structural
information of ACE Modules in the PI Module Database. This server is referred to as the PI
ACE Data Server. The actual PI tags used in calculations or for archiving results in an ACE
Module could come from either the PI ACE Data Server or other PI Servers (either PI2 or
PI3).

Introduction
ACE Scheduler
The ACE Scheduler can be installed on a PI ACE Data Server or on a client computer. The
computer must have:
Windows XP, Windows Server 2003, Windows Vista, Windows 7, or Windows Server
2008 with latest service pack
Note: We recommend running ACE Scheduler on server operating systems (for

example, Windows Server 2003 and Windows Server 2008) in production
environments.
Microsoft .NET Framework 2.0 or higher

PI SDK 1.3.8.387 or higher for 64-bit and PI SDK 1.3.8.388 or higher for 32-bit
PI API 1.6.2.4 or higher
Connection to a PI Server 3.3 or higher with read/write privileges
Where the ACE Scheduler should be installed depends on many factors. The most important
consideration is the tradeoff between the CPU load and the network load. If the ACE
Scheduler is installed on the PI ACE Data Server, it would increase the CPU load on the
server but it would have minimal impact on the network. If the ACE Scheduler is installed on
a client computer, executing ACE Modules would not impact the PI ACE Data Server CPU
load (other than the normal data retrieval calls to the server) but the frequent communication
between the ACE Scheduler and the server might affect the network load.
To run the ACE Scheduler, appropriate security should be set up for the ACE Scheduler to
access the ACE structural information on the PI ACE Data Server. For details on how to set
up a trust relationship between the ACE Scheduler and the PI ACE Data Server, see Security
(page 24). While ACE Schedulers for both versions can be run simultaneously, only one
instance of the ACE Scheduler for each version can be run on a computer.
ACE Manager
The ACE Manager can be installed on any computer. Different access levels (for example, no
access, read-only, and read/write) to a PI Server can be set up through the PI trust table. The
requirements are the following:
PI SDK 1.3.8.388 or higher
ACE Wizard
The ACE Wizard for both versions can be installed on any computer. Its requirements are:
Visual Basic 6 (either Enterprise or Professional Edition)
4
Installation
PI SDK 1.3.8.388 or higher

Connection to a PI Server 3.3 or higher with read/write privileges
Installation
The installation program is called Setup.exe and installs both ACE for VB6 (ACE 1.x) and
ACE for VB.NET (ACE 2.x). Before running the Setup program, verify that the target
platform meets the requirements specified in Configuration and System Requirements (page
3). The setup program automatically installs PI SDK and other components if they have not
been installed already. Because the setup program may write entries to shared portions of the
registry, it is necessary to log in as a user with Administrator privileges on the system. It is
advisable to close other applications during the setup process. If a PI System is running on the
target machine, you need not stop the system. By default, ACE is installed under the pipc
directory (that is, pipc\ACE).
Follow the setup program instructions to install appropriate components on the target
machine. You may choose to install ACE Wizard, ACE Manager, and/or ACE Scheduler.
Upon successful installation, ACE registers its Uninstall, which is then available through the
standard control panel Add/Remove Programs applet.
To install all features silently, the command is:
msiexec /i piace.msi /q
To install selected features silently, the command is:
msiexec /i piace.msi ADDDEFAULT="FeatureList" /q
where FeatureList is a list of features to be installed, separated by commas. piace.msi
consists of these features: Core, ACEManager, ACE1.x_Wizard, ACE2.x_Wizard,
ACE1.x_Scheduler, and ACE2.x_Scheduler. The Core feature must be installed for any other
ACE component to function. For example, the following installs ACE Manager and ACE 2.x
Wizard:
msiexec /i piace.msi ADDDEFAULT="Core,ACEManager,ACE2.x_Wizard" /q
Silently installing piace.msi does not check for component requirements; nor does it install
any required components (for example, .NET Framework and PISDK). To install the whole
package silently, modify the silent .ini file delivered with the setup package. See PI Server
Installation and Upgrade Guide for details on how to do this.
Types of Scheduling
The type of scheduling determines when a calculation will be performed. There are two types
of scheduling, clock and natural, available in ACE. The scheduling information applies to an
ACE Context (that is, an instance of ACE Module).

Introduction
Clock Scheduling
With clock scheduling, an ACE Context is evaluated at fixed intervals. Two attributes, period
and offset, determine when to evaluate the ACE Context. The period specifies the interval
between calculations and the offset specifies the time since the midnight to start the
calculation. While the period can have a fraction of a second, the offset should be an integer
between 0 and 86399 seconds. When specifying a small period (the smallest period allowed is
0.001 second), make sure that the resources (e.g., CPU and network) are adequate. The clock
for the PI Server specified in the ACE Context (for example, aceserver2k3 for an ACE
Context of \\aceserver2k3 and MyPIServer for
\\MyPIServer\MyPIModule\Controllers\PID) is used to generate the calculation
times.
Natural Scheduling
Natural scheduling means that an ACE Context is evaluated whenever one of its trigger PI
tags receives a new snapshot event. The trigger tags must be a subset of input tags or aliases
used in the ACE Module. Tags or aliases used as both input and output cannot be used as
trigger tags, because this can easily result in an infinite loop if not handled properly. By
default, the calculation result has the same timestamp as the trigger tag event. Natural
scheduling is highly accurate; it has the same effect as if the calculation were performed
continuously.
Event Scheduling
There is another type of scheduling in the PI2 Performance Equation subsystem (PIPE) called
event scheduling (that is, evaluate an equation when certain conditions are met). This has
been eliminated in ACE since any condition can be directly specified programmatically
within an ACE Module. For example, suppose we would like to evaluate an ACE Module
(and send results to PI Server) only when the PI tag pumpstatus is ON. This can be
accomplished by specifying the tag pumpstatus as a trigger tag and by including the
following condition in the ACE Module:
:
If UCase(pumpstatus.Value) <> "ON" Then
mblnSendDataToPI = False
Exit Sub
End If
' Code for carrying out actual calculations
:
Equation Ordering
Unlike the PIPE Subsystem where each tag consists of its own calculations and does not
depend on calculations for other tags, an ACE Module can contain calculations for many
tags. Thus, it is a simple task to programmatically order the calculations within the ACE
Module. However, calculations in different ACE Modules may be executed in an arbitrary
order.
6
Message Logs
Message Logs
ACE messages are logged to the central log file for the PI Message Subsystem and can be
retrieved using the pigetmsg utility. See the PI Server System Management Guide for details.
Different levels of message logging are available for each ACE Context (i.e., ACE Module
running under a specified context) and the ACE Scheduler. Details on how to set this level
are described in Message Log Levels (page 57).
High Availability
You can run ACE Schedulers on multiple machines against the same set of calculations
stored on one PI MDB. Only one of these Schedulers (i.e., master Scheduler), would
actually run the calculations while the rest are in a standby mode. When the master
Scheduler stops either gracefully or ungracefully, one of the standby Schedulers becomes
the master and runs the calculations.
With proper buffering setup, ACE automatically sends data to all members in a server
collective. Since the HA buffering is not currently supported on a PI Server, you should
not run the ACE Scheduler on a PI Server if you need to send data to all members of a
server collective.
When retrieving data from a PI Server collective, ACE Scheduler automatically connects
to the available collective member.
See High Availability User Guide and High Availability Advanced User Guide for details.
Documentation Overview
This document is organized as follows:
Chapter 2 gives several detailed examples on how to develop and run ACE Modules.
Chapters 3, 4, and 5 describe the basic features of the ACE Scheduler, the ACE Wizard,
and the ACE Manager, respectively.
Chapter 6 provides information on some more advanced usages
Chapter 7 describes the ACE library functions.
Chapter 8 discusses some commonly encountered problems and possible causes.
A separate manual is available for the migration wizard (PIPE2ACE) that converts PI
Performance Equations into ACE Modules. The manual (pipe2ace.doc) is installed in the
directory ..\ACE\Wizard.

Chapter 2
Tutorial Examples
In this chapter, we show several examples on how to develop ACE Modules. Example 1
(page 9) illustrates how someone may be contacted via email when a watchdog tag for an
interface receives a bad status. Example 2 (page 14) shows how to call programs written in
MATLAB from an ACE Module. In Example 3 (page 16), we demonstrate how a set of
calculations can be applied to different units or processes. In Example 4 (page 19), we discuss
how to develop and test an ACE Module on a computer and deploy it to another computer
where the ACE Scheduler (page 21) runs.
In the first three examples, we assume that ACE Modules are developed on the same
computer where the ACE Scheduler is running. To keep the illustrations clear, we have only
implemented very simple calculations.
Example 1 - Email Notification

Suppose that an interface has a watchdog PI tag. The goal is to email (or call) someone when
the watchdog tag receives a bad value. We will go through the details on how to develop an
ACE Module to achieve this goal. The basic steps are the following:
1. Start ACE Scheduler (page 9).
2. Develop ACE Module via ACE Wizard (page 9).
3. Monitor ACE Module (page 13) via ACE Manager.
Step 1 Start ACE Scheduler
Before starting the ACE Scheduler, verify that the version for the default or target PI Server
for the computer is 3.3 or higher and that there is a trust relationship set up for running ACE
applications. Start the ACE 1.x Scheduler either by typing net start piacescheduler at
the command prompt or by going through the Windows Service Control Manager. You can
monitor the statuses of all ACE Modules via the ACE Manager. The default server should be
automatically displayed. You can add a PI Server to display via Server > Add New
Server. The status for the ACE Scheduler should be On.
Step 2 Develop ACE Module via ACE Wizard
Start Visual Basic 6. You can either select PIACE in the Visual Basic new project dialog
window or select PIACEWizard > New from the Add-Ins menu in Visual Basic.

Tutorial Examples
Note: If you do not see PIACE in the Visual Basic new project dialog box, copy
piace.vbz from the ..\ACE\Wizard directory to the ..\Visual
Basic98\Template\Projects directory. It is not necessary to restart Visual Basic.
If you do not see PIACEWizard in the Add-Ins menu, add it as follows: In the Add-In
Manager window, select PI Advanced Computing Engine (ACE) Wizard and check
the Load/Unload box.
If you do not see PI Advanced Computing Engine (ACE) Wizard in the Add-In Manager
list, you can register the wizard by using the Windows utility regsvr32 as follows:
Open a command prompt window and enter the following:
regsvr32 [FULL_PATH]PIACEWizard.dll
Complete the first page and click Next>. Here the structural information for this ACE
Module would be stored on the PI Server localhost, and the names of ACE Executable and
ACE Module are ACEGSExamples and Communication, respectively. Obviously, you may
choose different names.
Figure 2-1. ACE Wizard New/Edit Page 1
10
On the second page, we specify the watchdog tag as the input tag. For illustration purposes,
we have assumed that the watchdog PI tag is IntWatch, which would get a bad status when
the target interface is shut down or experiences some problems. There is no output PI tag.
Figure 2-2 ACE Wizard New/Edit Page 2
Clicking Finish generates the necessary Visual Basic code for the ACE Module. After adding
a reference to Microsoft CDO for NTS Library (Project > References), we can use all its
objects in the project.
Note: Different versions of CDO are available on various Windows platforms. Consult
Microsoft Help for details on their use.
Specifically, we will use the NewMail object from this library (to use this object, the system
should have an appropriate mail service installed).
When executed, the following code in the subroutine ActualPerformanceEquations would
send an email to anonymous@unknown.com when the tag intwatch has a bad value:
Dim InterfaceProblem as NewMail
If Not intwatch.IsGood Then
InterfaceProblem.Send "anonymous@unknown.com",
"anonymous@unknown.com", "Unknown Interface", "Problem with
Unknown Interface"
End If

Tutorial Examples
Figure 2-3 User Code for ACE Module
We can debug the ACE Module by selecting PIACEWizard > Debug from the Add-Ins
menu. We need to test the ACE Module (via PIACEWizard > Test) before we can register
it. Testing ensures that the project can be compiled successfully and that the COM object
corresponding to the ACE Module can be created and destroyed properly. Since no output tag
is used, the Calculate Now and Advanced Test buttons are grayed out. Click Close.
Figure 2-4 Testing ACE Module
We register the ACE Module by selecting PIACEWizard > Register from the Add-ins
menu. We want to check the tag value only when the tag receives a new snapshot event. Thus
we should check Natural (Scheduling) with INTWATCH as the trigger tag. If you want to
12
enter a brief description for the ACE Module, you can enter it by clicking on the ACE
Module Description button. Click the OK button to complete the registration. Close the
form. The ACE Module should be running within a minute.
Figure 2-5 Register ACE Module
Step 3 - Monitor ACE Module
The status of the ACE Module (and all others) can be monitored via the ACE Manager. As
you can see, the ACE Scheduler has started the ACE Module successfully.
Figure 2-6 ACE Manager

Tutorial Examples
To verify that the ACE Module works properly, you can send a bad value for the tag
INTWATCH (this can be done in many ways, for example, using piconfig).
Remark
In this example, an email is sent to a known person when the tag INTWATCH receives a
bad value. One potential drawback is that the program would have to be recompiled if an
email needs to be sent to a different person or a list of people. This issue can be resolved by
storing the email address or addresses somewhere else (for example, PI Module Database)
and by dynamically retrieving them.
Example 2 - Calling External Functions

In this example, we demonstrate how to call programs developed in MATLAB within an
ACE Module. Calling any other out-of-process COM servers follows the same procedure.
Suppose a function named MyFunction.m in MATLAB has the following syntax:
y = MyFunction(x)
Here both x and y may be arrays. For simplicity, let us assume that x corresponds to snapshot
values of two PI tags (Sinusoid and Sinusoidu) while y is a scalar and its value needs to be
written to a PI tag (for example, MatlabTag1).
The basic procedure is identical as in Example 1 and we will not repeat everything here.
Instead, we focus on how to call the MATLAB function from the ACE Module. First, let us
declare a module-wide object that holds an instance of MATLAB (i.e., Dim mobjMatlab as
Object):
Figure 2-7 MATLAB Example
The following code, when executed, sends data from the ACE Module to MATLAB,
executes the MATLAB function, and retrieves the data from MATLAB. As one can see, the
object mobjMatlab is created in the subroutine UserDefinedInitialization and terminated in
the subroutine UserDefinedTermination, and the actual calculations are implemented in the
14
Example 2 - Calling External Functions
subroutine ActualPerformanceEquations. The wizard automatically generates the

prototypes for the three subroutines.
Figure 2-8 Calling Out-of-process COM Servers
This is all you need to do. You can test and register this ACE Module just like any other.
Note that you need to have MATLAB installed on the machine where the ACE Scheduler is
running.
You should consult the MATLAB documentation (MATLAB ActiveX Automation Server
Support in External Interfaces/API) for details on the methods exposed by the MATLAB
object and their usages.

Tutorial Examples
Example 3 - Write Once, Apply to Many

Often similar units employ an identical set of calculations, possibly with different parameters.
Developing and maintaining multiple copies of calculations increases the cost. In this
example, we show how to develop one set of calculations (that is, an ACE Module) and apply
that calculation to multiple units (that is, to multiple PI Modules in PI Module Database).
Suppose that we have four aquariums and that we want to compute and store their total power
usages in real time. The aquariums have similar instruments measuring pump and light
powers (in watts). We want to develop an ACE Module and apply it to all four aquariums. To
develop the ACE Module, follow these steps:
1. Build PI Module Database Structure (page 16).
2. Start ACE Scheduler (page 9).
3. Develop ACE Module via ACE Wizard (page 17).
4. Add New ACE Contexts (page 17).
Note that the differences between this example and Example 1 are in Step 1 and Step 4.
Step 1 - Build PI Module Database Structure
We need to build four PI Modules for the four aquariums. All PI Modules consist of a
collection of aliases (with identical names) corresponding to (different) PI tags and a
collection of properties that are specific to each PI Module. The identical aliases will be used
as tag/alias names in the ACE Module and PI Modules for the aquariums will be used as
contexts. One can build such a structure via the PI Module Database Editor. Here is the
structure used in this example:
Figure 2-9 Sample PI Module Database Structure
16
Note that the above structure does not contain any PI Module specific parameters. Users can
easily add these as a PI Properties collection underneath a PI Module and use them in the
ACE Module.
Step 2 - Start ACE Scheduler
See Example 1.
Step 3 - Develop ACE Module via ACE Wizard
In this step, the only difference between this example and Example 1 is the specification of
the context (\\localhost\Aquariums\Aquarium1 versus \\localhost) on page 2 of
the ACE Wizard New/Edit. The ACE Executable and ACE Module names are Aquariums
and PowerConsumption, respectively. PumpPower and LightPower are used as input
aliases and TotalPower is used as an output alias. The actual calculation is:
TotalPower.Value =
LightPower.Value + PumpPower.Value
Step 4 - Add New ACE Contexts
We have now developed, tested, and registered an ACE Module for one PI Module. We can
apply the calculation in the ACE Module to other PI Modules (that is, apply the ACE Module
in different contexts) without changing the source VB code via the ACE Manager (page 45).
Highlight the ACE Module (Aquariums\PowerConsumption) in ACE Manager and click
Module > Add New Context.
Figure 2-10 Adding Other Contexts
On the Add-New-Context dialog box, specify a new PI Module path (for example.
\\localhost\aquariums\aquarium2), priority, and scheduling information. Click Save,

Tutorial Examples
or click New to enter another PI Module path. When done, click Close. The ACE Scheduler
will pick up this information and start separate instances of the ACE Module (that is, ACE
Context) for each PI Module you specify.
Note: You can add multiple ACE Contexts simultaneously as follows: Select an existing
ACE Context and click Context > Apply Schedule To. See details in ACE
Manager (page 45).
Figure 2-11 Add Context dialog
18
The following display shows that all four contexts have been successfully started.
Figure 2-12 Example of four Contexts that are running
In this example, we want to move an ACE Executable developed and tested on one computer
(e.g., a development machine) to another computer (e.g., a production machine). Deploying
ACE calculations involves these basic steps:
1. Deploy the ACE structural information: If you can connect to both servers, you can use
ACE Manager to copy the ACE structural information from the source PI Server to the
target PI Server.
Start ACE Manager.
Add both PI Servers to the display. Make sure that ACE Manager displays ACE
Executables developed with ACE 1.x.
Select the ACE Executable and click Export from the ACE Executable menu.
Highlight the PI Server to which you want to copy the information and click Import
from the Server menu. The copying should be successful if you have read/write
privileges on the destination PI Server and if there is no name conflict among all
ACE Executables on the destination PI Server.
If you do not have access to both PI Servers simultaneously, you can use the MDB
Builder to export the appropriate ACE structural information under
%OSI/ACEExecutables (version 1.x) or %OSI/ACEClassLibraries (version 2.x) from the
source PI Server and export it to the target PI Server.
2. Deploy the .exe file containing the calculations: You need to copy the .exe file
containing the ACE Module from the source computer to the target computer where the
ACE Scheduler is running. Register the components of the .exe file by double clicking
on the file.

Tutorial Examples
Note: No dialog may appear. To check if the .exe file has been successfully
registered, open the registry. If it has been successfully registered you should
see an entry with the .exe file name under the registry key
HKEY_CLASSES_ROOT.
When copying the .exe file, we recommend keeping all ACE Executables files under the
directory ..\ACE\Executables for easy housekeeping. If the ACE Executable is currently
running on the destination computer, it should be taken out of service first via the ACE
Manager (select the ACE Executable and click the Stop button) before copying;
otherwise, copying may fail and the changes would not become effective.
Make sure all the references that an ACE Executable uses are properly installed;
otherwise, the registration may fail.
3. Modify contexts appropriately: When you deploy a calculation, the contexts may not be
the same. For example, it may still refer to PIModules on the source PI Server. In this
case, the easiest way is to delete all the contexts before exporting the structural
information and to add the contexts afterwards.
4. Build appropriate PIModules and tags: You may need to create appropriate PIModules
used as contexts and tags for the calculations to function.
A much simpler scenario is that you only want to run the calculations from a different
machine. In this case, only Step 2 is necessary.
When you intend to move an ACE Executable from one computer to another, you should
avoid using localhost during the development. Localhost on different computers may
correspond to different PI Servers.
20
Chapter 3
ACE Scheduler
The ACE Scheduler is a Windows service application. The ACE Scheduler can run on the
same or different machine as the PI Server. It automatically executes the calculations stored
on a target PI Server according to their schedules. The target PI Server is the default PI
Server in the PISDKs Known Servers Table or the PI Server specified in the following
registry key:
HKey_Local_Machine\Software\PISystem\PI-ACE\TargetPIServer
The latter takes precedence. If the registry key does not exist or the PI Server specified by the
registry key is invalid, the ACE Scheduler loads the calculations stored on the default PI
Server.
After the ACE Scheduler starts the calculations, it periodically checks for calculation updates.
For example, after a context for an ACE Module has been successfully registered or added,
the ACE Scheduler would automatically start the ACE Context. The status for the context
becomes On if successful and Error otherwise.
The executable for ACE 1.x is PIACEScheduler.exe. It can be started via the Service
Control Manager or by typing net start PIACEScheduler at the command prompt.
System requirements for ACE Scheduler are described in ACE Scheduler (page 4).
The basic functions of the ACE Scheduler are to:
Start/stop an ACE Context
Set/modify the scheduling information of a running ACE Context
Set/change priority and message logging level of a running ACE Context
Automatically update tag name change of a running ACE Context
Manage resource constraints
Handle abnormal behavior (for example, non-responsive processes)
Execution of ACE Modules

The calculations for an ACE Context are not carried out until the ACE Context is started by
and receives the scheduling information from the ACE Scheduler. The following diagram
shows how calculations are carried out and data, if any, are written to PI Systems.

ACE Scheduler
Figure 3-1 Flowchart for Calculations
Each ACE Context has an execution queue that contains a list of times when the calculations
should be executed. The execution time is generated either by a timer (for clock-scheduled
calculations) or by PI tag snapshot events (for natural-scheduled calculations). The execution
time becomes the default timestamp for all output tags. The execution time for natural-
scheduled calculations is the timestamp for the event (that is, not the timestamp when the
event arrives). Calculations for each ACE Context are carried out at each execution time,
except when there is resource constraint (see below for details). All data retrievals are done
via PI-SDK. The data writing is done via PI-API to leverage its buffering and data fanning
capabilities.
Clock Differences between ACE and PI Servers

The ACE Scheduler periodically estimates the clock difference between the ACE Scheduler
machine and PI Servers where data are retrieved and/or written. It automatically adjusts for
the time zone and the daylight savings time differences. By default, it adjusts for the clock
drift when sending data to PI. However, this behavior can be modified for each tag
programmatically by appropriately setting its AdjustClockOffset property. More details are
given in Advanced Topics (page 63). The clock drift is the difference in two clocks not due to
differences in time zone or daylight savings time settings. The estimate of the clock
difference is at most accurate within one second and can be worse if the call to determine the
time on a PI Server takes an excessively long time to return.
Resource Constraint
Each ACE Context has a priority value (i.e., High, AboveNormal, Normal, BelowNormal,
or Low). This value is used only when the resource is constrained. For example, if it takes ten
22
Tag and Alias Name Changes
minutes to carry out all the calculations scheduled to run every minute, it is impossible to
carry out all the calculations. Of course, a permanent fix would be to have a faster computer,
to reduce the number of ACE Modules, and/or to change the calculation period. We now
briefly explain how the ACE Scheduler handles this situation gracefully.
When calculations for an ACE Executable fall significantly behind, the ACE Scheduler starts
skipping calculations. Initially, a certain percentage of the lowest priority calculations is
skipped. If this is not sufficient, the skipping percentage is increased and higher priority
calculations start skipping calculations. So, this algorithm ensures that temporary resource
constraints would have minimal impact on the calculation of ACE Contexts, and, in the case
of permanent resource constraints, that ACE Contexts with the priority of High would skip
the least number of calculations and ACE Contexts with priority of Low would skip the most.
When a calculation is skipped, a warning message may be logged. The priority for an ACE
Context can be set either through the ACE Wizard (page 25) or via the ACE Manager (page
45).
Since ACE provides considerable flexibility to the users to develop complex applications, it
is possible for an ACE Context to enter an infinite loop, to take up a large percentage of the
CPU for a long period of time, etc. Clearly, this situation would severely affect timely
calculations of other ACE Contexts and, in almost all cases, is undesirable. To overcome this
problem, the ACE Scheduler periodically checks for non-responsive ACE Contexts. An ACE
Context is non-responsive if it exceeds its time limit for one calculation. The default time
limit is ten minutes per calculation. This time limit may be modified via the ACE Manager.
The ACE 1.x Scheduler is single-threaded. When a calculation for any ACE Context inside
an executable becomes non-responsive, no calculation inside the executable is executed.
When this occurs, the ACE 1.x Scheduler would have to terminate the whole ACE
Executable in order to restart calculations. Thus one offending calculation can potentially
bring down all calculations in an ACE Executable. By default, the ACE Scheduler does not
restart the offending ACE Context. However, you can configure the maximum number of
consecutive times, Maximum CL Violations, to restart an offending ACE Context via the
ACE Manager. This limit is defaulted to zero. After this limit is reached, the ACE 1.x
Scheduler would not restart the offending ACE Context and marks its status to Terminated.
For example, if you configure the limit to be 5, then the ACE 1.x Scheduler would attempt
restarting it five consequent times before terminating it. The number of consequent restarts is
reset to zero when the ACE Scheduler 1.x is restarted or when the ACE Context is taken out
of service and put into the service again. A warning message may be logged whenever an
ACE Context becomes non-responsive.
Tag and Alias Name Changes

Tag or alias names for an ACE Module are stored in the Module Database on a PI Server.
When the name for a PI tag is changed, this information should be updated. This is done
automatically for all running ACE Modules. Tags used in an ACE Module that is not running
need to be updated manually via the ACE Manager (page 45). Currently, alias name changes
are not handled automatically and the user needs to update them manually via the ACE
Manager.

ACE Scheduler
Security
The ACE Scheduler and the ACE Executables connect to PI Servers using the PI trust login
mechanism. It is important to set up appropriate trust entries so that the ACE Scheduler and
the ACE Executables have the right privileges. Since the ACE Scheduler and the ACE
Executables may use both PI-SDK and PI-API functions, it is important to set up trusts that
work for both. Here we briefly describe the trust setup specific to ACE. For details on how to
set up a trust table, see Configuring PI Server Security.
Since the ACE Scheduler reads from and writes to the PI Server where the ACE structural
information is stored, it should have read/write privileges to it. The following trust would
grant all applications from the computer where the ACE Scheduler is located read/write
privileges:
Trust = ACE
IPAddr = IP Address for the computer where the ACE Scheduler is
located
NetMask = 255.255.255.255
PIUser = piadmin
The following trusts (one for PI-SDK and one for PI-API) would grant the ACE 1.x
Scheduler read/write privileges:
PI-SDK:
Trust = ACESchedulerSDK
AppName = piacescheduler.exe
located
NetMask = 255.255.255.255
PIUser = piadmin
PI-API:
Trust = ACESchedulerAPI
AppName = piacE
located
NetMask = 255.255.255.255
PIUser = piadmin
The AppName entry for establishing a PI-API trust is the first four characters of the .exe
file name plus the letter E. If the ACE Scheduler and the default PI Server are on the same
machine, then the IPAddr entry would correspond to the IP address for the machine (not
127.0.0.1) and the IPHost entry would correspond to the machine name (not localhost).
24
Chapter 4
ACE Wizard
The ACE Wizard is a Visual Basic Add-In that helps users with the following tasks:
Creating New ACE Modules
Editing ACE Modules
Debugging ACE Modules
Testing ACE Modules
Registering ACE Modules
In this chapter, we describe how to accomplish these tasks.
System requirements for ACE Wizard are described in ACE Wizard (page 4).
Add-In Menu and Toolbar

The ACE Wizard is located under the Visual Basic 6 Add-Ins menu. If the ACE Wizard is
not found under the Add-Ins menu, you can add it via the Add-In Manager. Click Add-Ins >
Add-In Manager, select PI Advanced Computing Engine (ACE) Wizard, select the
Loaded/Unloaded check box, and click OK.
Figure 4-1 Visual Basic 6 Add-In Manager

ACE Wizard
If you do not see the ACE Wizard in the list of Add-Ins, you may consider repairing the
installation: Open the Add/Remove Programs Applet, select PI Advanced Computing
Engine, click Change and follow the instructions.
The ACE Wizard also exposes its functions via the toolbar PIACEWizard. The toolbar is
available only if the ACE Wizard has been added to the available Add-ins. The ACE Wizard
options are:
New: Creates a new ACE Module
Edit: Edits an existing ACE Module
Debug: Debugs an existing ACE Module
Test: Tests an existing ACE Module
Register: Registers an existing ACE Module
Upgrade (ACE 2.x only): Migrates ACE Modules developed in Visual Basic 6 to Visual
Basic .NET.
About: Displays the ACE version information.
Figure 4-2 ACE 1.x Wizard Menu
26

There are two ways to create a new ACE Module in Visual Basic 6 click Add-In >
PIACEWizard > New (or the equivalent Toolbar button) or click PIACE in the Visual Basic
new project dialog box.
Note: If you do not see PIACE in the Visual Basic new project dialog box, copy piace.vbz
from the ..\ACE\Wizard directory to the ..\Visual Basic98\Template\Projects
directory. It is not necessary to restart Visual Basic.
The only difference between them is that the former allows you create a new ACE Module as
well as edit an existing ACE Module while with the latter you can only create a new ACE
Executable (i.e., a new ACE Module in a new ACE Executable).
Creating a new ACE Module requires completing two pages. Page 1 (page 27) deals with the
names while Page 2 (page 29) deals with tags to be used in the ACE Module.
Page 1
Page 1 of the ACE Wizard, shown below, prompts for the PI Server where the structural
information for the ACE Module (called the PI ACE Data Server) will be stored, the name of
the ACE Executable, and the name of the ACE Module. The names of the ACE Executable
and the ACE Module should be different, should start with a letter, and should contain only
alphanumeric characters and the underscore (_). Both names should be 38 characters or less.
Figure 4-3 Page 1 of Creating or Editing an ACE Module

ACE Wizard
PI Server Name
Specifies the PI Server where the structural information for the ACE Module would be
stored. The PI Server should be version 3.3 or higher and you must have read/write privileges
to its Module Database. Initially, the wizard searches through the PI-SDK Known Servers
List for a valid PI Server, starting with the default server. If none is found, the wizard
prompts you if you would like to add a server. If you answer No or the addition fails, the
ACE Wizard exits since it cannot save any ACE structural information on a PI Server. By
default, the login is through the PI trust. If that fails, the user is prompted to connect.
The combo box is populated with the PI-SDK Known Servers List. Note that they are not
necessarily valid PI Servers for storing the ACE structural information. If the PI Server that
you want to save the ACE structural information is not in the list, you need to exit the wizard,
add it to the PI-SDK Known Servers List via AboutPI-SDK, and unload and reload the ACE
Wizard through the Visual Basic Add-In Manager. It should be in the list when you start the
ACE Wizard again. Alternatively, you can save the ACE structural information on one PI
Server and later copy it to another PI Server via the ACE Manager (page 45).
PI ACE Executable Name

Sets the name of the ACE Executable to which the ACE Module belongs. The combo box is
initially populated with all existing ACE Executables on the PI Server. You can either select
one from the list or enter a new name.
PIACE Class Module Name

Sets the name of the ACE Module. The combo box is initially populated with all existing
ACE Modules for the ACE Executable. Select a name from the list or enter a new name.
<Back and Next> Buttons

Use these buttons to navigate between the two pages.
Cancel and Finish Buttons

Clicking the Cancel button exits the form. Nothing is saved. Clicking the Finish button
would save the structural information of the ACE Module on the specified PI Server, close
the form (if there is no error), and automatically generate the necessary Visual Basic code for
communicating with the ACE Scheduler (page 21) and PI Servers.
28
Page 2
On Page 2, you specify the input and output tags or aliases to be used in the ACE Module,
and the ACE Context for the tags or aliases. Both input and output tags or aliases are optional
(that is, an ACE Module need not contain a PI tag or alias).
Figure 4-4 Page 2 of Creating or Editing ACE Module
The buttons on the right of the dialog box operate on either the Input Aliases or Output
Aliases table, whichever is selected. The Input Aliases table is selected by default. To apply
the buttons to the Output Aliases table, click the table to select it.
Context
The Context box on Page 2 of the wizard sets the PI Module path for the input and output
aliases. You can enter a PI Server name (for example, \\localhost), or the full PI Module path
(for example, \\localhost\DiamondPlant\CrushingUnit2\Controllers).

ACE Wizard
To search for a PI Module, click on the Context combo box. The Context dialog box
appears (Figure 4-5):
Figure 4-5 Context search
The PI Server name is either extracted from the Context combo box or set to the default PI
Server (for example, if the Context combo box is invalid). When the Context combo box
contains more than a PI Server name (for example, \\localhost\%OSI\ACEExecutables), the
display is automatically expanded with the appropriate PI Module selected. When a PI
Module is selected, its path is automatically inserted into the Context combo box when you
click Close.
Input Aliases
These entries set the names of all input tags or aliases to be used in the ACE Module. This
table is optional. An alias name can either be relative (for example, mytag, ..\Pump\FlowIn,
and Controller1\Setpoint) or absolute (for example, \\localhost\mytag and
\\localhost\DiamondPlant\WashingUnit3\Controllers\Controller4\Setpoint) and can be
up to 255 characters. No duplicated item is allowed. An alias name is combined with the
context to determine the corresponding PI tag. For a relative alias name, it is appended to the
context to get the full path name for the tag; for an absolute alias name, the context is ignored
and the alias name is the full path name for the tag.
The full path name for the tag has the format:
\\ServerName\[PIModulePath\]AliasName
If PIModulePath is present, we first search for the alias name in the PIAliases collection
under the PIModule corresponding to \\ServerName\PIModulePath. If there is a match, the
PI tag associated with the PI Alias is used; otherwise, PIModulePath is ignored.
30
Note: The server that this PI tag belongs to may differ from ServerName.
Note that a tag alias with a relative path is undefined until it is combined with a context.
Thus, the tag aliases mytag and \\localhost\mytag may differ and are not considered
duplicated items.
The current value is displayed if the PI tag can be found. If the server connection fails,
"Server Failure" would be displayed. If no PI tag can be found, "Invalid Tag" would be
displayed. An ACE Module is not created if there is an invalid tag. However, an ACE
Module can be created with server connection failures.
You can set clamping and bad value substitution options for each tag. Both options can be
changed later via the ACE Manager. The defaults are "No Clamping" and "No Substitution,"
respectively. Clamping determines what to do when a tag value is smaller than the tag's zero
or is larger than the tag's maximum value (that is, zero plus span). The clamping options are:
No Clamping: No action is taken for any value.
UR Clamping: Any under range value (that is, smaller than the tag's zero) is clamped to
the tag's zero.
OR Clamping: Any over range value (that is, larger than the maximum value) is clamped
to the tag's maximum value.
Both: Applies both UR Clamping and OR Clamping.
Clearly, the clamping makes sense for, and is therefore applicable to, numerical points only.
Bad Value Substitution determines what to do when a tag value is bad. A tag value is
considered bad if it equals a system digital state. A value outside of its range is not
considered as bad. For numeric points, its options are:
No Substitution: No action is taken for a bad value.
Previous Value: The bad value is substituted by a previously good value. Only the last ten
archival values are searched to find a good value. If a good value cannot be found, then
no action is taken.
Typical Value: The bad value is substituted by the tag's typical value.
Tag Zero: The bad value is substituted by the tag's zero.
Tag Maximum: The bad value is substituted by the tag's maximum value (that is, zero
plus span).
User Specified: The bad value is substituted by the user specified value. The value can be
numeric or a string corresponding to a digital state in the system table.
For a digital point, the bad value substitution options include No Substitution, Previous
Value, and strings corresponding to all digital states for the digital set associated with the
point. For other types of points, the bad value substitution options include No Substitution,
Previous Value, and User Specified. The value for the User Specified is treated as a string in
this case.

ACE Wizard
Output Aliases
This optional table sets the names of all output tags or aliases to be used in the ACE Module.
The discussion for Input Aliases applies here with the exception that during the run time, no
value is retrieved from PI for an output tag and no value is written to PI for an input tag.
While an output tag can be used to hold intermediate values, we recommend creating
temporary variables to store the intermediate values. For example, the following code is valid
but not recommended:
:
MyOutputTag = 10 * MyInputTag1
MyOutputTag = MyOutputTag + 23 * MyInputTag2
:
Note that a tag can be used both as an input tag and as an output tag. This may be useful for
doing cumulative calculations.
Delete
The Delete button removes the selected tags or aliases from either the input alias table or the
output alias table.
Tag Search
Use the Tag Search dialog box to search for tags on any PI Server. For help on this dialog
box, press F1.
32
Figure 4-6 Tag Search dialog
Clicking OK pastes the selected tags into the currently-selected alias table on Page 2. The
input alias table is selected initially. To paste tags onto the output alias table, click the output
alias table to select it, and then click Tag Search.
Alias Search
Use this dialog box to search for aliases in the PI Module Database (MDB).
Figure 4-7 Alias Search dialog box
Context: Sets the PI Module path. The Context box is populated with the text from the
Context combo box on Page 2. Use the button to search for a PI Module (see
Context (page 29))
Alias: Sets the partial name for an alias to search. The search is case-insensitive.
Wildcards are "?" for any character and "*" for zero or more characters.
Search: Starts a search for all matches of PI Aliases within the PI Module and its sub-
modules (and their sub-modules, and so on.). The returned results consist of the found
aliases with the path relative to the Context and the full path for the corresponding PI
tag.
Select All: Selects all tag aliases to be inserted into the active alias table.
Close: Inserts all selected aliases into the currently-selected (active) alias table on Page 2.
If the full path for an input alias contains the ACE Context specified for the ACE
Module, then the input alias with a relative path is inserted; otherwise, the input alias
with absolute path is inserted.
Cancel: Exits the dialog box and nothing is inserted into the active table.

ACE Wizard
Configure Tags
Use the Configure Tags dialog box to quickly configure a PI tag with the point class of Base.
Only a few attributes can be set via this dialog box. Default values are used for other
attributes. If this is not sufficient, use tools such as PIPointBuilder or PI SMT to configure PI
tags.
Figure 4-8 Tag Configuration dialog box
PI Server Name: Sets the PI Server where tags are created. You should have the
appropriate privileges on the server to create tags.
Name: Sets the tag name.
Point Type: Sets the point type. The PointSource defaults to L:
ACEexeName.ACEModuleName, where ACEExeName and ACEModuleName are the
names of the ACE Executable and ACE Module that you specified on Page 1,
respectively.
Specifications: Sets the zero, span, and compression deviation percent for a numerical
point, and the digital set for a digital point.
Description: Sets the tag descriptor.
New Tags: Displays a list of new tags created so far. The list is always empty when the
dialog box is opened.
Delete: Removes selected tags in the New Tags box permanently from the PI Server.
Create: Creates the specified tag.
34
Close: Inserts all new tags (absolute path) into the currently selected alias table on Page 2
of the wizard.
Tag Attributes
Views all attributes associated with a PI tag. The selected tag/alias on the main page, if any,
is automatically displayed.
Figure 4-9 Tag Attributes dialog box
Context: specifies a PI Module path or the name of a PI Server. The button searches
for a PI Module. See Context (page 29) for details.
Alias: Tag name or alias name for an alias of the PI Module. The specifications of
Context and Alias are identical to those on the main page and were discussed previously.
Retrieve: gets the point attributes for the tag corresponding to the specified PI Module or
PI Alias. The server and tag names are displayed.
Close: exits the dialog box.

ACE Wizard
Developing Equations in Visual Basic
After you complete the two pages, clicking the Finish button closes the form (if there is no
error), saves the ACE Module structural information in the Module Database on the specified
PI Server (that is, PI ACE Data Server), and automatically generates the necessary Visual
Basic code to communicate with PI Servers referenced by the input and output aliases and the
ACE Scheduler.
Figure 4-10 Visual Basic Equation Editor Window
Now you are writing programs in the Visual Basic environment and should follow sound
Visual Basic programming practices. There are numerous books on Visual Basic
programming and we would not even try to cover this topic. Instead, we offer a few
comments specific to developing ACE Modules.
It is important not to delete or modify the code generated by the wizard. In Visual Basic 6,
you can declare module-level variables directly below the following line at the beginning:
' ' ' ' ' Declare User Variables ' ' ' ' '
Variables that do not change from calculation to calculation or whose values from one
calculation are used in the next calculation should be declared as module-level variables. You
can initialize and terminate those variables in the subroutines UserDefinedInitialization and
UserDefinedTermination, respectively.
All the input and output tags or aliases you have specified have been declared as PIACEPoint
objects. A complete reference of the available methods and properties for the PIACEPoint
object can be found in the online help. Note that the Visual Basic variable name for a PI
tag/alias may differ from its name since not all valid PI tag/alias names are valid Visual Basic
variable names. The correspondence is shown in the table right before the subroutine
ActualPerformanceEquations. The name of this subroutine must not be changed.
36
Editing ACE Modules
Do not attempt to declare or remove any PIACEPoint object yourself. To add or remove tags,
select the Edit item from the ACE Wizard Add-In menu and add or remove tags from
appropriate tables on the second page.
Editing ACE Modules

To add or delete PI tags used by an existing ACE Module, use the Edit command. Edit
works like the New command (see Creating New ACE Modules (page 27)), except that
entries are populated with appropriate data for the specified ACE Module. Changes related to
the calculations can be made directly within the ACE Module.
When an input tag is removed or its type is changed (that is, to either an output tag or
input/output tag) and if the tag is used as a trigger tag in any of the ACE Contexts, the
scheduling information for the ACE Contexts is automatically updated. An error results if the
change causes no trigger tag for ACE Contexts with Natural scheduling.
Debugging ACE Modules

The Debug item compiles the ACE Executable and, if successful, breaks at the beginning of
the subroutine ActualPerformanceEquations. The users can then step through the code to
examine the results. Debugging can catch compilation errors and allows users to visually
inspect calculation results and is thus highly recommended.
Note: On some international versions of Windows and/or VB, the debugging may not
work. Users can manually place a breakpoint at the subroutine
ActualPerformanceEquations, substitute ACEModuleName in the declaration
statement Dim ACEClassModule As New ACEModuleName in the standard
module DebugModule with the actual ACE Module Name to be debugged, and
click Run > Start with Full Compile. For example, if the ACE Module name is
Test1, then the declaration statement becomes Dim ACEClassModule As New
Test1.
Note that debugging does not write data to PI, unless your code explicitly writes data to PI.
Testing ACE Modules

An ACE Module must be successfully tested before it can be started by the ACE Scheduler.
Testing ensures that the ACE Executable can be compiled and that the ACE Module can be
instantiated and destroyed properly. If the ACE Executable can be compiled successfully and
the ACE Module can be instantiated successfully, all the standard and class modules in the
ACE Executable are automatically saved in the directory ACE\Executables. The testing
options are: Basic Test and Advanced Test. The Basic Test page allows the users to test the
ACE Module for one set of snapshot values at a time; the Advanced Test page lets the users
test multiple sets of snapshot values simultaneously.

ACE Wizard
Note that testing does not support tags used as both input and output. Both input and output
values for these tags equal to the input value at the respective reference time.
Like debugging, testing does not write data to PI unless your calculation writes data to PI
explicitly.
Basic Test
The following shows the basic test page. The input and output aliases information as well as
the context are retrieved from the ACE Data Server. Note the test value type only affects the
value at the current execution time and does not affect the results of summary or archive
functions.
Figure 4-11 Basic Test Page
Context
Sets the ACE Context for the test. Only one from the list of available ACE Contexts can be
selected.
Reference Time
Sets the execution time. This value does not affect the absolute times (for example, 1-May-
2006), as well as any time argument passed to a PIACE built-in function (for example,
ParseTime("*")).
38
Testing ACE Modules
Test Value Type

Shows one of the following:
Current Value: The current snapshot value.
Typical Value: The typical value for the tag.
Minimum Value: The minimum value (that is, zero) for the tag.
Maximum Value: The maximum value (that is, zero plus span) for the tag.
Bad Value: The bad value for the tag. This is useful for testing how the ACE Module
handles bad values.
User Specified: A user specified value for the tag.
Note: Minimum value, maximum value, and typical value are not available for non-
numeric points.
Get Current Values

Retrieves the current snapshot values for all input tags for use in the test.
Get Typical Values

Retrieves the typical values for all input tags for use in the test.
Calculate Now
Determines the output tag values.
Advanced Test
Displays the Advanced Test dialog box. See Advanced Test (page 39).
Close
Exits the test page.
Advanced Test
The Advanced Test allows the users to carry out multiple tests simultaneously. The test
results are displayed in a histogram. The histogram has thirteen intervals: Bad Values, Under
Range Values (i.e., less than the tag's zero), ten equal intervals between the tag's zero and the
maximum value, and Over Range Values (i.e., larger than the maximum value for the tag). In
addition, the summary information consists of the total number of tests carried out, the
percentage of values that are good, and the interval size.

ACE Wizard
Figure 4-12 Advanced Test Page
Input Settings
Use the settings in the Input Settings group to select the Test Value Types (page 39) for all
input tags. Calculations for all possible combinations of input settings and input tags are
performed. That is, there are mn tests, where m is the number of input settings and n is the
number of input tags.
Estimated Time
Shows the estimated time for completing the tests.
Print
This button prints out this form. This is only supported in the VB6 Wizard and thus the
button is not visible within the Wizards for 2003/2005/2008.
Run Tests
Performs tests for the selected input settings.
Return
Returns to the basic test page.
40
Output Tag
The combo box shows all the outputs used in the calculation. Select any tag to display the
results.

An ACE Context cannot be run until its scheduling information is specified. This can be done
through either the ACE Wizard or the ACE Manager. The only difference between the two is
that the Wizard allows users to enter a description for the ACE Module and the Manager
allows users to alter the default latency value for natural-scheduled calculations.
The following form appears after clicking the Register command from the ACE Wizard Add-
In menu and specifying an ACE Module to register.
Figure 4-13 Registering Clock-Scheduled Calculations

ACE Wizard
Figure 4-14 Registering Natural-Scheduled Calculations
ACE Module
Displays the current ACE Module whose ACE Contexts are to be registered. Click to
select a module.
Context
Sets the ACE Context to which the scheduling information applies.
Priority
Selecting Priority sets the relative importance of the ACE Context. For a detailed discussion,
see Resource Constraint (page 22).
Scheduling Information
Sets the schedule type (either Clock or Natural) for the ACE Context.
42
Period and Offset
Sets the period and offset for clock-scheduled calculations. The smallest period is 0.001
seconds. The offset should be an integer between 0 and 86399 seconds, and should be less
than or equal to the period.
Trigger Tags
Specifies the trigger tags for natural-scheduled calculations. Only input tags or aliases can be
used as trigger tags. Tags or aliases that are used as both input and output cannot be used as
trigger tags, because this can easily result in an infinite execution loop if not properly
handled.
ACE Module Description
Displays the ACE Module description for editing.
OK
Writes the scheduling information for the ACE Context to the PI Module Database on the PI
ACE Data Server.
Close
Exits the dialog box.

Chapter 5
ACE Manager
The ACE Manager enables you to monitor and modify properties of an ACE Context, an
ACE Module, and an ACE Executable on any PI Server. For example, users can:
View status of all ACE Contexts on many PI Servers.
Copy the structural information for an ACE Executable from one server to another.
Take an ACE Executable, ACE Module, or ACE Context out of service, delete it, or
resume its calculations.
Change the scheduling information for an ACE Context.
Add a new ACE Context to an ACE Module.
Change clamping and bad value substitution options for a PI tag.
Change tag or alias names.
Change the level of message logging for an ACE Context and for the ACE Scheduler.
Both ACE 1.x and 2.x share the same ACE Manager. When the ACE Scheduler is running,
the ACE Scheduler periodically checks for updates and most of the changes become effective
within minutes.
Following an ACE Manager GUI (page 46) of the ACE Manager, we discuss in detail the
Server Menu (page 47), Executable Menu (page 50), Module Menu (page 51), Context Menu
(page 55), and Tag Menu (page 61).

ACE Manager
ACE Manager GUI

The main window for the ACE Manager is shown below.
Figure 5-1 ACE Manager GUI
The left pane is a tree view of all ACE Executables developed either with ACE 1.x or 2.x,
ACE Modules, and ACE Contexts stored on a PI Server. Multiple PI Servers can be added for
display.
What is displayed on the right depends on the selection in the tree view. In general, the status
(e.g., On, Off, Error, and New) for the selected item is displayed. Selecting a PI Server, ACE
Executable, or ACE Module displays the summary information for all ACE Contexts directly
underneath it. The summary information for an ACE Context includes:
Name. The format is Executable\Module\Context.
Current status.
Time when the status last changed.
Scheduling information. The format is Natural (m) where m is the number of trigger tags
or Clock (period, offset).
Number of output tags.
Double-clicking on an ACE Context in the summary in the right pane would display the
details for the ACE Context. The summary information is not updated but can be refreshed
via Server > Refresh Server.
The selection in the tree view activates the appropriate menu in the menu bar and affects the
meaning of toolbar buttons. For example, selecting a PI Server only enables all entries for the
Server menu and the Cut toolbar button is a shortcut for removing the selected PI Server from
display.
The status bar has two panels. One panel displays the number of ACE Executables, the
number of ACE Modules, and the number of ACE Contexts under the selected item. For ACE
Contexts, a summary of how many are running, have errors, are unregistered, and are out of
46
Server Menu
service is also shown. Clearly, the number of ACE Executables would not be displayed if the
selected item corresponds to an ACE Executable, ACE Module, or ACE Context. The other
panel displays ACE Executable(s), if any, to be exported to another PI Server.
To change the properties associated with an ACE Executable, ACE Module, or ACE Context,
you should have write privileges to the PI Module Database. Otherwise, you may only view
the information. When a property is changed, the ACE Scheduler, if running, automatically
picks up this change and does appropriate updates. In general, this should take less than a
minute but may take longer depending on the CPU load.
Since the ACE Manager connects to a PI Server through the PI Trust login, it is important to
establish an appropriate trust on the PI Server for the ACE Manager.
We now discuss in detail the Server, Executable, Module, Context, and Tag menu items.
Server Menu
Unless otherwise specified, the items for this menu are activated when the selection in the
tree view corresponds to a PI Server. Some of them may be grayed out for reasons explained
later.
Figure 5-2 Server Menu
Add New Server
Adds a new PI Server from the PI SDK Known Servers List.
Toggle ACE 1.x/2.x
This menu command toggles between displays for ACE Executables developed with ACE 1.x
and ACE 2.x. The ACE Manager does not support displaying ACE Executables developed in
both versions simultaneously. The version information is displayed on the right pane when a
PI Server is selected. The other difference between the displays is the icon for an ACE

ACE Manager
Executable node. The icon for an ACE Executable developed with ACE 1.x has Exe at the
bottom while the icon for an ACE Executable developed with ACE 2.x has DLL at the
bottom.
Set Default Display
Sets the current display (either ACE 1.x or ACE 2.x Executables) for the selected PI Server
as the default display. The default display appears the next time the ACE Manager starts.
Refresh Server
Updates the display for the selected PI Server.
Remove Server
Removes the PI Server from display. This does not remove the PI Server from the PI SDK
Known Servers List.
Reset Status
Resets the status of all ACE Executables, ACE Modules, and ACE Contexts on the selected
PI Server to Off. It prompts you if you want to reset all the Error and Terminated statuses. If
the status for the ACE Scheduler is On, then you may not be able to reset the statuses.
Export All Executables
This menu command exports all ACE Executables from the selected PI Server to be imported
by another PI Server. All previous exports are cleared.
Import
This menu command imports previously exported ACE Executables to the selected PI Server.
The structural information for the exported ACE Executables is copied to the selected PI
Server. The actual files for the ACE Executables are not copied. This command is available
only if there is at least one exported ACE Executable and the exported ACE Executables are
from a different PI Server. You cannot import an ACE Executable whose name conflicts with
the name of another ACE Executable that already exists on the PI Server.
48
Server Menu
Message Log Level
This menu command sets the message log level for the ACE Scheduler. Note this differs from
the message log level for an ACE Context discussed later.
Figure 5-3 ACE Scheduler Message Log Level Setting
By default, all messages generated by the ACE Scheduler are logged. Users can choose to log
messages related to warnings, starting/stopping of an ACE Executable/Module/Context,
calculation event generation, class object initialization/termination, and updates. The ACE
Scheduler message log level setting is read every minute.
Recalculate
Manually recalculates all ACE Contexts on the PI Server with status of Off, On, or
OutOfService. One needs to specify the start and end times, and optionally the interval, for
the recalculations. If the ACE Scheduler is not running or the ACE Executable is not in a
ready-to-calculate state (i.e., On, Off, or OutOfService), then this menu command is grayed
out.
Enable/Disable Caching
One can enable or disable the ACE caching server. In general, you should not disable caching
for performance reasons. One rare case that you may want to disable caching is when you
experience delay with the PI update mechanism.
Enable/Disable Auto Refresh
When Auto Refresh is enabled, ACE Manager signs up for updates and automatically
refreshes the displays.

ACE Manager
Exit
Exits the ACE Manager.
Executable Menu
Unless otherwise specified, the commands for this menu are available when an ACE
Executable is selected in the tree view.
Figure 5-4 Executable menu
Resume Calculation
Resumes calculation for the selected ACE Executable. This command is available only if the
current status of the selected ACE Executable is OutOfService or Error. If the status of the
ACE Scheduler is On, then the status of the executable is immediately set to Starting and
then to On when the calculation starts; otherwise, ACE Executable status is set to Off.
Take Out of Service
Takes the selected ACE Executable out of service. This command is available only if the
status for the selected ACE Executable is On or Off.
50
Module Menu
Export
Exports the selected ACE Executable so it can be imported to another PI Server. All previous
exports are cleared.
Delete
Permanently deletes the structural information for the selected ACE Executable and its ACE
Modules from PI Server. Before you delete a running ACE Executable, take it out of service.
This command does not delete the source files for the ACE Executable and its ACE Modules.
Recalculate
This menu command manually recalculates all ACE Contexts under the selected ACE
Executable with status of Off, On, or OutOfService. You need to specify the start and end
times for the recalculations. If the ACE Scheduler is not running, or the ACE Executable is
not in a ready-to-calculate state (that is, On, Off, or OutOfService), then the command
appears dimmed.
Module Menu
Unless otherwise specified, the commands in this menu are available when the selection in
the tree view corresponds to an ACE Module.
Figure 5-5 Module Menu

ACE Manager
Description
Displays the description of the ACE Module that can be edited via the ACE Wizard.
Resume Calculation
Resumes calculation for the selected ACE Module. This command is available only if the
current status of the selected ACE Module is either OutOfService or Error. If the status of
the associated ACE Executable is On, then the status of the ACE Module is immediately set
to Starting and then to On when the calculation resumes; otherwise, ACE Module status is
set to Off.
Take Out of Service
Takes the selected ACE Module out of service. This command is available only if the status
for the selected ACE Module is On or Off.
Add New Context
Adds a new ACE Context to the selected ACE Module. The user needs to specify the context
name, priority, and scheduling information.
For clock-scheduled calculations, the scheduling information consists of the period and
offset. The clock for the PI Server specified in the context (e.g., zheng for an ACE Context of
\\zheng and MyPIServer for \\MyPIServer\MyPIModule\Controllers\PID) is used
to generate calculation events.
For natural-scheduled calculations, the scheduling information consists of the trigger tags and
the latency. The latency specifies the maximum time to wait for events for other tags before
calculations are carried out. For example, suppose an ACE Context is natural-scheduled with
two trigger tags. An event arrives for one of the trigger tags. The calculation is not executed
immediately. Instead, the scheduler waits for an event for the other tag to arrive.
If no event comes in during the period specified by the latency, then the calculation is carried
out. If an event for the same trigger tag comes in during the latency period and the event
timestamp is after the first event, then a calculation is executed at the timestamp for the first
event and the second event waits up to the period specified by the latency before it can be
calculated. If the timestamp for the second event is before the first event, then a calculation
may be executed at the timestamp for the second event and the first event continues to wait. If
the timestamp for the second event is the same as that for the first event, then it is ignored.
The above algorithm applies when an event for the other trigger tag arrives during the period
except that if the timestamp for the event is the same as that for the first event, a calculation is
executed.
The default value for the latency is fifteen seconds. Of course, the latency has no effect on
natural-scheduled calculations with only one trigger tag.
In ACE 2.1.5 and earlier, a naturally scheduled calculation with multiple trigger tags would
execute when all triggers had updated, or when the latency period expired. Calculations with
52
Module Menu
only a single trigger would therefore always fire immediately. Starting with ACE 2.1.7,
calculation is always delayed for the latency period, even if the calculation has only a single
trigger tag. You can work around this issue by setting the latency of any calculations to zero.
One can also specify tags that would automatically trigger recalculations. The tags must be
selected from the list of input tags. When an archive event for a recalculation trigger tag is
added/modified/deleted and its timestamp is before the last executed calculation time, this
event would trigger recalculations. Note that there is a delay of one minute in carrying out the
automatic recalculation and that recalculations automatically have lower priorities than
normally scheduled calculations (i.e., normally scheduled calculations are always executed
first). The reason for the delay is that a change may result in many recalculations and that it
may be better to wait for other changes to come in. See Advanced Topics (page 63). for
details on how the actual recalculations are computed.
Figure 5-6 Add or edit context (clock scheduling)

ACE Manager
Figure 5-7 Add or edit context (natural scheduling)
Delete
Permanently deletes the structural information for the selected ACE Module and its ACE
Contexts from PI Server. Before you delete a running ACE Module, take it out of service.
This command does not delete the executable or .dll file for the ACE Module.
Recalculate
Recalculates all ACE Contexts with status of Off, On, or OutOfService. You need to specify
the start and end times for the recalculations. This command is not available if the ACE
Scheduler is not running, or if the ACE Module is not in a ready-to-calculate state (that is,
On, Off, or OutOfService).
54
Context Menu
Context Menu
Unless otherwise specified, the commands on this menu are available when the selection in
the tree view corresponds to an ACE Context.
The summary display for ACE for VB6 differs from that for ACE for VB.NET. ACE for
VB6 shows two additional parameters: CL Violations and Maximum CL Violations. CL
Violations shows the number of consequent calculations that have violated the calculation
limit. Maximum CL Violations equals the maximum number of consequent calculations
violating the calculation limit before the ACE Scheduler would not attempt to restart. CL
Violations is reset when the calculation is manually restarted or when the ACE Scheduler is
restarted.
Figure 5-8 Context Menu
Resume Calculation
Resumes calculation for the selected ACE Context. This command is available only if the
current status of the selected ACE Context is OutOfService, Terminated, or Error. If the
status of the associated ACE Module is On, the status of the ACE Context is immediately set
to Starting and then to On when the calculation resumes; otherwise, ACE Context status is
set to Off.
Take Out of Service
Takes the selected ACE Context out of service. This command is available only if the status
for the selected ACE Context is On or Off.

ACE Manager
Edit Schedule and Priority
Edits the scheduling and priority information for the selected ACE Context. The dialog box is
identical to that for Add New Context, except that the Context Name cannot be changed.
Apply Schedule to
Creates ACE Contexts with the same schedule as the currently-selected ACE Context. When
selected, displays a tree view of PI Module Database (Figure 5-9).
Figure 5-9 Tree view of PI Module Database
To create ACE Contexts, click the node in the tree view that includes the PI Modules you
want to use, and then click Close. You see a dialog box that shows a summary of all ACE
Contexts to be added to the ACE Module (Figure 5-10).
56
Context Menu
Figure 5-10 Summary of ACE Contexts to be added to the ACE Module
The summary contains the following information:

Context (PI Module Path) shows the full PI Module path in the format
\\PIServer\PIModule\PIModule.
Same Aliases? shows whether the PI Module contains all the PI Aliases that are used in
the calculations for the currently-selected ACE Context. If Yes, the check box is selected.
Otherwise, the check box is cleared. Notice that the PI Module might contain additional
PI Aliases.
To select only modules that contain the same PI Aliases as the currently-selected ACE
Context, select the Select only PIModules with exact alias match check box.
Same PIProperties? shows whether the PI Module contains all the PI Properties of the
PI Module for the current ACE Context.
Select the check boxes for the PI Modules you want to use, and then click Apply to create
ACE Contexts.
Edit Calculation Limit
For the selected ACE Context, changes the maximum amount of time (in seconds) per
calculation.
Delete
Permanently deletes the structural information for the selected ACE Context from PI Server.
Before you delete a running ACE Context, take it out of service.
Message Log Level
Sets the message logging level for the ACE Context:

ACE Manager
Figure 5-11 Message Log Level Setting
By default, only error messages for the ACE Context are logged. You can choose to log
messages related to warnings, counters, resource notification, calculation events, user
messages, and updates. User Messages are generic messages that do not fit into any of the
other categories.
Get Error Message
Retrieves the error message if the status for the selected ACE Context is Error.
Recalculate
Recalculates the ACE Context. Specify the start and end times for the recalculations. This
command is not available if the ACE Scheduler is not running, or if the ACE Context is not
in a ready-to-calculate state (that is, On, Off, or OutOfService).
58
Context Menu
Search
This command is available when you select a Server, ACE Scheduler, Executable, or Module
on the tree view. The search is limited to the children of the selected node. Search results
appear in the right pane. Use ? and * as wildcards in the search string. Figure 5-12 shows the
results for a search string l* when you select the ACE Executable Tests.
Figure 5-12 Results for search string "l*" under ACE Executable Tests.
However, the results are different for the same search string l* if you select the ACE Module
Test1:

ACE Manager
Figure 5-13 Results for search string "l*" under ACE Module Test 1.
60
Tag Menu
Tag Menu
The items for this menu, except List, are activated when the selection in the tree view
corresponds to a PI tag or alias and are grayed out otherwise. The List item is activated when
the selection in the tree view corresponds to a PI Server, an ACE Executable, an ACE
Module, or an ACE Context.
Figure 5-14 Tag Options Menu
List
Lists all PI tags that are used by ACE Executables that are included in the current selection on
the tree view: a PI Server, an ACE Executable, an ACE Module, or an ACE Context. For
example, selecting an ACE Executable in the tree view shows all the PI tags used by that
ACE Executable.
Figure 5-15 shows the list of tags used in the ACE Executable SmokeHeatDutyCalc on the
PI Server MyPIServer. The tag name, if valid, is shown with the absolute path
(\\MyPIServer\HeatDuty1). An invalid tag (that is, one that cannot be resolved for a given
PI Module and alias) is highlighted red. Also shown are the snapshot time and value; the tag
type (Input, Output, or Both); the ACE Module to which the tag belongs; and the ACE
Context and the alias used to resolve the tag. Note the tag name may differ from its alias
name. You can copy this information to the clipboard.

ACE Manager
Figure 5-15 List of tags for an ACE Executable
Change Name
Changes the name of the selected PI tag or alias. You need to use this command when any PI
tag or alias referenced by the ACE Module is renamed on PI Server.
Edit Tag Options
Changes the clamping and bad-value substitution options for the selected tag.
62
Chapter 6
Advanced Topics
In this chapter, we discuss the caching server (page 63), the recalculation (page 64) feature,
how to develop a library of functions (page 66) and use them in an ACE Module, and how to
retrieve the last snapshot value (page 68) (versus the last archive value).
Caching Server
Each ACE Executable signs up with the PI Update Manager for Snapshot and Archive
updates for all its input tags and caches the events when receiving them. The cache offers two
advantages: One call is made to a PI Server to retrieve multiple events instead of multiple
calls to the PI Server and the cached data may be reused. The latter is especially significant
when calculations in an ACE Executable make many data calls for the same PI tag. All
PIACEPoint data calls (e.g., Value, Avg, and PrevEvent) except the Values method are
evaluated using the data in the cache, if the cache contains enough data. Otherwise, the
equivalent calls to a PI Server are made.
The cache for each tag consists of Archive events and one Snapshot event. It is first
initialized with one day of Archive/Snapshot events or 1000 events, whichever is less. This
period is then dynamically adjusted based on its actual usage, subject to a limit on the
maximum number of cached events per tag. The limit depends on the total number of unique
input tags in an ACE Executable and is 2000 if the total number of unique input tags is less
than 1000.
Typically, retrieving data from the cache is much faster than retrieving data from a PI Server.
How much faster depends on many factors including the network speed, computer hardware,
PI Server usage, etc. Even in an ideal environment where the ACE Scheduler and the PI
Server are running on the same machine and no other application is accessing data from the
PI Server, retrieving data from the cache is about five times faster than retrieving data from
the PI Server.
One can view the number of data retrieval calls to the cache and the number of data retrieval
calls to PI Servers by enabling the message type Cache Server for the ACE Scheduler. About
every ten minutes, one should see messages similar to this:
0 ACEExe1.exe 17-Mar-04 16:23:51
>> Total cache/server retrievals: 94/0
The above message means that there have been 94 calls to the cache server and 0 calls to PI
Servers since the ACE Executable ACEExe1 started.

Advanced Topics
Recalculation
Recalculation is often necessary for many reasons (for example, when data arrive late, when
the data used in past calculations are changed, and when the actual calculation and its
parameters are changed). There are two types of recalculations: Manual and Automatic. The
manual recalculation is useful when a calculation was out-of service or its logic has changed.
The automatic recalculation is useful for a calculation where archive values for input tags are
modified frequently. Both of them can only be configured via the ACE Manager. See ACE
Manager (page 45) for details on how to configure them. The ACE Scheduler must be
running to execute both types of recalculations. It is important to realize that recalculation is
expensive as it bypasses exception reporting, may retrieve lots of archive data for many tags,
and may generate many out-of-order events. All of them place a significant burden on a PI
Server. Furthermore, if one is about to do a massive manual recalculation, one should check
that the archive files have sufficient space. Consult the PI Server System Management Guide
for details.
For manual recalculations, one specifies a start time, end time, and optionally a recalculation
interval. The recalculation can be applied to an ACE Context, an ACE Module, an ACE
Executable, or all ACE Executables. Recalculating an ACE Executable would recalculate all
its ACE Contexts. Timestamps of recalculated events depend on whether a recalculation
interval is specified, and on the context's scheduling type.
If a recalculation interval is specified, recalculation will be done at the requested interval and
at the start and end times.
If a recalculation interval is not specified, recalculations are based on the context's schedule.
If the calculation is event triggered, the actual recalculation times are based on the archive
events in the interval for both input and output tags used in the context, plus the start and end
times. Clock scheduled contexts are recalculated according to the schedule interval and
offset, plus the start and end times.
One cannot launch manual recalculation for an ACE Context, an ACE Module, or an ACE
Executable whose status is in a non-ready (for example, New, Edit, and so on) or error (for
example, Error, Terminated, and so on) state. For automatic recalculations, one specifies
recalculation trigger tags as a part of the schedule for an ACE Context. When an archive
event for any of the recalculation trigger tags is added/modified/deleted and the event
timestamp is before the current execution time for the ACE Context, recalculations are
automatically triggered. The recalculation interval is determined by two parameters: how far
in the past and how far in the future this archive event affects the calculation results. Consider
this calculation:
MyOutputTag.Value = MyInputTag.Avg("*-1h", "*")
Any past archive change to MyInputTag would affect the results of MyOutputTag for the
next hour. Thus, the recalculation period for MyInputTag is T to T+1hour where T is the
timestamp of the past archive event. Once the recalculation interval is determined, the same
logic in manual recalculations is used to determine the actual recalculation times.
Within an ACE Context, the recalculating events automatically have lower priorities (that is,
normally scheduled calculations are always executed first). Since the recalculations and
normally scheduled calculations share the same public data, it is important that any
dynamically changing public data be properly set during recalculations. For example, suppose
that a module-level variable is declared to store the current snapshot value. This works
64
Recalculation
perfectly fine when no recalculation occurs. However, when recalculations are triggered, the
value for the variable may be incorrect, since the recalculation times are likely before the
snapshot event time. Furthermore, after recalculations are completed, this variable may be
reset to a wrong value. It is also important to recognize the difference between the built-in
VB time function Now and the PI time *. The former equals the current time (that is, time
context insensitive) while the latter equals the time when the calculation is scheduled (that is,
time context sensitive). Using the function Now would most likely result in undesirable
recalculated values. So one should avoid using the function Now, especially when some
recalculations are expected. Instead, one should use * or the module-level variable
mdblExeTime.
Programmatically, one can determine whether the current calculation is a recalculation by
calling mpeqExecutionQueue.IsRecalculating. This is useful if different logic should be
applied to a recalculation.
To view the recalculation progress, one can turn on the messaging (Calculation Events) for
the ACE Scheduler and/or for the ACE Context. With the message type Calculation Events
selected for the ACE Scheduler, one should see messages similar to the following (note that
all timestamps are UTC seconds since January 1, 1970):
0 PIACEScheduler.exe 17-Mar-04 16:04:11
>> Manual recalculation for ZHENG\aceexe1\archivetests\ZHENG
0 ACEExe1.exe 17-Mar-04 16:04:11

>> Recalculating 6 events between 1079557442 and 1079561042
0 PIACEScheduler.exe 17-Mar-04 16:04:11

>> Manual recalculation for ZHENG\aceexe1\archivetests\ZHENG
between 1079557442 and 1079561042
0 ACEExe1.exe 17-Mar-04 16:04:12

>> Recalculation for ZHENG\aceexe1\archivetests\ZHENG completed
With the message type Calculation Events selected for the ACE Context, one should see
messages similar to the following:
0 ACEExe1.exe 17-Mar-04 16:04:12
>> ZHENG\aceexe1\archivetests\ZHENG: Execution time 1079557442
for ACE Context is removed from the execution queue
0 ACEExe1.exe 17-Mar-04 16:04:12

0 ACEExe1.exe 17-Mar-04 16:04:12

0 ACEExe1.exe 17-Mar-04 16:04:12

0 ACEExe1.exe 17-Mar-04 16:04:12


Advanced Topics
0 ACEExe1.exe 17-Mar-04 16:04:12

Similarly, one should see messages similar to the following for automatic recalculations:
0 ACEExe1.exe 17-Mar-04 16:13:05
>> Auto-recalculation starting for
ZHENG\aceexe1\archivetests\ZHENG
0 ACEExe1.exe 17-Mar-04 16:13:05

>> ZHENG\aceexe1\archivetests\ZHENG: Adding recalculation event
at 1079565122 from localhost\1.
0 ACEExe1.exe 17-Mar-04 16:13:05

>> Recalculating 1 events between 1079565122 and 1079565122
0 ACEExe1.exe 17-Mar-04 16:13:05

0 ACEExe1.exe 17-Mar-04 16:13:05

>> Recalculation for ZHENG\aceexe1\archivetests\ZHENG completed
Setting up Redundant Schedulers

You can set up multiple ACE Schedulers (one per machine) to run the same set of
calculations stored in a PI Module Database. One Scheduler, the master scheduler, runs the
calculations while others are in standby mode. All you need to do is to set up the same target
PI Server on all the machines and start the Scheduler services.
When the master Scheduler shuts down gracefully or ungracefully, a Scheduler in standby
mode automatically becomes the master and starts running the calculations within one
minute.
User-Defined Functions in Visual Basic 6

Developing a library of user-defined functions in Visual Basic 6 is straightforward and
involves the following basic steps (a library of user-defined functions can also be developed
in other languages such as C++). You should consult appropriate Visual Basic references for
details.
Create an ActiveX DLL project. The project should contain an empty class module. If not,
add a class module. Give the project and the class module appropriate names. Set the
Instancing property of the class module to 6-GlobalMultiUse.
Write all the user-defined functions that you want to expose in the class module as Public
Function, Public Sub, or Public Property. In some cases, it may be desirable to categorize
various functions into different class modules. This can be done by adding as many class
modules to the project as desired and by setting their Instancing properties to 6-
GlobalMultiUse.
66
In-process COM Servers
Compile the project. If successful, this would create a .dll file which has been automatically
registered on the computer and which is ready to be registered on other computers. To
maintain compatibility, you should check binary compatibility (Project > Properties >
Components > Version Compatibility) after the first successful compilation and recompile
it. Registering the .dll file on another computer can be done by copying the file to the
destination computer and by running regsvr32.exe (e.g., regsvr32 DLLNAME.dll).
Once you have successfully registered the .dll file consisting of the user-defined functions,
you can use the functions in any Visual Basic project by adding it to the reference list for the
project: From the Project menu, click References. This brings up the available reference
list. The name of the .dll (or its description) should be in the list if it has been successfully
registered. Check it and click OK. You are ready to use any of the functions in the library.
In-process COM Servers

An in-process COM server can be used directly in a Visual Basic project by including it on
the reference list. For example, the .dll file consisting of the user-defined functions that you
created in the previous section is an in-process COM server. PI SDK libraries (for example,
pisdk.dll and pitimeserver.dll) and steam table function library (that is,
pisteamtablefunctions.dll) are in-process COM servers.
Using a COM library in VB.NET differs from that in VB6. In VB.NET, you may need to
create an instance of the root object before you can use any of its child objects or methods. In
VB6, this is already done for you. Here is an example on how to use the steam table function
StmEng_HsatP in VB6 and VB.NET:
VB6:
StmEng_HsatP(Pressure)
VB.NET:
Dim objST As New PISTEAMTABLE.PISTFunctions
objST.StmEng_HsatP(Pressure)
Out-of-process COM Servers

Creating an instance of an out-of-process COM server in Visual Basic can be done by using
the Visual Basic function CreateObject().
Note: This function is not available in a learning edition of VB.
Details on the syntax of this function can be found in the Visual Basic online help. For
example, this is what we used in creating a MATLAB object in Example 2 Calling External
Functions (page 14). An ACE Executable built with ACE 1.x is an out-of-process server and
thus can be used for other purposes if desired.

Advanced Topics
Retrieving Last Snapshot Value or Last Archive Value

Because of compression, the last snapshot value is not necessarily the same as the last archive
value. The PrevVal and PrevEvent functions return the last archive value and its timestamp,
respectively. Although there is no function to retrieve the last snapshot value directly, this can
be done quite simply within an ACE Module. To simplify the discussion, let us assume that
we would like to get the last snapshot value of the PI tag SINUSOID. SINUSOID should be
defined as an input tag (or as both input tag and output tag) because the snapshot value for an
output tag is never retrieved. The scheduling type needs to be set to Natural and the trigger
tags include SINUSOID.
Within the ACE Module, we define a module-level variable (for example,
LastSnapshotValue) and initialize it with the current snapshot value (for example,
LastSnapshotValue = SINUSOID.Value). When SINUSOID receives a new snapshot
event, a calculation is triggered. Then LastSnapshotValue is truly the last snapshot value
and should be reset to the current snapshot value before leaving the calculation, so that it is
available for the next calculation.
Output Tag Timestamp

By default, the timestamp for an output tag equals the scheduled execution time (that is, the
time when the calculation is scheduled to be evaluated, not when the calculation is actually
carried out). To specify a different timestamp for the output tag, specify the desired
timestamp when setting the tag value (for example, OUTPUTTAG.Value(Now) =
INPUTTAG.Value).
Specification of Timestamp Argument

Since there may be difference between the time when a calculation is supposed to be carried
out and the time when the calculation is actually carried out, care should be taken in
specifying the timestamp for any function that takes it as an input argument.
For example, the following equations may produce different results:
AverageValue = SINUSOID.Avg(Now 1, Now)
AverageValue = SINUSOID.Avg(mdblExeTime - 86400, mdblExeTime)
With the first equation, AverageValue would depend on when this equation is evaluated.
With the second equation, AverageValue does not depend on when this equation is
evaluated. Note that the module-level variable mdblExeTime represents UTC seconds since
1-1-1970 and the VB function Now() has the unit of Day (1 Day = 86400 Seconds).
Note: The above example and mdblExeTime apply to VB 6. Use ExeTime or

MyBase.ExeTime instead in VB .NET.
68
PI System Backup and Connection
PI System Backup and Connection

The backup of a PI System should not affect ACE calculations. When an ACE Module loses
the connection to PI Server, the ACE Module automatically attempts a reconnection when
retrieving values or attributes for a tag on PI Server. During the period when the connection
could not be established, the calculation (see below for detail on natural-scheduled
calculations) might fail. However, the calculation returns to normal when the connection is
established again.
Similarly, when a PI System is shut down and restarted, an ACE Context automatically
attempts the reconnection and everything returns to normal after successful reconnection.
For natural-scheduled calculations, calculations might be missed even if the values are
buffered on the PI Interface node. When PI Server restarts, the ACE Scheduler needs to re-
signup all the trigger tags with the PI Update Manager. The buffered events sent to PI Server
before this signup do not trigger any calculations. In addition, because there is a limit on the
number of items on the execution queue that is associated with an ACE Context, calculations
might be missed if the number of events received once by the ACE Scheduler exceeds this
limit. This limit can be set via the MaxQueuesize property. If the trigger tags are on multiple
PI Servers, events from other PI Server continue to trigger calculations. When the inactive PI
Server restarts, all events from this PI Server before the last execution time are considered
out-of-order and might be ignored, unless the tag is one of the automatic recalculation
triggers. Thus, calculations might be missed.
Security
In order to retrieve/write data from/to a PI Server, appropriate security should be established
between an ACE Executable and the PI Server. ACE uses the PI trust login to connect to PI
Servers, and users need to establish appropriate trusts on PI Servers for various ACE
components. A brief discussion on how to set up a trust relation is in Security (page 24) and
the detailed discussion can be found in the PI Server System Management Guide.
Running ACE on a Cluster

Running ACE on a cluster is supported. The following scenarios are supported:
ACE accesses data on a PI Server that runs on a cluster but the ACE Scheduler is not
installed on a cluster.
The ACE structural information is stored on a PI Server that runs on a cluster but the
ACE Scheduler is not installed on a cluster.
The ACE Scheduler is installed on a cluster.
Because PI Server supports only the cold failover (that is, the server shuts down and restarts
during a failover), the first two cases are identical to restarting a PI Server. During the
failover, the ACE calculations might not be able to access PI data. This can result in Calc
Failed for output tags.
To install and run the ACE Scheduler on a cluster:

Advanced Topics
1. Install the ACE Scheduler on a shared disk on both cluster nodes as follows: Install ACE
on the current node; fail over to the other node and install ACE again.
2. The following step is only necessary if you run the ACE Scheduler on the same PI Server
where the ACE structure information is stored: Add the ACE Scheduler to the cluster
group for PI Server and make it depend on pibasess. Note that this dependence only
applies to failover and differs from the service dependence. Do not make the ACE
Scheduler service dependent on the pibasess service. One potential issue with this
resource dependence is that when pibasess is shut down, the ACE Scheduler is also shut
down. However, the ACE Scheduler is not restarted automatically when pibasess is
restarted. This can be the case if you run a backup script that shuts down pibasess. If this
is the case, make sure to start the ACE Scheduler afterwards.
3. Register all the ACE Executables on both nodes.
4. Make sure the target PI Server to start calculations on both nodes is identical.
Note: Always use the Microsoft Cluster Administrator to manage clustered resources
(starting, stopping, setting dependencies, and so on), after the services are
configured as cluster resources. Not following this rule can inadvertently trigger
the clustered resources to fail and potentially cause an unnecessary cluster group
failover.
Testing a Running ACE Module

Testing an ACE Module (with the Wizard) compiles the ACE Executable to which the ACE
Module belongs. If the Scheduler has already started the ACE Executable on the same
machine, the compilation fails, as the .exe file cannot be replaced. There are two solutions to
this problem. One is to take the ACE Executable out of service, test its ACE Modules, and
resume calculation for the ACE Executable.
The other method, which does not take the ACE Executable out of service, is:
1. Set the version compatibility to No Compatibility for the ACE Executable project within
Visual Basic.
Note: To do this: from the main menu, click Project and then ProjectName
Properties. On the Project Properties dialog, click the Component tab
and select No Compatibility under Version Compatibility.
2. Proceed to test any ACE Module within the ACE Executable.

3. When finished, take the ACE Executable out of service via the ACE Manager.
4. Set the version compatibility back to Project Compatibility with the .exe file for the ACE
Executable.
5. Compile the project (File > Make).
6. Resume calculation for the ACE Executable. The changes would become effective.
70
Chapter 7
ACE Library Functions

The ACE library functions are implemented as methods or properties of the object
PIACEPoint, or as shared (or static) routines. Every PI tag is declared as a PIACEPoint object
within an ACE Module. When an error occurs, all ACE library functions log the error and
most of them return Null or Nothing for ACE 1.x and raise an error for ACE 2.x.
GetLastPIACEError retrieves the last error generated by a library function.
After discussing different formats that can be used for a timestamp argument and the error
handling difference between ACE 1.x and 2.x, most of functions in the ACE library are
described. We recommend that the users do not use others that are not described here. Either
they have not been implemented or their behaviors may change.
Timestamp
Many functions take a timestamp as an argument. Unless otherwise specified, any of the
following formats can be used:
A time/date string in Microsoft formats
(i.e., "2-10-2001 1:12pm")
UTC seconds since 1-1-1970
A Date representing a local time on the current system
A string representing the relative PI time format with respect to the scheduled execution
time or the current time (e.g., +1h), the absolute PI time format (e.g., t), and the
combined PI time format (e.g., *-1h).
If a timestamp is specified as a date or string, ACE converts it into UTC seconds since 1-1-
1970 and automatically adjusts for time zone, daylight savings, and clock drift. Thus, the VB
function Now() represents the exact same time instance on all PI Servers, regardless of their
time zones.
Note: The clock drift is the time difference between a PI Server and the machine running
the ACE Scheduler. It is estimated periodically and is accurate at most within 1
second. It cannot be more than 15 minutes (either faster or slower). A clock drift of
more than 15 minutes may results in incorrect time conversion.
When specifying the relative PI time format, the scheduled execution time is used as the
reference time for all PIACEPoint methods and properties while the current time is used as
the reference time for all standalone functions. For example, MyTag.Value("-2h") would
retrieve the archive value two hours before the scheduled execution time while DaySec("-
2h") would determine the seconds since the beginning of the day two hours before the

current time. If this is not desirable, the function ParseTime can be used to set the reference
time explicitly. For example, DaySec(ParseTime("-2h", mdblExeTime), where
mdblExeTime is the module-level variable representing the scheduled execution time, would
determine the seconds since the beginning of the day two hours before the scheduled
execution time.
When specifying the absolute or combined PI time format, no reference time is used and the
expression is evaluated with respect to the current time. Since the scheduled execution time
may differ from the current time, MyTag.Value("-2h") differs from MyTag.Value("*-
2h"). The former retrieves the archive value two hours before the scheduled execution time
while the latter retrieves the archive value two hours before the current time.
For all ACE functions and methods returning a timestamp (or a PITime object), the
timestamp is not adjusted for the clock drift. For example, the timestamp returned by the
PrevEvent method corresponds to the actual timestamp stored in the PI archive.
Error Handling
Discussing general error handling is beyond the scope of this manual. We discuss the relevant
topics specific to ACE below.
Visual Basic 6 supports the Null propagation (i.e., the result of an operation involving Null is
Null). ACE 1.x suppresses and logs most of the errors and appropriately handles Null when
sending data to PI. The advantage of this design is that one failed calculation does not affect
other calculations in the same ACE Module. However, Visual Basic.NET does not support
the Null propagation. Furthermore, any operation involving Null would result in an error.
Thus, this ACE 1.x design is not useful in Visual Basic .NET. Instead of returning Null, ACE
2.x raises an error. So, it is important to trap errors properly in calculations developed in
Visual Basic .NET.
If your calculation does not handle an error or exception, ACE would automatically trap and
log its message. By default, ACE writes Calc Failed to any output whose value is not set. You
can change this behavior by specifying a different bad value substation option for an output.
To support the Null propagation, most of the methods return Variant in ACE 1.x. This is
assumed unless specified otherwise. With ACE 2.x, the return types are more precise (e.g.,
Double instead of Variant).
PIACEPoint Methods and Properties

The methods and properties can be functionally categorized into the following groups.
Archive Summary
Avg
FindEQ, FindGE, FindGT, FindLE, FindLT, FindNE
Is Trigger
Max, Min
Mean
72
PctGood
Range
StDev
TimeEQ, TimeGE, TimeGT, TimeLE, TimeLT, TimeNE
Total
Alarm
AlmAckStatus
AlmCondition
AlmCondText
AlmPriority
Point Attribute
Desc
DigState
EU
ExDesc
GetAttribute
PointType
Source
Span
TypVal
Zero
Snapshot or Archive Value
IsGood
NextVal, NextEvent
PrevVal, PrevEvent
Value
Values
Identification and Others
ExeTime
IsAlias
IsSet
IsTrigger
ResultTimestamp
SendDataToPI
Server
SetTag
StateNo
Tag
TagID

Note that some methods or properties are not described here. Either they have not been
implemented or their behavior may change. Be extra careful when using them.
AlmAckStatus
Returns the acknowledgement status code for an alarm tag. Possible return values are: 0-
acknowledged, or no alarm; 1 unacknowledged; 2-missed alarm.
Syntax
AlmAckStatus()
Arguments
None.
Exceptions
For non-alarm tags, Null is returned or an error is raised.
Example
CurrentAckStatus = alarmtag.AlmAckStat
AlmCondition
Returns the condition code for an alarm state.
Syntax
AlmCondition()
Arguments
None.
Exceptions
Example
CurrentAlarmCondition = alarmtag.AlmCondition
AlmCondText
Returns the string for the condition of an alarm state.
Syntax
AlmCondText()
74
Arguments
None.
Exceptions
Example
CurrentConditionString = alarmtag.AlmCondText
AlmPriority
Returns the priority of an alarm state. Priorities are positive integers. Priority 0 is an alarm
that is never unacknowledged.
Syntax
AlmPriority()
Arguments
None.
Exceptions
Example
CurrentPriority = alarmtag.AlmPriority
AdjustClockOffset
Sets and returns the flag on whether to adjust all time arguments for the clock drift between
the ACE server and the PI Server. The default value is True.
Syntax
AdjustClockOffset [ = Boolean]
Arguments
None.
Remark
When retrieving PI events, carrying out summary calculations, or sending data to PI, a time
argument, be it explicitly specified or implicitly set to its default value, may be corrected for
the clock drift between the ACE server and the PI Server.
The clock drift is defined to be the difference in UTC seconds between two clocks at the
same time (i.e., it does not depend on time-zone difference between the two clocks). Note that

this flag does not affect the events retrieved from PI (e.g., via PrevEvent and PIValues
methods) as they are not corrected for the clock drift.
Example
myTag.AdjustClockOffset = False
ArcMode
The ArcMode sets and returns the archive mode. The default value is dmErrorDuplicates.
Syntax
ArcMode [ = DataMergeConstants]
Arguments
None.
Remark
The DataMergeConstants enumeration has these values:
dmErrorDuplicates
dmInsertDuplicates
dmReplaceDuplicates
dmReplaceOnlyDuplicates
Currently only dmInsertDuplicates and dmReplaceDuplicates are supported. All
other values are treated as dmErrorDuplicates.
With ArcMod set to dmInsertDuplicates, no archive value is replaced.
With ArcMode set to dmReplaceDuplicates, an archive value with the same timestamp is
replaced. Setting ArcMode to dmReplaceDuplicates bypasses the exception reporting
process and may result in significant performance degradation. Use it with care.
Example
myOutputTag.ArcMode = dmReplaceDuplicates
Avg
Determines the time-weighted average of archived values for the point over a given time
interval.
Syntax
Avg(Starttime, Endtime, [PctGood])
Arguments
Starttime: Timestamp for the beginning of the time range.
76
Endtime: Timestamp for the end of the time range.

PctGood (optional): Minimum time percentage over the given time range, that the points
archived values must be good.
Exception
If the point has no good values or the percentage of good values in the specified time interval
is less than PctGood, the method returns Null or an error.
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 the
percentage of the values that are good.
Examples
TempVar = Sinusoid.Avg(Now-0.1, Now)
TempVar = Sinusoid.Avg(Now-0.1, Now, 80)
Desc
Returns the descriptor for a point.
Syntax
Desc()
Arguments
None
Examples
TempVar = sinusoid.Desc
TempVar = cdm158.Desc
DigState
Returns the digital state object for a specified string if successful and Nothing if otherwise.
Syntax
DigState(DigitalStateString) as DigitalState
Argument
DigitalStateString: String corresponding to a digital state.
Remarks
For a digital point, the digital state is obtained based on first the digital state table for the
point and, if not found, the system digital state table. For non-digital points, the digital state is
generated based on the system digital state table. The digital state object has two properties:
Code and Name; the default property is Name.

If there is no digital state corresponding to the specified string, then Nothing is returned.
Examples
TempVar = sinusoid.DigState("Shutdown")
' TempVar equals the string "Shutdown"
Set TempVar = cdm158.DigState("Auto")
EU
Returns the string for the points engineering unit.
Syntax
EU()
Arguments
None.
Examples
TempVar = sinusoid.EU
TempVar = cmd158.EU
ExDesc
Returns the points extended descriptor.
Syntax
ExDesc()
Arguments
None.
Examples
TempVar = sinusoid.ExDesc
TempVar = cmd158.ExDesc
ExeTime
Sets and returns the current execution time in UTC seconds.
Syntax
ExeTime() [= UTCSeconds] As Double
Arguments
None.
78
Caution
The execution time is automatically set when calculations are carried out and is used as the
default timestamp for retrieving data from and writing data to PI. Rarely should the users set
its value.
Remark
In general, the current execution time differs from the current time (i.e., the Now() function in
Visual Basic). Some of the reasons include the delay of calculations due to resource
constraints. For natural-scheduled calculations, the execution time, which equals to the event
time for a PI tag, generally differs from the time when an ACE Module is notified about this
new event. Furthermore, there is an intentional latency to execute calculations after receiving
an event.
Examples
TempVar = Cdm158.ExeTime
TempVar = Sinusoid.ExeTime - 60
FindEQ, FindGE, FindGT, FindLE, FindLT, FindNE
Finds the first time, within a specified time range, when an archive value for the point is
equal to, greater than and equal to, greater than, less than and equal to, less than, or not equal
to, a given value.
Syntax
FindEQ(Starttime, Endtime, Value) As PITime
FindGE(Starttime, Endtime, Value) As PITime
FindGT(Starttime, Endtime, Value) As PITime
FindLE(Starttime, Endtime, Value) As PITime
FindLT(Starttime, Endtime, Value) As PITime
FindNE(Starttime, Endtime, Value) As PITime
Arguments
Starttime: Timestamp for the beginning of the time range to search.
Endtime: Timestamp for the end of the time range to search. This time may be earlier than
Starttime; if so, the range is searched backwards.
Value: The value to search for. Must be an integer or real number, or character string
corresponding to a digital state.
Exceptions
If the point does not contain any value that meets the criteria, returns Nothing.
Remark
The default property for the PITime object is the UTC seconds.
Examples
TempVar = sinusoid.FindEQ(Now-1, Now, "Shutdown")

TempVar = sinusoid.FindGE(Now, Now-1, 55)
GetAttribute
Returns the specified attribute for the point.
Syntax
GetAttribute(AttributeName)
Argument
AttributeName: The name of the attribute (string) to return.
Exceptions
If the specified attribute does not exist for the point, returns Null or an error.
Examples
TempVar = sinusoid.GetAttribute("pointclass")
TempVar = cdm158.GetAttribute("ExDesc")
IsAlias
Returns True if the tag corresponds to a PIAlias and False otherwise.
Syntax
IsAlias() As Boolean
Argument
None.
IsGood
Returns True if a value is good and False otherwise.
Syntax
IsGood([TimeStamp])
Argument
TimeStamp (optional): If omitted, the current execution time is used.
Remark
A value is considered bad if it equals one of the system digital states. False is returned if the
point does not contain any value at or before the specified timestamp, or if the requested
event could not be retrieved from the Server. One should avoid using a boolean in arithmetic
80
as the behavior is implementation dependent. For example, True is converted to -1 in VB

while it is 1 for PE.
Examples
TempVar = Sinusoid.IsGood
TempVar = Cdm158.IsGood(Cdm158.ExeTime)
IsQuestionable
Sets or returns whether the current output value is questionable. The default is False (i.e., not
questionable).
Syntax
IsQuestionable [ = Boolean]
Arguments
None.
Remark
This flag is only applicable to output tags and its setting applies only to the current value. The
flag is reset to its default value (i.e., False) when the timestamp is reset.
Example
myOutputTag.IsQuestionable = True
IsSet
Determines if a PI value is annotated, substituted, or questionable.
Syntax
IsSet(QualityString, [TimeStamp])
Arguments
QualityString: A string but only the first character is considered. "a" for annotated;
"s" for substituted; and "q" for questionable. It is case-insensitive.
TimeStamp (optional): Timestamp. If omitted, the current execution time is used.
Example
TempVar = Sinusoid.IsSet("a")
IsTrigger
Returns True if the tag triggers the current calculation and False if otherwise.

Syntax
IsTrigger() As Boolean
Argument
None.
Remarks
A calculation may be triggered by multiple trigger tags. The function accesses a cache of one
hundred triggering events per tag. If the calculation is severely delayed (e.g., the calculation
has been triggered by the tag more than a hundred times but none of the calculations has been
executed), this function may return the wrong status.
Max, Min
Returns the maximum (or minimum) archive value of the point over a given time interval.
Syntax
Max(Starttime, Endtime, [PctGood])
Min(Starttime, Endtime, [PctGood])
Arguments
PctGood (optional): Minimum time percentage (double) over the given time range, that the
points archived values must be good.
Exceptions
If the point has no good values or the PctGood minimum is not met for the given time range,
returns Null or an error.
Examples
TempVar = Sinusoid.Max(Now-1, Now)
TempVar = Sinusoid.Min(Now-1, Now, 80)
Mean
Returns the average value of all archive events in the interval.
Syntax
Mean(Starttime, Endtime, [PctGood])
Arguments
Starttime: Starttime for the beginning of the time range.
82
Endtime: Endtime for the end of the time range.

PctGood (optional): Minimum time percentage over the given time range, that the points
Exceptions
Remark
Care should be taken when calling this method, as the events are not time-weighted. Use Avg
for time weighting.
Examples
TempVar = Sinusoid.Mean(Now-1, Now)
TempVar = Sinusoid.Mean(Now-1, Now, 80)
NextVal, NextEvent
Returns the value as variant or timestamp (as a PITime object) of the points next archive
event after a specified time.
Syntax
NextVal(TimeStamp)
NextEvent(TimeStamp) as PITime
Argument
TimeStamp: Timestamp.
Exceptions
If the point has no archive data after the specified time, NextVal returns Null or an error and
NextEvent returns Nothing or an error.
Remarks
NextEvent returns the timestamp as a PITime object. The default property for the PITime
object is the UTC seconds since 1-1-70. If you want to get the local date, use the LocalData
property. See the PI-SDK Reference Manual for details.
Examples
TempVar = Sinusoid.NextVal("1-1-2001 1:13AM")
TempVar = Cdm158.NextEvent(Now.AddDays(-0.1)).LocalDate
PctGood
Returns the percentage of time, over a given time period, that the points archived values are
good.

Syntax
PctGood(Starttime, Endtime)
Arguments
Endtime: Timestamp for the end of the time range
Exceptions
If an error occurs in retrieving values from archive, returns Null or an error.
Examples
TempVar = Sinusoid.PctGood(Now-1, Now)
TempVar = Cdm158.PctGood(Now-1, Now)
PointType
Returns the points type. Can be one of the following values:

6 Int16
8 Int32
11 Float16
12 Float32
13 Float64
101 Digital
102 Blob
105 String
Syntax
PointType()
Arguments
None.
Examples
TempVar = Sinusoid.PointType
TempVar = Cdm158.PointType
PrevVal, PrevEvent
Returns the value or timestamp of the points archive event before a specified time.
84
Syntax
PrevVal([TimeStamp])
PrevEvent([TimeStamp]) as PITime
Argument
Exceptions
If the point has no archive data before the specified time, PrevVal returns Null or an error and
PrevEvent returns Nothing or an error.
Remarks
Due to the exception reporting and compression, the last archived value generally differs
from the last snapshot value. PrevVal returns the previous archived value. The chapter on
Advanced Topics (page 63) discusses a method on how to obtain the last snapshot value.
Examples
TempVar = Sinusoid.PrevVal("1-1-01 1am")
TempVar = Cdm158.PrevEvent(Now-0.1).LocalDate
Set TempVar = Cdm158.PrevEvent
PutValue
Sends the value for an output tag to the PI Snapshot Subsystem. Users should not normally
attempt to call this method themselves.
Range
Returns the difference between the points maximum and minimum archive values during a
specified time interval.
Syntax
Range(Starttime, Endtime, [PctGood])
Arguments
Endtime: Timestamp for the end of the time range
PctGood (optional): Minimum time percentage over the given time range that the points
Exceptions
If the point has no good values or the time percentage of archive values for the specified time
range that is good is less than PctGood, returns Null or an error.

Examples
TempVar = Sinusoid.Range(Now-1, Now)
TempVar = Sinusoid.Range(Now-1, Now, 80)
RefreshAttribute
Refreshes tag attributes immediately.
Syntax
RefreshAttribute()
Arguments
None.
ResetCurrentValue
Resets the currently cached value for the point.
Syntax
ResetCurrentValue()
Arguments
None.
Remarks
For an input tag, the currently cached value is the snapshot or archive value retrieved when
the Value method is called or equals the last value set through the Value method. For an
output tag, the currently cached value is the last value set through the Value method.
The timestamp associated with the currently cached value equals either the execution time or
the last time specified for the Value method.
When the Value method is called with a different timestamp, the currently cached value is
automatically updated.
Examples
Debug.Print Sinusoid.Value
' 40 (for example)
Sinusoid.Value = Sinusoid.Value + 10
Debug.Print(Sinusoid.Value)
' 50
Sinusoid.ResetCurrentValue
Debug.Print(Sinusoid.Value)
' 40
86
ResultTimestamp
Returns the timestamp associated with the current value.
Syntax
ResultTimestamp As PITime
Arguments
None.
Remarks
This property applies to an output or input/output point only and returns Nothing for an input
point. In the former case, it returns the timestamp associated with the last value set. If the last
value set has no timestamp specified, it defaults to ExeTime. The timestamp is overwritten
whenever you set a new value.
SendDataToPI
Sets and returns if the current value for the point should be sent to PI.
Syntax
SendDataToPI() [= True (or False)]
Arguments
None.
Remark
The default is to send every value for an output tag to PI. Setting this value applies only to
one execution time.
Examples
TempVar = Cdm158.SendDataToPI
Sinusoid.SendDataToPI = False
Server
Returns the server name where the point is defined.
Syntax
Server()
Arguments
None.

Example
TempVar = Cdm158.Server
SetTag
Sets the context and tag alias and returns True if successful and False if otherwise.
Syntax
SetTag(Context, AliasName, [AliasType])
Arguments
Context: A string consisting of the full PIModule path or the server name. The delimiter
separating two PIModules is a backslash ( \ ). For example:
\\MyPIServer\ParentPIModule\ChildModule.
AliasName: A string for a tag or PIAlias. If Context is a PIModule path, then the tag
corresponding to the PIAlias in the PIAliases collection of the specified PIModule is used. If
no such PIAlias exists, the tag whose name is AliasName is used. If no tag exists, then no tag
is used and an error is logged.
AliasType (optional): Is the alias used as an input, output, or both? The default is as an
input.
Remark
When defining a PIACEPoint object, it is necessary to call the SetTag method so that other
calls can be resolved.
Examples
Dim MyInputTag As PIACEPoint
Set MyInputTag = New PIACEPoint
MyInputTag.SetTag "MyPIServer", "MyInputTag"
Dim MyOutputTag As New PIACEPoint
MyOutputTag.SetTag "MyPIServer\MyPIModule", "MyOutputTag",
taTagAliasAsOutput
Source
Returns the PI SDK string point source.
Syntax
Source()
Arguments
None.
Example
TempVar = Sinusoid.Source
88
Span
Returns the points span.
Syntax
Span()
Arguments
None.
Example
TempVar = Sinusoid.Span
StateNo
Returns the digital state code for a specified string.
Syntax
StateNo(DigitalStateString)
Argument
DigitalStateString: String for a digital state.
Remarks
The digital state is obtained based on the digital state table for the point. If the digital state
table does not contain a digital state with the corresponding string, the method returns Null or
an error. For non-digital points, the method always returns Null or an error.
Examples
TempVar = Sinusoid.StateNo("Calc Failed")
' = Null if Sinusoid is a numeric point
' or an error is raised
TempVar = Cmd158.StateNo("Manual")
StDev
Returns the time-weighted standard deviation of archive values for the point over a given
time interval.
Syntax
StDev(Starttime, Endtime, [PctGood])
Arguments

Exceptions
If the point has no good values or the PctGood minimum is not reached for the given time
range, returns Null or an error.
Examples
TempVar = Sinusoid.StDev(Now - 1, Now)
TempVar = Sinusoid.StDev(Now - 1, Now, 80)
Tag
Returns the tag name for the point.
Syntax
Tag()
Arguments
None.
Example
TempVar = Cdm158.Tag
TagID
Returns the tag ID for the point.
Syntax
TagID()
Arguments
None.
Example
TempVar = Cdm158.TagID
TagUsedAsType
Returns the tag used as type (i.e., as Input, Output, or Both).
Syntax
TagUsedAsType()
90
TimeEQ, TimeGE, TimeGT, TimeLE, TimeLT, TimeNE
Finds the total time in seconds, within a specified time range, when archive values for the
point are equal to, greater than and equal to, greater than, less than and equal to, less than, or
not equal to, a given value.
Syntax
TimeEQ(Starttime, Endtime, Value)
TimeGE(Starttime, Endtime, Value)
TimeGT(Starttime, Endtime, Value)
TimeLE(Starttime, Endtime, Value)
TimeLT(Starttime, Endtime, Value)
TimeNE(Starttime, Endtime, Value)
Arguments
Value: The value to search for. Must be an integer or real number or digital state (character
string).
Exceptions
If the point does not contain any value that meets the criteria, returns Null or an error.
Remark
TimeGE, TimeGT, TimeLE, and TimeLT interpolate between archive events, if necessary,
to find the times when the point crossed the given value.
Examples
TempVar = Cdm158.TimeEQ(Now-1, Now, "Manual")
TempVar = Sinusoid.TimeGE(Now, Now-1, 55)
Total
Returns the totalized value (time integral) in unit per day of archive values for the point over
a given time interval.
Syntax
Total(Starttime, Endtime, [PctGood])
Arguments

Exceptions
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 the percentage of the values that are
good.
Remarks
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 should 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 Total 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.
Example
TempVar = sinusoid.Total(Now, Now-1)
TypVal
Returns the points typical value.
Syntax
TypVal()
Arguments
None.
Example
TempVar = sinusoid.TypVal
Value
Sets or returns the value at a specified time for the point. This is the default property for the
PIACEPoint object.
Syntax
Value([TimeStamp]) (= SOMEVALUE or SOMEObject)
Argument
92
Remarks
For an output tag, this property does not retrieve data from PI. For an input tag, it always
retrieves data from PI the first time it is called and the data is cached. Since this property can
be used to store any intermediate value, its value may differ from the snapshot or archive
value. The following example illustrates this point:
Dim TimeStamp As Date
TimeStamp = Now
Debug.Print ACEPoint.Value(TimeStamp)
' 23.45 (for example)
ACEPoint.Value(TimeStamp) = ACEPoint.Value(TimeStamp) + 10
Debug.Print ACEPoint.Value(TimeStamp)
' 33.45
Examples
TempVar = Cdm158
TempVar = Cdm158.Value
TempVar = Cdm158.Value(Now 0.1)
Set Cdm158 = SomeDigitalStateObject
Cdm158.Value = TempVar
Cmd158.Value("1-1-2001 1:13AM") = TempVar
Values
Returns all events for a specified time range from the archive as a PIValues collection.
Syntax
Values(StartTime, EndTime, BoundaryType) as PIValues
Arguments
BoundaryType: An enumerated type (0, 1, 2, and 3) that determines how the boundary
points are returned:
0 to return boundary values at or within the time range specified.
1 to return boundary values at or outside the time range specified.
2 to return boundary values interpolated to the start and end times specified.
3 to boundary values at or within the time range specified for points with the Step
attribute set (i.e., Step = 1) and to return boundary values interpolated to the
start and end times specified for points without the Step attribute set (i.e., Step =
0).
Example
Set TempVar = Sinusoid.Values(Now-1, Now, 2)

Zero
Returns the points zero.
Syntax
Zero()
Arguments
None.
Example
TempVar = Sinusoid.Zero
Static (or Shared) Functions

The standalone functions can be functionally grouped into the following categories:
Time
BOD
BOM
BONM
DaySec
FONM
IsDST
Noon
ParseTime
PIDay, PIHour, PIMinute, PIMonth, PISecond, PIWeekDay, PIYear
YearDay
Errors/Messages
ClearLastPIACEError, GetLastPIACEError, LogLastPIACEError
LogPIACEMessage
Math
ACos
ASin
Atn2
Avg
Cosh
Curve
Frac
InRange
InSet
Log10
94
Max
Median
Min
Poly
PStDev, SStDev
Sinh
Tanh
Total
Trunc
String
Char
Compare
Concat
Other
AdjustClockDrift
DigState
ACos
Returns the inverse (or arc) cosine of a number.
Syntax
ACos(x)
Argument
x: A real number between -1.0 and 1.0.
Exceptions
If x is a number smaller than -1.0 or greater than 1.0, an error is raised.
AdjustClockDrift
Set and return if ACE should adjust clock drifts between the ACE machine and PI servers.
Syntax
AdjustClockDrift = True or False
Remarks
The default value for AdjustClockDrift is True. It applies to all calculations within an ACE
Executable. One should be careful when changing the default value: If the ACE Machine is
ahead of a PI Server, you may try to retrieve a value in the future and may get the No Data
event.

ASin
Return the inverse (or arc) sine of a number.
Syntax
ASin(x)
Arguments
x: A real number between -1.0 and 1.0.
Exceptions
If x is a number smaller than -1.0 or greater than 1.0, an error is raised.
Atn2
Returns 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 (x, y) and the
origin, the angle between that line and the x-axis is the inverse tangent of y/x.
Syntax
Atn2(y, x)
Arguments
y: A number representing the y-axis coordinate.
x: A number representing the x-axis coordinate.
Examples
Atn2(0,1) (returns 0)
Atn2(1,0) (returns /2)
Avg
Returns the average of all the arguments.
Syntax
Avg(x1, x2, ., xn)
Arguments
x1, ., xn: Real numbers.
96
Example
Avg(1.2, 2.3, 5.6)
BOD
Returns the timestamp for the midnight at the start of a day.
Syntax
BOD([Timestamp])
Argument
Timestamp (optional): Timestamp. If omitted, the current time is used.
Examples
TempVar = BOD
TempVar = BOD(Now)
BOM
Returns the timestamp for the midnight at the beginning of the month.
Syntax
BOM([Timestamp])
Argument
Examples
TempVar = BOM
TempVar = BOM(Now)
BONM
Returns the timestamp for the midnight at the beginning of the next month.
Syntax
BONM([Timestamp])
Argument
Examples
TempVar = BONM
TempVar = BONM(Now)

Char
Returns a string from ASCII character codes.
Syntax
Char( n1, n2, , nn )
Arguments
n1, n2, ..., nn: Integers representing ASCII codes.
Exceptions
If an argument is not a number, an error is raised.
Example
Char(65) returns "A"
Char(80, 73) returns "PI"
Char(6 * 9) returns "6"
ClearLastPIACEError, GetLastPIACEError, LogLastPIACEError
Clears, gets, and logs the last error message generated by ACE library functions.
Syntax
ClearLastPIACEError()
GetLastPIACEError()
LogLastPIACEError(Number, Location, [Description], [Expression])
Arguments
Number: Integer. Error number.
Location: String. Location where the error occurs.
Description (optional): String. Detailed error description.
Expression (optional): String. Offending expression causing the error.
Examples
Dim TempVar As String
TempVar = GetLastPIACEError
LogLastPIACEError -12034, "MyProgram.MySub", "Invalid number:
Should be between 0 and 5", "intTest = 6"
ClearLastPIACEError
Compare
Compares two strings and returns True if they are the same and False if otherwise. "*" and
"?" in the second string are treated as wild characters.
98
Syntax
Compare(str1, str2 [,casesen])
Arguments
str1, str2: Strings. Str2 may contain wild characters.
Casesen (optional) : Boolean flag indicating if the comparison is case sensitive.
Exceptions
No character in str1 is treated as wild.
Examples
Compare("?","a") returns False
Compare("What","wh") returns False
Compare("What","wha?") returns True
Compare("What","wh*") returns True
Compare("What","wh*", 1) returns False
Concat
Concatenates two or more strings.
Syntax
Concat(s1, s2, ., sn)
Arguments
s1, ., sn: Strings.
Example
Concat("shut", "down") returns "shutdown"
Cosh
Returns the hyperbolic cosine of a number.
Syntax
Cosh(x)
Argument
x: A number.
Examples
Cosh(.9)
Cosh(1)

Curve
Returns the y value of a curve given the x value.
Syntax
Curve( x, xs, ys )
Arguments
x: A numeric value.
xs, ys: Arrays of numeric values. The dimensions for both arrays must be the same.
Remarks
The function does not extrapolate and the xs should be sorted with strictly increasing order.
Returns Null or an error if there is at least one non-numeric value in xs or ys.
Example
TempVar = Curve(1, Array(0,1,2), Array(2,3,4))
DaySec
Returns the number of seconds since the midnight.
Syntax
DaySec([Timestamp])
Argument
Examples
TempVar = DaySec(Sinusoid.ExeTime)
TempVar = DaySec(Now)
TempVar = DaySec
DigState
Returns the digital state corresponding to a character string representing the digital state.
Syntax
DigState(State, [PIServer]) As DigitalState
Arguments
State: A string representing a digital state.
100
PIServer (optional): The PI Server name whose system digital state table is searched for
the specified digital state. The default is the default PI Server from the PISDK known servers
table.
Exceptions
If the character string does not represent a digital state in the system table, returns Nothing.
Examples
Set MyDigState = DigState("digitalstring")
Set MyDigState = DigState("digitalstring", "MyPIServer")
FONM
Returns the timestamp for the midnight at the first of the next month.
Syntax
FONM([Timestamp])
Argument
Examples
TempVar = FONM
TempVar = FONM(Now)
Frac
Returns the fractional part of a real number.
Syntax
Frac(x)
Arguments
x : A number.
Examples
Frac(1.1)
Frac(-2.3)
GetPIModuleFromPath
Gets the PIModule object for a given path below a root PIModule.
Syntax
GetPIModuleFromPath(Path, [RootPIModule]) as PIModule

Arguments
Path: String indicating PIModule path. The format should be
[ServerName\]PIMod1\PIMod2\\PIModN.
RootPIModule (optional): The root PIModule object. If missing, Path should contain a
server name.
Examples
Set TempVar =
GetPIModuleFromPath("localhost\%OSI\Aquariums\Aquarium1")
Set TempVar = GetPIModuleFromPath("Aquariums\Aquarium1",

RootPIModule)
InRange
Determines if a value is in the specified range.
Syntax
InRange(Value, LowerBound, UpperBound)
Arguments
Value, LowerBound, Upperbound: Numbers.
Remark
If LowerBound is larger than UpperBound, their values are switched.
InSet
Determines if a value (a number or string) equals to the specified set of values.
Syntax
InSet(Value, x1, , xn)
Arguments
Value, x1, , xn: Numbers or strings.
Examples
InSet(1, "1", 2, 3) returns True
InSet("3", 1, 2, 3) returns True
InSet("What?", "about", 1, 2) returns False
102
IsDST
Determines if a timestamp is in a daylight saving time (DST) period on the local machine.
Returns 1 if the time is in a DST period, 0 if the time is not in a DST period, and -1 if the
time is invalid.
Syntax
IsDST(Timestamp)
Argument
Timestamp: Timestamp.
Exceptions
If the argument is not a time value, an error condition is returned.
Examples
IsDST("*")
IsDST("*-182.5d")
IsDST(1021914442) UTC seconds
Log10
Returns the common (base-10) logarithm of a positive number.
Syntax
Log10(x)
Argument
x: A positive number.
Exceptions
If x is zero or negative, an error is raised.
LogPIACEMessage
Logs a message to the PI message system.
Syntax
LogPIACEMessage(MessageType, Message, FullACEContextPath)
Arguments
MessageType: Type of message to be sent and the relevant ones are mlError, mlWarning,
mlChange, and mlUserMessage.
Message: A message string.

FullACEContextPath: Full ACE Context path. Should be set to the module-level

variable mstrRegisteredName within the ACE Module.
Example
LogPIACEMessage(mlUserMessage, "This is a test", MyBase.Name)
Max
Returns the maximum of arguments.
Syntax
Max(x1, x2, ., xn)
Arguments
x, ., xn: Numbers.
Remark
Non-numerical arguments are ignored in the evaluation. An error may be raised if there is no
numeric argument.
Median
Returns the median (middle) value of all arguments.
Syntax
Median(x1, x2, ., xn)
Arguments
x1, ., xn: Numbers.
Remark
If the number of arguments is even, the average of the two middle values is returned.
Exceptions
If an argument is not a number, an error may be raised.
Examples
Median(1) returns 1
Median(1, 2) returns 1.5
Median(1, 2, 5) returns 2
Min
Returns the minimum of arguments.
104
Syntax
Min(x1, x2, ..., xn)
Arguments
x1, ..., xn: Numbers.
Remark
Non-numerical arguments are ignored in the evaluation. An error may be raised if there is no
numeric argument.
Noon
Returns a timestamp for the noon on the day of a given timestamp.
Syntax
Noon([Timestamp])
Argument
Examples
TempVar = Noon
TempVar = Noon(Sinusoid.ExeTime)
ParseTime
Returns a PITime object for a time, absolute PI time, or relative PI time.
Syntax
ParseTime(TimeString, [RelativeTimeString])
Arguments
TimeString: A timestamp string.
[RelativeTimeString] (optional): A relative timestamp string. If omitted, the current
time is used.
Examples
ParseTime("14-Dec-97")
ParseTime("t")
ParseTime("-1h", Now)
ParseTime("-1h", "*")

PIDay, PIHour, PIMinute, PIMonth, PISecond, PIWeekDay, PIYear
Returns the day, hour, minute, month, second, weekday, or year of a timestamp.
Syntax
PIDay([Timestamp])
PIHour([Timestamp])
PIMinute([Timestamp])
PIMonth([Timestamp])
PISecond([Timestamp])
PIWeekDay([Timestamp])
PIYear([Timestamp])
Argument
Examples
TempVar = PIMinute
TempVar = PIDay(Now)
Poly
Returns the result of the polynomial .
Syntax
Poly(x, Coefficients)
Arguments
x: A numeric value.
Coefficients: Array of coefficients. All elements should be numeric.
Exceptions
If x or any coefficient is not numeric, returns Null or an error.
Examples
TempVar = Poly(1.2, Array(0,0.5,2))
(i.e., 0 + 0.5 * 1.2 + 2 * 1.22)
PStDev, SStDev
Returns the population or sample standard deviation of two or more values.
Syntax
PStDev(xs)
SStDev(xs)
106
Argument
xs: Array of numbers, timestamps, or time periods, but all must be the same.
Exceptions
Bad values are ignored in computing the standard deviations. If all values are bad, returns
Null or an error.
Remark
The population standard deviation of a population x1, ..., xn is
where is the mean of the arguments, i.e., xi / n.

The sample standard deviation of a sample x1, ..., xn is equal to
where is the sample mean, i.e., xi / n.
Examples
TempVar = PStDev(Array(1,2,3,4))
TempVar = SStDev(Array(Now, Now-1, Now-0.5))
Sinh
Returns the hyperbolic sine of a number.
Syntax
Sinh(x)
Argument
x: A number.
Tanh
Returns the hyperbolic tangent of a number.
Syntax
Tanh(x)
Arguments
x: A number.

Total
Returns the sum of all arguments.
Syntax
Total(x1, x2, ., xn)
Arguments
x1, x2, ., xn: Numbers
Exceptions
If an argument is not a number, an error is raised.
Trunc
Returns the truncation of a number or time to the next lower unit.
Syntax
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, 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).
Remark
The largest value smaller than x which is an integer multiple of unit is returned. Returns Null
or an error if x is a string or unit is of wrong type.
Examples
TempVar = Trunc(1.2) = 1
TempVar = Trunc(3.3, 2) = 2
YearDay
Returns 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.
Syntax
YearDay([Timestamp])
Argument
108
Examples
TempVar = YearDay
TempVar = YeadDay(Now)

Chapter 8
Troubleshooting
ACE Scheduler Does Not Start
Timeout Version
Some ACE install kits (for example, beta and demo versions) are distributed with a timeout.
To find out the timeout date for the ACE Scheduler, select the file piacescheduler.exe
located in the directory ..\ACE\Scheduler, click Properties and select the Version tab.
For a timeout version, you should see the following Comments:
This is a timeout version (Timeout Date).
Multiple Instances Not Allowed
Only one instance of the ACE Scheduler can be run against a PI 3.3 Server. You can find out
if one instance of the ACE Scheduler has already been started on another machine via the
ACE Manager. For example, the following figure shows that an instance of the ACE
Scheduler was started against the PI Server localhost on the machine named AlexZheng.
No other instance of the ACE Scheduler can be started against the PI Server localhost.

Troubleshooting
Figure 9 1 Status and Location of ACE Scheduler
While the location of the ACE Scheduler is always accurate, the actual status of the ACE
Scheduler may be incorrect if the ACE Scheduler was shut down abnormally (e.g., due to
power outage). You can find out if the ACE Scheduler is running on the indicated machine in
the task manager by looking for the process piacescheduler.exe. If the status of the ACE
Scheduler displayed in the ACE Manager is incorrect, you can correct it by starting and
stopping the ACE Scheduler on the machine displayed in the ACE Manager.
ACE Context Is Not Running

An ACE Context can only be started if all of the following conditions are met:
The ACE Scheduler is running.
The ACE Scheduler has read/write privileges to the default PI Server. If not, the
following error appears in the PI message log on the machine where the ACE Scheduler
is running:
Error number: 10063
Location: PIACESchedule.StartServer
Description: The ACE Scheduler does not
have the write access to PI Module Database.
Scheduling information for the ACE Context has been specified.
The ACE Executable to which the ACE Context belongs is properly registered on the
computer where the ACE Scheduler is running. Make sure that the .exe file for the ACE
Executable is there, that all the references that the ACE Executable uses are properly
installed, and that the ACE Executable is registered (double-click the .exe file or enter
ACEExeName register at a command prompt). See Example 4 - Deploying ACE
Calculations (page 19) for details.
112
No Data Written To PI Tag
Its status and the status of the ACE Module and ACE Executable to which it belongs are
not Out Of Service, Error, or Terminated. If any status is Out Of Service, you can change
it to Off. If any status is Error, investigate the cause before changing its status to Off. If
the status for the ACE Context is Terminated, it means that the calculations took longer
than the allowed limit and were terminated by the ACE Scheduler. Examine whether that
calculation time is normal. If it is normal, you can increase the calculation limit for the
ACE Context via the PI Module Database Editor. Change the property Calculationlimit
in %OSI\ACEExecutable\ExeName\ModuleName\Context.
No Data Written To PI Tag

The following are possible causes:
The ACE Context is not running. No data is written to any of the output tags in the ACE
Context.
The tag does not exist. To check this, the ACE Context in the ACE Manager and then
click Tag > List. All invalid tags are highlighted red.
The security level for the tag is invalid. In this case, the following error appears in the PI
message log on the machine where the ACE Scheduler is running:
[-10401] No Write Access - Secure Object
Because ACE writes data to PI Server using exception reporting, it is possible that no
data are sent to PI because the values do not pass the exception tests.
Skipped Calculations
As discussed earlier, when under resource limitations, ACE skips calculations to keep up.
There are other cases where calculations might appear to be skipped:
The output values do not pass exception reporting.
The output values are compressed out.
For natural-scheduled calculations, the trigger events do not arrive because of update
manager list overflow. In this case, increase the timeout parameters MaxUpdateQueue
and/or TotalUpdateQueue on the trigger tags PI Server. See the PI Server Reference
Guide for details on how to change timeout parameters.
Incorrect Output Timestamp

The output timestamp is set by a PI Server clock (for clock-scheduled calculations) or a
trigger-event time (for natural-scheduled calculations). The ACE Scheduler periodically
estimates the clock drift between its machines clock and a PI Server clock. The estimate is at
most accurate within one second and can be worse if the call to determine the PI Server time
takes excessively long to complete (for example, because network problems). This can result
in an incorrect output timestamp.

Troubleshooting
The workaround is to run the ACE Scheduler on the PI Server whose tags receive incorrect
timestamps. Of course, this may not be possible if tags from multiple PI Servers experience
the same problem.
Cannot Find Error Messages

To prevent overloading the message log, only one message is logged if the same error occurs
repeatedly and consecutively within a function. For example, suppose if connection to a PI
Server is lost and MyTag.Value fails to retrieve an archive or snapshot value, the error
message is logged the first time. If the same error occurs again, the error message is not
logged.
Thus, you might need to go back in time in the message log to locate an error message.
ACE Calculations Take Excessive Amount of CPU
Module-Level Variables
Variables that do not change from calculation to calculation should be declared as module-
level variables and initialized only once. For example, the following code is inefficient
because the PIModule object that stores the PIProperties is created/destroyed every time the
calculation is carried out:
Public Sub ActualPerformanceEquations()
Dim CurrentPIModule As PIModule
Set CurrentPIModule =
GetPIModuleFromPath(mstrACEContext)
MyOutputTag = MyInputTag *
CurrentPIModule.PIProperties("Factor").Value
+ CurrentPIModule.PIProperties("Bias").Value
End Sub
A more efficient way is to define two module-level variables corresponding to the two
PIProperties and to initialize them the first time they are used.
Profiling
Typically, the following steps are involved in carrying out a calculation:

1. Initialization
2. Retrieval of data used in the calculation
3. Calculation
4. Sending data to PI
We will discuss how to profile performance in ACE 1.x. Similar procedures can also be done
in ACE 2.x.
114
ACE Calculations Take Excessive Amount of CPU
You can use the function timeGetTime to determine how long each step takes and the
function LogPIACEMessage to log this information. Both functions are already declared in
an ACE Module. The following example determines and logs the amount of time to initialize,
to retrieve data from PI, and calculate:
Public Sub ActualPerformanceEquations()
Dim lngStartTime As Long
Dim dblInputValue As Double
Dim dblFactor As Double
Dim dblBias As Double
Dim CurrentPIModule As PIModule
lngStartTime = timeGetTime
Set CurrentPIModule =
GetPIModuleFromPath(mstrACEContext)
dblFactor =
CurrentPIModule.PIProperties("Factor").Value
dblBias =
CurrentPIModule.PIProperties("Bias").Value
LogPIACEMessage mlUserMessage,
"Initialization takes " & timeGetTime
lngStartTime & " ms", mstrRegisteredName
dblInputValue = myInputTag
LogPIACEMessage mlUserMessage, "Data
retrieval takes " & timeGetTime
MyOutputTag = myInputTag * dblFactor + dblBias
LogPIACEMessage mlUserMessage, "Calculation
takes " & timeGetTime
End Sub
Often some network problems would cause Steps 2 and 4 to take excessively long. If the
majority of the time is spent doing the actual calculation, examine if the code could be
optimized. If not, consider upgrading the hardware and/or increase the calculation period for
clock-scheduled calculations.

Appendix A
Differences between ACE for VB6 (ACE 1.x) and

ACE for VB.NET (ACE 2.x)
The major differences between ACE for VB6 (ACE 1.x) and ACE for VB.NET (ACE 2.x)
are as follows:
Because of the significant differences in the integrated development environments (IDEs)
for VB6 and Visual Basic .NET 2005/2008/2010, OSIsoft provides two versions of the
ACE Wizard: PIACEWizard.dll for VB6, and PIACENetWizard.dll for Visual Basic
.NET 2005/2008/2010. However, the user interface and functionality of the two versions
are almost identical.
With ACE for VB6 (ACE 1.x), calculations are implemented in a COM class in an out-
of-process server (that is, VB6 ActiveX Exe project type). VB.NET does not support the
ActiveX Exe project type. Calculations developed with ACE for VB.NET reside in a
.NET class in a .NET Class Library assembly (with the .dll extension). Thus, there are
two ACE Schedulers (PIACEScheduler for VB6 and PIACENetScheduler for
VB.NET). Because a class library cannot be run by itself, it is hosted by an executable
named PIACEClassLibraryHost. PIACEClassLibraryHost is also invoked by the
ACE Wizard to debug calculations developed in VB.NET.
VB6 supports Null propagation (that is, the result of an operation involving Null is Null).
ACE for VB6 suppresses and logs most of the errors and appropriately handles Null
when sending data to PI Server. The advantage of this design is that the failure of one
calculation does not affect other calculations in the same class. However, VB.NET does
not support Null propagation. Furthermore, any operation involving Null results in an
error. Instead of returning Null, ACE for VB.NET raises an error.
ACE for VB.NET exposes all its calculations through a Web service.
ACE Scheduler for VB.NET is multi-threaded, while ACE Scheduler for VB6 is single-
threaded.
While developing calculations with ACE for VB.NET, consider the following:
Because VB.NET does not support the default property, you must specify the Value
property for the PIACEPoint object explicitly. For example, while the following is
valid in VB6, it is not valid in VB.NET:
If myInputTag = "Manual" Then
The correct code in VB.NET is as follows:
If myInputTag.Value = "Manual" Then
VB.NET has eliminated the keyword Set. The result of the following code differs in
the two Visual Basic versions:
myOutputTag = myInputTag

Differences between ACE for VB6 (ACE 1.x) and ACE for VB.NET (ACE 2.x)
In VB6, the value of myOutputTag is set to the value of myInputTag. In VB.NET, the
object for myOutputTag is set to that of myInputTag. OSIsoft recommends explicitly
specifying all properties and avoiding VB6 default properties.
Upgrading ACE Modules from VB6 to VB.NET

The ACE Wizard can be used to upgrade ACE Modules from VB6 to VB.NET. Click Tools
> PIACEWizard > Upgrade to migrate ACE Executables from VB6 to VB.NET. An out-of-
process COM server is converted into a .NET Class Library. Because VB.NET differs
significantly from VB6, it is important to understand that this upgrade represents only one
step in the migration process. Consult the VB.NET documentation for details on migrating
code from VB6 to VB.NET.
Although the migration wizard can restore all the source files, we recommend that you back
the files up before an upgrade. Specify the PI Server where the structural information for the
ACE Executable is stored and the name of the ACE Executable to be upgraded. The source
code for the ACE Executable should be accessible from the computer.
Figure A-1 Upgrading ACE for VB6 Calculations
The upgrade process involves the following steps:

Preprocessing: Checks if all the source files exist. Note that all the source files must be
in the same directory as the project file (that is, .vbp). A temporary directory is created to
store the original files so that they are preserved during the upgrade. The temporary
directory is in the same directory as the project file. If a crash occurs during the upgrade,
one can recover the original files from this temporary directory.
Code Conversion: Invokes the Visual Basic upgrade wizard to convert the code from
VB6 to VB.NET. This step is the most time-consuming and CPU intensive. It is not
uncommon for the computer to use a high percentage of the CPU for tens of seconds after
the dialog box disappears. In some extreme cases, the Upgrade Wizard might crash.
Note: Visual Basic Upgrade Wizard is not available in the Standard Version of Visual
Basic and Visual Studio .NET.
118
Post-processing: Restores the original source files and copies the structural information
for the ACE Executable into the PI Module Database on the PI ACE Data Server.
The Visual Basic Upgrade Wizard has five pages. Only the third page, which specifies the
new project path, is relevant here. The default directory path is
ACEExePath\ACEExeName.NET, where ACEExePath is the directory where the ACE
Executable is located and ACEExeName is the ACE Executable name. You should change
this path appropriately. We recommend creating a directory named ClassLibraries in the
directory where ACE is installed, and putting all ACE Executables that are developed with
ACE for VB.NET in the ClassLibraries directory.
Figure A-2 Page 3 of Visual Basic Upgrade Wizard with default path

Differences between ACE for VB6 (ACE 1.x) and ACE for VB.NET (ACE 2.x)
Figure A-3 Page 3 of Visual Basic Upgrade Wizard with modified path
After a successful upgrade, read the upgrade report generated by the Visual Basic Upgrade
Wizard. You can ignore all the compiler errors and warnings related to the PIACEPoint
object because the ACE upgrade wizard should have fixed most of those errors and warnings.
Here are some samples:
Compiler error: PIACEPoint object was not upgraded.
Runtime warning: Couldnt resolve default property of object
piacedemotag.Value.
After all the issues are resolved, you can then proceed to debug and test all the ACE Modules
in the ACE Executable. An ACE Module cannot be started by the ACE Scheduler until it has
been successfully tested.
120
Appendix B
Technical Support and Resources

You can read complete information about technical support options, and access all of the
following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
For information on programming and integration with OSIsoft products see the OSIsoft
vCampus Web site, or the OSIsoft vCampus section at the end of this document.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers
Computer platform (CPU type, operating system, and version number)
The time that the difficulty started
The log files at that time
Help Desk and Telephone Support
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location Access Number Local Language Options
San Leandro, CA, USA 1 510 297 5828 English
Philadelphia, PA, USA 1 215 606 0705 English
Johnson City, TN, USA 1 423 610 3800 English
Montreal, QC, Canada 1 514 493 0663 English, French
Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese
Frankfurt, Germany 49 6047 989 333 English, German
Manama, Bahrain 973 1758 4429 English, Arabic
Singapore 65 6391 1811 English, Mandarin
86 021 2327 8686 Mandarin
Perth, WA, Australia 61 8 9282 9220 English

Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail will
be treated as a regular phone call and will be directed to the first TSE who becomes available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site's support solutions,
documentation, and support bulletins using the advanced MS SharePoint search engine.
E-MailBased Technical Support
techsupport@osisoft.com
When contacting OSIsoft Technical Support by e-mail, it is helpful to send the following
information:
Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue.
Log files: See the product documentation for information on obtaining logs pertinent to
the situation.
Online Technical Support
From the OSIsoft Technical Support Web site, click My Support > My Calls.
Using OSIsoft's Online Technical Support, you can:
Enter a new call directly into OSIsoft's database (monitored 24 hours a day)
View or edit existing OSIsoft calls that you entered
View any of the calls entered by your organization or site, if enabled
See your licensed software and dates of your Service Reliance Program agreements
122
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support
Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Support Options page for details on the
various methods you can use.
On-Site Service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service
Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
The Search Support feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including user manuals,
release notes, and white papers).
System Manager Resources include tools and instructions that help you manage archive
sizing, backup scripts, daily health checks, daylight saving time configuration, PI Server
security, PI System sizing and configuration, PI trusts for interface nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.
OSIsoft Virtual Campus (vCampus)
The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that
focuses on PI System development and integration. The Web site's annual online
subscriptions provide customers with software downloads, resources that include a personal
development PI System, online library, technical webinars, online training, and community-
oriented features such as blogs and discussion forums.

OSIsoft vCampus is intended to facilitate and encourage communication around PI

programming and integration between OSIsoft partners, customers and employees. See the
OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or
contact the OSIsoft vCampus team at vCampus@osisoft.com for more information.
124
Index
A C
ACE caching calculations
performance improvements in 63 dependencies within an ACE Module 6
ACE Context deploying to multiple contexts (example) 19
adding to module 52 performance considerations 112
deleting from module 54 using MATLAB functions in 14
editing schedule 56 clock scheduling, definition of 6
setting maximum calculation time 57
setting priority of 56 D
taking out of service 52 Delete
troubleshooting 110 Context menu 57
ACE Executable Executable menu 51
deleting 51 Module Menu 54
exporting all 48 Description, Module menu 51
exporting selected 50
taking out of service 50 E
ACE for Visual Basic .NET (ACE for VB.NET, ACE
2.x) Edit Calculation Limit, Context menu 57
differences from ACE for VB6 115, 116 Enable/Disable Auto Refresh, Server menu 49
ACE for Visual Basic 6 (ACE for VB6, ACE 1.x) event scheduling 6
differences from ACE for VB.NET 115 Export All Executables, Server menu 48
upgrading to VB.NET 116 Export, Executable menu 50
ACE Manager
managing PI Servers with 47 G
overview 46 Get Error Message, Context menu 58
ACE Modules
registering 41 I
taking out of service 52
Import, Server menu 48
upgrading from 1.x 116
ACE Scheduler
L
clock differences between ACE Server and PI
Server 22 last snapshot value, method for retrieving 68
configuration and system requirements 4
execution queue 22 M
prioritizing calculations 23 MATLAB functions, calling within ACE Module
running on a cluster 69 (example) 14
troubleshooting incorrect output time stamp message logging
111 for ACE Scheduler 47
troubleshooting timeouts 109
updating changed names of tags and aliases 23 N
ACE Wizard
automatic generation of code by 14 natural scheduling, definition of 6
configuration and system requirements 25
Add New Server, Server Menu 47 P
PI ACE (PI Advanced Computing Engine)
components 2

Index
differences between ACE for VB.NET and VB6

115
features 1
installation 5
message logging on PI Message Subsystem 7
scheduling 5
support for high availability (HA) 7
PI Server
adding 47
exporting ACE Executables from 48, 50
importing ACE Executables to 48
PI Tags, troubleshooting 110
process monitoring, checking for bad values 9
R
Recalculate
Context Menu 58
Module menu 54
recalculations, manual and automatic 64
Refresh Server, Server menu 48
Remove Server, Server menu 48
Resume Calculation
Resume Calculation, Context menu 55
Resume Calculation, Executable menu 50
Resume Calculation, Module menu 52
S
scheduling, categories of 5
T
Take Out of Service
Context menu 55
Executable menu 50
Module menu 52
timestamps
for output tags 68
guideline for input arguments 68
supported formats 71
V
Visual Basic
error handling differences between .NET and
non-.NET 72
in-process COM servers 67
out-of-process COM servers 67
126

PI ACE 2010 R2 User Guide For Visual Basic 6 en

Uploaded by

Document Information

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

PI ACE 2010 R2 User Guide For Visual Basic 6 en

Uploaded by

Copyright:

Available Formats

PI ACE 2010 R2

User Guide for Visual Basic 6

OSIsoft Australia Perth, Australia

PI ACE 2010 R2 User Guide for Visual Basic 6

U.S. GOVERNMENT RIGHTS

Chapter 2 Tutorial Examples ........................................................................................................9

Chapter 3 ACE Scheduler ...........................................................................................................21

Chapter 4 ACE Wizard.................................................................................................................25

Chapter 5 ACE Manager..............................................................................................................45

PI ACE 2010 R2 User Guide for Visual Basic 6 iii

Chapter 6 Advanced Topics .......................................................................................................63

Chapter 7 ACE Library Functions ..............................................................................................71

Appendix B Technical Support and Resources .....................................................................121

PI ACE 2010 R2 User Guide for Visual Basic 6 1

To provide the ability to migrate from PI 2 and PI 3 performance equations.

Figure 1-1 ACE Components and Their Common Data

Structure of ACE Modules

Figure 1-2 Structure of ACE Modules

Configuration and System Requirements

PI ACE 2010 R2 User Guide for Visual Basic 6 3

Note: We recommend running ACE Scheduler on server operating systems (for

Microsoft .NET Framework 2.0 or higher

PI SDK 1.3.8.388 or higher

PI ACE 2010 R2 User Guide for Visual Basic 6 5

PI ACE 2010 R2 User Guide for Visual Basic 6 7

Example 1 - Email Notification

Step 1 Start ACE Scheduler

Step 2 Develop ACE Module via ACE Wizard

PI ACE 2010 R2 User Guide for Visual Basic 6 9

Figure 2-1. ACE Wizard New/Edit Page 1

Figure 2-2 ACE Wizard New/Edit Page 2

PI ACE 2010 R2 User Guide for Visual Basic 6 11

Figure 2-3 User Code for ACE Module

Figure 2-4 Testing ACE Module

Figure 2-5 Register ACE Module

Step 3 - Monitor ACE Module

Figure 2-6 ACE Manager

PI ACE 2010 R2 User Guide for Visual Basic 6 13

Example 2 - Calling External Functions

Figure 2-7 MATLAB Example

subroutine ActualPerformanceEquations. The wizard automatically generates the

Figure 2-8 Calling Out-of-process COM Servers

PI ACE 2010 R2 User Guide for Visual Basic 6 15

Example 3 - Write Once, Apply to Many

Step 1 - Build PI Module Database Structure

Figure 2-9 Sample PI Module Database Structure

Step 2 - Start ACE Scheduler

Step 3 - Develop ACE Module via ACE Wizard

Step 4 - Add New ACE Contexts

Figure 2-10 Adding Other Contexts

PI ACE 2010 R2 User Guide for Visual Basic 6 17

Figure 2-11 Add Context dialog

Figure 2-12 Example of four Contexts that are running

PI ACE 2010 R2 User Guide for Visual Basic 6 19

Execution of ACE Modules

PI ACE 2010 R2 User Guide for Visual Basic 6 21

Figure 3-1 Flowchart for Calculations

Clock Differences between ACE and PI Servers

Tag and Alias Name Changes

PI ACE 2010 R2 User Guide for Visual Basic 6 23

Add-In Menu and Toolbar

Figure 4-1 Visual Basic 6 Add-In Manager

PI ACE 2010 R2 User Guide for Visual Basic 6 25