AOT3.1RevA EntireManual1

W O N D E R W A R E T R A I N I N G
Training Manual
Revision A
August 2009
Part Number 11-GM-10014
ArchestrA Object
Toolkit 3.1
INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT NOTICE.
2009 by Invensys Systems, Inc. All rights reserved. No part of this document may be reproduced, stored in
or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,
photocopying, recording or otherwise), or for any purpose, without the express written permission of Invensys
Systems, Inc. Except where noted, the companies, organizations, products, domain names, e-mail
addresses, logos, people, places and events depicted herein are fictitious and no association with any real
company, organization, product, domain name, e-mail address, logo, person, place or event is intended or
should be inferred.
Invensys and the author(s) assume no responsibility for errors or omissions and no liability is assumed for
damages resulting from the use of the information contained herein. Use of the Invensys software described
in this document is subject to the terms of the applicable Invensys Systems, Inc. / Wonderware license.
These terms include provisions that limit your rights such as use restrictions, disclaimers of warranties and
limitations of Wonderware / Invensys liability. By installing or using the Invensys software, you agree to accept
all of the terms of the applicable Invensys Systems, Inc. / Wonderware license. A copy of the applicable
license will be displayed upon initial installation of the software. If a copy of the license is not displayed or you
require an additional copy of the license, you may obtain one from Invensys' Wonderware business unit by
calling 1.949.727.3200 or by sending an e-mail to support@wonderware.com.
Invensys, Wonderware, ArchestrA, Factelligence, IntelaTrac, InBatch, InControl, IndustrialSQL Server,

InSQL, InTouch, InTrack, QI Analyst, SCADAlarm, SuiteLink, SuiteVoyager, WindowMaker, WindowViewer
are trademarks and registered trademarks of Invensys plc, its subsidiaries and affiliated companies. All other
brands and product names may be the trademarks or service marks of their respective owners.
Table of Contents 1
Table of Contents
Module 1 Introduction .................................................................................1-1
Section 1 Course Introduction......................................................................... 1-3
Section 2 System Platform Review............................................................... 1-15
Lab 1 Creating the Galaxy...................................................................... 1-17
Section 3 ArchestrA Object Toolkit Overview ............................................... 1-23
Section 4 System Requirements, Licensing, and Support............................ 1-29
Module 2 Application Objects Development.............................................2-1

Section 1 Application Objects Design Overview ............................................. 2-3
Lab 2 Developing the Counter Object .................................................... 2-23
Section 2 Attribute Set Handlers................................................................... 2-37
Lab 3 Implementing Set Handlers .......................................................... 2-41
Section 3 Runtime Events............................................................................. 2-53
Lab 4 Enhancing the Counter Object ..................................................... 2-57
Section 4 Configtime Events......................................................................... 2-65
Module 3 Utility Primitives ..........................................................................3-1

Section 1 Primitives Overview ........................................................................ 3-3
Section 2 Utility Primitives Overview............................................................... 3-7
Lab 5 Adding a Counter Input ................................................................ 3-11
Lab 6 Adding Counter Alarms and History ............................................. 3-21
Section 3 Quality and Timestamp Handling.................................................. 3-37
Lab 7 Handling Quality in the Counter Object ........................................ 3-41
Module 4 Error Handling and Debugging..................................................4-1

Section 1 ArchestrA Logger Message Methods.............................................. 4-3
Section 2 Configtime Validation ...................................................................... 4-7
Lab 8 Implementing Configuration Validation........................................... 4-9
Section 3 Debugging..................................................................................... 4-21
Module 5 Virtual Primitives.........................................................................5-1

Section 1 Virtual Primitives Overview ............................................................. 5-3
Lab 9 Adding a Counter Reset Input ........................................................ 5-9
Module 6 Custom Primitives.......................................................................6-1

Section 1 Local Primitives Overview............................................................... 6-3
Lab 10 Adding Counter Statistics ............................................................. 6-7
Section 2 Reusable Primitives Overview ...................................................... 6-19
Lab 11 Creating a Rate Calculator Reusable Primitive .......................... 6-21
Module 7 Object Editor................................................................................7-1

Section 1 Editor Design .................................................................................. 7-3
Lab 12 Enhancing the Counter Editor .................................................... 7-11
Module 8 Advanced Features .....................................................................8-1

Section 1 Application Objects Documentation ................................................ 8-3
Section 2 Object Dictionary............................................................................. 8-5
Lab 13 Using the Object Dictionary .......................................................... 8-7
Section 3 Version Management.................................................................... 8-13
Section 4 Dependent Files............................................................................ 8-21
ArchestrA Object Toolkit

2 ArchestrA Object Toolkit
Appendix A SimpleAnalog Object .................................................................A-1
Wonderware Training
Module 1
Introduction
Section 1 Course Introduction 1-3
Section 2 System Platform Review 1-15
Lab 1 Creating the Galaxy 1-17
Section 3 ArchestrA Object Toolkit Overview 1-23
Section 4 System Requirements, Licensing, and Support 1-29
1-2 Module 1 Introduction
Module Objectives
List the objectives of the course and describe the agenda
Describe what the ArchestrA Object Toolkit is used for and list its main features
Wonderware Training
Section 1 Course Introduction
Section Objectives
Describe the objectives of the course.
Summarize the product offerings provided with the Wonderware Software Solutions.
This section describes the ArchestrA Object Toolkit course and agenda, and it provides an
overview of Wonderware solutions and product offerings.
Course description
The ArchestrA Object Toolkit course is a 3-day, instructor-led class that provides lectures and
hands-on labs designed to demonstrate the creation and development of Application Objects
using the ArchestrA Object Toolkit 3.1 software. In this course, you will create, configure, and
deploy Application Objects using the ArchestrA Object Toolkit, Microsoft Visual Studio, and
Wonderware System Platform. You will learn about the general object development cycle, and you
will leverage the power of reusable code through the use of object-oriented building blocks, such
as utility primitives provided with the software and custom primitives you will create. You will also
create and customize you own object editor.
Objectives
Upon completion of this course, you will be able to:
Create custom ArchestrA Application Objects using the ArchestrA Object Toolkit and
Microsoft Visual Studio
Take advantage of the code reusability features in the ArchestrA Object Toolkit
Audience
Current Wonderware System Platform users who want to extend the capabilities of their System
Platform through the creation of custom ArchestrA Application Objects.
Prerequisites
The prerequisites for this course are:
Wonderware System Platform Part 1 course
Knowledge of C# and Microsoft Visual Studio .NET
Manufacturing industry experience

Agenda
Module 1 Introduction
Section 1 Course Introduction
This section describes the ArchestrA Object Toolkit course and agenda, and it provides an
overview of Wonderware solutions and product offerings.
Section 2 System Platform Review
This section describes the fundamental concepts and architecture of the Wonderware System
Platform.
Lab 1 Creating the Galaxy
Section 3 ArchestrA Object Toolkit Overview
This section provides a high-level overview of the ArchestrA Object Toolkit and describes its
features and components. It also includes an overview of ArchestrA objects.
Section 4 System Requirements, Licensing, and Support
This section describes the hardware recommendations and software requirements for the
ArchestrA Object Toolkit. It also explains how to access product support.
Module 2 Application Objects Development

Section 1 Application Objects Design Overview
This section describes the concepts, development workflow, and best practices for designing
ArchestrA application objects. It also provides an overview of the Counter object, which will be
built in this course.
Lab 2 Developing the Counter Object
Section 2 Attribute Set Handlers
This section describes and explains how to configure the configtime, runtime, and
GetStatusDesc event set handlers for attributes.
Lab 3 Implementing Set Handlers
Section 3 Runtime Events
Lab 4 Enhancing the Counter Object
Section 4 Configtime Events
This section describes how to add and implement configtime event handlers.
Module 3 Utility Primitives

Section 1 Primitives Overview
This section provides an overview of primitives and describes the different types of primitives.
Section 2 Utility Primitives Overview
This section describes the utility primitives that are included with the ArchestrA Object Toolkit.
Lab 5 Adding a Counter Input
Lab 6 Adding Counter Alarms and History
Wonderware Training
Section 3 Quality and Timestamp Handling

This section describes and provides guidelines for calculated quality and calculated time
usage.
Lab 7 Handling Quality in the Counter Object
Module 4 Error Handling and Debugging

Section 1 ArchestrA Logger Message Methods
This section describes the Logger View, and provides information on using the methods
provided by the ArchestrA Object Toolkit to write messages to the ArchestrA Logger.
Section 2 Configtime Validation
This section describes the Validate event handler.
Lab 8 Implementing Configuration Validation
Section 3 Debugging
This section describes debugging objects and how to attach the Visual Studio debugger in the
ArchestrA Object Toolkit.
Module 5 Virtual Primitives

Section 1 Virtual Primitives Overview
This section describes virtual primitives and gives examples of how they can be used. It also
describes methods that can be used in logic for working with virtual primitives.
Lab 9 Adding a Counter Reset Input
Module 6 Custom Primitives

Section 1 Local Primitives Overview
This section describes local primitives and explains how to configure them.
Lab 10 Adding Counter Statistics
Section 2 Reusable Primitives Overview
This section describes reusable primitiveswhat they are, how they are used, and how to
create and configure them.
Lab 11 Creating a Rate Calculator Reusable Primitive
Module 7 Object Editor

Section 1 Editor Design
This section describes how to design a custom object editor to provide users with a graphical
interface for configuring an application objects attributes in the ArchestrA IDE.
Lab 12 Enhancing the Counter Editor

Module 8 Advanced Features

Section 1 Application Objects Documentation
This section describes how to add object help to your custom application object so that end
users can access it from the ArchestrA IDE.
Section 2 Object Dictionary
This section provides an overview of the object dictionary, including what it is used for, how to
edit the dictionary file, and how to use it for internationalizing objects.
Lab 13 Using the Object Dictionary
Section 3 Version Management
This section describes object versioning for major and minor builds of an object. It also
provides information about migration of new object versions into an application in the
Wonderware Application Server.
Section 4 Dependent Files
This section provides an overview of dependent files and explains how to configure them in
the ArchestrA Object Toolkit.
Wonderware software solutions

Wonderware is the leading supplier of real-time operations management industrial software
solutions for Manufacturing Execution Systems (MES), Performance Management, Enterprise
Manufacturing Intelligence (EMI), and integration with asset management, Supervisory HMI,
GeoSCADA, Production Management, supply and demand chain, and Enterprise Resource
Planning (ERP) applications.
Wonderware delivers significant cost reductions associated with designing, building, deploying
and maintaining secure and standardized applications for manufacturing and industrial operations.
Wonderware software solutions enable companies to synchronize their production operations with
business objectives, obtaining the speed and flexibility to attain sustained profitability.
Over one-third of the world's plants and facilities run Wonderware software solutions in dozens of
industries worldwide, such as:
Automotive
Chemical & Pharmaceutical
CPG (Food & Beverage)
Discrete Manufacturing
Electrical Power
Facilities Management
Mining and Metals
Oil and Gas
Process Manufacturing
Water and Wastewater
Wonderware software solutions deliver manufacturing and operational performance improvements
that help reduce the amount of project-specific work required to develop information and
automation applications that are integrated across entire operational enterprises. They can be
implemented in the context of existing systems, at a companys own pace and to the extent that
they choose.
Wonderware Training
These solutions leverage a powerful, layered software architecture that enables a variety of
features and capabilities, such as visualization, optimization and control of plant floor data
collection, and data storage and analysis.
Dev
InteSystem Engelopm
grato inee ent Con
r r
Opetrol R
Infr
rato oom
r P
Suproducti
Ope astru
ervis on
or
P
Eng rocess
Pla
rat ctur
IT inee
.F Bu i n &
r Ope Line Mo
bile
.P acilit
rato
i on e
r Use
ld r
owe ies s O pe
Tra M
.T n rG an rate Q
Eng uality
sm en ag inee
.W ransp issio eratio emen
r
P
ate o n n& t Eng rocess
.E r & rtatio
inee
r
t c. Wa n Ma
Opeintena
ste rato nce
wat Ma
i
r
er Evo ntain Ma
lve & IT
Sup intena
ervis nce
or
Ma
n
per ctu O ufa
Machin
.D
.F iscre atio ring
ns
e
.M odo t eM
a
.O ining & Beve nufac
Sys .S il& & r a turin
t
Con em & pec Gas Meta ge g
nec Dev P ls
.E harm ialty C
Line
tivi ice
ty tc. ace hem
/ De
utic
al ical &
par
tm
nt e
Plan
t / Sit
es
E n te rp ris e
Wonderware offers the following software solutions:

Manufacturing Execution Systems Manufacturing Execution Systems (MES)
solutions feature a complete set of functional capabilities for consistent and effective
execution of operational activities. Leveraging the ArchestrA software architecture (see
page 1-9), Wonderware MES solutions are completely scalable and configurable. This
enables a unique, incremental approach to operational improvements where low-risk
deployment of increased application functionality can be realized one step at a time.
Wonderware MES solutions help to substantially reduce lead time and manufacturing
costs, increase production throughput and product quality, and reduce efforts involved in
compliance and governance.
Enterprise Manufacturing Intelligence Enterprise Manufacturing Intelligence (EMI)
software solutions empower companies to analyze their overall operational performance
using simple yet powerful data analysis and reporting tools. Production, costs, process
capability, equipment downtime, and quality and variance data can be collected,
aggregated, and displayed using Wonderware EMI software solutions. A powerful yet
secure Web interface helps deliver this information to the full range of plant workers
tailored to their specific information requirements.
HMI/SCADA HMI/SCADA solutions often impose complex demands on software
architectures. Wonderware InTouch HMI visualization software, coupled with the award-
winning ArchestrA technology-based Wonderware System Platform is uniquely positioned
to meet these challenges. The HMI/SCADA software solutions are easy to use, implement
and configure, and offer simplified maintenance, high security and availability, and virtually
unlimited scalability.
Data Historian Wonderware Historian software leverages the state-of-the-art
Wonderware System Platform, industry leading historian technology, Web-based reporting
capabilities, and renowned open data source connectivity from Wonderware. The resulting

historian solution is unlike any other data archiving and reporting solution found in the
market today. With blazing speed, broad scalability, highly efficient data storage and
retrieval, high availability and simple one-click historization setup, the Wonderware
Historian software has an industry reputation for low total cost of ownership.
Preconfigured Web-based reports and data analysis capabilities drive immediate value
from data captured by the Wonderware Historian.
Batch Management Wonderware batch management solutions perform repeatable and
consistent execution of batching processes across all hybrid industries, whether it is
electronic batch records (EBR) systems in regulated industries, Paper-On-Glass
capabilities in paperless production environments, or automated recipe management for
supervisory systems. From simple batch processes, where only the formula changes for
different products, to the most complex batch processes requiring dynamic allocation of
shared equipment, Wonderware has a solution. Each of these solutions ensures reduced
lifecycle costs and investment protection by leveraging the ArchestrA architecture.
Product Quality Management and SPC Delivering products with high quality defined
as meeting specifications at the lowest possible cost is a top priority for manufacturers
and industrial operations, and Wonderware software applications meet these quality
needs. InTouch HMI offers real-time data monitoring and alarming; Wonderware Historian
stores voluminous process data for quality analysis; Wonderware QI Analyst software
provides enterprise-wide SPC; Wonderware ActiveFactory software trends data;
Operations & Performance software provides spec management, genealogy, BOM
enforcement, OEE and Downtime monitoring; the Wonderware System Platform monitors
data levels, and application templates can help deliver nearly any quality capability;
InBatch software collects information on batch quality and recipe settings; and the list
goes on.
Mobile Solutions Wonderware mobile solutions feature the industry's leading Mobile
Workforce & Decision Support System. Wonderware IntelaTrac enables the delivery of
Best Practices to field workers improving Asset Management for the leading refiners,
chemical manufacturers, and power generators globally.
For more information on Wonderware software solutions and products, visit the Wonderware Web
site at http://www.wonderware.com.
Wonderware Training
ArchestrA technology
ArchestrA technology, or architecture, helps reduce application engineering effort and deployment,
increase efficiency, provide optimization and standardization, and enable integration of distributed
automation systems and applications from virtually any vendor. Geographically dispersed
applications (from a few hundred to one million I/O, and from a single node to hundreds of
stations) can be rapidly and securely implemented.
The ArchestrA architecture leverages advanced software technologies to fill the gap between ERP
systems and control systems. This architecture provides the following:
Framework which supports common services and a core set of system objects
Domain Objects which are industry-specific objects
Object Development Toolkit which enables third parties to create new domain objects
customized for specific needs
The supervisory control and manufacturing information environment is served by a variety of
systems, including (HMI), Distributed Control Systems (DCS), Supervisory Control and Data
Acquisition systems (SCADA), Process Information Management systems (PIM), Manufacturing
Execution Systems (MES), batch and recipe management systems, and advanced control/
simulation systems. The ArchestrA Framework supports core services that are required by most of
these different types of supervisory control and manufacturing information systems.
These core services include the following:
Integrated Development Environment (IDE)
Version management
License management and centralized deployment
System diagnostics and system administration
Internationalization
Data visualization and monitoring
Event-based processing, scripting, and calculation capabilities
Alarm and event management, historization and security
Data acquisition and field device integration
Inter-object communications and name service
Reporting and ad-hoc query capability
Support for industry standards such as OPC and SQL
The ArchestrA architecture consists of the following:
Configuration and Deployment Related Components that are required for centralized
deployment of the runtime components. These components are installed just like any
other Windows application and include the following:
Centralized object repository (called Galaxy Repository)
Integrated Development Environment (IDE)
Object deployment services (called Bootstrap)
Runtime Components that are centrally deployed and administered. These components
include the following:
PCs with core infrastructure (called Platforms)
Key software applications (Engines)
Objects (Framework Objects) that expose framework related functionality

Wonderware individual software products

Wonderware software solutions offer robust, best-of-breed software components that empower
customers to effectively develop and manage their automation and information applications in
continuous, discrete, process, hybrid, and batch manufacturing environments. All the latest
Wonderware software offerings leverage the latest ArchestrA technology and offer increased
functionality and flexibility as well as extensive connectivity.
Wonderware System Platform

Wonderware System Platform provides a single platform for all the SCADA, Supervisory HMI,
MES, and EMI software solutions needs of industrial automation and information personnel. At the
center of the Wonderware System Platform is the plant model, which is the logical representation
of the physical equipment and processes being controlled and supervised. Within the System
Platform is a high-performance process historian with production history archiving, efficient data
compression, and auto-configuration of historical archiving that helps eliminate duplicate effort,
and an industrial Web information server that dramatically simplifies the organization and delivery
of operations information for use across all functions in an organization.
Wonderware InTouch HMI

Wonderware InTouch software is a human machine interface (HMI) for process visualization and
control. It takes operations management, control, and optimization to a whole new level. The
InTouch HMI reputation stands above all the rest. No other HMI can match InTouch software for
industry-leading innovation, architectural integrity, unequaled device integration and connectivity,
uninterrupted software version migration path, and truly legendary ease of use.
Wonderware HMI Reports

Wonderware HMI Reports is an easy-to-use and powerful reporting tool for creating and delivering
usable, visually appealing reports containing real-time process data or information extracted from
InTouch HMI, Wonderware Historian, third-party HMI applications and database systems, or
almost any data source that supports OPC, OLE DB, and ODBC standards. Reports can be
generated on-demand or automatically on-event or on a regular schedule. The reports can be
printed or generated as Microsoft Excel, Adobe Acrobat (PDF), and HTML formats and distributed
automatically by e-mail, stored on a network share, or shared over the Internet or intranet through
the HMI Reports Web portal.
Wonderware Historian
The Wonderware Historian component of the System Platform is a high-performance, real-time
database for historical information. It combines the power and flexibility of a relational database
with the speed and compression of a true process historian, integrating the office with the factory
floor or any industrial operation. The Wonderware Historian is designed to collect a wide variety of
plant data, at full resolution and very high data rates.
Wonderware ActiveFactory
The Wonderware ActiveFactory software provides data-trend analysis, sophisticated numerical-
data analysis using Microsoft Excel, comprehensive data reporting using Microsoft Word, and the
capability to publish real-time and historical plant information to the Web or company intranet site
using Wonderware Information Server. Plant knowledge workers using ActiveFactory information
can quickly troubleshoot problems, study potential process inefficiencies, and eliminate the time-
consuming process of locating the data.
Wonderware Training
Wonderware Information Server

The Wonderware Information Server offers an easy solution for aggregating and presenting plant
production and performance data over the Web or company intranet. Using Wonderware
Information Server, large amounts of process data can be aggregated into highly informative
production reports tailored to the information needs of plant personnel. Content from the
Wonderware Information Server can be incorporated into other Web portals, helping to make
existing corporate IT portals more informative and valuable.
Wonderware Operations Software

Wonderware Operations Software provides a scalable and configurable Manufacturing Execution
System (MES) designed to improve operational efficiency, manufacturing responsiveness, and
brand integrity. It provides an incremental, low-risk approach to building Manufacturing Execution
systems that can be implemented in steps, from basic MES functionality including bill of materials,
specifications, data collections, and traceability to enhanced capabilities such as inventory
management, certifications, labor, and production steps.
Wonderware Performance Software

Wonderware Performance Software provides a highly scalable and functionally rich solution for
collecting, tracking, and communicating real-time equipment performance information. It helps
deliver critical equipment downtime and efficiency information to operators and decision-makers
who can take immediate action to improve plant performance. The software is highly configurable
and leverages the Wonderware System Platform, which offers many benefits as a result of the
underlying ArchestrA technology.
Wonderware QI Analyst
Wonderware QI Analyst Statistical Process Control (SPC) software is an important part of any
quality management program. Performing both online and historical SPC, QI Analyst supports
real-time process monitoring and alarms, as well as historical reports to view process health over
any period of time. Real-time SPC, analysis, and reporting are equally easy. By storing process
data in the QI Analyst database and linking to external data sources, users can leverage
enterprise-wide SPC to reduce variation, reduce costs of manufacturing, and increase productivity.
Wonderware InBatch Software

Wonderware InBatch flexible batch management software optimizes the management of any
batch process. InBatch software automates recipe management using a graphical procedure
environment featuring Sequential Function Charts (SFC). Consistent with the ISA S88 flexible
batching standard, InBatch software offers comprehensive batch execution and equipment history,
material genealogy, stringent security, Web-based reporting, and the ability to facilitate the design
and implementation of systems that are compliant with FDA 21 CFR Part 11 regulations.
Wonderware Equipment Operations Module

Wonderware Equipment Operations Module helps manufacturers capture complete as-built
records for rapid response to unforeseen production events such as product recalls. Leveraging
the ISA-95 standard, it enables consistent execution of unit/line operations, improved reliability,
and repeatability of equipment setup.

Wonderware Manufacturing Execution Module

Wonderware Manufacturing Execution Module empowers Wonderware customers to define logical
manufacturing models in terms of routes, operations, resources, and bills of materials as well as
their relationship. It enables the operational execution of production plans with accurate tracking
and control of work-in-process (WIP) information related to inventories, resource utilization, and
conformance to specifications.
Wonderware SCADAlarm
SCADAlarm alarm and event-notification software provides a telecommunications link to industrial
automation software systems. It seamlessly integrates with the comprehensive Wonderware
product family and has built-in browsers to enable fast configuration of information from
Wonderware System Platform and InTouch HMI software.
Wonderware Toolkits
Wonderware Toolkits provide powerful extensibility to InTouch HMI and System Platform
applications by enabling developers to extend the capabilities of Wonderware products to meet
specific system integration needs. The Toolkits promote adherence to industry standards, provide
additional customization and intellectual property protection, and enhance the ability to interface
Wonderware products with other software and hardware.
Wonderware offers the following Toolkits:
Toolkit Enables developers to:

DAServer Toolkit Build custom device integration servers more easily
ArchestrA Object Toolkit Extend the ArchestrA architecture with objects that provide specific application
or device integration functionality
Historian Toolkit Create high-value industrial applications that integrate with data sources from
the System Platform and other data sources
Alarm Toolkit Produce custom distributed alarm providers and consumers
Wizard Toolkit Produce their own Wizards for inclusion in InTouch HMI
Script Toolkit Develop custom InTouch scripts
GRAccess Toolkit Create programmatic access to and interaction with System Platform Galaxy
configuration data
MXAccess Toolkit Create programmatic access to runtime data in a System Platform Galaxy
Wonderware Device Integration Servers

Device Integration Objects (DI Objects) within the Wonderware System Platform provide seamless
connectivity to any data source, and the DAServer Toolkit allows developers to create custom
connectivity servers. In collaboration with more than 100 third-party interface developers,
Wonderware provides the largest selection of connectivity options to hundreds of control systems
and other hardware devices. Wonderware has also fully embraced the openness of OPC
technology, exposing data via OPC from Wonderware products as an OPC Client and also
providing the means to connect to any third party OPC Server.
Wonderware Training
Wonderware Enterprise Integration Application

Wonderware offers powerful capabilities to complete the manufacturing supply chain by linking the
manufacturing system to business applications like ERP, PLM, SCM, and LIMS systems.
Wonderware Enterprise Integration Application provides a scalable and configurable solution
designed to accommodate even the most complex requirements for tightly aligning business and
manufacturing systems.
Wonderware IntelaTrac
Wonderware IntelaTrac is a suite of configurable software and ruggedized mobile hardware
products that provides workflow management, procedural and general task management
capabilities typically focused around plant operations, maintenance management, and production
tracking and compliance applications to mobile field workers.

Wonderware Training
Section 2 System Platform Review 1-15
Section 2 System Platform Review
Section Objectives
Explain what components comprise the Wonderware System Platform
Describe the benefits of an integrated ArchestrA architectural environment
This section describes the fundamental concepts and architecture of the Wonderware System
Platform.
Introduction
The Wonderware System Platform is a strategic industrial application platform built on ArchestrA
technology which uses Wonderware Application Server as its foundation. Designed to suit the
needs of industrial automation and information personnel, the System Platform provides a single,
scalable software platform for Geographically Distributed SCADA (Geo-SCADA), Supervisory
HMI, and Production and Performance Management software solutions. The System Platform is a
unified bundle of previously available Wonderware software products, including: Wonderware
Application Server, Wonderware Historian, Wonderware Information Server, and Device
Integration products.
The Wonderware System Platform contains an integral core set of capabilities and services to
support sustainable production and operations performance improvement through a
comprehensive set of six capability areas:
Industrial domain services for industrial computing functions that are not provided by
commercial operating systems or products
Software and device connectivity services for easy communication to virtually any
plant or business information source
Information and data management services for management of real-time and historical
information
Information delivery and visualization services for functions that provide information to
the right user at the right time, and in the form in which they expect it
Application development services that provide easy and intuitive development of
modular industrial software solutions that can be easily changed to meet future needs
System management and extensibility services that provide easy management,
expansion, and modification of the application or the computing architecture
The ArchestrA technology that the System Platform is built on is a comprehensive plant
automation and information architecture designed from the outset to extend the life of legacy
systems by leveraging the latest software technologies. For more information, see ArchestrA
technology on page 1-9.
In the ArchestrA environment, software applications can be rapidly assembled rather than
programmed. New applications also can be created simply through the reassembly of existing
applications. The ArchestrA Integrated Development Environment (IDE) provides a centralized
environment for development, deployment, and maintenance of scalable, secure, and
standardized information and automation applications.

System Platform architecture

The Wonderware System Platform consists of a variety of software components, including:
Application Server for system-wide, real-time data acquisition, alarm and event
management, centralized security, data manipulation, remote deployment, and
collaborative engineering
Historian plant data historian
Information Server for Internet/intranet visualization and content management
Device Integration Products for field device connectivity with third-party data sources,
software applications, and third-party controllers
Wonderware Clients, including:
InTouch human-machine interface (HMI) software as a visualization client for the
System Platform
ActiveFactory trending and analysis software
Reporting Client-Access Licenses for Information Server to enable information-
sharing and reporting over the Web
WonderwareClients
InTouch ActiveFactory InformationServerCAL
(Visualization) (AnalysisClient) (ReportClient)
WonderwareSystemPlatform
ApplicationServer InformationServer
Historian
DeviceIntegrationProducts
3rd Party Software 3rd Party

DataSources Applications Controllers
Wonderware Training
Lab 1 Creating the Galaxy

Introduction
In this lab you will use the ArchestrA IDE to create a new Galaxy that will be used for testing the
Application Objects you will develop in subsequent labs. After you create the Galaxy, you will
import, configure, and deploy the objects required for testing purposes.
Objectives
Upon completion of this lab, you will be able to:
Set up the Galaxy required for testing the objects in subsequent labs

Summary Lab Instructions

Following is a summary of the general steps you will complete for this lab. Use this summary to
complete the lab if you prefer a shortened version of the instructions. Otherwise, please refer to
the Detailed Lab Instructions on subsequent pages.
Create a new Galaxy (page 1-19)

a. Start the ArchestrA IDE and create a new Galaxy named DevGalaxy, and then connect to it.
Import and set up Galaxy objects (page 1-20)

b. Import the objects from the following file:
C:\Wonderware Training\Training_AOT31.aaPKG
c. Open GRPlatform and set the Network address to your local computer node.
d. Cascade deploy the GRPlatform instance.
Wonderware Training
Detailed Lab Instructions

Following are detailed lab instructions for completing this lab. For a summary of instructions,
please refer to the Summary Lab Instructions on the previous page(s).
Create a new Galaxy

1. Go to Start / All Programs / Wonderware, and click ArchestrA IDE.
The Connect to Galaxy dialog box appears:
2. Click New Galaxy.

The New Galaxy dialog box appears.
3. For the Galaxy name, enter DevGalaxy.
4. Click Create.
5. After the Galaxy is created, click Close.
6. When the Connect to Galaxy dialog box reappears, click Connect.

Import and set up Galaxy objects

7. On the Galaxy menu, select Import/Object(s).
The Import Automation Object(s) dialog box appears.
8. Browse to the C:\Wonderware Training folder and open Training_AOT31.aaPKG.
The Import Preferences dialog box appears:
9. Leave the default settings and click OK.

10. When the import is complete, click Close.
11. In Model view, expand the DevArea Area instance.
12. Double-click the GRPlatform instance to open its editor.
Wonderware Training
13. In the Network address field, enter the node name of your local computer.
14. Click to save and close the editor.

The Check In dialog box appears.
15. Enter a comment if you want, and then click OK to check in the object.
16. In Deployment view, right-click GRPlatform and select Deploy.

17. In the Deploy dialog box, verify that Cascade Deploy is checked
18. Click OK.

19. After deployment is complete, click Close.
Wonderware Training
Section 3 ArchestrA Object Toolkit Overview
Section Objectives
Describe the features and components of the ArchestrA Object Toolkit
Summarize the characteristics of an ArchestrA object
This section provides a high-level overview of the ArchestrA Object Toolkit and describes its
features and components. It also includes an overview of ArchestrA objects.
ArchestrA Object Toolkit introduction

The ArchestrA Object Toolkit allows developers to create their own custom ArchestrA application
objects and primitives which can be used in an ArchestrA System Platform application.
Application objects are domain objects that represent plant equipment and instrumentation, such
as pumps, valves, temperature transmitters, and conveyors. They can also represent plant
processes or control strategies such as batches or control loops.
Note: DIObjects are not supported in this release of the ArchestrA Object Toolkit.
The Toolkit tightly integrates with the Microsoft Visio Studio 2008 development environment and
provides easy-to-use tools to integrate development for ArchestrA base template objects.
With the Toolkit, developers can:
Configure an objects general properties, attributes, and primitives using an easy-to-use
object designer while maintaining synchronization with the underlying code
Graphically visualize an objects shape and easily navigate to all sections of an objects
code using a hierarchical, collapsible tree structure
Create a custom editor for an application object that allows end-users to easily configure
the objects attributes
Quickly enter code leveraging Microsofts Intellisense feature
Create standardized reusable primitives (compiled code modules that can be reused in
multiple custom application objects)
Build encapsulated .aaPDF files and automatically import them into the Galaxy for testing
Debug all aspects of the base template object leveraging Microsoft Visual Studio
debuggers and the ArchestrA aaLogger
Components of the ArchestrA Object Toolkit

The Toolkit is comprised of the following components:
The Microsoft Visual Studio add-in, which includes a Visual Studio toolbar, Object Browser
window, Logger window, and Object Designer to assist users unfamiliar with Visual Studio
and C# projects.
ArchestrA Object Solution templates, files (Utility primitives), and assemblies
Help documentation and sample projects

ArchestrA Object Toolkit add-in for Microsoft Visual Studio

The Add-in uses Visual Studio Extensibility to provide the following functionality within Microsoft
Visual Studio:
ArchestrA Object toolbar and menu commands
Object Design View for easily navigating to the objects code
Logger View for viewing the ArchestrA Logger
Object Designer for configuring the objects shape
Pre-Build and Post-Build Events to automate tasks associated with packaging and
importing objects
Toolbar
Object Design View Logger View Object Designer
Wonderware Training
ArchestrA Object toolbar
Options
Build the Object
Deploy/Undeploy
Restart Processes
Dependent File Manager
Migrate
Object Design View

Object Designer
Validate
Logger View
Debug
Help
Build Mode
ArchestrA Object Toolkit menu commands
The ArchestrA Object Toolkit menu commands are located under the Tools menu in Visual
Studio.

Object Design View

The Object Design View, shown below, is an expandable/collapsible tree structure that provides
an easy way to navigate to the code sections of the application object. The top-level item in the
tree represents the application object being developed. Each of the items listed under the top level
represents a section of source code or an editable file.
Logger View
The Logger View allows you to check for any errors and warnings that may be reported by the
ArchestrA Object Toolkit. The Logger View shows the same ArchestrA Logger messages that you
see in the ArchestrA Log Viewer. The Logger View is intended for quick reference; it does not offer
the full functionality of the ArchestrA Log Viewer.
Wonderware Training
Object Designer
The Object Designer allows you to edit and configure the properties for your object template and
configure the objects attributes, primitives, and supported methods and properties.
This data is always synchronized with the objects underlying code. For example, when you use
the Object Designer to change the properties of an attribute, you will see the updated property
values in the code, and vice versa.
Although you can edit all aspects of your object directly in the underlying code, it is easier, and is
recommended, to edit your objects using the Object Designer. The Object Designer also allows
you to perform tasks that impact multiple code sections simultaneously (such as renaming
attributes, adding local primitives, and changes associated with modifying an objects major
version).
The Object Designer window contains the following panes:
Shape Shows the structure (shape) of your object. You can edit your object here by
adding and deleting attributes and primitives.
Configuration Allows you to set and modify parameters for the application object,
attributes, and primitives. The parameters in this pane change according to which item is
currently selected in the Shape pane. For example, with the top-level object item selected,
you can configure the global properties for the object.
Attributes Shows a list of all custom attributes in your object, including their
configuration.
Configuration
Shape
Attributes

Wonderware Training
Section 4 System Requirements, Licensing, and Support 1-29
Section 4 System Requirements, Licensing, and Support
Section Objectives
Describe the hardware recommendations and software requirements for the ArchestrA
Object Toolkit
Explain how to access product support
This section describes the hardware recommendations and software requirements for the
ArchestrA Object Toolkit. It also explains how to access product support.
Hardware recommendations
The following are the hardware requirements and recommendations for ArchestrA Object Toolkit
version 3.1.
Hardware Minimum Requirement Recommended

CPU 2 GHz >2 GHz
Memory 1 GB RAM >1 GB RAM
Free hard drive space 30 GB of free disk space >30 GB of free disk space
Display Hardware Super VGA (1024 x 768) video adapter Higher resolution video adapter
and monitor and monitor
Network Hardware Network interface card N/A
Optical Hardware CD-ROM or DVD drive N/A
UI Hardware Mouse or compatible pointing device N/A
The Windows Vista operating system imposes hardware requirements that may exceed the
minimum requirements for Application Server version 3.1. If you intend to install the ArchestrA
Object Toolkit on a computer running Windows Vista, see the following Microsoft Web site for
hardware requirements:
www.microsoft.com/windows/products/windowsvista/editions/systemrequirements.mspx
Software requirements
Note the following requirements, compatibilities, and prerequisites that must be met for the proper
operation of ArchestrA Object Toolkit 3.1.
Supported operating systems

Windows Server 2003 R2 SP2
Standard Edition
Enterprise Edition
Windows XP Professional SP2 or SP3
Windows Vista SP1
Business, Enterprise, or Ultimate
Note: For the most recent Vista restrictions, refer to the documentation included with
Wonderware Application Server.

Software prerequisites
The ArchestrA Object Toolkit requires that the following software be installed:
Microsoft Visual Studio 2008 with the following components:
Visual C#
The Tools and Runtime libraries of Visual C++
Application Server version 3.1 with all the features of Bootstrap, IDE, and Galaxy
Repository
Microsoft .NET Framework 2.0
The Object Designer is supported only in English. Development of objects with localized external
names is supported using localized versions of Visual Studio 2008 for Simplified Chinese,
Japanese, French, and German locales.
All tools and examples provided by the ArchestrA Object Toolkit work with English, French,
German, Japanese, and Simplified Chinese Locale operating systems and the matching versions
of Visual Studio 2008.
Licensing
For information on licensing and licensing requirements, contact your local distributor.
Installation
For instructions on installing ArchestrA Object Toolkit, see the Readme.html file located in the root
folder of the installation CD.
Product support
Wonderware provides responsive, award-winning teams of specialists committed to delivering
world-class customer support, training, and consulting services. For information on the various
customer support programs, contact your local distributor or access the Wonderware Technical
Support site online at http://www.wonderware.com/support/mmi/
You will find a variety of information on the Technical Support site including the Wonderware
Developer Network (WDN) Library, Documentation, FAQs, Tech Alerts, Tech Articles, Tech Notes,
and Tech Support Forums. When you first enter the site, you will have limited access. To gain
access to the different areas and services, you must first register.
Also on the Technical Support site is the Technical Support Policies, Terms & Conditions guide
which provides information on how to contact Technical Support, information on the support
policies and procedures, and much more.
Wonderware Training
Module 2
Application Objects Development

Section 1 Application Objects Design Overview 2-3
Lab 2 Developing the Counter Object 2-23
Section 2 Attribute Set Handlers 2-37
Lab 3 Implementing Set Handlers 2-41
Section 3 Runtime Events 2-53
Lab 4 Enhancing the Counter Object 2-57
Section 4 Configtime Events 2-65
2-2 Module 2 Application Objects Development
Module Objectives
Explain the concepts of ArchestrA application object design
Using the ArchestrA Object Toolkit and Microsoft Visual Studio, create a simple
application object and configure it with basic functionality
Wonderware Training
Section 1 Application Objects Design Overview
Section Objectives
Discuss the concepts of an application object and identify its pieces
Describe a typical workflow for developing ArchestrA application objects
Explain how to use the ArchestrA Object Toolkit to define an object and its attributes
Describe the Counter object that will be built in this course
This section describes the concepts, development workflow, and best practices for designing
ArchestrA application objects. It also provides an overview of the Counter object, which will be built
in this course.
Overview of objects
Application objects represent plant equipment and instrumentation such as pumps, valves, They
usually get their source data from other objects, such as device integration objects. To the end
user, the application object seems monolithic. It has attributes and behaviors, and the ArchestrA
IDE is used to configure the attributes by means of an object editor or a Galaxy Load.
The object's state is validated and the object can be deployed. During runtime, the object exhibits
interesting behavior and operators can interact with it through its attributes. However, an object is
not monolithic. It has several pieces, as shown below:
Attribute Runtime Configtime Editor

Definitions
List of Code executed Maintains & Contains

attributes in runtime after protects Configuration
object deployed integrity of UI
Shape of the configuration
object Customized in information Viewed in the
Visual Studio ArchestrA IDE
Created during Customized in
object building Visual Studio Customized in
Visual Studio
The Attribute Definitions piece is an XML file containing all the information that defines the
shape of the object. It contains a list of all the attributes an object contains, and their data types,
default values, specifications, and so on. Your job as a developer is to define, using Object
Designer or directly in code, the various attributes your object will have and the configuration for
those attributes.
The Runtime piece is a DLL file containing the code that defines the behavior of the object when it
is deployed and executing in runtime. Your job as a developer is to customize this runtime code to
make the object execute in runtime whatever custom logic you want it to execute.
The Configtime piece is a DLL file containing all the code necessary for configuration validation.
This code ensures that when a user enters configuration information in the ArchestrA IDE, the
information is valid, has the right format, and that it makes good sensethat it is consistent with

the configuration of the rest of the object. Your job as a developer is to customize this validation
logic in Visual Studio using C#.
The Editor piece is a DLL file containing a form for the objects editor (graphical interface) in the
ArchestrA IDE. Users will use this editor to configure the objects parameters. Your job as a
developer is to customize this editor by placing .NET controls on the form for UI elements, like
check boxes and text boxes, to enable users to configure the information the object needs to
execute the logic.
As stated above, the Runtime code, Configtime code, and Editor are separate DLL files. This
means that they can be loaded individually by the different processes provided by the System
Platform, for example, by the Galaxy Repository (GR) process, ArchestrA IDE process, or
Application Engine process.
All of these pieces within an object are needed because in reality your object does not run in one
single place. The code for your object can run in different places, and potentially, depending on the
architecture of your Galaxy, can run in different computers.
For example, as shown below, you may have a highly distributed Galaxy where you have a node
dedicated for the Galaxy Repository, and you run the ArchestrA IDE in a separate engineering
station dedicated to configuration and application development, and then you run the Application
Engine and Platform (the runtime) in a separate Automation Object Server (AOS).
Galaxy Repository Runtime
(aaGR.exe)
App Engine
Configtime IDE (aaEngine.exe)
(aaIDE.exe)
Editor Platform
MS SQL
Server DB
Attribute
Bootstrap
Definition
Galaxy Engineering Automation

Repository Station Object Server
In this configuration, when you first import your object template using the ArchestrA IDE on the
engineering station, the IDE connects to the GR on the GR node, and the GR stores the Attribute
Definition information in the Microsoft SQL Server database. The GR is responsible for managing
all the configuration information in the Galaxy and will store and retrieve information from Microsoft
SQL Server as needed.
When you use the ArchestrA IDE on the engineering station to configure the objects derived
templates and instances, the IDE will load the Editor (the graphical UI) so you can configure the
object. Every time you enter a value in the editor and save it, the GR loads your Configtime code
in the GR, and the Configtime code executes your custom validation logic.
Note: The editor is just a graphical interface used to configure your objects. The editor is not
supposed to have any validation logic; the Configtime code does the validation.
Wonderware Training
Then, when you go to the ArchestrA IDE and send the command to deploy the object, the
command goes to the GR, and the GR retrieves all the custom configuration information coming
from Microsoft SQL Server and attaches the information to your Runtime code. This logic then
goes to the Application Engine on the AOS to be executed in runtime.
So ultimately, your object, which seems monolithic, is not one single piece in reality. From the
developers perspective, the code is split into pieces that run in different places and may
potentiality run in different computers.
Primitives
The Attributes Definition, Editor, and Runtime pieces are delivered by smaller implementation
pieces called primitives. Primitives are the building blocks of an object. They have their own
attributes and behaviors. By modularizing your object into primitives, you can create a clear,
logical structure and dynamically enable or disable functionality as needed.
For an overview of primitives, see page 3-3.
Also see the following sections for information on the different types of primitives:
Local primitives This type of primitive is defined and used in one single object. See
Local Primitives Overview on page 6-3.
Reusable primitives This type of primitive can be reused in multiple objects. See
Reusable Primitives Overview on page 6-19.
Virtual primitives Both local and reusable primitives can be made virtual. A virtual
primitive allows you to dynamically add and delete instances of the primitive at configtime.
See Virtual Primitives Overview on page 5-3.
Utility primitives A utility primitive is a predefined reusable primitive that provides
common functionality. See Utility Primitives Overview on page 3-7.
Object development workflow

The basic steps for creating an application object or reusable primitive are described below.
Create Test &

Plan Define Build
Project Debug
Plan
Before you start defining your object, you should plan its features and structure. You should decide
how to design the objects structure by using primitives. You should make a list of the attributes
that your object and any of its primitives will need, and develop a naming structure.
Create Project
You create a project for every application object or reusable primitive that you want to create.
ArchestrA Object Toolkit projects are simply Visual Studio projects of a special type. You create
and manage them just like other Visual Studio projects.
When you first create an object, the ArchestrA Object Toolkit creates a solution folder containing
four projects. One project corresponds to the object. It contains a general definition of the object
and is responsible for packaging the object into a base template that can be imported into the
Galaxy. The other three projects contain the files for the configtime, runtime, and editor code.

Define
This step typically involves the tasks listed below.
Configure your objects basic properties, such as name and description (see Object
configuration on page 2-7)
Define the shape of your object by adding attributes (see Attribute configuration on page
2-8)
Structure your object by adding primitives (see Primitives on page 3-3)
Customize code for your objects configtime and runtime events and set handlers (see
Sections 2, 3, and 4 in this Module)
Create a custom object editor that your users can use to configure the objects properties
in the ArchestrA IDE (see Editor Design on page 7-3)
Configure associated files in case your object uses any external files or assemblies (see
Dependent Files on page 8-21)
Configure other object properties, including Advise Only Active support, the objects
behavior in the ArchestrA IDE, and dump/load or failover support for dynamic attributes
Add object help that end users can access from the ArchestrA IDE (see Application
Objects Documentation on page 8-3)
Localize text strings and create a central repository for user messages (see Object
Dictionary on page 8-5)
Build
When you build your object, the ArchestrA Object Toolkit creates an .aaPDF object file that
contains your custom application object (or an .aaPRI file if youre developing a reusable
primitive). You can then import your object into the Galaxy, instantiate it, and deploy it to runtime.
You can also import, instantiate, and deploy the object automatically as part of the build process,
and you can configure various build options.
Test and Debug

Throughout the defining and building phases, you will typically test your application object, and if
you encounter problems while testing, debug it. See Debugging on page 4-21 for more
information.
Wonderware Training
Object configuration
Once you have created an ArchestrA Object Toolkit project in Visual Studio, you can start defining
your object in the Object Designer.
If the Object Designer is not open, click the Object Designer button ( ) on the ArchestrA
Object toolbar.
Selecting the top-level object item in the Shape pane allows you to configure the objects global
properties in the Configuration pane shown below.
The parameters you can configure for the object are described below.
External Name Name of the object that will be exposed in the ArchestrA IDE, must be
ArchestrA compliant (Unicode), maximum length 31 characters
Internal Name Name of the object that represents the instance of the class in code,
must be C# compliant (ANSI), maximum length 329 characters
Dump/Load support For Dynamic Attributes & Virtual Primitives Preserves the
current configtime status and configuration of dynamic attributes and virtual primitives in
derived templates and instances
Failover support for Runtime Dynamic Attributes In a redundant application engine
environment, preserves any dynamic attributes created at runtime if a failover occurs
Advise only Active supported Stops individual attributes from updating if no one is
subscribing to them. This reduces the processing and network load. Individual attributes
also need to be configured for Advise Only Active support
Category Type of object (Application Object or Reusable Primitive)

Version Current build version of the object, defaults to 0 and can be manually set or
automatically incremented according to the parameters set in the Options window (see
Version on page 2-15)
Min IAS Version Minimum version (and patch) of Application Server for which the
object is designed, prevents users from importing the object into earlier versions
Vendor String identifier for vendor name, used internally to organize the code in the GR,
must not contain double-byte characters or any characters that are invalid in Windows file
names
Toolset Toolset to place the object in when importing into the ArchestrA IDE, the list of
toolsets displayed in the drop-down list can be specified in the Options window (see
Toolset Names on page 2-16)
Description Short description of the object (for example you could describe the purpose
and usage of the object), corresponds to the ShortDesc attribute in runtime, maximum
length 1024 characters
YOu can also configure the following parameters when you use the expandable sections found at
the bottom of the Configuration pane:
Associated Files Files that are automatically associated with building the set of
assemblies and the .aaPDF or .aaPRI file
Configuration Event Handlers Adds a section for configtime event handlers in the
source code so you can add code
IDE Behavior Controls various aspects of the objects behavior in the ArchestrA IDE,
such as hiding the object from certain views and disabling some commands
Advanced Configuration Determines the execution order of primitives within the
object, and specifies that a primitive should use assemblies other than the ones
automatically generated
Attribute configuration
Attributes are the data items of an application object or primitive. By reading from and writing to
attributes, objects can exchange data with each other. In addition, your objects can also have
Inputs and Outputs to communicate with other attributes in the ArchestrA environment.
Note: Unless specifically noted, attributes in this manual mean ArchestrA attributes, not C#
attributes.
Application objects expose two sets of attributes to users:

Configtime attributes that are manipulated by configuration clients such as object editors
and the ArchestrA IDEs Galaxy Dump/Load feature
Runtime attributes that are seen by runtime components, including other application
objects and runtime GUI clients
An attribute can be configtime-only, runtime-only, or both configtime and runtime.
Wonderware Training
Once you create your object, you can start adding attributes to it. The easiest way to add attributes
to an object is by using the Object Designer. In the Shape pane, select the location in the tree
you want to add the attribute, click the Add button ( ),and then click Attribute.
When you create an attribute, the ArchestrA Object Toolkit will create a variable in code so that
later you can use it in your custom configtime and runtime code.
As you add attributes to your object, you will see them in the hierarchical list in the Shape pane.
You can also see all the attributes in the Attributes pane, shown below. This shows a flat list of all
the attributes in your object (as you would see in Object Viewer). You can expand this pane to see
more information. Also, you can filter the list to show configtime or runtime attributes only.
The abbreviated column headings in the Attributes pane are described in the following table:
Heading Description
FA Frequently Accessed option is enabled
CQ Calculated Quality option is enabled
Cfg Configtime set handler is enabled
Run Runtime set handler is enabled
Al Attribute is alarmed
His Attribute is historized

Selecting an attribute in either the Shape pane or Attribute pane allows you to configure the
attributes properties in the Configuration pane shown below. (You can also configure attributes
directly in code.)
The parameters you can configure for the attributes are described below.
External Name Name by which other objects can access the attribute, must be
ArchestrA compliant (Unicode), maximum length 31 characters
Note: Using the dot (period) is often used to create a hierarchy of related attributes. This
is acceptable for the external name, but not for the internal name. If you enter a dot in an
external name, the ArchestrA Object Toolkit substitutes the dot with an underscore in the
internal name. For guidelines on naming attributes and primitives, see Appendix B in the
ArchestrA Object Toolkit Developers Guide.
Internal Name Name used in code to refer to the attribute, must be C# compliant
(ANSI), maximum length 329 characters
Type Corresponds to the ArchestrA data type (see Data Types on page 2-13)
Category Determines who can write to the attribute and whether it is lockable in the
template (see Attribute Categories on page 2-11)
Configuration Set Handler Allows you to create custom configtime set handlers for the
attribute (see Configtime set handler event on page 2-37)
Runtime Set Handler Allows you to create custom runtime set handlers for the attribute
(see Runtime set handler event on page 2-38)
Support Calculated Quality and Calculated Time Enables the object to set the
attributes quality (for example, Bad or Uncertain) and timestamp (see Quality and
Timestamp Handling on page 3-37)
Frequently Accessed Marks the attribute as Frequently Accessed which is used as a
special filter in the Galaxy Browser to display only Frequently Accessed runtime attributes
Wonderware Training
Note: You should mark only key runtime attributes as frequently accessed. For example,
the standard $FieldReference object has just one frequently accessed attribute.
Advise only Active Enables Advise Only Active support for the attribute, which allows
you to configure the attribute to stop updating if no one is subscribing to it, thus reducing
the processing and network load
Value Allows you to set a default value for the attribute, and for user writeable attributes,
set the security classification
You can also expand the sections at the bottom of the Configuration pane to make the attribute
an array and configure default values for the array elements, and to enable and configure history
and alarms for the attribute.
Attribute Categories
Whether an attribute appears in an objects configtime namespace, runtime namespace, or both is
mainly controlled by the attributes Category.
An attributes category provides the ArchestrA framework with a great deal of information. In
addition to determining which namespaces an attribute appears in (configtime, runtime, or both),
an attributes category determines whether the attribute can be written to, and what type of client
(users, scripts, etc.) can write to it.
Lockable Attributes
Some attributes categories allow an attribute to be locked. The value of a locked attribute cannot
be modified, not even internally by the objects configtime or runtime code.
Attributes in primitives that are used by an object can be locked in the Object Designer. In addition,
ArchestrA IDE users can lock attributes to protect the configured values within a template from
being changed by other engineers who derive instances or templates from it.
In general, make attributes lockable whenever possible. Lockable attributes allow users to enforce
standards and can simplify system maintenance. Locking data also helps minimize the size of a
systems configuration database, which improves the speed of configuration tasks.
Note: An exception will be raised if an objects logic attempts to modify a locked attribute. This
must be taken into account when coding the object. Before modifying a lockable attribute, always
examine it to see if it is locked. This will not be necessary for a lockable attributes SetHandler
method, which will never be executed if the attribute is locked.
Security Classifications
Some attribute categories allow an attribute to be written to by users (operators, engineers, etc.) at
runtime. These attributes have an additional configurable property called a Security
Classification which determines what permissions an operator needs in order to write to the
attribute, such as Tuning, Operate, Config, and so on. (See the ArchestrA Object Toolkit
Developers Guide for a list of all security classifications.)
Security classifications can be changed in the Object Designer. They can also be modified later by
an ArchestrA IDE user to enforce site-specific security rules. By default, new attributes are created
with the Free Access security classification, which means that any user can write to them.
Note: Security classifications are only effective if security is enabled in the Galaxy.

The following table describes each attribute category.
Category Name Description

PackageOnly Only exists at configtime. Not deployed.
PackageOnly_Lockable Only exists at configtime. Not deployed. Can be locked.
Calculated Only exists at runtime. Not externally writeable by users or other objects.
runtime changes are not persisted to disk by the AppEngine.
Calculated_Retentive Only exists at runtime. Not externally writeable by users or other objects.
runtime changes are persisted to disk by the AppEngine.
Constant Defined by an object developer. Never changes. Exists at configtime and
runtime.
Writeable_U Exists at configtime and runtime, but only the Security Classification is
configurable. Only externally writeable by users at runtime.
Writeable_S Only exists at runtime. Only externally writeable by other objects at runtime.
Writeable_US Exists at configtime and runtime, but only Security Classification is
configurable. Externally writeable by users or other objects at runtime.
Writeable_UC Exists at configtime and runtime. Only externally writeable by users at runtime.
Writeable_UC_Lockable Exists at configtime and runtime. Only externally writeable by users at runtime.
Can be locked.
Writeable_USC Exists at configtime and runtime. Externally writeable by users or other objects
at runtime.
Writeable_USC_Lockable Exists at configtime and runtime. Externally writeable by users or other objects.
Can be locked.
Writeable_C_Lockable Exists at configtime and runtime. Not writeable at runtime, even by the object
itself. Can be locked.
U = User
S = Supervisory
C = Configuration
It is important to select a category that only allows as much access to an attribute as necessary.
For example:
An attribute that is used only by configuration logic to add or remove virtual primitives (see
page 5-3) should be given a category that prevents it from becoming part of the runtime
namespace (for example. PackageOnly).
An attribute that does not need to be configured in an editor should be given a category
that prevents it from becoming part of the configtime namespace, and the objects editor
(for example, Calculated).
An attribute that needs to be configured and deployed but is not allowed to be modified at
runtime should be given a category that prevents users or other objects from writing to it
(for example, Writeable_C_Lockable).
Wonderware Training
Data Types
Objects you create using the ArchestrA Object Toolkit can have attributes of any standard data
type that is supported in the ArchestrA environment. The following table lists the available data
types. For more information on data types, see Appendix D in the ArchestrA Object Toolkit
Developers Guide.
Equivalent C#
Data Type Valid Values Notes
Data Type
Boolean bool True, False (default:
False)
Integer int -2147483648 to
2147483647, signed
(default: 0)
Float float 3.40282 E+38 to - 32-bit IEEE single-precision floating point, used
3.40282 E+38, signed when 6-7 significant digits are needed. Smallest
(default: NaN) representable absolute value is 1.175 E-38.
Double double 1.79769 E+308 to - 64-bit IEEE double-precision floating point,
1.79769 E+308, used when 15-16 significant digits are needed.
signed (default: NaN) Smallest representable absolute value is 2.23
E-308.
String string 0 to 1024 characters, Variable-length Unicode string, size: 4 + 2*n
default: empty string bytes (n = number of characters)
Time DateTime Microsoft FILETIME 64-bit FILETIME value in UTC (Coordinated
values (default: zero Universal Time). Represents the number of
time) 100-millisecond ticks since January 1, 1601,
00:00:00 (zero time).
Elapsed Time TimeSpan Number of 100-ms Stored as a 64-bit FILETIME structure. For
ticks, signed (default: example, -1 corresponds to a duration of -
0) 00:00:00.0000001.
Attribute string Valid reference strings Standard structure containing a reference string
Reference (default: empty string and MxHandle (bound or unbound). A string of
and null handle) --- results in a null handle, and no warning is
generated when the object is validated (i. e.
when the user saves the object configuration).
A string of ---.--- results in a null handle, but a
warning is generated on validation.
MxStatus ArchestrA.Core Default: Success Standard structure containing access status
.MxStatus information for a Message Exchange call.
Data Type ArchestrA.Core Enumeration, see Data type of an attribute. Valid enumeration
.MxDataType notes (default: values are: MxNoData, MxBoolean, MxInteger,
MxNoData) MxFloat, MxDouble, MxString, MxTime,
MxElapsedTime, MxReference, MxStatus,
MxDataType, MxSecurityClassification,
MxQuality, MxCustomEnum, MxCustomStruct,
MxInternationalizedString and MxBigString.
Custom string array Default: ordinal=1, Enumerations start at the value 1. Zero is not a
Enumeration String=String1 valid ordinal value for an enumeration.
Custom ArchestrA.Core Default: GUID = 0, Provides support for custom data in the form of
Structure .MxCustomStruct length = 0. a GUID and byte array.
Internationalized 0 to 1024 characters, A vector of strings and corresponding locale IDs
String default: empty string in the configuration database. An MxString at
runtime.

Equivalent C#
Data Type Valid Values Notes
Data Type
Big String string 0 to 2147483647 Variable-length Unicode string, size: 4 + 2*n
characters, default: bytes (n = number of characters)
empty string
Variant CMxValue N/A Use this data type if the actual type of an
attribute cannot be determined in advance.
Additional object properties

You can configure various additional properties for your application object in the Options dialog
box. To access the Options dialog box, select it from the Tools / ArchestrA Object / Options
menu or click on the Options button on the ArchestrA Object toolbar.
The options are separated by categories, shown on the left side of the dialog box.
Build
In the Build category, you can specify options for debugging and copying build-generated files.
You can choose to attach the following debuggers to debug your object:
IDE Debugger to debug custom editor code
Configuration Debugger to debug configtime code
Runtime Debugger to debug runtime code
Note: Once the build is finished, Visual Studio switches into debugging mode. To stop
debugging, click the Debug button ( ) on the ArchestrA Object toolbar.
Wonderware Training
Also, you can specify to copy the following build-generated files to different folders:
The build output files to a custom folder instead of the \Output subfolder of your project
folder. This allows you to use a common location for all objects.
Reusable primitives to a subfolder of the ArchestrA C:\Program Files\Common
Files\ArchestrA\ReusablePrimitives folder. The folder will be created using the reusable
primitives vendor name.
Version
In the Version category of the Options dialog box, you can specify to keep the current version
number when you build your object, or you can automatically increment the major or minor
version. (You can also specify the version number of the object manually in the Object Designer.)
The following options are available for versioning.

Increment Minor Version (Not Applicable for Reusable Primitives)
Restart Bootstrap to release runtime dlls
Restart aaGR to release configtime dlls
Restart IDE to release editor dlls
Increment Major Version
Append version number to template name
Delete all templates with the same vendor and object name
Delete all templates and append version number
Retain current version number
While developing an object, the recommended selection is Increment Major Version and Delete
all templates with the same vendor and object name.
For more information on object versioning, see Version Management on page 8-13.

Galaxy
In the Galaxy category of the Options dialog box, you can specify which Galaxy to use when you
use the automated import, instantiate, and deploy build modes. You can also set the default Area
to assign the object instances to.
Note: In most cases, it is best to use a Galaxy on the local machine. Otherwise, the build process
cannot automatically restart the Application Server processes to make sure that the latest object
version gets used.
Toolset Names
In the Toolset Names category of the Options dialog box, you can configure the toolset names
that appear in the drop-down list in the Object Designer in the Configuration pane for the object.
Toolset names are saved in an XML file and can be saved in a central network location to share
across multiple systems.
Wonderware Training
Search Paths
In the Search Paths category of the Options dialog box, you can specify one or more additional
locations for dependent files. This gives you more flexibility because you can store your
development files in multiple locations.
Custom object editor configuration

In the development of your application object you will most likely want to create a custom object
editor so end users can configure your object in the ArchestrA IDE. A custom object editor
provides a graphical interface for configuring your objects attributes and primitives.
Note: If you want your end users to be able to configure your attributes in the ArchestrA IDE, you
need to add the necessary UI elements for the attributes on your custom object editor form. Users
cannot use the User-Defined Attributes (UDAs) tab in the standard editor to configure these
attributes.
To begin creating the custom editor, double-click Editor in the Object Design View. An Editor
form appears in the Visual Studio Design view. It already contains a tab page. This is the first
custom tab page that appears when you edit your object in the ArchestrA IDE.

Tab pages
You can create multiple custom tab pages for your object editor. In the ArchestrA IDE, these
custom tab pages appear alongside the standard tab pages that are shown for every object
(Object Information, Scripts, UDAs, etc.). You can hide these standard editor tabs if you do not
need them (in Object Designer, check the option under IDE Behavior).
To rename a tab, change its Text property in the Visual Studios Properties window.
To add a new tab, right-click the forms tab control and click Add Tab.
Tab control
Placing controls
To place controls onto your custom editor, you can simply drag attributes from the Object Design
View onto the tab page. The ArchestrA Object Toolkit then automatically adds a standard label as
well as ArchestrA controls for editing the value, security classification, and lock status of that
attribute.
You can also use the standard controls from the Visual Studio toolbox and special ArchestrA
controls that you add to the toolbox. For information on using the ArchestrA controls, see Editor
Design on page 7-3.
Wonderware Training
Once a control is placed on the tab page, you can use the Visual Studios Properties window to
set its properties, such as label or internal name. You can also double-click on a control to edit its
source code.
The Counter object

In the first lab of this course, you will create a simple Counter object, and then as you progress
through the remaining labs, you will add more complexity into the object.
Initially, the Counter object will have a single attribute name Count, whose value will increase by
one every scan. You will then add a MaxCount attribute that will cause the count to automatically
reset to zero when the maximum count is reached and a Reset attribute that can be used to
manually reset the count in runtime. You will then add a ResetOnScan attribute that will control
whether the count is to reset to zero when the object is set On Scan.
You will then further customize the Counter object by adding an Input primitive named
Count.Input and implementing the runtime logic necessary to make the count increment only
upon change of the input value. You will add an Alarm Primitive to implement a watchdog alarm
that will rise whenever the count input value remains unchanged for a certain configurable period
of time. In order to implement this, you will add several attributes, such as a time watchdog
counter, an alarm limit, and an alarm condition.
You will enable the object to support quality handling by taking into account the input quality when
calculating the count. You will then calculate the quality of the Count attribute based on various
rules.
You will add configuration validation to the Counter object by implementing the Validate configtime
event handler to add a configuration warning to the object if the Engineering Units attribute is left
empty. You will also write messages to the ArchestrA Logger using some of the methods provided
by the ArchestrA Object Toolkit. You will generate a warning message when the input source
quality is bad or unknown, and you will generate a trace message whenever the count is reset On
Scan.
In later labs, you will convert the Count history and Timeout.Condition alarm primitives to virtual
primitives, develop a local primitive to offer Counter statistics, and add a reusable primitive that will
calculate the rate of change of any analog variable.

The graphic below illustrates the final Counter object you will build in the upcoming labs.
Count
INPUTPRIM
Count.Input
VIRTHISTORYPRIM
CountHistory
MaxCount
ResetOnScan
EngUnits
TimeSinceChange
Timeout.Limit
Timeout.Condition
VIRTALARMPRIM
TimeoutAlarm
Reset
Counter Reset.InputEnabled
VIRTINPUTPRIM
Reset.Input
Stats.Enabled
RolloverCnt
VIRTPRIM
BadInputCnt
Stats
Reset
CountRate.Enabled
VIRTREUS Rate In each labs introduction, a graphic similar

PRIM CalcPeriod to the one below is shown to illustrate the
CountRate functionality you will add to the object(s) in
Reset
the lab. As depicted in the following legend,
CUSTOMEDITOR the shaded areas designate the new
functionality, and the icons designate the
DICTIONARY data types.
Legend
ExistingAttrib DataTypes:
PRIMTYPE Boolean
ArchestrA PrimitiveName Integer
Object NewAttrib Float
Implemented String
method Time
ADDITIONAL ElapsedTime
Wonderware Training
Conventions used in code

In many labs in this course, you will be instructed to edit an objects source code in order to
implement certain functionality. In these cases, the final code, as it appears after editing, is shown.
This is illustrated in the example below.
The code in bold type designates the changes from the original or previously edited code. If a line
of code extends beyond the margins in this manual, a return arrow symbol () is shown, and the
rest of the line appears right-aligned on the next line.
private void CounterConfigtime_ConfigtimeValidate(object sender, ref

EPACKAGESTATUS status)
{
//This method performs custom configuration validation
//for errors that cannot be detected by Set Handlers
if (EngUnits.Value.Length < 1)
{
//EngUnits is empty. Generate a warning
AddWarningMessage("Engineering Units is empty");
status = EPACKAGESTATUS.ePackageWarning;
}
else
{
//Object is good.
status = EPACKAGESTATUS.ePackageGood;
}
// The following statement will exit validate when validating

templates.
// Place code that should be validated in templates and instances
before this
// statement. Code placed after this statement will execute in
instances only.
if (IsTemplate)
{
return;
}
}

Wonderware Training
Lab 2 Developing the Counter Object

Introduction
This lab shows how to use the ArchestrA Object Toolkit to create a simple Counter application
object. This object will expose one single integer attribute named Count, whose value will
increase by one every scan. To create this object, you will use Object Designer to define its
shape, and then implement the runtime logic in the Execute method. You will use this object
throughout the rest of the class as you add more functionality and explore the ArchestrA Object
Toolkit features.
Count
Note: See page 2-19 for
Counter
Execute() a legend to this graphic.
Objectives
Create an ArchestrA Object project in Microsoft Visual Studio
Use Object Designer to configure and shape an object
Edit the source code to implement an objects runtime behavior
Configure the Galaxy options for a project
Use the Build Mode and Build commands to build, instantiate, and deploy a developed
object


Design the Counter object (page 2-26)

a. In Microsoft Visual Studio, create a new ArchestrA Object project in your training folder
(C:\Wonderware Training), and name it Counter.
b. In Object Designer, configure the Counter object as follows:
Vendor: Wonderware, and set as default

Toolset: Training, and set as default
Description: Counter object for training class
c. Add a new attribute, and configure it as follows:
External Name: Count

Type: Integer
Category: Calculated
Frequently Accessed: Check
Implement runtime logic (page 2-29)

d. Modify the Execute method of the Runtime project to make it look exactly like this:
private void Counter_RuntimeExecute(object sender)
{
//Code in this method is executed in runtime every scan
//while the object is On Scan
//Increment the Count attribute every scan

Count++;
}
Build and import object (page 2-29)

e. In the ArchestrA Object Toolkit Options window, configure the Galaxy settings as follows:
GR Node Name: localhost

Galaxy Name: DevGalaxy
Assign to Area: DevArea
f. Test the connection to the Galaxy, and set the parameters as default.
g. Ensure that the Version options are set to Increment Major Version and Delete all
templates with the same vendor and object name, and then set as default.
h. Use the ArchestrA Object toolbar to build, import, and instantiate the Counter object.
i. In the ArchestrA IDE, deploy the Counter_001 instance.
j. Open Object Viewer from within the ArchestrA IDE and rename the default watch window to
Counter Info.
Wonderware Training
k. Add the following attribute reference to the watch window:

Object Attribute
Counter_001 Count
l. Save the watch list to your training folder (C:\Wonderware Training) with the name Dev
Watch Windows.


Design the Counter object

To begin designing the Counter object, you will create a new ArchestrA Object project.
1. Open Microsoft Visual Studio (Start / All Programs / Microsoft Visual Studio 2008 /
Microsoft Visual Studio 2008).
2. On the File menu, click New / Project.
The New Project dialog box appears.
3. In the Project types pane, click ArchestrA, and then select the ArchestrA Object template.
4. In the Name field, enter Counter,.

5. In the Location field, enter C:\Wonderware Training.
6. Click OK.
Wonderware Training
After a few moments, the Object Designer appears.
7. In the Configuration pane, configure the Counter object as follows:

Vendor: Enter Wonderware, and then click Set Default.
Toolset: Enter Training, and then click Set Default.
Description: Enter Counter object for training class.

Now you can begin shaping the Counter object.
8. In the Shape pane, click the Add button , and then click Attribute.
9. In the Configuration pane, configure the attribute as follows:
External Name: Count

Type: Integer
Category: Calculated
10. Click OK to save and close the Object Designer.
Note: You can dock the Logger View and Object Design View windows if you want.
Wonderware Training
Implement runtime logic

11. In Object Design View, expand Runtime and double-click Execute.
The CounterRuntime.cs file opens, and the cursor is positioned at the
Counter_RuntimeExecute method.
12. Modify the Counter_RuntimeExecute method to make it look exactly like this:
{

Count++;
}
Build and import object

13. On the ArchestrA Object toolbar, click the Options button.
14. In the Options dialog box, select the Galaxy category.

15. Configure the Galaxy settings as follows:
GR Node Name: localhost

Galaxy Name: DevGalaxy
Assign to Area: DevArea
16. Click the Test button to test the connection to the Galaxy.
A success message appears:
17. Click OK to close the message.

18. Click Set Default.
Wonderware Training
19. Select the Version category.

20. Ensure that Increment Major Version and Delete all templates with the same vendor and
object name are selected.
21. Click Set Default.

22. Click OK to close the Options dialog box.
23. On the ArchestrA Object toolbar, change the Build Mode to Build & Instantiate.
24. Click the Build Object button.

The Build dialog box appears and shows the progress as the object is being built, imported
into the Galaxy, and instantiated.
25. When the process is complete, click Close.

26. Go to the ArchestrA IDE.
27. In the Template Toolbox, expand the Training toolset.
The ArchestrA Object Toolkit created both the base and derived templates for the Counter
object.
Wonderware Training
28. In Deployment view, fully expand GRPlatform.

The ArchestrA Object Toolkit automatically instantiated the object.
29. Deploy the Counter_001 instance.

30. Right-click Counter_001 and click View in Object Viewer.
Object Viewer opens and displays the Counter objects attributes in the right pane.

31. Right-click in the watch window (bottom pane), and click Rename Tab.
32. In the Rename Tab dialog box, enter Counter Info.
33. Click OK.

34. From the attributes list in the right pane, drag the Count attribute to the watch window:
35. Right-click in the watch window, and click Save As.
Wonderware Training
36. In the Save As dialog box, browse to your training folder (C:\Wonderware Training) and
enter Dev Watch Windows as the File name.
37. Click Save.

38. Verify that the Count value is incrementing.

Wonderware Training
Section 2 Attribute Set Handlers
Section Objective
Describe the configtime, runtime, and GetStatusDesc attribute set handlers
Explain how to enable attribute event handlers in the Object Designer
This section describes and explains how to configure the configtime, runtime, and GetStatusDesc
event set handlers for attributes.
Configtime set handler event

The configtime set handler is triggered when the value of an attribute is changed at configuration
time. It can be used for validation or to trigger a special action such as adding virtual primitives.
You can configure a configtime set handler for any attribute that can be written to at configtime.
The code in this set handler is executed every time a value is written to the attribute during
configuration. The set handler can then accept the value and write it to the attribute, or reject it.
A set handler can also perform other actions, like modifying the values of other attributes or
clamping a value.
When rejecting a value, a config time set handler should not generate an alarm, event, or Logger
message. Instead, return a localized message to the client.
To configure an attributes configtime set handler, first enable the Configuration Set Handler
option in the attributes configuration in Object Designer, as shown below. The ArchestrA Object
Toolkit then adds a set handler delegate and associated method to the Configtime Class in the
underlying code.

ConfigtimeSetHandlerEventArgs class
ConfigtimeSetHandlerEventArgs is a class that provides configtime set handlers with the
information they need when called.
Syntax
public class ConfigtimeSetHandlerEventArgs : SetHandlerEventArgs
Members
Message A string that the user can set to write a message back to the set handler
caller when an error or warning is needed. The message must be empty for the set
handler to be successful.
Syntax
string Message
Runtime set handler event

Use a runtime set handler to implement any logic required to set an attribute value at runtime,
including range checking and accepting or rejecting the set handler.
You can configure a runtime set handler for any attribute that can be written to at runtime. The
code in this set handler is executed whenever anyone other than the primitive logic associated
with that attribute attempts to write to it. The set handler can then accept the value and write it to
the attribute, or reject it.
A set handler can also perform other actions, like modifying the values of other attributes or
clamping a value.
When the set handler is called at runtime, it is passed not only the new value, but also information
about the client making the call (whether the client is a user, another object, or another primitive
within the same object). The set handler can take this information into account when deciding
whether to accept the new value.
When rejecting a value, runtime set handlers should not generate an alarm, event, or Logger
message. Instead, return an appropriate error code to the client.
To configure an attributes runtime set handler, first enable the Runtime Set Handler option in the
attributes configuration in Object Designer. The ArchestrA Object Toolkit then adds a set handler
delegate and associated method to the Runtime Class in the underlying code.
Wonderware Training
RuntimeSetHandlerEventArgs class
RuntimeSetHandlerEventArgs is a class that provides runtime set handlers with the information
they need when called.
Syntax
public class RuntimeRuntimeSetHandlerEventArgs : RuntimeSetHandlerEventArgs
Members
attributeInfo the SetInfo of the current set
Syntax
SetInfo attributeInfo
status A status to report the status of the set handler back to the caller
Syntax
MxStatus status
Time The timestamp of the value being set
Syntax
DateTime Time
Quality The data quality of the value being set
Syntax
CMxDataQuality Quality
Runtime GetStatusDesc event

The GetStatusDesc event is used for returning an error status string at runtime. The
RuntimeGetStatusDesc event occurs when the runtime component requests a detailed message
for an error, for example, after a set handler returns a failure. The ArchestrA Object Toolkit
automatically generates code to register the delegate
<objectname>Runtime_RuntimeGetStatusDesc for this event.
Syntax
public event RuntimeGetStatusDescDelegate RuntimeGetStatusDesc;
RuntimeGetStatusDescEventArgs class
This class is the argument to the GetStatusDescription event.
Syntax
public class RuntimeGetStatusDescEventArgs : EventArgs
Members
status A string describing the detailed error code.
Syntax
string status
detailedErrorCode The detailed error code to look up for a description.
Syntax
short detailedErrorCode

Wonderware Training
Lab 3 Implementing Set Handlers

Introduction
In this lab you will extend the functionality of the Counter object you created in the previous lab.
You will add a MaxCount attribute that will cause the count to automatically reset to zero when the
maximum count is reached. You will also add a Reset attribute that can be used to manually reset
the count in runtime. To ensure that changes to the value of the MaxCount and Reset attributes
are handled correctly, you will implement their corresponding configtime and runtime set handlers.
Finally, you will modify the editor of the counter to enable users to set MaxCount in the ArchestrA
IDE.
Count
MaxCount
Reset
MaxCount_ConfigtimeSH() Note: See page 2-19 for
Counter MaxCount_RuntimeSH() a legend to this graphic.
Reset_RuntimeSH()
Execute()
GetStatusDesc()
EDITOR
Objectives
Add and implement runtime and configuration time set handlers
Modify the GetStatusDesc runtime method to return detailed error messages to users
Implement a simple editor for an object


Add the MaxCount and Reset attributes (page 2-45)

a. In Microsoft Visual Studio, ensure that the Counter solution is opened.
b. Use Object Designer to add the following attributes:
External Name Type Category Additional Configuration

MaxCount Integer Writeable_USC_Lockable Configuration Set Handler: Check
Runtime Set Handler: Check
Value: 100
Security Classification: Operate
Reset Boolean Writeable_US Runtime Set Handler: Check
Modify the runtime logic (page 2-45)

c. Modify the Execute method of the Runtime project to make it look exactly like this:
{

//But only if Count has not reached MaxCount
if (Count < MaxCount)
{
//Count has not reached max. Increment it.
Count++;
}
else
{
//Count has reached max. Reset to zero.
Count = 0;
}
}
Wonderware Training
Implement configuration set handler (page 2-46)

d. Modify the Configtime Set Handler for the MaxCount attribute to make it look exactly like
this:
private void MaxCountSetHandler(object sender, ref
ConfigtimeSetHandlerEventArgs e)
{
//Verify that the set value is greater than zero
if (e.Value > 0)
{
//Valid set value. Set MaxCount.
MaxCount.SetHandlerValue = e;
}
else
{
//Invalid set value. Return error message.
e.Message = "MaxCount must be greater than 0";
}
}
Implement runtime set handlers (page 2-46)

e. Modify the Runtime Set Handler for the MaxCount attribute to make it look exactly like this:
RuntimeSetHandlerEventArgs e)
{
if (e.Value > 0)
{
}
else
{
//Invalid set value. Return error information
e.status.Category =
MxStatusCategory.MxCategoryOperationalError;
e.status.detectedBy =
MxStatusSource.MxSourceRespondingAutomationObject;
//The detailed error code will be passed to the GetStatusDesc

//method in order to return an error message string
e.status.detail = 10001;
}
}
f. Modify the GetStatusDesc method of the Runtime project to make it look exactly like this:
private void CounterRuntime_RuntimeGetStatusDesc(object sender, ref
RuntimeGetStatusDescEventArgs e)
{
//Return the correct error message based on the
//detailed error code passed by the Set Handler
switch (e.detailedErrorCode)
{
case 10001:

e.status = "MaxCount must be greater than 0";

break;
default:
e.status = GetText((int)e.detailedErrorCode);
break;
}
}
g. Modify the Runtime Set Handler for the Reset attribute to make it look exactly like this:
private void ResetSetHandler(object sender, ref RuntimeSetHandlerEventArgs e)
{
//If the attribute is set to true, reset Count
if (e.Value)
{
//Reset Count
Count = 0;
}
//The Reset attribute is never modified

//It will always keep its initial value in runtime
}
Modify the Editor (page 2-48)

h. Open the Editor form, and rename the tabPage1 tab to General (Text property).
i. Change the Name property to generalTab.
j. From Object Design View, drag the MaxCount attribute onto the General tab.
k. Save the project.
Build and import the object (page 2-50)

l. Use the ArchestrA Object toolbar to build, import, and instantiate the Counter object.
m. In the ArchestrA IDE, open the editor for the Counter_001 instance, and verify that MaxCount
must be greater than zero.
n. Deploy the Counter_001 instance.
o. Open Object Viewer and, if not opened yet, open the watch window you created in the
previous lab.
p. Add the following attributes to the watch window:
Object Attribute
Counter_001 MaxCount
Counter_001 Reset
q. Save the modified watch list.

r. Verify the runtime behavior of the object.
Wonderware Training

Add the MaxCount and Reset attributes

1. In Microsoft Visual Studio, ensure that the Counter solution is opened.
2. On the ArchestrA Object toolbar, click the Object Designer button.
3. In Object Designer, add and configure the following attributes:

MaxCount Integer Writeable_USC_Lockable Configuration Set Handler: Check
Value: 100
4. Click OK to close the Object Designer.
Modify the runtime logic

5. In Object Design View, under Runtime, double-click Execute.
6. In the CounterRuntime.cs file, modify the Counter_RuntimeExecute method, which you
modified in the last lab, to make it look exactly like this:
{

//But only if Count has not reached MaxCount
{
Count++;
}
else
{
Count = 0;
}
}

Implement configuration set handler

7. In Object Design View, expand Configtime and double-click MaxCount Set Handler.
8. In the CounterConfigtime.cs file, modify the MaxCountSetHandler method to make it look
exactly like this:
{
if (e.Value > 0)
{
}
else
{
e.Message = "MaxCount must be greater than 0";
}
}
Implement runtime set handlers

9. In Object Design View, under Runtime, double-click MaxCount Set Handler.
10. In the CounterRuntime.cs file, modify the MaxCountSetHandler method to make it look
exactly like this:
{
if (e.Value > 0)
{
}
else
{
e.status.Category =

}
}
Wonderware Training
11. In Object Design View, under Runtime, double-click GetStatusDesc.

12. Modify the CounterRuntime_RuntimeGetStatusDesc method to make it look exactly like
this:
{
{
case 10001:
break;
default:
break;
}
}
13. In Object Design View, under Runtime, double-click Reset Set Handler.
Note: You could also open the code by expanding Attributes and Reset, and then double-
clicking Runtime Set Handler.
14. Modify the ResetSetHandler method to make it look exactly like this:
{
if (e.Value)
{
//Reset Count
Count = 0;
}

}

Modify the Editor

15. In Object Design View, double-click Editor.
The pre-configured Editor form appears showing one tab page named tabPage1.
16. Right-click anywhere on the tabPage1 control and click Properties.

17. Locate the Text property and change it to General.
Wonderware Training
18. Locate the Name property and change it to generalTab.
19. In Object Design View, expand Attributes and drag the MaxCount attribute onto the
General tab.
20. Save the project.

Build and import the object

21. On the ArchestrA Object toolbar, ensure that the Build Mode is set to Build & Instantiate.
22. Click the Build Object button to build the Counter object and import it in the Galaxy.
24. In the ArchestrA IDE, double-click the Counter_001 instance to open its editor.
25. On the General tab, verify that MaxCount must be greater than zero.
26. Close the editor without saving.

Wonderware Training
29. If the watch window (bottom pane) you created in the previous lab is not opened, right-click in
the watch window, click Open, and open Dev Watch Windows.
30. Add the following attributes to the watch window:
MaxCount
Reset
31. Save the modified watch list.

32. In the watch window, verify the following runtime behaviors of the Counter object:
The Count value is counting and wraps around to 0 after hitting the maximum value
(MaxCount)
The MaxCount value cannot be set to a value less than zero
The Count value restarts at zero when Reset is set to true

Wonderware Training
Section 3 Runtime Events
Section Objectives
Describe how runtime event handlers are used and when they are triggered
List the runtime event handlers that are enabled on all application objects
This section describes how to add and implement runtime event handlers.
Runtime event handlers

An ArchestrA application object and each of its local primitives have a variety of runtime events
that you can link with custom handler code. Runtime events are part of the RuntimeBase class and
are only available at runtime.
Runtime event handlers are triggered when an object is executed at runtime. By implementing
handlers for these events, you can link custom code with these events. For example, you could
execute certain code on every scan cycle.
Application objects have a number of runtime event handlers already enabled. You can see these
in the Object Design View tree by expanding Runtime.
Runtime
events

The following table describes these runtime event handlers.
Event Occurs
Execute On every scan cycle of the hosting AppEngine while the object is On Scan
GetStatusDesc When the runtime component requests a detailed message for an error, for example,
after a set handler returns a failure
Initialize After the object is created in runtime (usually after deployment, but also after a failover
or after the bootstrap is restarted). Occurs before the Startup event. No attribute
information is available at this time
SetScanState When the objects scan state (On Scan/Off Scan) is changed
Shutdown When the object is shutting down (usually after the object is set to Off Scan, but during
a failover Off Scan may not be set). This event does not occur if the object goes off the
network during a network failure
Startup When the object is being started (after the Initialize event and before it goes On Scan).
You can use the events startup context to find out whether the object is starting up
after a failover or other reasons.
[attribute]SetHandler When the value of an attribute is changed at runtime.
Execution order for runtime events

The graphic on the next page shows the execution order of the runtime events described below.
1. When you deploy the object, the runtime code gets instantiated. As soon as the runtime DLL is
instantiated, the system calls Initialize. At this time, the attributes in the object are not
available.
2. Immediately, the system will instantiate the attributes in the object, and once they are
available, you can initialize the attributes and the system calls Startup.
3. The object then needs to be executed, so the system calls SetScanState and puts the object
Off Scan.
When you deploy an object, you have the option to deploy it On Scan or Off Scan. If you deploy
the object Off Scan, then the deployment will stop and wait for you to manually set the object On
Scan at some point in runtime.
4. If you deploy the object On Scan, then the system calls SetScanState and puts the object On
Scan. At this point you can manipulate any attributes that need to be initialized or reset upon
Off Scan or On Scan.
5. Once the object in On Scan, the application engine will execute every scan, so the system
calls Execute every single scan of the application engine.
6. At this time, if any value or external source starts to write to an attribute, the corresponding set
handler for that attribute gets called ([attribute]SetHandler).
Note: Set handlers run independently from the Execute method. They do not need to be
called during the execution of the object or only when the object is On Scan. As long as the
object is instantiated, the set handlers get called every time the engine receives a request to
write. This can be between scans, or even if the object is Off Scan.
At this point, you can leave the object On Scan, and the object will execute continuously, or you
can set the object Off Scan and undeploy the object.
7. Before the object is undeployed, the system calls Shutdown. Here you can run any shutdown
logic you may have, for example you could close any opened files to free resources you have
allocated during the execution of the object.
Wonderware Training
DeployinganObject
Initialize 1
Startup 2
FALSE
TRUE
SetScanState 3 4
Execute 5
[Attribute]SetHandler 6
Shutdown 7

Wonderware Training
Lab 4 Enhancing the Counter Object

Introduction
In this lab you will enhance the functionality of the Counter object you have worked with in
previous labs. You will implement runtime event handlers (other than the Execute event) that
affect the runtime behavior of the object. You will add a ResetOnScan attribute that will control
whether the count is to reset to zero when the object is set On Scan. You will also modify the
Startup runtime event to initialize the object upon deployment. Finally, you will modify the editor of
the counter to enable users to set ResetOnScan in the ArchestrA IDE.
Count
MaxCount
Reset
Note: See page 2-19 for
Counter ResetOnScan a legend to this graphic.
SetScanState()
Startup()
EDITOR
Objectives
Implement runtime event handlers, such as Startup and SetScanState


Add the ResetOnScan attribute (page 2-60)

b. Use Object Designer to add the following attribute:

ResetOnScan Boolean Writeable_USC_Lockable Frequently Accessed: Check
Security Classification: Configure

c. Modify the SetScanState method of the Runtime project to make it look exactly like this:
private void Counter_RuntimeSetScanState(object sender,
RuntimeSetScanStateEventArgs e)
{
//Code in this method is executed in runtime
//every time the Scan State of the object changes
if (e.onScan)
{
//Object is set On Scan. Check whether ResetOnScan is true
if (ResetOnScan)
{
//Reset count to zero
Count = 0;
}
}
}
d. Modify the Startup method of the Runtime project to make it look exactly like this:
private void Counter_RuntimeStartup(object sender,
RuntimeStartupEventArgs e)
{
//when object is starting
//Initialize runtime attributes

//as a Toolkit best practice
Count = 0;
Reset = false;
// RestoreDynamicAttributes will recreate the Dynamic Attributes and

restore the check pointed
// values during failover startup. The Failover Support for Dynamic
Attributes option must
// be enabled via the Object Editor to support this function. To
maintain the
// Dynamic Attribute values the CheckpointDynamicAttributeData function
must be called
Wonderware Training
// when Dynamic Attribute values are modified (refer to the Dynamic

Attribute Set Handler).
//RestoreDynamicAttributes();
// Execute offscan code to initialize the object in its offscan state.

SetScanState(false);
// Suspend marked attributes at startup

AdviseOnlySuspendAttributes();
}

e. Open the Editor form, and drag the ResetOnScan attribute onto the General tab.
f. Save the project.

g. Use the ArchestrA Object toolbar to build, import, and instantiate the Counter object.
h. In the ArchestrA IDE, deploy the Counter_001 instance.
i. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
j. Add the following attributes to the watch window:
Object Attribute
Counter_001 ResetOnScan
Counter_001 ScanState
Counter_001 ScanStateCmd
k. Save the modified watch list.

l. Verify the runtime behavior of the object.


Add the ResetOnScan attribute

2. In Object Designer, add and configure the following attribute:

ResetOnScan Boolean Writeable_USC_Lockable Frequently Accessed: Check
Security Classification: Configure
Wonderware Training

4. In Object Design View, under Runtime, double-click SetScanState.
5. In the CounterRuntime.cs file, modify the Counter_RuntimeSetScanState method of the
Runtime project to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
}
}
}
6. In Object Design View, under Runtime, double-click Startup.

7. Modify the Counter_RuntimeStartup method of the Runtime project to make it look exactly
like this:
private void Counter_RuntimeStartup(object sender,
{
//when object is starting
//Initialize runtime attributes

//as a Toolkit best practice
Count = 0;
Reset = false;

maintain the
must be called


}

Modify the Editor

9. In Object Design View, under Attributes, drag the ResetOnScan attribute onto the General
tab.

12. Click the Build Object button to build the Counter object and import it into the Galaxy.
14. In the ArchestrA IDE, deploy the Counter_001 instance.
16. If not already opened, open the watch window you have used in previous labs.
ResetOnScan
ScanState
ScanStateCmd
Wonderware Training
19. In the watch window, verify the following runtime behavior of the Counter object:
When ResetOnScan is false, the Count value does not restart at zero when the object is
set Off Scan and then back On Scan.
When you set ResetOnScan to true, the Count value restarts at zero when the object is
set Off Scan and then back On Scan.
Note: The object must be set Off Scan before the ResetOnScan attribute can be modified
because you configured the attribute with a Security Classification of Configure in step 2.

Wonderware Training
Section 4 Configtime Events
Section Objectives
Describe how configtime event handlers are used and when they are triggered
List the configtime event handlers that are enabled on all application objects
List the optional configtime event handlers
This section describes how to add and implement configtime event handlers.
Configtime event handlers

An ArchestrA application object and each of its local primitives have a variety of configtime events
that you can link with custom handler code. Configtime events are part of the ConfigtimeBase
class and are only available at configtime.
Configtime event handlers are triggered when a user configures or works with an object in the
ArchestrA IDE. By implementing handlers for these events, you can link configuration actions with
custom code. For example, you could execute certain code after an object instance is created.
Standard configtime event handlers

All application objects have the following standard configtime event handlers enabled:
Event Occurs
Initialize When the object is initialized. Use this event handler for any custom initialization
code.
Migrate When derived templates or instances are migrated.
PostCreate After the object (instance or derived template) is created
PreValidate Before the object is validated (when the user has edited its configuration and saves it)
Validate When the object is validated. Use this event handler for any custom validation code
(for example, checking for invalid combinations of attribute values)
[attribute]SetHandler When the value of an attribute is changed at configtime.

Execution order for standard configtime events

The graphic below shows the order that these configtime events get called when you create a new
object, use the editor, or use the Galaxy Load feature.
Createa Usingthe GalaxyLoad GalaxyLoad

newObject Editor
NewObject ExistingObject
Initialize 1 1 1 1
PostCreate 2 2
[Attribute]SetHandler 2 3 2
PreValidate 3 3 4 3
Validate 4 4 5 4
Wonderware Training
Optional configtime event handlers

In addition to the standard configtime event handlers, there are various optional configtime event
handlers. To use these event handlers, you must first enable them in the Object Designer, as
shown below.
With the object selected in the Shape pane, check the Configuration Event Handlers check box
in the Configuration pane. The section expands to expose a list of configuration events that you
can implement.
The following optional configtime event handlers can be enabled.

Event Occurs
Pre Rename Before object is renamed
Post Rename After object is renamed
Pre CheckIn Before object is checked in
Post CheckIn After object is checked in
Pre Deploy Before object is deployed
Pre Undeploy Before object is undeployed
Post Deploy After object is deployed
Post Undeploy After object is undeployed
Pre Delete Before object is deleted
Post Delete After object is deleted
Pre Unassign On a child object before it is unassigned from its parent
Pre Assign To On a parent object before a new child object is assigned to it
Post Unassign On a child object after it is unassigned from its parent
Post Unassign From On a parent object after a child object is unassigned from it
Post Assign On a child object after it is assigned to its new parent
Post Assign To On a parent object after a new child object is assigned to it

Wonderware Training
Module 3
Utility Primitives
Section 1 Primitives Overview 3-3
Section 2 Utility Primitives Overview 3-7
Lab 5 Adding a Counter Input 3-11
Lab 6 Adding Counter Alarms and History 3-21
Section 3 Quality and Timestamp Handling 3-37
Lab 7 Handling Quality in the Counter Object 3-41
3-2 Module 3 Utility Primitives
Module Objectives
Using the utility primitives included with the ArchestrA Object Toolkit, configure an
application object with alarming, history, input, and quality handling capabilities
Wonderware Training
Section 1 Primitives Overview
Section Objectives
Explain what primitives are and how they are structured in an application object
Identify the different types of primitives
This section provides an overview of primitives and describes the different types of primitives.
Primitives
Primitives are building blocks of code containing specific functionality for an application object.
Like the main application object, primitives have their own attributes and their own configtime and
runtime behaviors. In addition, a primitive can leverage the attributes and behaviors of other
primitives by including the other primitive as a child primitive. A primitive can be contained locally
in one object, or it can be standalone and reused in multiple objects.
By using primitives to separate your code into different blocks or layers, you can write your code
easier, create a more logical structure for your code, isolate where the code is coming from if
something is not working, and reuse your code in other projects.
Primitives and application objects structure

An application object is really a collection of two or more primitives, with each primitive containing
a series of attributes, runtime code, and configtime code to implement a particular block of logic
within the object. Together, these primitives define the overall behavior of an object.
As stated in the previous module, objects consist of four pieces or components: Attribute
Definitions, Runtime, Configtime, and Editor. The Attribute Definitions, Runtime, and Configtime
pieces are actually collections of components associated with primitives, as shown below.
.aaDEF DLL DLL

CommonPrimitive
.aaDEF DLL DLL

CustomPrimitive1
DLL
.aaDEF DLL DLL

CustomPrimitive2
Attribute
Runtime Configtime Editor
Definition

As shown in the previous graphic, a primitive consists of a set of Attribute Definitions (stored in
an aaDEF file), and one or more components that implement behavior associated with those
attributes. The configuration behavior is implemented as a primitive Configtime component (DLL
file), and the runtime behavior is implemented as a primitive Runtime component (DLL file).
At a minimum, an object always includes the Common primitive (which contains attributes
common to all objects), and the topmost Local primitive (which contains attributes and behaviors
unique to the object). The topmost Local primitive is special. Its icon in the Object Designer
represents a primitive as well as the overall object. It will normally be the only primitive containing
editor implementation files, since objects provide a single unified editor to users.
All attributes combine to form the Namespace of the object. Everything is done by getting and
setting an objects attributes.
Note: Editors Get or Set attributes by name. They do not know anything about primitives.
Object primitives have a hierarchical relationship to one another: Parents know about the children,
but child primitives (especially reusable ones) typically do not know about their parents. This
relationship enables complex primitives to be built out of simpler ones. For example, ArchestrA
application objects leverage (child) Input/Output primitives to communicate with other objects or
field devices.
A primitives logic refers to its attributes or to the attributes of its child primitives. If necessary, a
primitive can refer to the attributes of parents and siblings (more rare).
A primitive is an implementation detail. At most it is visible to the user as a dotted prefix common to
the names of the attributes within it. Within the ArchestrA IDE, some visible primitives are called
extensions. One example of an extension primitive is a script attached to an object.
Types of primitives
There are three main types of primitives, which are discussed below and in other sections of this
manual.
Common primitive
Every application object automatically has a common primitive, which provides the set of attributes
(Tagname, ScanState, ShortDesc, etc.) and behaviors required by all application objects. This
common primitive is included as support for the ArchestrA framework. This primitive is hidden and
cannot be modified or removed.
Note: The Common primitive has no representative icon in the Object Designer, although its
attributes can be seen in the Object Viewer when the hidden attributes option is enabled.
Local primitives
Local primitives provide unique functionality for a single application object. They are defined and
used in only that single object. Every object contains at least one local primitive (the topmost Local
primitive). Other local primitives (children of the topmost) will typically be used to define optional
attributes and will usually be marked as Virtual.
A virtual primitive allows you to dynamically add and delete instances of the primitive at configtime.
Primitives can be marked Virtual when they are configured and added to an object. These
primitives are designed and implemented in the same way as other primitives. For more
information, see Virtual Primitives Overview on page 5-3.
Wonderware Training
For more information on local primitives, see Local Primitives Overview on page 6-3.
Reusable primitives
Reusable primitives are standalone primitives that can be reused in multiple application objects,
providing a mechanism for component-level code sharing across objects. Organizing common
functionality into reusable primitives makes it easier to maintain code.
The ArchestrA Object Toolkit includes predefined reusable primitives called Utility primitives.
These primitives allow objects created from your templates to access ArchestrA framework
features such as alarms, history, and inter-object communication by simply accessing the
attributes of those primitives. For more information, see Utility Primitives Overview on page 3-7.
You develop reusable primitives independently, similar to developing an object. You create a
separate Microsoft Visual Studio project for every reusable primitive you create.
For more information on reusable primitives, see Reusable Primitives Overview on page 6-19.
Both reusable primitives and local primitives (see above) can be made as Virtual primitives. For
more information, see Virtual Primitives Overview on page 5-3

Wonderware Training
Section 2 Utility Primitives Overview
Section Objectives
Summarize what utility primitives are and how they are used
This section describes the utility primitives that are included with the ArchestrA Object Toolkit.
Utility primitives
Utility primitives are predefined reusable primitives that are included with the ArchestrA Object
Toolkit. They provide historization, alarming, input, and output capabilities for your object. A typical
application object will use one or more of these utility primitives.
Utility primitives are added within the Object Designer, by either adding the primitive in the Shape
pane (I/O primitives) or checking the Alarmable or Historizable check boxes in the
Configuration pane for a Boolean attribute.
Input primitives
The Input primitive provides the hosting primitive the capability of collecting data from another
ArchestrA object. There is only one generic Input primitive, and it is used for all data types.
The Input primitive performs the key function of reading data from an attribute in an application
object. The Input primitive is usually configured by the end user with a reference string that
indicates the input source location. Any attribute within any application object can be configured as
the input source.
Use this primitive to read one piece of data of any data type. If you know the expected data type,
then specify it and lock it within the Object Designer after you add the Input primitive. Give the
primitive a useful external name that indicates its purpose to the end user.
Output primitives
The Output primitive provides the hosting primitive the capability to request that a value of any
data type be written to an attribute of another ArchestrA object.
There is only one generic Output primitive, and one or more Output primitives can be used in a
template. You define the data type of the output when the Output primitive is embedded in the host
primitive.
The Output primitive performs the key function of writing data to an attribute in an application
object. The Output primitive is configured by the end user with a reference string that indicates the
output destination. Any attribute within any application object can be configured as the output
destination.
Use this primitive to write one piece of data of any data type. If you know the expected data type
(this will typically be the case), then specify it and lock it within the Object Designer after you add
the Output primitive. Give the primitive a useful external name that indicates its purpose to the end
user.
Input/Output primitives
The Input/Output primitive performs the key functions of reading data from and writing data to an
attribute in an application object. The Input/Output primitive is configured by the end user with

either one or two reference strings that indicate the input source and output destination locations.
Two locations are used in the case when the input is read back from a secondary source location
that is different from the output destination location. Some field devices may be set up with
separate input and output locations for security or robustness purposes.
Use this primitive to read and write data of any data type. If you know the expected data type, then
specify it and lock it within the Object Designer once you add the Input/Output primitive. Give the
primitive a useful external name that indicates its purpose to the end user.
Alarm primitives
The Alarm primitive performs the key function of generating an alarm report once an alarm
condition has been detected. The Alarm primitive is added within the Object Designer by indicating
that a Boolean attribute is Alarmable. The Boolean attribute thereby indicates an Alarm condition,
and if the Alarm primitive is enabled, then an Alarm is generated at runtime when the Boolean
attribute transitions from false to true. Likewise, the Alarm is cleared (returned-to-normal) when the
Boolean attribute returns to false. The object or primitive that contains the Boolean attribute is
responsible for setting the attribute false or true.
Behind the scenes, the following happens when an attribute is marked alarmable:
A virtual Alarm primitive is added to the object and associated with the specified attribute.
An associated Boolean attribute .Alarmed is added which will appear in the object's
editor. This allows System Engineers to specify whether alarming that attribute is actually
required or not.
ArchestrA Object Toolkit automatically generates the set handler logic for the .Alarmed attribute
which adds or removes the actual non-virtual alarm primitive.
Once added, the Alarm primitive can be configured in the Object Designer to indicate other pieces
of information that are to be reported with the alarm. These pieces of information include the
current value that triggered the alarm, the limit value that was violated, the alarm category, the
engineering units string, and the alarm message string. The alarm message defaults to the
object's ShortDesc attribute in the Common primitive. However, it can be reconfigured by the end
user to refer to any String or InternationalString attribute within the ArchestrA IDE by use of the
editor. Thereby, the capability of specifying custom alarm message text is provided.
The Alarm primitive can be either concrete or virtual. If concrete, it is always deployed with the
object. If virtual, it is deployed only if the end user enables it. Make Alarm primitives virtual if you
want to allow the System Engineer to specify whether a condition should be reported to the alarm
subsystem. If virtual, the object's Package code is responsible for adding or removing the alarm
primitive when the end user indicates to do so. The Alarm Primitive is configured by the end user
with an alarm priority and an alarm message attribute that contains a custom alarm message
string.
Lock down any attributes (such as Category, Engineering Units) that are not to be changed. The
Object Designer automatically gives the primitive a useful external name that corresponds to the
Boolean attribute being alarmed.
Deciding which attributes are alarmable

Attributes which represent potential alarm conditions can be marked alarmable in the Object
Designer. Limit the alarmable attributes to those attributes of the object that almost all engineers
would want to alarm. Other attributes can always be alarmed using the Extensions tab of the
editor.
Wonderware Training
If this option is enabled when the object is designed, it will make it easier for engineers to set up
alarm reporting for an attribute, but it also introduces more choices that must be made when the
object is configured.
History primitives
The History primitive performs the key function of recording history for an attribute. The History
primitive is added within the Object Designer by indicating that an attribute is Historizable.
Behind the scenes, the following happens when an attribute is marked historizable:
A virtual History primitive is added to the object and associated with the specified attribute.
An associated Boolean attribute .Historized is added which will appear in the object's
editor. This allows System Engineers to specify whether historization of that attribute is
actually required or not.
ArchestrA Object Toolkit automatically generates the package's set handler logic for the
.Historized attribute which adds or removes the actual non-virtual history primitive.
Once added, the History primitive can be configured in the Object Designer to indicate other
pieces of information that are to be stored within the history. These pieces of information include
the engineering units string attribute and default values for trend limits, value deadband, and force
storage period. Generally, those latter three attributes are configured by the end user.
The History primitive is always virtual and is only deployed if the end user enables it. The object's
Package code is responsible for adding or removing the history primitive when the end user
indicates to do so. The History primitive is configured by the end user with value deadband, force
storage period, and trend limits. Value deadband and trend limits are always in the engineering
units of the attribute being historized.
Deciding which attributes are historizable

Attributes which are potentially useful to store in history at runtime can be marked historizable in
the Object Designer. Limit the historizable attributes to those attributes of the object that almost
all engineers would want to historize. Other attributes can always be historized using the
Extensions tab of the editor.
If this option is enabled when the object is designed, it will make it easier for engineers to historize
an attribute, but it also introduces more choices that must be made when the object is configured.

Wonderware Training
Lab 5 Adding a Counter Input

Introduction
This lab demonstrates how to add an Input to the Counter object to make the count react to
external signals. You will add an Input primitive named Count.Input, and you will implement the
runtime logic necessary to make the count increment only upon change of the input value. You will
also modify the editor of the Counter to enable users to set the input source in the ArchestrA IDE.
To test the implemented functionality, you will use the Blinker object that was imported into your
Galaxy in Lab 1.
Count Blinker Bit

INPUTPRIM (Providedby
Count.Input Instructor)
MaxCount
Counter Reset
ResetOnScan
OnExecute() Note: See page 2-19 for a
EDITOR legend to these graphics.
Objectives
Add and manipulate Input primitives in an application object


Add the Counter Input (page 3-14)

b. Use Object Designer to add an Input primitive, and configure it as follows:
External Name Internal Name Primitive Attributes Configuration
Count.Input CounterInput Attribute Value
DataType MxDouble (and lock it)

c. Modify the Declarations region of the Runtime project to make it look exactly like this:
#region Declarations
//Declare Runtime Class Variables here.
//Variables declared in this region are available to all methods
//in the Runtime Class.
//Variable used to store Input value from previous scan

double lastInputValue;
#endregion Declarations
{

//But only if the Input value has changed
if (CounterInput.Value.Value != lastInputValue)
{
//Input value has changed since last scan

{
Count++;
}
else
{
Count = 0;
}
lastInputValue = CounterInput.Value.Value;
}
}
Wonderware Training

e. Open the Editor form, and drag the InputSource attribute of the Counter.Input primitive onto
the General tab.
f. Save the project.

g. Use the ArchestrA Object toolbar to build, import, and instantiate the Counter object.
h. In the ArchestrA IDE, create an instance of the $Blinker template located in the Training
toolset, accepting the default instance name.
i. Assign the Blinker_001 instance to DevArea.
j. Open the editor for Counter_001, and set Count.Input.InputSource to Blinker_001.Bit.
k. Deploy the Counter_001 and Blinker_001 instances.
l. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
m. Add a new watch window and rename it to Counter IO.
n. Add the following attributes to the new watch window:
Object Attribute
Counter_001 Count
Counter_001 Count.Input.InputSource
Counter_001 Count.Input.Value
Blinker_001 Bit
Blinker_001 ScanState
Blinker_001 ScanStateCmd
o. Save the modified watch list.

p. Verify the runtime behavior of the Counter by changing the scan state of the Blinker.


Add the Counter Input

2. In Object Designer, in the Shape pane, click the down arrow next to the Add button and click
Input.
3. In the Configuration pane, configure the primitive as follows:
External Name: Count.Input

Internal Name: CounterInput
Wonderware Training
4. In the Shape pane, under Count.Input, click DataType.

The Configuration pane displays the parameters for the DataType attribute.
5. Click the Value drop-down list and select MxDouble.
6. Click the Value fields lock icon .


8. In Object Design View, under Runtime, double-click Declarations.
9. In the CounterRuntime.cs file, expand the Declarations region and modify it so it looks
exactly like this:


{

{

{
Count++;
}
else
{
Count = 0;
}
}
}
Wonderware Training
Modify the Editor

13. In Object Design View, expand the Count.Input (CounterInput) primitive and drag the
InputSource attribute onto the General tab.

18. In the ArchestrA IDE, create an instance of the $Blinker template (located in the Template
Toolbox in the Training toolset), accepting the default instance name.
19. Assign the Blinker_001 instance to DevArea.

20. Open the editor for Counter_001, and set Count.Input.InputSource to Blinker_001.Bit.
21. Save and close the editor.

22. Deploy the Counter_001 and Blinker_001 instances.
25. Right-click in an empty area of the watch window, and click Add Watch Window.
Wonderware Training
26. Rename the tab Counter IO.

27. Add the following attributes to the new watch window:
Count
Count.Input.InputSource
Count.Input.Value
28. In the console tree on the left, click Blinker_001 [Blinker_001].

Bit
ScanState
ScanStateCmd

31. In the watch window, verify the following runtime behavior of the Counter object:
Count is halted when the input value stops changing
Note: You can stop the input from changing by setting the Blinker to Off Scan.

Wonderware Training
Lab 6 Adding Counter Alarms and History

Introduction
This lab shows how to add alarm and historization capabilities to the Counter object. You will make
the count historizable, which will associate a History Primitive with this attribute. To supply
adequate configuration parameters, you will create an attribute to configure Engineering Units for
the count.
You will also use an Alarm Primitive to implement a watchdog alarm that will rise whenever the
count input value remains unchanged for a certain configurable period of time. In order to
implement this, you will add several attributes, such as a time watchdog counter, an alarm limit,
and an alarm condition. You will ensure that the alarm limit remains within valid boundaries by
implementing the corresponding set handlers.
Finally, you will modify the editor of the Counter to enable users to set the newly added attributes
in the ArchestrA IDE.
Count
INPUTPRIMITIVE
Count.Input
HISTORYPRIM
CountHistory
TimeSinceChange
Timeout.Limit
Timeout.Condition
ALARMPRIMITIVE
Note: See page 2-19 for a
TimeoutAlarm
legend to this graphic.
Counter
EngUnits
MaxCount
Reset
ResetOnScan
SetScanState()
Execute()
Timeout_Limit_ConfigtimeSH()
Timeout_Limit_RuntimeSH()
GetStatusDesc()
EDITOR
Objectives
Make an attribute historizable, and configure the corresponding History Primitive
parameters
Make an attribute alarmable, and configure the corresponding Alarm Primitive parameters


Modify the shape of the Counter (page 3-27)

b. Use Object Designer to add the following attributes:

EngUnits String Writeable_C_Lockable Frequently Accessed: Check
TimeSinceChange Elapsed Time Calculated
Timeout.Limit Elapsed Time Writeable_USC_Lockable Configuration Set Handler: Check
Value: 00:00:05.000000 (5 seconds)
Security Classification: Tune
Timeout.Condition Boolean Calculated
c. For the Timeout.Condition attribute, check the Alarmable check box and configure the alarm
information as follows:
Category: System, and lock

Limit: Timeout.Limit, and lock
Value: TimeSinceChange, and lock
d. For the Count attribute, check the Historizable check box and configure the history
information as follows:
Engineering Units: EngUnits, and lock

Trend Scale Max: 100.0
Trend Scale Min: 0.0
Rollover Value: 100
Implement the alarm runtime logic (page 3-28)

e. Modify the Declarations region of the Runtime project to make it look exactly like this:

//Variable used to store last time input value changed

DateTime inputChangedTime;
Wonderware Training
f. Modify the SetScanState method of the Runtime project to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
}
//Initialize time of last input change to now

inputChangedTime = GetScanTime();
}
}
g. Modify the Execute method of the Runtime project to make it look exactly like this:
{

{

{
Count++;
}
else
{
Count = 0;
}
//Set time of last input value change to now

//Calculate time since last change

//And then use it to calculate alarm condition
TimeSinceChange = GetScanTime() - inputChangedTime;
Timeout_Condition = TimeSinceChange > Timeout_Limit;
}

Implement the alarm limit set handlers (page 3-30)

h. Modify the Configtime Set Handler for the Timeout.Limit attribute to make it look exactly like
this:
private void Timeout_LimitSetHandler(object sender, ref
{
if (e.Value > 0)
{
//Valid set value. Set Timeout Limit.
Timeout_Limit.SetHandlerValue = e;
}
else
{
e.Message = "Timeout Limit cannot be negative";
}
}
i. Modify the Runtime Set Handler for the Timeout.Limit attribute to make it look exactly like
this:
{
if (e.Value > 0)
{
}
else
{
e.status.Category =

}
}
Wonderware Training
j. Modify the GetStatusDesc method of the Runtime project to make it look exactly like this:
{
{
case 10001:
break;
case 10002:
e.status = "Timeout Limit cannot be negative";
break;
default:
break;
}
}

k. Open the Editor form.
l. Add a new tab, rename it alarmsTab, and change its text to Alarms.
m. From Object Design View, drag the following attributes onto the Alarms tab:
Timeout.Limit
Timeout.Condition
n. Add a new tab, rename it historyTab, and change its text to History.
o. From Object Design View, drag the following attributes onto the History tab:
EngUnits
Count
p. Save the project.

q. Use the ArchestrA Object Toolbar, to build, import, and instantiate the Counter object.
r. In the ArchestrA IDE, open the editor for the Counter_001 instance, and set the necessary
operational parameters, such as count input source, and the new alarm and history attributes.
Verify that the alarm limit cannot be set to a negative number.
s. Deploy the Counter_001 instance.
t. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
u. Add a new watch window and rename it to Alarms.

v. Add the following attributes to the new watch window:

Object Attribute
Counter_001 TimeSinceChange
Counter_001 Timeout.Limit
Counter_001 Timeout.Condition
Counter_001 InAlarm
DevArea AlarmOnCnt
w. Save the modified watch list.

x. Verify the runtime behavior of the timeout alarm by changing the scan state of the Blinker.
Verify that the alarm limit cannot be set to a negative number.
y. Verify that the count is being historized by using ActiveFactory Trend.
Wonderware Training

Modify the shape of the Counter

2. In Object Designer, add and configure the following attributes:

EngUnits String Writeable_C_Lockable Frequently Accessed: Check
TimeSinceChange Elapsed Calculated
Time
Timeout.Limit Elapsed Writeable_USC_Lockable Configuration Set Handler: Check
Time Runtime Set Handler: Check
Value: 00:00:05.000000 (5 seconds)
Security Classification: Tune
Timeout.Condition Boolean Calculated
3. In the Shape pane, click the Timeout.Condition attribute, and then in the Configuration
pane, check the Alarmable check box and configure the alarm information as follows:
Category: System, and lock

Limit: Timeout.Limit, and lock
Value: TimeSinceChange, and lock

4. Click the Count attribute, and then check the Historizable check box and configure the
history information as follows:
Engineering Units: EngUnits, and lock

Trend Scale Max: 100.0
Trend Scale Min: 0.0
Rollover Value: 100
Implement the alarm runtime logic

7. In the CounterRuntime.cs file, expand the Declarations region and modify it to look exactly
like this:


Wonderware Training

9. Modify the Counter_RuntimeSetScanState method to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
}

}
}

{

{

{
Count++;
}
else
{
Count = 0;
}




}
Implement the alarm limit set handlers

12. In Object Design View, under Configtime, double-click Timeout.Limit Set Handler.
13. In the CounterConfigtime.cs file, modify the Timeout_LimitSetHandler method to make it
look exactly like this:
{
if (e.Value > 0)
{
}
else
{
e.Message = "Timeout Limit cannot be negative";
}
}
14. In Object Design View, under Runtime, double-click Timeout.Limit Set Handler.
15. In the CounterRuntime.cs file, modify the Timeout_LimitSetHandler method to make it look
exactly like this:
{
if (e.Value > 0)
{
}
else
{
e.status.Category =

}
}
Wonderware Training

this:
{
{
case 10001:
break;
case 10002:
break;
default:
break;
}
}
Modify the Editor

19. Right-click on the Editor forms tab control (above the General tab page) and click Add Tab.
Tab control

20. Right-click anywhere on the tabPage1 control and click Properties.

21. Locate the Text property and change it to Alarms.
22. Locate the Name property and change it to alarmsTab.
23. From Object Design View, drag the following attributes onto the Alarms tab:
Timeout.Limit
Timeout.Condition
Wonderware Training
24. Remove the Attribute Category not supported in label and move the
Timeout.Condition label so the form looks similar to the following:
25. Add a new tab and change its Text property to History and its Name property to historyTab.
26. From Object Design View, drag the following attributes onto the History tab:
EngUnits
Count
27. Change the default controls and labels as needed to make the form look similar to the
following:
Hint: To change the EngUnits text box control to single line, change the Multiline property to
False.


32. In the ArchestrA IDE, open the editor for the Counter_001 instance.
33. On the General tab, set the count input source to Blinker_001.Bit.
34. On the Alarms tab, verify that the alarm timeout limit cannot be set to a negative number.
35. On the History tab, enter a valid value for engineering units and set the desired historization
parameters.
40. Add a new watch window and rename it to Alarms.
Object Attribute
Counter_001 TimeSinceChange
Counter_001 Timeout.Limit
Counter_001 Timeout.Condition
Counter_001 InAlarm
DevArea AlarmOnCnt
Wonderware Training

43. Verify the following runtime behaviors of the object:
The alarms work as expected when the input value stops changing
Note: You can stop the input from changing by setting the Blinker to Off Scan.
The alarm limit cannot be set to a negative number
Now you will use ActiveFactory Trend to verify that the count is being historized.
44. On the Start menu, click All Programs / Wonderware / ActiveFactory / Trend.
The Server List Configuration window appears.
45. In the Server field, enter LOCALHOST.
46. Check Use Integrated security, and then click Add.
47. Click Close.

48. In the Tags pane, double-click Counter_001.Count.

ActiveFactory Trend displays the Count data.
Wonderware Training
Section 3 Quality and Timestamp Handling
Section Objectives
Describe how to configure an object to support calculated quality and calculated time
List the guidelines for using calculated quality and time
This section describes and provides guidelines for calculated quality and calculated time usage.
Quality and timestamp

You may want to configure your object so it can set the quality and timestamp for an attribute
whose values are calculated at runtime. For example, this may be necessary if you use field data
(with potentially Bad or Uncertain quality) to calculate the attributes value.
You can use the Object Designer to enable and disable this functionality, as shown below.
Select the Supports Calculated Quality and Calculated Time check box if the object should be
able to set the attributes quality and timestamp. This inserts the appropriate code into the
attributes declaration statement. As the developer, you are responsible for writing code that
inspects the Quality states of source values and sets a resulting Quality state for the defined
attribute.
If you clear this check box, the attributes quality is always Good, and the timestamp is always the
objects startup time.
Calculated Quality
When an object calculates the value of an attribute, it usually is appropriate to also calculate that
value's quality. The quality of a calculated value is defined as the 16-bit OPC quality that can be
set to Good, Bad, or Uncertain. The ArchestrA environment additionally treats one substate of the
OPC Bad state as the special quality of Initializing. Initializing quality is Bad quality with the
Initializing bit set.

The table below describes the quality states.
Quality State Description

Good If the quality of an attributes value is Good, the associated value can be trusted and used.
However, the value could still be out of range or invalid (for example, NaN). Your object
must check for these conditions separately.
Uncertain If the quality is Uncertain, the associated value can be used, but there is some doubt about
the integrity of the value. For example, this could be the case when manually overriding an
attribute that is normally calculated automatically. When using an input with Uncertain
quality, do it with care and mark the resulting (calculated) attribute as Uncertain also.
Bad If the quality is Bad, there are a number of possible reasons. These include:
The object that contains the attribute set its quality to Bad because insufficient or bad
data was available.
The infrastructure returns Bad quality for an attribute when the attribute cannot be
accessed within Message Exchange. For example, the target attribute does not exist
or communication is faulty.
A field device may not be connected or accessible, resulting in Bad inputs that
propagate through the system.
Initializing Initializing quality is a form of Bad quality that requires special attention. It is temporary and
only occurs while an object is initialized. It lasts until the object receives its first input data
value. The quality then goes to Good, Bad (non-Initializing) or Uncertain.
Before you use data values in calculations and logic, always check their quality. For example, it
does not make sense to calculate the average of two values if one or both values have Bad
quality, since Bad quality indicates that the value is not to be used or trusted. Instead, in this case,
you should skip the calculation of the average and set the resulting attribute to Bad quality itself.
The ArchestrA infrastructure does not automatically enforce a specific value (such as IEEE NaN)
when quality is Bad, or a specific quality (such as Bad) when a value is NaN. Your object must
check for these conditions before using any values in logic or calculations. For example, a float
value read from a field device may have a value of NaN but Good quality. In that case, the object
must be aware that the value may be unusable for a calculation. Conversely, a value read from a
UDA attribute may be 4.3 but Bad quality. Again, the object must inspect the quality first, realize it
is Bad, and take appropriate action.
Guidelines for using calculated quality

If an attributes value is set by the objects runtime logic, enable the Supports Calculated
Quality and Calculated Time option for that attribute in the Object Designer.
For static attributes (attributes that you didnt create programmatically), you can use the
auto-generated wrapper to access the attributes quality. For example:
Attribute1.Quality = DataQuality.DataQualityGood;
Set such attributes to Bad quality when the object goes OffScan. Set them to Initializing
quality when the object goes OnScan.
Do not use an input value with Bad (including Initializing) quality in a calculation. Instead,
set the result quality Bad or Initializing (if input was Initializing) and leave the value at the
last value. (For a float or double result, consider setting the result to NaN.)
Do not use a NaN (float or double) input in a calculation. Instead, set the result to Bad
quality and leave the result value at the last value, or set it to NaN if it is a float or double.
If an illegal combination of input values exists, set the resulting quality to Bad.
Optionally, provide an option to report a bad value alarm when a result value has Bad
quality. Do not report a bad value alarm when a value has Initializing. Otherwise,
transient alarms occur when the object goes OnScan.
Wonderware Training
Do not trigger any other alarms when the quality of an attribute goes Bad. For example, do
not trigger a PV change-of-state alarm when the PV goes to some default state after its
quality goes Bad. Instead, always use a separate alarm for bad value reporting.
Inputs with Uncertain quality can be used with care. Set the result to Uncertain quality also
to indicate its questionable status.
Do not generate Logger messages when setting an attribute to Bad quality in the cases
outlined above.
Do not attempt to change the quality of an input, output, or input/output by using its
wrapper. This is not supported and may result in unexpected I/O values being written.
Calculated Time
Guidelines for using calculated time

In most cases, it is appropriate to enable the Supports Calculated Quality and
Calculated Time option for values whose value is calculated at runtime.
For attributes that are updated based on the value of an input or input/output, set the time
of the attribute to the input value's time. This ensures that timestamps are propagated
properly.
Attribute1.Time = Input1.Value.Time;
When setting the value of a calculated attribute that is not connected to an input, it is
usually best practice to set the time to the current time. For attributes that have the
Supports Calculated Quality and Calculated Time option enabled, the system
automatically does this when you set the value.
When setting the value of an attribute based on the value from another object, make sure
to set the time of the attribute to the time from the CMxIndirect value. This ensures that
timestamps are propagated properly.

Wonderware Training
Lab 7 Handling Quality in the Counter

Object
Introduction
In previous labs, you ignored the quality of the counter input during the runtime implementation of
the Counter object. In this lab, you will enable the object to support quality handling by taking into
account the input quality when calculating the count. You will then calculate the quality of the
Count attribute based on the following rules:
When set On Scan, the Count quality will be set to INITIALIZING
When set Off Scan, the Count quality will be set to BAD
While the object is On Scan, the Count quality and value will be calculated as follows:
Input Quality Count Quality Count Value

INITIALIZING Does not increment Does not increment
GOOD GOOD Increments as expected
UNCERTAIN UNCERTAIN Increments as expected
BAD UNCERTAIN Does not increment
None of the above UNCERTAIN Does not increment
To test the runtime behavior of the Counter, you will change the quality of the Bit attribute in the
provided Blinker object by using a series of runtime command attributes.
Count
INPUTPRIMITIVE
Count.Input
HISTORYPRIM
CountHistory
TimeSinceChange Bit
Timeout.Limit GoodQualityCmd
Blinker
Timeout.Condition (Providedby InitializingQualityCmd
Counter ALARMPRIMITIVE Instructor) UncertainQualityCmd
TimeoutAlarm
BadQualityCmd
EngUnits
MaxCount
Reset
ResetOnScan
SetScanState() Note: See page 2-19 for a
Execute() legend to these graphics.
EDITOR

Objectives
Add support for calculated quality and calculated time to an attribute
Handle attribute quality in runtime
Wonderware Training

Add support for calculated quality (page 3-46)

b. Use Object Designer to add support for calculated quality and calculated time to the Count
attribute.
Implement quality handling in runtime (page 3-46)

c. Modify the SetScanState method of the Runtime project to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
}
//Set quality to INITIALIZING

Count.Quality = DataQuality.DataQualityInitializing;

}
else
{
//Object is set Off Scan. Set quality to BAD
//but leave value unchanged
Count.Quality = DataQuality.DataQualityBad;
}
}

{

{
//Check for quality of the input
DataQuality inputQuality = CounterInput.Value.Quality;
switch(inputQuality)
{
case DataQuality.DataQualityGood :
//If input quality is GOOD
case DataQuality.DataQualityUncertain :
//or input quality is UNCERTAIN
//Increment Count value

{
Count++;
}
else
{
Count = 0;
}

//Set quality to input quality

Count.Quality = inputQuality;
break;
case DataQuality.DataQualityInitializing :
//If input quality is INITIALIZING
//Leave Count value and quality unchanged
break;
case DataQuality.DataQualityBad :
//If input quality is BAD
default :
//or input quality is unknown
//Leave Count value unchanged
//and set quality to UNCERTAIN
Count.Quality = DataQuality.DataQualityUncertain;
break;
}
}
Wonderware Training

}

e. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
f. In the ArchestrA IDE, open the editor for the Counter_001 instance, and set the count input
source to Blinker_001.Bit.
g. Deploy the Counter_001 instance.
h. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
i. Add the following attributes to the Counter IO watch window:
Object Attribute
Blinker_001 GoodQualityCmd
Blinker_001 InitializingQualityCmd
Blinker_001 UncertainQualityCmd
Blinker_001 BadQualityCmd
j. Save the modified watch list.

k. Verify the runtime behavior of count value and quality by manipulating the quality of the
Blinker. Also verify the quality of the Counter when the object is set On/Off Scan.


Add support for calculated quality

2. In Object Designer, click the Count attribute and check the Supports Calculated Quality
and Calculated Time parameter.
Implement quality handling in runtime

5. In the CounterRuntime.cs file, modify the Counter_RuntimeSetScanState method to make
it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
}

Wonderware Training

}
else
{
}
}

{

{
{

{
Count++;
}
else
{
Count = 0;
}


break;


break;
default :
break;
}
}

}

15. Right-click Blinker_001 and click View in Object Viewer.
17. Add the following attributes to the Counter IO watch window:
GoodQualityCmd
InitializingQualityCmd
UncertainQualityCmd
BadQualityCmd
Wonderware Training
19. In the watch window, verify the following runtime behaviors of the Counter object:
When the object goes On Scan, the Count quality is INITIALIZING
When the object goes Off Scan, the Count quality is BAD
While the object it being executed, the Count quality depends on the input value quality as
shown in the following table:
Input Quality Count Quality Count Value
INITIALIZING Does not increment Does not increment
GOOD GOOD Increments as expected
UNCERTAIN UNCERTAIN Increments as expected
BAD UNCERTAIN Does not increment
Note: You can control the input value quality by using the runtime command attributes in
the Blinker object.

Wonderware Training
Module 4
Error Handling and Debugging

Section 1 ArchestrA Logger Message Methods 4-3
Section 2 Configtime Validation 4-7
Lab 8 Implementing Configuration Validation 4-9
Section 3 Debugging 4-21
4-2 Module 4 Error Handling and Debugging
Module Objectives
Add the necessary logic to an object to implement configuration validation
In the context of the ArchestrA Object Toolkit., explain how to troubleshoot and debug
application objects
Wonderware Training
Section 1 ArchestrA Logger Message Methods
Section Objectives
Explain how to use the ArchestrA Object Toolkit Logger View
List the methods available for writing messages to the ArchestrA Logger
This section describes the Logger View, and provides information on using the methods provided
by the ArchestrA Object Toolkit to write messages to the ArchestrA Logger.
ArchestrA Logger messages

The ArchestrA Logger is a background process that stores messages in the system log file. To
view and monitor these messages, you can use the ArchestrA Object Toolkits Logger View,
shown below.
The Logger View displays errors and warnings reported by the ArchestrA Object Toolkit.
Note: You can clear all messages from the view by pressing Ctrl+R to reset the start time.
The Logger View can be shown or hidden by clicking the Logger View button on the ArchestrA
Object toolbar.
The Logger View window shows the same ArchestrA Logger messages that you see in the
ArchestrA Log Viewer in the ArchestrA System Management Console (SMC). The Logger View is
intended for quick reference; it does not offer the full functionality of the ArchestrA Log Viewer.
Writing messages to the Logger

You can write messages to the ArchestrA Logger using some of the methods provided by the
ArchestrA Object Toolkit. For example, You could write a warning message to the Logger when an
input source quality is bad or unknown, or write a trace message whenever a count is reset On
Scan.
Note: By default, trace logger messages are not displayed in the Logger. To display these, you
need to enable the trace log flag in the Log Flag Editor. See page 4-5.

Use the Logger only for tracing trapped software errors or diagnostics, and only use it sparingly in
production objects. Do not use it to provide information that is intended for operators. Operators
dont typically look at the Logger information, but rely on alarm and quality information instead.
If you use the Logger to trace diagnostic information, make sure that the logging does not continue
indefinitely (for example, on every Application Engine scan). Otherwise, performance issues
occur.
If you use the Logger to provide debugging information during development, either remove the
logging calls before releasing the object to production, or change them so that logging only occurs
when a custom log flag is set.
Logger message methods

The following common methods are available for writing messages to the ArchestrA Logger.
LogError
Writes an error message to the Logger. Errors are considered serious software problems such
as unhandled exceptions or errors.
Syntax
public void LogError(string _message);
Parameters
_message
string value that holds the error message to be logged.
LogException
Writes a formatted exception (message and stacktrace) to the Logger as a LogError message.
If desired, an optional message can be included.
Syntax
public void LogException(Exception ex);
Parameters
ex
Exception value to be logged.
LogInfo
Writes an information message to the Logger. Information messages indicate a piece of
information that is useful to log for end users. Use sparingly to avoid Logger noise.
Syntax
public void LogInfo(string _message);
Parameters
_message
string value that holds information to be logged.
Wonderware Training
LogTrace
Writes a trace message to the Logger. Trace messages describe internal object states,
variable values, and other low-level data from the component.
Syntax
public void LogTrace(string _message);
Parameters
_message
string value that holds trace message to be logged.
LogWarning
Writes a warning message to the Logger. Warnings indicate an unexpected problem occurred.
Syntax
public void LogWarning(string _message);
Parameters
_message
string value that holds warning message to be logged.
Log Flag Editor

You can use the Log Flag Editor, which is part of the ArchestrA SMCs Log Viewer, to assign a
flag value to each category of messages issued by an ArchestrA component. By switching flags on
or off, you control which categories of messages are saved to the ArchestrA Logger.
Note: You can open the Log Flag Editor directly, bypassing the Log Viewer, by using the following
run command: logflgeditor
The following figure summarizes how log flags control whether component messages are logged
or not. Also, you can use log flags to assign message categories to other ArchestrA components.
Log ArchestrA
ArchestrA Component Components
Flags
Message Categories
Error Messages
ArchestrA
Logger
Warning Messages
SQL Messages
Connection Messages

Most categories of messages are not logged. Typically, a component issues only error, warning,
and informational messages. Most other message categories remain inactive.
The ArchestrA Log Flag Editor is primarily a troubleshooting tool. When a component begins
logging error messages, you can use log flags to activate other message categories and begin
saving additional diagnostic messages to the ArchestrA Logger.
Setting log flags

You can enable or disable message logging by setting the log flags associated with the selected
components message categories. To set log flags for a single ArchestrA component:
a. From the Component list, select an ArchestrA component.
b. In the Log Flags view, check the log flags you want to enable.
c. On the File menu, click Apply.
Component list Log Flags view
Wonderware Training
Section 2 Configtime Validation 4-7
Section 2 Configtime Validation
Section Objectives
Explain how to use the Validate event handler to include configuration validation for an
object
This section describes the Validate event handler.
Validate event handler

In the development of your object, you will want to include validation at configuration time to
ensure that attribute value parameters are configured properly and that they make sense (for
example, the value for HiHi is higher than Hi for alarm limits).
All objects have a standard configtime event handler that can be coded to validate the
configuration of an object. The Validate event is triggered when a user works with the object in the
ArchestrA IDE. Use this event handler for any custom validation code (for example. checking for
invalid combinations of attribute values).
The ConfigtimeValidate event is fired when the object is validated. Validate sets the warning or
error text for the object. It is used to check conditions that would not be checked using a
SetHandler, such as reporting that an object was not configured, or that combinations of attributes
are illegal.
The ArchestrA Object Toolkit automatically generates code to register the delegate
<objectname>Configtime_ConfigtimeValidate for this event.
Syntax
public event ConfigtimeValidateDelegate
ConfigtimeValidate;
Example code
The following code shows an example of performing configtime validation with the
ConfigtimeValidate() method and putting the object in a warning or error state by using
EPACKAGESTATUS enum.
private void
AOTObject4Configtime_ConfigtimeValidate(object
sender, ref EPACKAGESTATUS status)
{
// By default set the object status to Good
if (HiLimit < LoLimit)
{
status = EPACKAGESTATUS.ePackageBad;
AddErrorMessage("Hi Limit must be greater
than or equal to Lo Limit");
}
else
{
}
}

PreValidate event handler

The PreValidate event is fired before the object is validated (when the user has edited its
configuration and saves it).
The toolkit automatically generates code to register the delegate
<objectname>Configtime_PreValidate for this event.
Syntax
public event ObjectEventDelegate PreValidate;
Wonderware Training
Lab 8 Implementing Configuration

Validation
Introduction
In this lab you will add configuration validation to the Counter object. You will assume that the user
must configure engineering units for the counter so that history information can be correctly
reported. To verify this, you will implement the Validate configtime event handler to add a
configuration warning to the object if the Engineering Units attribute is left empty.
You will also write messages to the ArchestrA Logger using some of the methods provided by the
ArchestrA Object Toolkit. You will generate a warning message when the input source quality is
bad or unknown, and you will generate a trace message whenever the count is reset On Scan.
Count
INPUTPRIMITIVE
Count.Input
HISTORYPRIM
CountHistory
TimeSinceChange
Timeout.Limit
Timeout.Condition
ALARMPRIMITIVE
Counter TimeoutAlarm
EngUnits
MaxCount
Reset
ResetOnScan
Validate() Note: See page 2-19 for a
Execute() legend to this graphic.
SetScanState()
EDITOR
Objectives
Implement the Validate configtime event handler to verify object configuration
Generate object errors and warnings based on the validation result
Write messages to the ArchestrA Logger


Implement configtime validation (page 4-14)

b. Modify the Validate method of the Configtime project to make it look exactly like this:
{
//-----------------------------------------------------------------------
// TODO: Configtime Event - Validate
//
// Validate sets the warning or error text for the object.
// It is used to check conditions that would not be checked using
// a SetHandler, such as reporting that an object was not
// configured, or that combinations of attributes are illegal.
//
// Other than calling AddWarningMessage or AddErrorMessage, Validate
// should never modify the state of the object.
//-----------------------------------------------------------------------
Example code

// The following statement will exit validate when validating templates.

before this
instances only.
if (IsTemplate)
{
return;
}
//This code performs custom configuration validation

//at the instance level only
if (string.IsNullOrEmpty(EngUnits.Value))
{
}
}
Wonderware Training
Generate ArchestrA Logger messages (page 4-15)

c. Modify the Execute method of the Runtime project to make it look exactly like this:
{

{
{

{
Count++;
}
else
{
Count = 0;
}


break;
break;
default :
//Write warning message to the ArchestrA Logger

LogWarning(string.Format(
"{0}: Input source quality is bad or unknown", Tagname));
break;
}
}

}
d. Modify the SetScanState method of the Runtime project to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
//Write trace message to the ArchestrA Logger

LogTrace(string.Format("{0}: Count reset On Scan", Tagname));
}


}
else
{
}
}

e. Use the ArchestrA Object toolbar, to build, import and instantiate the Counter object.
f. In the ArchestrA IDE, open the editor for the Counter_001 instance, and set the count input
source to Blinker_001.Bit and set ResetOnScan to True.
g. Verify that leaving EngUnits blank will generate a warning.
h. Deploy the Counter_001 instance.
Wonderware Training
i. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
j. Verify the runtime behavior of the Counter object by monitoring the ArchestrA Logger
messages when quality of the input source is bad. Also, enable the trace Log Flag for the
counter in the Log Viewer to verify that a trace message is generated when the object is set
On Scan.
Configure a default value for EngUnits (page 4-19)

k. To avoid receiving the object configuration warning in later labs, set the default value for the
EngUnits attribute to counts.


Implement configtime validation

2. In Object Design View, under Configtime, double-click Validate.
3. In the CounterConfigtime.cs file, modify the CounterConfigtime_ConfigtimeValidate
method to make it look exactly like this:
{
//-----------------------------------------------------------------------
// TODO: Configtime Event - Validate
//
// Validate sets the warning or error text for the object.
// It is used to check conditions that would not be checked using
// a SetHandler, such as reporting that an object was not
// configured, or that combinations of attributes are illegal.
//
// Other than calling AddWarningMessage or AddErrorMessage, Validate
// should never modify the state of the object.
//-----------------------------------------------------------------------
Example code

// The following statement will exit validate when validating templates.

before this
instances only.
if (IsTemplate)
{
return;
}
//This code performs custom configuration validation

//at the instance level only
if (string.IsNullOrEmpty(EngUnits.Value))
{
}
}
Wonderware Training
Generate ArchestrA Logger messages

5. In the CounterRuntime.cs file, modify the Counter_RuntimeExecute method to make it look
exactly like this:
{

{
{

{
Count++;
}
else
{
Count = 0;
}


break;
break;
default :


break;
}
}

}
7. Modify the Counter_RuntimeSetScanState method to make it look exactly like this:
{
if (e.onScan)
{
if (ResetOnScan)
{
Count = 0;
//Write trace message to the ArchestrA Logger

LogTrace(string.Format("{0}: Count reset On Scan", Tagname));
}


}
else
{
}
}
Wonderware Training

12. On the General tab, check ResetOnScan and set the count input source to Blinker_001.Bit.
13. Click to save and close the editor.

A warning appears because you did not configure the Engineering Units.
14. Click Cancel, and then click the History tab and enter any value in the EngUnits field.
You will now verify the runtime behavior of the Counter object.
19. Set the quality of the Blinker_001.Bit attribute to bad, and then monitor the messages in the
Logger View window in Visual Studio.
Note: If the Logger View window in Visual Studio is not open, click the Tools menu, point to
ArchestrA Object, and click Logger View.
By default, trace Logger messages are not displayed. In the next steps you will enable the
trace log flag in Log Viewer.

20. Set the quality of the Blinker_001.Bit attribute back to good.

21. On the Windows task bar, click Start, and then click Run.
22. In the Run dialog box, enter logflageditor and click OK.
23. In the Log Flag Editor, locate and select ArchestrA.Toolkit.ArchestrAObjectSupport, and
then check Trace.
24. Close the Log Flag Editor and click Yes to apply the changes.
25. In Object Viewer, set the Counter object to Off Scan, and then back to On Scan.
26. In the Logger View window, verify that a trace message is generated.
Wonderware Training
Configure a default value for EngUnits

Now that you have seen how to implement the Validate configtime event handler to add a warning
if the Engineering Units attribute is left empty, you will configure a default value for the attribute to
avoid receiving the warning in later labs.
27. In Visual Studio, open the Object Designer and click the EngUnits attribute.
28. in the Value field, enter counts.

Wonderware Training
Section 3 Debugging
Section Objectives
Describe how to attach the debugger in the ArchestrA Object Toolkit
This section describes debugging objects and how to attach the Visual Studio debugger in the
Debugging objects
The following information is intended to explain debugging in the context of the ArchestrA Object
Toolkit. The material is not intended to be a complete overview of a debugging phase.
Each component of an application object includes its own debugging characteristics. In other
words, the Runtime, Package (Configtime), and Editor components of an object are debugged in
different ways.
Attaching the debugger

The ArchestrA Object Toolkit allows you to attach the Visual Studio debugger to the Application
Server processes running your objects code. This allows you to troubleshoot and debug your
objects. In order to use the debugging features, you must use the object on a computer that has
Visual Studio installed.
Caution: Never debug objects on a production system. Always use a development node with a
local Galaxy for debugging.
Caution: Never ship an object that was created from a debug build. These objects may require
debug modules and may not function correctly in a production environment.
There are two ways for attaching the debugger:

If you have already created a build with the required PDB files and instantiated or
deployed the object on the local system, you can attach the debugger to the Application
Server processes running the current object version and debug that version.
If youve made changes to your object and want to debug the new version, you can attach
the debugger as part of the build process and then debug the new version.
Attaching the debugger to the processes running the current object version
If you want to debug the current version of an object that you have already instantiated or
deployed on the local system, you can attach the debugger to the Application Server processes
running the current object version. There are two prerequisites for this:
You must have created the required PDB (Program Database) files as part of the current
build.
Visual Studio must be able to find the PDB files. If necessary, set up the search paths in
Visual Studio accordingly.
For help on these points, refer to the Visual Studio documentation.

To attach the debugger, click the Debug button on the ArchestrA Object toolbar.
The Debug dialog box appears, as shown below.
Select one or more of the following options:

Attach IDE Debugger to debug custom editor code
Attach Configuration Debugger to debug configtime code
Attach Runtime Debugger to debug runtime code
Visual Studio then switches to debug mode, and you can work with your object and use the
debugging features as required.
To stop debugging, click the highlighted Debug button again.
Attaching the debugger during the build process

If youve made changes to your object and want to debug the new version, you can attach the
debugger as part of the build process and then debug the new version.
To attach the debugger during the build process, click the Options button on the ArchestrA Object
toolbar.
The Options dialog box appears with the Build category selected.
Select one or more of the following options:

Attach IDE Debugger to debug custom editor code
Attach Configuration Debugger to debug configtime code
Attach Runtime Debugger to debug runtime code
Wonderware Training
Then build your object using a build mode on the ArchestrA Object toolbar. For example, to debug
configtime or custom editor code, Build & Instantiate is convenient.
Once the build is finished, Visual Studio switches into debugging mode. You can now work with
your object and use the debugging features as required.
To stop debugging, click the highlighted Debug button.

Wonderware Training
Module 5
Virtual Primitives
Section 1 Virtual Primitives Overview 5-3
Lab 9 Adding a Counter Reset Input 5-9
5-2 Module 5 Virtual Primitives
Module Objectives
Explain what virtual primitives are and how they are used
Create a virtual primitive
Wonderware Training
Section 1 Virtual Primitives Overview
Section Objectives
Summarize what virtual primitives are and how they can be used
Explain how to designate a primitive as virtual
Describe some of the methods used with virtual primitives
This section describes virtual primitives and gives examples of how they can be used. It also
describes methods that can be used in logic for working with virtual primitives.
Virtual primitives
Virtual primitives are primitives that are added and removed on demand. You can use a virtual
primitive to implement a block of optional functionality that can be enabled as required by an end
user. This ensures that only required primitives are actually deployed at runtime, reducing
overhead and processing load.
A virtual primitive is like other primitives with the following exceptions:
They are added to the Galaxy database, but do not get added to the global Object
Namespace, which is browsable from within the ArchestrA IDE
Special Add and Remove methods called by configtime logic or runtime logic, typically
within set handler code, use the virtual primitive as a template to create instances of the
primitive that are contained within the parent object instance
You design and implement a virtual primitive in the same way as any other primitive. However,
from the end users perspective, a virtual primitive does not appear to be part of the object by
default. Instead, it is only made real at configuration time by programmatically adding instances
of the virtual primitive to the object as needed.
For example, you might want to provide an optional Hi alarm for an objects PV (process value). To
do this, you would add a virtual primitive that contains the alarming functionality, and an attribute
that enables or disables the Hi alarm. When the user enables that attribute at configtime, you
create an instance of the virtual primitive by means of a call in the attributes configtime set
handler. If the attribute stays disabled, you never create an instance of the primitive, and the
primitive never gets deployed.
You can create multiple instances of a virtual primitive in the same object. Each instance behaves
like a separate primitive. For example, you could re-use the same Hi alarm primitive for multiple
attributes by simply creating multiple instances of it. However, when you add the instances, you
must provide a unique external and internal name for each instance to avoid naming conflicts.
You can also use virtual primitives to define optional attributes and arrays of related primitives.
Defining optional attributes using virtual primitives
Using virtual primitives, you can include primitives (and their attributes) in an object only when they
are really necessary. For example, if the monitoring of a particular input is optional, you can mark
the input primitive as virtual and include it in the object only when a certain attribute (for example,
EnableInputMonitoring) is set to true. To do this, you would include logic for creating or removing
an instance of the virtual primitive in that attributes configtime set handler.
Arrays of related primitives
Using the same technique as described above, you can easily monitor a variable number of inputs
(for example, 0 to 4). The only difference is that you create more than one instance of the virtual

primitive. Each primitive instance must have unique internal and external names so its attribute
names do not collide with those of the other primitive instances.
Referencing attributes using GetValue and SetValue

You can reference attributes in a virtual primitive by using the GetValue and SetValue methods.
The GetValue and SetValue methods use the primitive external name and attribute external name
as shown in the following example:
GetValue(PrimitiveExternalName.AttributeExternalName)
You can use several other common attribute methods with virtual primitives to access attribute
data at configtime. These include:
Get Gets the value of an attributes property
GetValue Gets the value of an attribute
GetName Gets the name of an attribute
GetType Gets the type of an attribute
GetIsLocked Gets the lock status of an attribute
GetSecurityClassification Gets the security classification of an attribute
You can also use the following runtime attribute methods with virtual primitives to access attribute
data at runtime:
GetAttributeProperties Gets all the properties of an attribute
GetQuality Gets the quality of an attribute
GetTimeStamp Gets the time of an attribute
GetMxStatus Gets the value of a MxStatus attribute
Designating a primitive as Virtual

To designate that a primitive will be virtual, use the Object Designer and check the Virtual check
box in the Configuration pane, as shown below.
Wonderware Training
When you make an alarm or history primitive virtual, you also have the option to add an attribute to
enable and disable the primitive, as shown in the example below.
When this option is checked, an additional attribute named <AttributeName>.Historized or

<AttributeName>.Alarmed is added with configtime set handler code to enable and disable the
primitive. You can simply add this attribute to the custom object editor to allow your users to
enable or disable alarming or history for the attribute.
Virtual primitive methods

You can use the following ConfigtimeBase methods to add, delete, or rename an instance of a
virtual primitive at configtime:
AddPrimitive
Syntax
public bool AddPrimitive(
string virtualPrimitiveName,
string internalName,
string externalName
);
Parameters
virtualPrimitiveName Name of the virtual primitive
internalName New Internal name of the instance
externalName New External name of the instance
Return Value
true if the Primitive instance addition is successful
false if the user tries to add a primitive with the same name of an existing primitive or if
the user tries to create an instance of the non-virtual primitive

DeletePrimitive
Syntax
public bool DeletePrimitive(string internalName);
Parameters
internalName Internal name of the virtual primitive instance
Return Value
bool
true if Primitive instance deletion is successful
false if the user tries to delete a non-existing primitive instance or the user tries to
delete a non-virtual primitive
RenamePrimitive
Syntax
public bool RenamePrimtive(
string primitiveInternalName,
string newInternalName,
string newExternalName
);
Parameters
primitiveInternalName Internal name of the virtual primitive instance
newInternalName New Internal name of the virtual primitive instance
newExternalName New External name of the virtual primitive instance
Return Value
bool
true if the primitive internal and external names are renamed
You can also test the ability to add, delete, or rename an instance of a virtual primitive by using the
following methods:
CanAddPrimitive
Syntax
public bool CanAddPrimitive(string virtualPrimitiveName, string internalName,
string externalName)
Parameters
virtualPrimitiveName Internal name of the virtual primitive
internalName New Internal name of the virtual primitive instance
externalName New External name of the virtual primitive instance
Return Value
bool
true if the primitive instance can be added with the Internal and External names
Wonderware Training
CanDeletePrimitive
Syntax
public bool CanDeletePrimitive(string internalName)
Parameters
internalName Internal name of the virtual primitive instance
Return Value
bool
true if the primitive instance can be deleted with the Internal name
CanRenamePrimitive
Syntax
public bool CanRenamePrimtive(string primitiveInternalName, string
newExternalName
Parameters
primitiveInternalName Internal name of the virtual primitive instance
newExternalName New External name of the virtual primitive instance
Return Value
bool
true if the primitive instance can be renamed with the External name

Wonderware Training
Lab 9 Adding a Counter Reset Input

Introduction
In previous labs, you added utility primitives to the Counter, such as input, alarm, and history
primitives. These primitives were always present and available, even when not needed. In this lab,
you will make some of those primitives Virtual so they can be added and used on demand.
You will enable the Virtual option for the Count history primitive and the Timeout.Condition alarm
primitive. You will also check the option to add the corresponding enable/disable attributes so that
the code will automatically handle the logic to add and remove the virtual primitives. Then you will
add an input primitive whose value will be associated to the Reset attribute. You will make this
input primitive virtual, and then you will control its add/delete logic by adding an attribute named
Reset.InputEnabled. This change will require modifying the reset logic in runtime. Finally, you will
modify the object's editor to enable users to set the newly added attributes in the ArchestrA IDE.
Count
INPUTPRIMITIVE
Count.Input
HISTORYPRIM
CountHistory
TimeSinceChange
Bit
Timeout.Limit
GoodQualityCmd
Timeout.Condition
InitializingQualityCmd
ALARMPRIMITIVE Blinker
TimeoutAlarm UncertainQualityCmd
(Providedby
EngUnits Instructor) BadQualityCmd
Counter ResetTrigger
MaxCount
ResetOnScan
Reset
INPUTPRIMITIVE
Reset.Input
Reset.InputEnabled
Reset_InputEnabled_ConfigtimeSH()
Execute()
Reset_RuntimeSH()
GetStatusDesc() legend to this graphic.
EDITOR
Objectives
Add virtual primitives to an application object
Write the necessary logic to add and remove virtual primitives dynamically


Modify the shape of the Counter (page 5-15)

b. Use Object Designer to modify the Count attribute's history primitive as follows:
Virtual: checked
Add Attribute to enable/disable History: checked
c. Modify the Timeout.Condition attributes alarm primitive as follows:
Virtual: checked
Add Attribute to enable/disable Alarm: checked
d. Add an Input primitive, and configure it as follows:
External Name Internal Name Additional Configuration Primitive Attributes Configuration

Reset.Input ResetInput Virtual: Check Attribute Value
DataType MxBoolean (and lock it)
e. Add an attribute, and configure it as follows:

Reset.InputEnabled Boolean Writeable_C_Lockable Configuration Set Handler: Check
Implement the virtual primitive add/delete logic (page 5-17)

f. Modify the Configtime Set Handler for the Reset.InputEnabled attribute to make it look
exactly like this:
private void Reset_InputEnabledSetHandler(object sender, ref
{
//If the set value is equal to the current value, ignore it
if (e.Value == Reset_InputEnabled)
{
return;
}
//Add or delete the Reset.Input virtual primitive

//based on the set value
bool success;
if (e.Value)
{
//Value set to true. Add input primitive
success =
AddPrimitive("ResetInput", "ResetInput1", "Reset.Input");
}
else
{
//Value set to false. Delete input primitive
Wonderware Training
success = DeletePrimitive("ResetInput1");
}
//Accept set value or return error message

//based on success
if (success)
{
//Virtual primitive was added/deleted. Set value
Reset_InputEnabled.SetHandlerValue = e;
}
else
{
//Primitive could not be added/deleted
//Generate an error and do not set value
e.Message = PrimitiveResult.message;
}
}
Modify the reset runtime logic (page 5-18)

g. Modify the Declarations region of the Runtime project to make it look exactly like this:


//Variable used to store previous Reset input value

bool lastResetInput;
h. Modify the Execute method of the Runtime project to make it look exactly like this:
{
//Check whether the Reset input is enabled

if (Reset_InputEnabled)
{
//Get current reset input value
//The GetValue() method has to be used here
//because the attribute belongs to a virtual primitive
bool currentResetInput = GetValue("Reset.Input.Value");
//Check whether the reset input has become true

if (currentResetInput && !lastResetInput)
{
//The reset input has become true. Initialize Counter
Count = 0;

}
//Assign current Reset input value as "last"

lastResetInput = currentResetInput;

}

{
{

{
Count++;
}
else
{
Count = 0;
}


break;
break;
default :
Wonderware Training

break;
}
}

}
i. Modify the Runtime Set Handler for the Reset attribute to make it look exactly like this:
{
//If the reset input is enabled, return an error
{
//Return error information
e.status.Category =
return;
}

if (e.Value)
{
//Reset Count
Count = 0;
}

}
j. Modify the GetStatusDesc method of the Runtime project to make it look exactly like this:
{
{
case 10001:
break;
case 10002:
break;
case 10003:

e.status =
"Reset cannot be modified because Reset Input is enabled";
break;
default:
break;
}
}

k. Open the Editor form.
l. From Object Design View, drag the following attributes onto the specified tabs:
Attribute Tab
Reset.InputEnabled
General
Reset.Input.InputSource
Timeout.Condition.Alarmed Alarms
Count.Historized History
m. Save the project.

n. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
o. In the ArchestrA IDE, open the editor for the Counter_001 instance, and verify that all virtual
primitives are added and deleted correctly.
p. Configure the Counter instance as follows:
Set the count input source to Blinker_001.Bit
Set Reset.InputEnabled to True
Set the reset input source to Blinker.ResetTrigger
q. Deploy the Counter_001 instance.
r. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
s. Add the following attribute reference to the Counter IO watch window:
Object Attribute
Blinker_001 ResetTrigger
t. Save the modified watch list.

u. Verify the runtime behavior of the Counter object by using the Blinker instance to reset the
counter. Also verify that if the reset input is enabled, you cannot modify the Reset attribute
from Object Viewer.
Wonderware Training

Modify the shape of the Counter

2. In Object Designer, click the Count attribute, expand the Historizable section, and check the
following parameters:
Virtual
Add Attribute to enable/disable History (automatically checked after checking Virtual)
3. Click the Timeout.Condition attribute, expand the Alarmable section, and check the
following parameters:
Virtual
Add Attribute to enable/disable Alarm (automatically checked after checking Virtual)

4. Add an Input primitive, and configure it as follows:

External Name Internal Name Additional Configuration
Reset.Input ResetInput Virtual: Check
5. In the Shape pane, under Reset.Input, click DataType.

6. In the Configuration pane, click the Value drop-down list and select MxBoolean.
7. Lock the Value field.
Wonderware Training
8. Add an attribute to the Counter object, and configure it as follows:

Reset.InputEnabled Boolean Writeable_C_Lockable Configuration Set Handler: Check
Implement the virtual primitive add/delete logic

10. In Object Design View, under Configtime, double-click Reset.InputEnabled Set Handler.
11. In the CounterRuntime.cs file, modify the Reset_InputEnabledSetHandler method to make
private void Reset_InputEnabledSetHandler(object sender, ref
{
if (e.Value == Reset_InputEnabled)
{
return;
}
//Add or delete the Reset.Input virtual primitive

bool success;
if (e.Value)
{
//Value set to true. Add input primitive
success =
AddPrimitive("ResetInput", "ResetInput1", "Reset.Input");
}
else
{
//Value set to false. Delete input primitive
success = DeletePrimitive("ResetInput1");
}


//based on success
if (success)
{
Reset_InputEnabled.SetHandlerValue = e;
}
else
{
}
}
Modify the reset runtime logic

13. In the CounterRuntime.cs file, modify the Declarations region of the Runtime project to
make it look exactly like this:


//Variable used to store previous Reset input value

bool lastResetInput;

15. Modify the Counter_RuntimeExecute method of the Runtime project to make it look exactly
like this:
{
//Check whether the Reset input is enabled

{
//Get current reset input value
//The GetValue() method has to be used here
//because the attribute belongs to a virtual primitive
bool currentResetInput = GetValue("Reset.Input.Value");
//Check whether the reset input has become true

if (currentResetInput && !lastResetInput)
Wonderware Training
{
//The reset input has become true. Initialize Counter
Count = 0;
}
//Assign current Reset input value as "last"

lastResetInput = currentResetInput;

}

{
{

{
Count++;
}
else
{
Count = 0;
}


break;
break;
default :



break;
}
}

16. In Object Design View, under Runtime, double-click Reset Set Handler.
{
//If the reset input is enabled, return an error
{
//Return error information
e.status.Category =
return;
}

if (e.Value)
{
//Reset Count
Count = 0;
}

}

this:
{
Wonderware Training
{
case 10001:
break;
case 10002:
break;
case 10003:
e.status =
"Reset cannot be modified because Reset Input is enabled";
break;
default:
break;
}
}
Modify the Editor

21. From Object Design View, drag the following attributes onto the General tab:
Reset.InputEnabled
Reset.Input.InputSource (located under the Reset.Input primitive)
22. Arrange the attributes to make the form look similar to the following:

23. From Object Design View, drag the following attribute onto the Alarms tab:
Timeout.Condition.Alarmed
24. From Object Design View, drag the following attribute onto the History tab:
Count.Historized
Wonderware Training

30. On the General tab, check and uncheck Reset.InputEnabled to verify that the virtual primitive
(Reset.Input.InputSource) is added and deleted correctly.
Note: The controls on the editor tab will be enabled and disabled when the primitive is
added and deleted.
31. Repeat the previous step to verify the virtual primitives on the Alarms and History tabs.
(Leave the check boxes unchecked when done.)
33. Check Reset.InputEnabled and set the reset input source to Blinker.ResetTrigger.

36. Right-click Blinker_001 and click View in Object Viewer.

38. Add the following attribute to the Counter IO watch window:

ResetTrigger

40. Verify the following runtime behaviors:
The Counter restarts at zero when the reset input is set to True
Note: You can change the reset input by using the ResetTrigger signal in the Blinker
object.
When the reset input is enabled, you cannot modify the Reset attribute from Object
Viewer
No attributes related to the alarm and history primitives are available in runtime when the
virtual primitives are unloaded
Note: You can check for the following attributes in runtime:

For alarms:
Timeout.Condition.Priority
Timeout.Condition.Category
For history:
Count.TrendHi
Count.TrendLo
Wonderware Training
Module 6
Custom Primitives
Section 1 Local Primitives Overview 6-3
Lab 10 Adding Counter Statistics 6-7
Section 2 Reusable Primitives Overview 6-19
Lab 11 Creating a Rate Calculator Reusable Primitive 6-21
6-2 Module 6 Custom Primitives
Module Objectives
Explain what local and reusable primitives are and how they are used
Create a local primitive and a reusable primitive
Wonderware Training
Section 1 Local Primitives Overview
Section Objectives
Summarize what local primitives are and how to configure them
This section describes local primitives and explains how to configure them.
Local primitives
Local primitives are custom primitives that are local to your object. They contain all the logic and
attributes unique to the object. Local primitives are usually created to be virtual primitives.
Local primitives are created and maintained using the Object Designer. You can configure
custom code for the primitives events and set handlers in the same way as you would configure it
for the object itself.
In the Object Design View, local primitives are shown with a special icon, and they have their own
subentries for Attributes, Configtime events, and Runtime events.
Local primitive
Primitive hierarchies
When you add a local primitive to an application object, the ArchestrA Object Toolkit adds a
subfolder to the solution folder that contains the code files for that primitive. The primitive folder, in
turn, has different subfolders for configtime and runtime code. When you add another primitive to
that primitive, the ArchestrA Object Toolkit creates a subfolder in the primitive subfolder, and so
on.
Primitive embedded
in object
Primitive embedded
in primitive

Note: There is a limit to how many levels of primitives you can use. However, the current
Windows operating system imposes a limit of 260 characters for the complete file path. Therefore,
no path to any code file in any ArchestrA Object Toolkit project folder may exceed this limitation.
The exact number of levels you can use depends on the path length of the base ArchestrA Object
Toolkit solution folder and on the length of the primitive names. The shorter the primitive names,
the shorter the folder names, and the more levels you can use.
Adding and configuring local primitives

In the Shape pane of the Object Designer, first elect the location where you want to add the
primitive. For example, if you want to add a primitive to another primitive, select that primitive or
one of its attributes. Then you can add the primitive by selecting Local Primitive from the Add
button, as shown below.
You can then configure the local primitive in the Configuration pane. The available parameters
are listed in the table below.
Parameter/Option Description
External Name The unique name by which other objects can access the primitives
attributes. The name must be ArchestrA compliant.
Internal Name The unique name by which you can refer to the primitive in the objects
code. The name must be C# compliant.
Dump/Load support for Dynamic attributes and virtual primitives are added and configured at
Dynamic Attributes & Virtual configtime, so their status & configuration may be different in each object.
Primitives This option preserves the configuration and allows the object to be
processed by the Galaxy Dump/Load feature without generating warnings.
Failover support for Runtime In a redundant environment with dual ApplicationEngines configured for
Dynamic Attributes failover, this option preserves any dynamic attributes created on your
object during runtime in case of a failover.
Virtual Designates that the primitive should be virtual.
You can also configure additional parameters by expanding the sections for Associated Files and
Advanced Configuration.
Associated Files is used for manually associating files with your object that are not set up as
project references in Visual Studio (for example, custom data files). Files listed here are included
in the object package file when you build the object, and optionally registered on the target system
when you import the object.
Advanced Configuration is used for configuring the order in which the primitive should be
executed relative to other primitives in the object, and for specifying that the primitive should use
other assemblies than the ones automatically generated by the ArchestrA Object Toolkit
Wonderware Training
Referencing attributes in other primitives

You can reference attributes in other primitives by using the GetValue and SetValue methods with
a relative string reference. The string reference is relative to the primitive that contains the code,
and can be prefixed with the following modifiers:
me
myparent
myobject
Note: The prefix me is implied when no prefix is provided.
As stated in the previous module, the GetValue and SetValue methods use the primitive external
name and attribute external name, as shown in the following example:
GetValue(PrimitiveExternalName.AttributeExternalName)
Examples for referencing attributes in other primitives

The examples below are based on the following hierarchy:
Local references Use the attribute name with no prefixes or scope. Using the me prefix
explicitly sets the reference to local and can be used to make it clear what type of reference is
required.
Either of the following statements in Child2 gets the value of AOTObjectx1.Child2.Attribute1:
GetValue("Attribute1");
GetValue("me.Attribute1");
Referencing Down (child) Prefix the reference string with the name of the child primitives.
The following statement in Child2 gets the value of AOTObjectx1.Child2.Child4.Attribute1:
GetValue("Child4.Attribute1");
The following statement in AOTobjectx1 gets the value of AOTObjectx1.Child2.Child4.Attribute1:
GetValue("Child2.Child4.Attribute1");
Referencing Up (parent) Use the myparent prefix.
The following statement in Child2 gets the value of AOTObjectx1.Attribute1:
GetValue("myparent.Attribute1");
The following statement in Child4 gets the value of AOTObjectx1.Child2.Attribute1
GetValue("myparent.Attribute1");

The myparent prefix cannot be used more than once in a reference. To reference attributes of
objects or primitives more than one level higher, you must use myobject to locate the reference to
the top of the hierarchy and then work relative to that location.
The following statement in Child4 gets the value of AOTObjectx1.Attribute1:
GetValue("myobject.Attribute1");
The following statement in Child4 gets the value of AOTObjectx1.Child1.Child3.Attribute1:
GetValue("myobject.Child1.Child3.Attribute1");
Wonderware Training
Lab 10 Adding Counter Statistics

Introduction
This lab demonstrates how to add and implement a local primitive in an application object. You will
develop a local primitive for the Counter to offer some statistics about the behavior of the count,
such as a rollover count, and a bad counter input quality count. The statistics primitive will also
have a writable attribute to allow users to reset these counts in runtime. You will make this
statistics primitive virtual, and you will add a Boolean attribute to the Counter to control its add and
delete logic. Finally, you will modify the object's editor to enable users to set the newly added
attributes in the ArchestrA IDE.
Count

Stats.Enabled
RolloverCnt
VIRTUALPRIMITIVE BadInputCnt
Counter
Stats Reset
Execute()
ResetCmd_RuntimeSH()
Stats_Enabled_ConfigtimeSH() Note: See page 2-19 for a

legend to this graphic.
EDITOR
Objectives
Add and implement local primitives within an application object


Add the Stats custom child primitive (page 6-12)

b. Use Object Designer to add the following attribute:
Stats.Enabled Boolean PackageOnly_Lockable Configuration Set Handler: Check
c. Add a new Local Primitive, and configure it as follows:

Stats Stats Virtual: Check
d. Add the following attributes to the Stats local primitive:

RolloverCnt Integer Calculated
BadInputCnt Integer Calculated
Implement virtual primitive add/delete logic (page 6-13)

e. Modify the Configtime Set Handler for the Stats.Enabled attribute to make it look exactly like
this:
private void Stats_EnabledSetHandler(object sender, ref
{
if (e.Value == Stats_Enabled)
{
return;
}
//Add or delete the Stats virtual primitive

bool success;
if (e.Value)
{
//Value set to true. Add virtual primitive
success =
AddPrimitive("Stats", "Stats1", "Stats");
}
else
{
//Value set to false. Delete virtual primitive
success = DeletePrimitive("Stats1");
Wonderware Training

//based on success
if (success)
{
Stats_Enabled.SetHandlerValue = e;
}
else
{
}
}
Implement the runtime logic for the local primitive (page 6-14)
f. Modify the Declarations region of the Runtime project of the Stats primitive to make it look
exactly like this:
//Variable used to store last Count value

int lastCount = 0;
//Variable used to store last counter input quality

DataQuality lastInputQuality = DataQuality.DataQualityInitializing;
g. Modify the Execute method of the Runtime project of the Stats primitive to make it look
exactly like this:
private void StatsRuntime_RuntimeExecute(object sender)
{
//Code written in this method is executed every scan
//only if the Stats primitive is loaded
//Check for a Count rollover

//Get current Count
int currentCount = GetValue("myparent.Count");
//If current Count is less than previous value, a rollover has happened
if (currentCount < lastCount)
{
RolloverCnt++;
}
lastCount = currentCount;
//Check for input bad quality

//Get current counter input quality

DataQuality currentInputQuality = GetQ("myparent.Count.Input.Value");
//If input quality has turned bad, increase BadInputCnt

if ((currentInputQuality == DataQuality.DataQualityBad)
&& (lastInputQuality != DataQuality.DataQualityBad))
{
BadInputCnt++;
}
lastInputQuality = currentInputQuality;
}
h. Modify the Runtime Set Handler for the Reset attribute of the Stats primitive to make it look
exactly like this:
private void ResetSetHandler(object sender, ref
{
//If the attribute is set to true, reset stats
if (e.Value)
{
//Reset stats
RolloverCnt = 0;
BadInputCnt = 0;
}

}

i. Open the Editor form.
j. From Object Design View, drag the Stats.Enabled attribute onto the General tab.
k. Save the project.

l. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
m. In the ArchestrA IDE, open the editor for the Counter_001 instance, and verify that no errors
are generated when adding and deleting the Stats primitive.
n. Configure the Counter instance as follows:
Check Stats.Enabled
o. Deploy the Counter_001 instance.
p. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
q. Add a new watch window and rename it to Stats.
Wonderware Training
r. Add the following attributes to the new watch window:

Object Attribute
Counter_001 Stats.RolloverCnt
Counter_001 Stats.BadInputCnt
Counter_001 Stats.Reset
s. Save the modified watch list.

t. Verify the runtime behavior of the Counter object by using the Reset attribute of the Counter to
cause a rollover, and the quality command attributes of the Blinker to force bad quality in the
counter input. Also verify the behavior of the stats calculations when the Stats.Reset attribute
is modified.


Add the Stats custom child primitive

Stats.Enabled Boolean PackageOnly_Lockable Configuration Set Handler: Check
3. Add a new Local Primitive, and configure it as follows:

Stats Stats Virtual: Check
Wonderware Training
4. Add the following attributes to the Stats local primitive:

RolloverCnt Integer Calculated
BadInputCnt Integer Calculated
Implement virtual primitive add/delete logic

6. In Object Design View, under Configtime, double-click Stats.Enabled Set Handler.
7. In the CounterConfigtime.cs file, modify the Stats_EnabledSetHandler method to make it
private void Stats_EnabledSetHandler(object sender, ref
{
if (e.Value == Stats_Enabled)
{
return;
}
//Add or delete the Stats virtual primitive

bool success;
if (e.Value)
{
success =
AddPrimitive("Stats", "Stats1", "Stats");
}
else
{


success = DeletePrimitive("Stats1");
}

//based on success
if (success)
{
Stats_Enabled.SetHandlerValue = e;
}
else
{
}
}
Implement the runtime logic for the local primitive

8. In Object Design View, expand the Stats local primitive, expand Runtime, and then double-
click Declarations.
9. In the StatsRuntime.cs file, expand the Declarations region and modify it so it looks exactly
like this:
//Variable used to store last Count value

int lastCount = 0;
//Variable used to store last counter input quality

DataQuality lastInputQuality = DataQuality.DataQualityInitializing;
10. In Object Design View, under Stats and Runtime, double-click Execute.
11. Modify the StatsRuntime_RuntimeExecute method to make it look exactly like this:
private void StatsRuntime_RuntimeExecute(object sender)
{
//only if the Stats primitive is loaded
//Check for a Count rollover

//Get current Count
int currentCount = GetValue("myparent.Count");
//If current Count is less than previous value, a rollover has happened
if (currentCount < lastCount)
{
RolloverCnt++;
Wonderware Training
lastCount = currentCount;
//Check for input bad quality

//Get current counter input quality
DataQuality currentInputQuality = GetQ("myparent.Count.Input.Value");
//If input quality has turned bad, increase BadInputCnt

if ((currentInputQuality == DataQuality.DataQualityBad)
&& (lastInputQuality != DataQuality.DataQualityBad))
{
BadInputCnt++;
}
lastInputQuality = currentInputQuality;
}
12. In Object Design View, under the Stats local primitive, expand Attributes, expand Reset,
and then double-click Runtime Set Handler.
private void ResetSetHandler(object sender, ref
{
//If the attribute is set to true, reset stats
if (e.Value)
{
//Reset stats
RolloverCnt = 0;
BadInputCnt = 0;
}

}

Modify the Editor

15. From Object Design View, drag the Stats.Enabled attribute onto the General tab.

21. Verify that no errors are generated when adding and deleting the Stats primitive by checking
and unchecking Stats.Enabled. Leave Stats.Enabled checked when done.
22. Set the count input source to Blinker_001.Bit.
Wonderware Training

27. Add a new watch window and rename it to Stats.
Stats.RolloverCnt
Stats.BadInputCnt
Stats.Reset

30. Verify the following runtime behaviors of the object:

Whenever the count of the counter rolls over, it causes Stats.RolloverCnt to increase
Hint: You can force the count to roll over by using the Reset attribute.
Whenever the counter input has a bad quality, it causes the Stats.BadInputCnt attribute
to increase
Hint: You can force the input to bad quality using the quality command attributes in the
Blinker object.
Setting the Stats.Reset attribute resets the stats counts
Wonderware Training
Section 2 Reusable Primitives Overview 6-19
Section 2 Reusable Primitives Overview
Section Objectives
Describe what reusable primitives are and how they are beneficial
Explain how to create a reusable primitive
This section describes reusable primitiveswhat they are, how they are used, and how to create
and configure them.
Reusable primitives
Reusable primitives are primitives that are intended to be included in multiple objects. By
implementing common features as reusable primitives, you can share component-level code
across objects and avoid code duplication. The Input and Output primitives that you can add in the
Object Designer are good examples of how reusable primitives are beneficial.
From a development perspective, creating a reusable primitive is the same as creating an object,
except that there is no information describing the overall object, there is no editor (since only
objects have editors), and the final file created by the development process is an aaPRI file, not an
aaPDF. Reusable primitives must be added to an object before it can be imported into a Galaxy (a
reusable primitive cannot be imported alone). You can also add multiple instances of a reusable
primitive to the same object.
Using the ArchestrA Object Toolkit, you can create your own custom reusable primitives and use
them in other objects. Also, standard reusable primitives installed by Wonderware Application
Server are available in the following folder:
C:\Program Files\Common Files\ArchestrA\ReusablePrimitives\ ArchestrA
Technically, the Inputs and Outputs as well as the Alarm and History extensions that you can add
in the Object Designer are reusable primitives as well. (See Utility Primitives Overview on page
3-7.) However, there are separate mechanisms in the Object Designer for adding and configuring
these primitives.
Creating reusable primitives

You create a Visual Studio project for every reusable primitive that you want to create. Reusable
primitives are created and maintained by opening them independently.
Once you have created the project, you can use the Object Designer to specify whether the object
will be an application object or a reusable primitive. This is done in the Configuration pane by
choosing the appropriate option for the Category parameter.

As shown below, select Reusable Primitive from the Category drop-down list to create a
reusable primitive.
You can switch between Reusable Primitive and Application Object at any time. Any properties
and features that are not relevant to the current mode are blocked from access in the Object
Designer and Object Design View. However, they are still preserved in the project code, so when
you switch back to the other mode, they are available again.
Developing a reusable primitive is very similar to creating an application object; however, there are
certain differences.
The Object Designer does not have fields for editing the minor version, toolset name, or
description. These settings are irrelevant for a reusable primitive.
The Configuration Event Handlers and IDE Behavior sections are removed from the
Object Designer. Both are irrelevant for a reusable primitive. (The standard configtime
event handlers are still available via the Object Design View.)
A reusable primitive does not have its own setting for Advise Only Active support.
Advise Only Active support is determined by the object that the primitive is used in.
Reusable primitives do not have their own custom editor. Any required configuration UI
must be implemented in the editor of the object that contains it.
The Build & Import, Build & Instantiate, and Build & Deploy build modes are not
available. They are not applicable to a reusable primitive.
The Increment Minor Version versioning option is not applicable to reusable primitives.
The output file created by the build process is an .aaPRI file, not an .aaPDF file. You must
add the reusable primitive to an object before you can import it into a Galaxy. You cannot
import a reusable primitive alone.
Overriding and Locking Attributes of Reusable Primitives

When you include a reusable primitive into another primitive or object, you may be able modify the
default values and security classification of its attributes. This is called overriding.
When appropriate, you can also lock these overridden values, which prevents them from being
changed after the object is imported into a Galaxy. A common example is an object that is
designed to monitor only Boolean items from the field. To do so, include an Input primitive,
override its data type attribute to Boolean, and lock it.
Wonderware Training
Lab 11 Creating a Rate Calculator Reusable

Primitive
Introduction
Until now, all the functionality you have defined and implemented has been specific to the Counter
object, and therefore, not reusable. This lab will demonstrate how to add and implement a
reusable primitive in an application object.
You will develop a rate calculator reusable primitive that will calculate the rate of change of any
analog variable. You will include in this primitive an attribute to configure how often the rate will be
calculated, and a command attribute to enable users to reset the rate in runtime. You will then
insert the reusable primitive in the Counter object and make it virtual, allowing users to enable a
count rate calculation. Finally, you will modify the object's editor to enable users to set the newly
added attributes in the ArchestrA IDE.
Count

Count.RateEnabled
Rate
CalcPeriod
Counter REUSABLE RateReset
PRIMITIVE
Startup()
Count
Execute()
RateResetCmd_RuntimeSH()
CalcPeriod_ConfigtimeSH()
Count_RateEnabled_ConfigtimeSH()
EDITOR legend to this graphic.
Objectives
Add and implement reusable primitives within an application object


Create the rate calculator reusable primitive (page 6-27)

a. In Microsoft Visual Studio, close the Counter solution if opened.
b. Create a new ArchestrA Object project in your training folder (C:\Wonderware Training),
and name it RateCalculator.
c. In Object Designer, change the Category field to Reusable Primitive.
d. Add the following attributes to the RateCalculator primitive:

Rate Float Calculated Frequently Accessed: Check
CalcPeriod Elapsed Time Writeable_C_Lockable Configuration Set Handler: Check
Value: 00:00:10.000 (10 seconds)
RateReset Boolean Writeable_US Runtime Set Handler: Check
Implement the rate calculator logic (page 6-29)

e. Modify the Configtime Set Handler for the CalcPeriod attribute of the RateCalculator
primitive to make it look exactly like this:
private void CalcPeriodSetHandler(object sender, ref
{
//Verify that the calculation period is not negative

if (e.Value > TimeSpan.Zero)
{
CalcPeriod.SetHandlerValue = e;
}
else
{
e.Message = "CalcPeriod cannot be negative";
}
}
f. Modify the Declarations region of the Runtime project of the RateCalculator primitive to
//Variable used to store the name of the attribute

//used as source value for the rate calculation
string myName;
//Variable used to store last analog source value

double lastValue;
Wonderware Training
//Variable used to store last time rate was calculated

DateTime lastCalculationTime;
g. Modify the Startup method of the Runtime project of the RateCalculator primitive to make it
private void RateCalculator_RuntimeStartup(object sender,
{
//This code assumes that the external name of this primitive
//as assigned within an application object
//is equal to the source attribute name.
//Find this source attribute name

string myExternalName = GetValue(
(short)ECOMMONATTRIBUTES.idxComAttExternalName, ThisPrimitive);
myName = string.Format("myparent.{0}", myExternalName);
//Set initial time of rate calculation

lastCalculationTime = GetScanTime();

maintain the
must be called


}
h. Modify the Execute method of the Runtime project of the RateCalculator primitive to make it
private void RateCalculator_RuntimeExecute(object sender)
{
//only if this primitive is loaded
//Find out whether rate is due for calculation

TimeSpan timeSinceCalc = GetScanTime() - lastCalculationTime;
if (timeSinceCalc >= CalcPeriod)
{
//Rate calculation is due

//Get current source value

double currentValue = GetValue(myName);
//Calculate rate
Rate = (float)((currentValue - lastValue)
/ timeSinceCalc.Seconds);
//Set current values as "last"

lastValue = currentValue;
}
}
i. Modify the Runtime Set Handler for the RateReset attribute of the RateCalculator primitive
to make it look exactly like this:
private void RateResetSetHandler(object sender, ref
{
//If the attribute is set to true, reset rate
if (e.Value)
{
Rate = 0.0f;
}
//The RateReset attribute is never modified

}
Build and add the RateCalculator primitive (page 6-31)

j. Use the ArchestrA Object toolbar to build the RateCalculator primitive.
k. In Microsoft Visual Studio, close the RateCalculator solution, and open the Counter solution.
l. Use Object Designer to add the following attribute:
Count.RateEnabled Boolean PackageOnly_Lockable Configuration Set Handler: Check
m. Add a Reusable Primitive, selecting the C:\Wonderware

Training\RateCalculator\Output\RateCalculator1.aaPRI file, and configure it as follows:
Count CountRate Virtual: Check
n. Change the Value of the CalcPeriod attribute to 00:00:05.000 (5 seconds).
Wonderware Training
Implement virtual reusable primitive add/delete logic (page 6-33)

o. Modify the Configtime Set Handler for the Count.RateEnabled attribute to make it look
exactly like this:
private void Count_RateEnabledSetHandler(object sender, ref
{
if (e.Value == Count_RateEnabled)
{
return;
}
//Add or delete the Count (reusable) virtual primitive

bool success;
if (e.Value)
{
success =
AddPrimitive("CountRate", "CountRate1", "Count");
}
else
{
success = DeletePrimitive("CountRate1");
}

//based on success
if (success)
{
Count_RateEnabled.SetHandlerValue = e;
}
else
{
}
}

p. Open the Editor form.
q. From Object Design View, drag the Count.RateEnabled attribute onto the General tab.
r. Save the project.


s. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
t. In the ArchestrA IDE, open the editor for the Counter_001 instance, and verify that all virtual
primitives are added and deleted correctly.
u. Configure the Counter instance as follows:
Check Count.RateEnabled
v. Deploy the Counter_001 instance.
w. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
x. Add a new watch window and rename it to Rate.
y. Add the following attributes to the new watch window:
Object Attribute
Counter_001 Count.Rate
Counter_001 Count.CalcPeriod
Counter_001 Count.RateReset
z. Save the modified watch list.

aa. Verify the runtime behavior of the Counter object by using the scan state of the Blinker to
cause a change of the count rate. Also verify the behavior of the rate calculation when the
Count.RateReset attribute is modified.
Wonderware Training

Create the rate calculator reusable primitive

1. In Microsoft Visual Studio, on the File menu, click New / Project.
2. In the New Project window, create the project as follows:
Project type ArchestrA

Templates: ArchestrA Object
Name: RateCalculator
Location: C:\Wonderware Training
3. Click OK.

4. In Object Designer, change the Category field to Reusable Primitive.
5. Add the following attributes to the RateCalculator primitive:

Rate Float Calculated Frequently Accessed: Check
CalcPeriod Elapsed Time Writeable_C_Lockable Configuration Set Handler: Check
Value: 00:00:10.000 (10 seconds)
RateReset Boolean Writeable_US Runtime Set Handler: Check
Wonderware Training
Implement the rate calculator logic

7. In Object Design View, under Configtime, double-click CalcPeriod Set Handler.
8. In the RateCalculatorConfigtime.cs file, modify the CalcPeriodSetHandler method to make
private void CalcPeriodSetHandler(object sender, ref
{
//Verify that the calculation period is not negative

if (e.Value > TimeSpan.Zero)
{
CalcPeriod.SetHandlerValue = e;
}
else
{
e.Message = "CalcPeriod cannot be negative";
}
}

10. In the RateCalculatorRuntime.cs file, expand the Declarations region and modify it so it
looks exactly like this:
//Variable used to store the name of the attribute

//used as source value for the rate calculation
string myName;
//Variable used to store last analog source value

double lastValue;
//Variable used to store last time rate was calculated

DateTime lastCalculationTime;
11. In Object Design View, under Runtime, double-click Startup.

12. Modify the RateCalculator_RuntimeStartup method to make it look exactly like this:
private void RateCalculator_RuntimeStartup(object sender,
{
//This code assumes that the external name of this primitive
//as assigned within an application object
//is equal to the source attribute name.
//Find this source attribute name

string myExternalName = GetValue(
(short)ECOMMONATTRIBUTES.idxComAttExternalName, ThisPrimitive);
myName = string.Format("myparent.{0}", myExternalName);

//Set initial time of rate calculation


maintain the
must be called


}

14. Modify the RateCalculator_RuntimeExecute method to make it look exactly like this:
private void RateCalculator_RuntimeExecute(object sender)
{
//only if this primitive is loaded
//Find out whether rate is due for calculation

TimeSpan timeSinceCalc = GetScanTime() - lastCalculationTime;
if (timeSinceCalc >= CalcPeriod)
{
//Rate calculation is due
//Get current source value

double currentValue = GetValue(myName);
//Calculate rate
Rate = (float)((currentValue - lastValue)
/ timeSinceCalc.Seconds);
//Set current values as "last"

lastValue = currentValue;
}
}
Wonderware Training
15. In Object Design View, under Runtime, double-click RateReset Set Handler.
16. Modify the RateResetSetHandler method to make it look exactly like this:
private void RateResetSetHandler(object sender, ref
{
//If the attribute is set to true, reset rate
if (e.Value)
{
Rate = 0.0f;
}
//The RateReset attribute is never modified

}
Build and add the RateCalculator primitive

17. On the ArchestrA Object toolbar, ensure that the Build Mode is set to Build.
18. Click the Build Object button to build the RateCalculator primitive.
20. Close the RateCalculator solution, and open the Counter solution.
Count.RateEnabled Boolean PackageOnly_Lockable Configuration Set Handler: Check
22. Add a Reusable Primitive, and select the following file:

C:\Wonderware Training\RateCalculator\Output\RateCalculator1.aaPRI

23. Configure the reusable primitive as follows:

Count CountRate Virtual: Check
24. In the Shape pane, under the Count reusable primitive, click CalcPeriod.
25. In the Configuration pane, change the Value to 00:00:05.000 (5 seconds).
Wonderware Training
Implement virtual reusable primitive add/delete logic

27. In Object Design View, under Configtime, double-click Count.RateEnabled Set Handler.
28. In the CounterConfigtime.cs file, modify the Count_RateEnabledSetHandler method to
private void Count_RateEnabledSetHandler(object sender, ref
{
if (e.Value == Count_RateEnabled)
{
return;
}
//Add or delete the Count (reusable) virtual primitive

bool success;
if (e.Value)
{
success =
AddPrimitive("CountRate", "CountRate1", "Count");
}
else
{
success = DeletePrimitive("CountRate1");
}

//based on success
if (success)
{
Count_RateEnabled.SetHandlerValue = e;
}
else
{
}
}

Modify the Editor

30. From Object Design View, drag the Count.RateEnabled attribute onto the General tab.

36. On the General tab, verify that no errors are generated when adding and deleting the Count
rate primitive by checking and unchecking Count.RateEnabled. Leave Count.RateEnabled
checked when done.
Wonderware Training

42. Add a new watch window and rename it to Rate.
Count.Rate
Count.CalcPeriod
Count.RateReset

45. Verify the following runtime behaviors:

A change in the count rate occurs when Count is counting at a different speed or is
stopped
Hint: You can make the count stop by using the Blinker object.
Setting the Count.RateReset attribute resets the rate calculation
Wonderware Training
Module 7
Object Editor
Section 1 Editor Design 7-3
Lab 12 Enhancing the Counter Editor 7-11
7-2 Module 7 Object Editor
Module Objectives
Use Archestra controls in a custom object editor
Wonderware Training
Section 1 Editor Design
Section Objectives
Describe the process of designing a custom object editor in the ArchestrA Object Toolkit
Explain how to add ArchestrA controls to the Visual Studio Toolbox
This section describes how to design a custom object editor to provide users with a graphical
interface for configuring an application objects attributes in the ArchestrA IDE.
About the custom object editor

To allow end users to configure your objects attributes in the ArchestrA IDE, you need to create a
custom object editor. The custom object editor is the graphical interface that appears when the
user opens the object for configuration in the ArchestrA IDE.
All ArchestrA editors follow a standard design pattern. They are always implemented as .Net
controls that derive from the class aaBaseEditorForm.
The BaseEditorForm class provides a standard tabbed interface that includes one or more custom
tabs defined by the object developer, as well as standard tabs common to all objects. The
BaseEditorForm class also provides communication and data binding services needed by editors
and the controls they contain.
Designing the editor

To start designing your custom object editor, open the Editor form by double-clicking Editor in the
Object Design View. The Editor form appears in the Visual Studio Design view, showing one
empty tab page named tabPage1.
Adding tabs
You can create multiple custom tab pages for your object editor. In the ArchestrA IDE, these
custom tab pages appear alongside the standard tab pages that are shown for every object
(Object Information, Scripts, UDAs, etc.).
You can hide these standard editor tabs if you do not need them. To hide these tabs, open Object
Designer, select the object in the Shape pane, and check the Hide Standard Editor Tabs option
under IDE Behavior.

To add a new tab, right-click the forms tab control and click Add Tab.
Tab control
To rename a tab, change its Text property in the Visual Studios Properties window.
To delete a tab, bring it to focus and then right-click the forms tab control and click Remove Tab.
Embedding controls
Your editor should have controls to allow the user to configure all configurable attributes of the
object and its primitives. Your editor can also include controls for configuring attributes of virtual
primitives. In the ArchestrA IDE, these controls are automatically enabled or disabled depending
on whether the virtual primitive instance exists or not.
To place controls in your custom object editor, drag controls and items onto a tab page on the
Editor form. You can use the following types of controls and items:
Attributes from the Object Design View (The ArchestrA Object Toolkit automatically adds
a standard label as well as ArchestrA controls for editing the value, security classification,
and lock status of that attribute.)
Standard UI design controls and items from the Visual Studio Toolbox
Special ArchestrA controls that have been added to the Visual Studio Toolbox
Wonderware Training
Note: The ArchestrA controls are in the ArchestraEditorFramework.dll file located in

the following folder by default:
C:\Program Files\Wonderware\Toolkits\ArchestrA Object\Bin
Object dictionary items from the Object Design View (The ArchestrA Object Toolkit
automatically adds a label that will show the correct localized value at runtime.)
Binding controls
After you have added controls to your object editor, you can associate (link) them with an attribute
in code. To do this, set the controls Attribute property (in the Properties window) to the external
name of the attribute.
You can also do this programmatically from configtime code. This allows you, among other things,
to configure multiple primitive instances using the same editor page. For example, to set the
attribute reference of the control instance aaTextBox1 to Prim1.Attr1, use this statement:
aaTextBox1.Attribute = "Prim1.Attr1";
Framework Controls
Most framework controls are designed to easily bind to and automatically display a single attribute
value. Although the presentation of the attribute values vary with each control, the basic design
pattern for all of these controls is consistent and share the following characteristics:
The controls derive from a standard WinForm control. That control's properties and events
are therefore available in the associated editor framework control.
The controls implement the interface IaaControl. These methods are normally called only
by the containing editor's base class.
The controls expose the standard properties and events, as discussed below.
Properties
Attribute: The name of the attribute that the control is bound to. The control will subscribe
for data associated with this attribute.
ControlStyle: Provides some information to the editor infrastructure about how to process
the control. This value will always be AACONTROLSTYLE_TabPageContent for user
defined controls.
Enabled: Each control overrides the base class defined Enabled property. This is needed
to manage how controls are enabled in response to user and system interactions with the
form. The rules for enabling and disabling are as follows:
Any enabled control can be disabled by the editor code or the system.
A control that has been disabled by the editor can only be enabled by the editor. The
system cannot enable an editor disabled control.
A control that has been disabled by the system can only be enabled by the system.
The editor cannot enable a system disabled control.
If the editor is opened in read-only mode neither the editor nor the system can enable
a disabled/read-only control.
Dictionary & PhraseID (optional): These properties only apply to controls which can
display localizable text. Specifies the Dictionary file (.aaDCT) to use and the PhraseID
identifying the localized text within it. If the dictionary is left blank, the default dictionary for
the editor will be assumed.

Events
These events are raised when the controls associated IaaControl methods are processed. This
allows editors, for example, to react to data changes for a specific control.
Initialized
Syntax
private void Initialized(object sender, EventArgs e);
Remarks
Called early in the loading process, before the Editor is completely loaded and functional.
This method can be overridden in order to handle custom initialization tasks.
DataChanged
Syntax
private void DataChanged(object sender, DataChangeEventArgs e);
Remarks
This method is called when a subscribed attribute's value has changed. The form will then
pass on the event to all controls that have subscribed to the data.
Applied
Syntax
private void Applied(object sender, EventArgs e);
Remarks
This method is called when the current Editor values are saved, for example, when the
user clicks the Save button in the ArchestrA IDE. The form will then pass on the event to
all controls currently enabled.
Editor Methods
GetData
Syntax
public object GetData(string sAttribute, string sProperty);
Parameters
sAttribute Attribute external name. In addition, GetData() supports reading individual
elements of arrays using the syntax: attributename[index].
sProperty Property to access. Possible values are:
value The attribute's value. The type of object returned will depend on the
attribute's type. Bools are returned as System.Booleans, Integers are returned as
System.Int32s. All other non-array datatypes are returned as a System.Strings.
Arrays are returned as System.Object[] containing elements for the attribute's
datatype.
securityclassification The attribute's security classification. Returned as
one of the following System.Strings:
MxSecurityFreeAccess
Wonderware Training
MxSecurityOperate
MxSecuritySecuredWrite
MxSecurityVerifiedWrite
MxSecurityTune
MxSecurityConfigure
MxSecurityReadOnly
MxSecurityUndefined
lock The attribute's lock status. Returned as one of the following
System.Strings:
MxUnLocked
MxLockedInMe
MxLockedInParent
MxSecurityUndefined
valuereadonly, lockreadonly, and securityclassificationreadonly
These are not true ArchestrA attribute properties. They indicate whether the
specified property is writeable. Controls that modify attributes should monitor
these items and enable/disable themselves (or change to a readonly mode)
based on their value, but only if the editor itself is not ReadOnly and the control
was not disabled via its Enabled property. In those situations the control should
remain disabled.
The value returned is a System.Boolean.
attributecategory Returned as a System.Int32
type Returned as a System.Int32
upperbounddim1 The length of a attribute containing an array. Returned as a
System.Int32
enumstringarray Returns a System.String[] defining an attribute of type
"custom enumeration"
isenum Returns a System Boolean. True if attribute is an enumeration
Remarks
Returns the value of an attribute or one of its other properties. Value will be null if not
present.
SetData
Syntax
public void SetData(string sAttribute, string sProperty, object sVal);
Parameters
sAttribute Attribute external name
sProperty Property to access. Possible values are those listed for GetData, or:
add Valid only if attribute is "beo:UDAs" or "beo:ScriptExtension". sVal specifies
name of UDA or script extension to add.
delete Valid only if attribute is "beo:UDAs" or "beo:ScriptExtension". sVal
specifies name of UDA or script extension to remove.
Remarks
This function is used to set data into a specific attribute. If not passed, the property is
assumed to be the attribute's value.

If the set fails, a message will be displayed to the user via a message box. The success or
failure of the SetData() call can also be checked by calling the editor's IsSuccess()
method.
GetLocalizedText
Syntax
public object GetLocalizedText(string sPhraseID, string sDictionary);
Parameters
sPhraseID The PhraseID within the dictionary to retrieve
sDictionary The associated aaDCT file to retrieve the text from (If blank, the editor's
Dictionary property is used instead.)
Remarks
This function returns localized text for the specified Phrase ID from the specified
dictionary.
LogError
Syntax
public void LogError(string strMsg);
Parameters
strMsg The string to add to the ArchestrA log file
Remarks
This function adds the string to the Archestra logger as a LogError message.
LogWarning
Syntax
public void LogWarning(string strMsg);
Parameters
Remarks
This function adds the string to the Archestra logger as a LogWarning message.
LogInfo
Syntax
public void LogInfo(string strMsg);
Parameters
Remarks
This function adds the string to the Archestra logger as a LogInfo message.
Wonderware Training
LogException
Syntax
public void LogException(Exception ex);
public void LogException(Exception ex, string str);
Parameters
ex The exception to be logged
str Optional text to add to the log entry
Remarks
This function will format the exception (message and stacktrace) into a string and add the
formatted string to the ArchestrA logger as a LogError message. If desired, an optional
message can be included.

Wonderware Training
Lab 12 Enhancing the Counter Editor

Introduction
In previous labs, you have customized the Counter's editor in order to fully test the capabilities of
the object. You have used the automatic control generation feature of Object Design View to
create a simple, but fully functional editor interface. In this lab, you will enhance this simple editor,
taking advantage of the ArchestrA controls library to create a richer editor interface. You will first
bring the ArchestrA controls into the Visual Studio Toolbox. Then, you will use these controls to
modify the Alarms tab of the Counter and make it look like the figure below. You will configure the
ArchestrA controls to show the Counter alarm attributes, therefore taking advantage of the data
binding provided by the controls. Finally, you will write some simple code to enhance the usability
of your new editor interface.
Objectives
Add ArchestrA controls to the Visual Studio Toolbox
Use ArchestrA controls to implement a custom object editor


Add ArchestrA controls to the Visual Studio Toolbox (page 7-14)

b. Open the Editor form.
c. In the Visual Studio Toolbox, add a new tab named ArchestrA.
d. Add to the ArchestrA tab all controls in the following library:
C:\Program Files\Wonderware\Toolkits\ArchestrA Object\Bin\ArchestraEditorFramework.dll
e. On the ArchestrA tab, sort the items alphabetically.
Enhance the Counter's editor (page 7-16)

f. Using the ArchestrA controls, modify the Alarms tab to make it look like the editor shown on
page 7-11.
g. Configure the properties of the ArchestrA controls on the Alarms tab so they will be bound to
the Counter attributes as follows:
Editor Element Attribute
Timeout Alarm Timeout.Condition.Alarmed
Limit Timeout.Limit
Priority Timeout.Condition.Priority
Alarm Message Timeout.Condition.DescAttrName
Modify the editor logic (page 7-18)

h. Configure the name properties of the controls on the Alarm tab as follows:
Editor Element (Name) Property
Timeout Alarm check box aaTimeoutConditionAlarmed
Limit text box aaTimeoutLimit
Limit lock icon aaTimeoutLimitLock
Limit security classification icon aaTimeoutLimitSC
i. Implement the DataChanged event of the aaTimeoutConditionAlarmed control, and modify

it to make it look like this:
private void aaTimeoutConditionAlarmed_DataChanged(object sender,
ArchestraEditorFramework.DataChangeEventArgs e)
{
//Verify the event argument SubItem property.
//SubItem indicates, for the subscribed attribute,
//which property has changed.
//In this case, we only want to catch events
//where the value of the attribute has changed.
if (string.Compare(e.SubItem.ToString(), "value", true) == 0)

{
Wonderware Training
//Enable Timeout Limit text box

//only if the alarm is enabled
bool alarmEnabled = (bool)e.Value;
aaTimeoutLimit.Enabled = alarmEnabled;
//Enable Timeout Limit lock icon

//and the lock status is not read only
bool lockReadOnly = (bool)GetData(
aaTimeoutLimitLock.Attribute, "lockreadonly");
aaTimeoutLimitLock.Enabled = alarmEnabled && !lockReadOnly;
//Enable Timeout security classification icon

//and the security classification is not read only
bool securityClassificationReadOnly =
(bool)GetData(aaTimeoutLimitSC.Attribute,
"securityclassificationreadonly");
aaTimeoutLimitSC.Enabled = alarmEnabled &&
!securityClassificationReadOnly;
}
}
j. Save the project.

k. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
l. In the ArchestrA IDE, open the editor for the $Counter_001 template, and verify the behavior
of the Alarms tab.
m. Configure the $Counter_001 template as follows:
Check Timeout Alarm
Set Priority to any number between 1 and 999
Set Alarm Message to Counter Input Timeout Alarm
Lock the Alarms group
n. Save and close the template editor.
o. Configure the Counter_001 instance by setting the count input source to Blinker_001.Bit.
p. Deploy the Counter_001 instance.
q. Open Object Viewer and, if not opened yet, open the watch window you have used in previous
labs.
r. Add the following attributes to the Alarms watch window:
Object Attribute
Counter_001 Timeout.Condition.Priority
Counter_001 Timeout.Condition.DescAttrName
s. Save the modified watch list.

t. Verify that the runtime values of the alarm attributes correspond with the values configured in
the IDE.


Add ArchestrA controls to the Visual Studio Toolbox

3. If the Visual Studio Toolbox is not showing, click the View menu, and then click Toolbox.
4. In the Toolbox, right-click and click Add Tab.
5. Name the new tab ArchestrA.

6. Right-click in the new tab and click Choose Items.
Wonderware Training
The Choose Toolbox Items dialog box appears.
7. Click Browse and select the following library:

C:\Program Files\Wonderware\Toolkits\ArchestrA Object\Bin\ArchestraEditorFramework.dll
8. Click Open.
All the ArchestrA controls in the library are added and selected in the Choose Toolbox Items
dialog box.

9. Click OK to add the controls to the Toolbox (it will take a few moments to populate).
10. Right-click on the ArchestrA tab and click Sort Items Alphabetically.
Enhance the Counter's editor

Now you will use the ArchestrA controls to make the Alarms tab look like the editor shown below:
11. On the Editor form, click the Alarms tab.

12. Delete the aaAlarmExtensionCtl1 control and its corresponding label.
13. Add an aaGroupBox control to the tab, and then change its label to Alarms.
14. Place an aaLockGroupIcon control inside the group next to the Alarms label.
Note: To ensure that the aaLockGroupIcon control will lock the controls in the group, do
not move it outside the group.
15. Move the alarm Timeout Condition and Limit controls (the remaining controls) to inside the
group, and then change their labels as necessary.
Wonderware Training
16. For the alarm priority, place the following controls inside the group, and then change the label
as necessary:
aaLabel
aaTextBox
aaLockIcon
aaSecurityClassification
17. For the alarm message, place the following controls inside the group, and then change the
label as necessary:
aaLabel
aaTextBoxMxReference
aaLockIcon
aaSecurityClassification
18. Arrange the controls to look like the Alarms tab shown on the previous page.
Next you will configure the properties of the ArchestrA controls so they will be bound to the
Counter attributes.
19. On the Alarms tab, select the Priority text box, lock icon, and security classification icon.
20. In the Properties window, locate the Attribute property and change it to
Timeout.Condition.Priority.
21. Repeat the previous steps to change the Alarm Message attribute properties to
Timeout.Condition.DescAttrName.
Note: The lock group icon control is not bound to any attribute, but it is bound to all controls
within the same group.

Modify the editor logic

Next you will modify the logic so the alarm Limit controls become disabled when the Timeout
Alarm check box is unchecked. This is necessary because the rest of the alarm controls are
automatically disabled when the alarm primitive is deleted in configtime, but since the alarm Limit
does not belong to the alarm primitive, it needs to be disabled explicitly.
22. Click the Timeout Alarm check box control.
23. In the Properties window, locate the (Name) property and change it to
aaTimeoutConditionAlarmed.
24. Repeat the previous steps to change the following name properties:
Editor Element (Name) Property
Limit text box aaTimeoutLimit
Limit lock icon aaTimeoutLimitLock
Limit security classification icon aaTimeoutLimitSC
Now you will implement the DataChanged event of the aaTimeoutConditionAlarmed control.
25. Click the Timeout Alarm check box control.
26. On the toolbar of the Properties window, click Events.
27. Locate the DataChanged event and double-click it.

28. In the CounterEditor.cs file, modify the event code to look like this:
private void aaTimeoutConditionAlarmed_DataChanged(object sender,
ArchestraEditorFramework.DataChangeEventArgs e)
{
//Verify the event argument SubItem property.
//SubItem indicates, for the subscribed attribute,
//which property has changed.
//In this case, we only want to catch events
//where the value of the attribute has changed.
if (string.Compare(e.SubItem.ToString(), "value", true) == 0)

{
//Enable Timeout Limit text box
bool alarmEnabled = (bool)e.Value;
Wonderware Training
aaTimeoutLimit.Enabled = alarmEnabled;
//Enable Timeout Limit lock icon

//and the lock status is not read only
bool lockReadOnly = (bool)GetData(
aaTimeoutLimitLock.Attribute, "lockreadonly");
aaTimeoutLimitLock.Enabled = alarmEnabled && !lockReadOnly;
//Enable Timeout security classification icon

//and the security classification is not read only
bool securityClassificationReadOnly =
(bool)GetData(aaTimeoutLimitSC.Attribute,
"securityclassificationreadonly");
aaTimeoutLimitSC.Enabled = alarmEnabled &&
!securityClassificationReadOnly;
}
}

33. In the ArchestrA IDE, open the editor for the $Counter_001 template.
34. Verify the behavior of the Alarms tab.
35. Configure the $Counter_001 template as follows:
Check Timeout Alarm
Set Priority to any number between 1 and 999
Set Alarm Message to Counter Input Timeout Alarm
Lock the Alarms group

36. Save and close the template editor.

37. Open the Counter_001 instance.
43. Add the following attributes to the Alarms watch window:
Timeout.Condition.Priority
Timeout.Condition.DescAttrName

45. Verify that the runtime values of the alarm attributes correspond with the values configured in
the IDE.
Wonderware Training
Module 8
Advanced Features
Section 1 Application Objects Documentation 8-3
Section 2 Object Dictionary 8-5
Lab 13 Using the Object Dictionary 8-7
Section 3 Version Management 8-13
Section 4 Dependent Files 8-21
8-2 Module 8 Advanced Features
Module Objectives
Describe how to add object help to a custom object template
Configure the object dictionary file to contain user error messages that can be retrieved
by runtime and configtime set handlers
Explain the object versioning options and migration features
Describe dependent file management
Wonderware Training
Section 1 Application Objects Documentation 8-3
Section 1 Application Objects Documentation
Section Objectives
Explain how to include object help with a custom application object.
This section describes how to add object help to your custom application object so that end users
can access it from the ArchestrA IDE.
Help documentation
You should provide documentation with your application objects that includes help on object
usage, configuration, runtime behavior, and attributes. The help should be in the form of an
Object Help page so that end users can access it from the ArchestrA IDE.
The .aaPDF file that Visual Studio generates contains only the configuration data and
implementation code for your base object template; it does not contain an object help file. To
provide object help for your end users, you need to package your object in an .aaPKG file, as
described in the procedure below.
Creating the object help file

Your object help must be a standard HTML file. Do not use Microsoft Word as an editor to create
object help HTML pages. Use a proper HTML editor. You may find it easier to start with an existing
object help file to use as a template, such as one that is included with Wonderware Application
Server. (See below for object help folder locations.)
You can use the following procedure to create an object help file from a predefined template
containing headers for common topics or from an existing help file. If you create your object help
file this way, the file will automatically be saved to the correct help folder for your object.
Important: Before using this procedure, you should ensure that your systems file association for
.htm files is set to a proper HTML editor.
a. Develop and test your object as usual.

b. Import your objects final .aaPDF file into the ArchestrA IDE.
a. In the ArchestrA IDE, open the editor for the base template of your object.
b. On the Object Information tab, click Add Object Help.
The dialog box shown below appears:
c. Click No to open a predefined template, or click Yes to browse for a pre-existing help file.
d. Add your custom text to the object help file.
e. Save the file.

f. Export your object as an .aaPKG.

The exported .aaPKG file will contain your objects .aaPDF file as well as you object helps
.htm file. When you import the .aaPKG file into a different Galaxy, the object help file is
automatically imported and saved to the correct location.
Help folder locations

The path to each objects Help folder is unique. It depends on where the Galaxy Repository is
installed and the name of the Galaxy and the object ID. The default path to an objects help file is:
C:\Program Files\ArchestrA\Framework\FileRepository\<YourGalaxyName>\Objects\
<TheObjectID>\Help\1033
If you have not saved a help file in your objects help folder, you can find the correct folder location
name by importing your object template into the ArchestrA IDE, and then right-clicking on the
object and selecting Object Help. The help window appears with a message that no help file could
be found.
This is the path and file name that will be used for your object help file after it is added using the
ArchestrA IDE. If you have images in your help file, place them in the proper folder and use a
relative path to those images in the HTML file. For example, place them in the \1033 folder or
create an images folder under it.
To test that your object can find the help file, right-click on the object in the ArchestrA IDE and
select Object Help.
Wonderware Training
Section 2 Object Dictionary 8-5
Section 2 Object Dictionary
Section Objectives
Specify the purpose of the object dictionary file
Explain how to use the object dictionary for internationalizing objects
This section provides an overview of the object dictionary, including what it is used for, how to edit
the dictionary file, and how to use it for internationalizing objects.
About the object dictionary

You can use the object dictionary for:
A central repository for user error and warning messages that can be used in code
Localization or internationalization purposes by specifying phrases for different locale IDs
The object dictionary file

The object dictionary is saved as an XML file with the .aaDCT extension. By default, it contains
only a sample entry (shown below) and you have to add your own messages, phrases,
translations, etc. to it before you can use it.
<?xml version="1.0" encoding="UTF-8"?>
<Dictionary>
<Phrase_Index PhraseID="SampleEntry">
<Language LangID="1033">
<VALUE>English Example</VALUE>
</Language>
<VALUE>German Example</VALUE>
</Language>
</Phrase_Index>
</Dictionary>
There is a single Phrase_Index element for every translatable string. Its PhraseID attribute
defines the ID by which you can access the string.
Each Phrase_Index element contains one Language element for each language-specific
translation of the string. The LangID attribute of the Language element specifies the locale that the
translation applies to.
Each Language element contains a single VALUE element with the translated string for the
specified locale.
Editing the dictionary file

You can edit the dictionary using any text editor or a special XML editor. You can also directly edit
the object dictionary with the ArchestrA Object Toolkit using the built-in Visual Studio 2008 XML
editor. The Visual Studio editor adds some XML-aware features including Intellisense. However,
more advanced editors provide additional features focused on particular tasks such as
highlighting.

To edit the dictionary file in Visual Studio, double-click Dictionary in

the Object Design View.
Retrieving dictionary strings

To retrieve a dictionary string at configtime or runtime, simply use
the GetText method. For example:
GetText("idsError");
This statement gets the translation for the dictionary entry with the ID idsError for the default
locale of the process it is called from. For configtime code, this is the default locale of the Galaxy
(the operating system locale at the time the Galaxy was created).
If your object will be used in localized environments, you can internationalize it by defining a
multilingual dictionary that contains translated strings for the target locales. At runtime, the object
can retrieve the appropriate strings for the locale it is used in, and show those translated strings to
the end user.
By internationalizing an object, you enable it to run in various language environments and use
different translated text messages, prompts, etc. in each case. For example, assume that you
develop a complex object with its own custom editor pages. Customers in North America would
expect to see English editor pages. On the other hand, customers in South America might use the
object on a Spanish operating system and expect to see the editor pages in Spanish.
One way to do this is to create and maintain separate language versions of the object. However,
this makes it very hard to maintain and update your code. A better way is to maintain one object
version that will use the correct translated strings depending on the locale it is used in.
To do this, you separate the objects code (which works identically in all locales) from the
translatable text phrases (which are different for each locale). The translatable content in the code
is replaced with abstract phrase IDs. The object then retrieves the appropriate translated content
for whatever phrase ID it needs, when it needs it.
ApplicationObject running in English locale Same ApplicationObject running in Spanish locale
GetText("idsWelcome"); GetText("idsWelcome");
Object Dictionary Object Dictionary

Phrase ID English Spanish Phrase ID English Spanish
idsWelcome Welcome Bienvenidos idsWelcome Welcome Bienvenidos
... ... ... ... ... ...
If an application object contains local primitives, all local primitives use the objects main
dictionary. Reusable primitives, on the other hand, have their own dictionary.
Wonderware Training
Lab 13 Using the Object Dictionary

Introduction
In this lab you will modify the Counter's dictionary file to contain user error messages that can be
retrieved by the runtime and configtime set handlers. The dictionary file is the localization
mechanism in the ArchestrA Object Toolkit which allows you to specify phrases for different locale
IDs. You will not use the dictionary for localization in this lab, but you will use it as a central
repository for the various user messages used throughout your code. This is a best practice
because it makes your code easier to write, read, and maintain. After you modify the dictionary file,
you will modify the runtime and configtime logic to allow set handler methods to return user error
messages from the dictionary file instead of hardcoded error strings.
Count

GetStatusDesc()
Counter MaxCount_ConfigtimeSH()
Timeout_Limit_ConfigtimeSH()
DICTIONARY legend to this graphic.
Objectives
Modify the object dictionary file and use it to retrieve user error messages


Modify the object dictionary (page 8-10)

b. Open the Dictionary file, and modify it to make it look like this:
<Dictionary>
</Language>
</Language>
</Phrase_Index>
<Phrase_Index PhraseID="10001">
<VALUE>MaxCount must be greater than 0</VALUE>
</Language>
</Phrase_Index>
<VALUE>Timeout Limit cannot be negative</VALUE>
</Language>
</Phrase_Index>
<VALUE>Reset cannot be modified because Reset Input is enabled</VALUE>
</Language>
</Phrase_Index>
</Dictionary>
Modify the runtime logic to use the dictionary file (page 8-11)
c. Modify the GetStatusDesc method of the Runtime project to make it look exactly like this:
{
{
//All error codes will be retrieved from the dictionary
//using the GetText() method
default:
break;
}
}
Wonderware Training
Modify the configtime logic to use the dictionary file (page 8-11)
d. Modify the Configtime Set Handler for the MaxCount attribute to make it look exactly like
this:
{
if (e.Value > 0)
{
}
else
{
e.Message = GetText(10001);
}
}
e. Modify the Configtime Set Handler for the Timeout.Limit attribute to make it look exactly like
this:
{
if (e.Value > 0)
{
}
else
{
}
}

f. Use the ArchestrA Object toolbar, to build, import, and instantiate the Counter object.
g. In the ArchestrA IDE, open the editor for the Counter_001 instance, and verify that you get the
appropriate error messages when setting invalid values for MaxCount and Timeout.Limit.
h. Configure the Counter instance as follows:
Set Reset.InputEnabled to True
Set the reset input source to Blinker.ResetTrigger
Check Timeout Alarm
i. Deploy the Counter_001 instance, open Object Viewer and, if not opened yet, open the watch
window you have used in previous labs.
j. Verify in runtime that you get the appropriate error messages when setting invalid values for
MaxCount, Timeout.Limit, and Reset.


Modify the object dictionary

2. In Object Design View, double-click Dictionary.
3. The objects dictionary file opens:
4. Modify the dictionary file to make it look like this:

<Dictionary>
</Language>
</Language>
</Phrase_Index>
<VALUE>MaxCount must be greater than 0</VALUE>
</Language>
</Phrase_Index>
<VALUE>Timeout Limit cannot be negative</VALUE>
</Language>
</Phrase_Index>
<VALUE>Reset cannot be modified because Reset Input is enabled</VALUE>
</Language>
</Phrase_Index>
</Dictionary>
Wonderware Training
Modify the runtime logic to use the dictionary file

6. In the CounterRuntime.cs file, modify the GetStatusDesc method to make it look exactly like
this:
{
{
//All error codes will be retrieved from the dictionary
//using the GetText() method
default:
break;
}
}
Modify the configtime logic to use the dictionary file

7. In Object Design View, under Configtime, double-click MaxCount Set Handler.
8. In the CounterConfigtime.cs file, modify the MaxCountSetHandlerfor method to make it
{
if (e.Value > 0)
{
}
else
{
}
}
9. In Object Design View, under Configtime, double-click Timeout.Limit Set Handler.

10. In the CounterConfigtime.cs file, modify the Timeout_LimitSetHandler method to make it
{
if (e.Value > 0)
{
}

else
{
}
}

15. On the General tab, ensure that you get the appropriate error message when setting an
invalid value (less than zero) for MaxCount.
17. Check Reset.InputEnabled.
18. Set the reset input source to Blinker.ResetTrigger.
19. On the Alarms tab, check Timeout Alarm.

20. Ensure that you get the appropriate error message when setting an invalid value (less than
zero) for Limit.
25. Verify that you get the appropriate error messages when setting invalid values for MaxCount,
Timeout.Limit, and Reset.
Wonderware Training
Section 3 Version Management
Section Objectives
Identify the different object versioning options and summarize how they are used
Explain how to use the Migrate tool and enter migration code
This section describes object versioning for major and minor builds of an object. It also provides
information about migration of new object versions into an application in the Wonderware
Application Server.
Object versioning
An application object has a version number that consists of a major version and a minor version.
For example, 1.3 where 1 is the major version and 3 is the minor version. This version number
helps Application Server distinguish object versions and detect any migration requirements.
When you build your object, you can keep the current version number, or you can automatically
increment the minor or major version. You can also specify the version numbers manually in the
object properties.
While developing an object, it is safest to have the major version number increment automatically
on new builds. This helps avoid problems if you change the object shape but forget to increment
the major version accordingly. Once there is a stable build and successful test, you can reset the
major revision number back to the desired number and do a final Build.
Minor version builds

A minor version update is equivalent to a service pack update. Neither the intended functionality
nor attribute and primitive definitions need to be changed in any way. The only changes that are
considered minor are bug fixes or performance improvements. If you change the object shape in
any way, you must increment the major version instead.
When you build a new minor version of an object, you can choose to automatically restart
Application Server processes. This is necessary if you have already imported a previous version of
the object with the same major version into your Application Server working Galaxy. If you do not
restart the processes, Application Server continues to use the previous version even after you
import the new minor version.
The ArchestrA Object Toolkit can only restart processes running on the local machine. For
example, if you are using a remote Galaxy Repository (GR) machine or if you have deployed your
object to a remote machine, you must restart the relevant processes manually.

Building a minor version

To build a new minor version of your object, open the Options dialog box, select the Version
category, and select the Increment Minor Version option.
Then select the Restart Bootstrap, Restart aaGR and Restart IDE check boxes as required (see
above). If you select Restart aaGR, Restart IDE is always selected as well.
Major version builds

Any change to an existing object that is not minor (see above) is considered major. Except for
simple bug fixes or performance enhancements, changes to an object are major. This includes
any change to the definition of the objects attributes or primitives.
While you develop an object, it is recommended that you use this setting to have the major version
number increment automatically on new builds. This helps avoid problems if you change the object
shape but forget to increment the major version accordingly.
When you build an object with a new major version, you can choose to automatically delete the old
versions templates and instances from your working Galaxy. Alternatively, you can have the new
version imported with the version number appended to the template name. This allows you to keep
multiple versions of the same template in the Galaxy without having to manually rename existing
templates.
Building a major version

To build a new major version of your object, open the Options dialog box, select the Version
category, and select the Increment Major Version option.
Then specify what to do with existing templates and instances if the ArchestrA Object Toolkit
automatically imports the new object version into the Galaxy.
To keep the old template version and import the new version with the version number
appended to its name, select the Append version number to template name check box.
To delete all previous versions of the object template (as determined by its vendor and
object name), select the Delete all templates with the same vendor and object name
check box. Any instances of these templates are deleted too.
To delete all previous versions of the object template and import the new version with the
version number appended to its name, select the Delete all templates and append
version number check box.
Wonderware Training
Building without incrementing the version

You can create a new build without incrementing the objects current version number. For
example, you would do this if:
You are using an automated build system that only recompiles the project.
You set the final version number manually before release and dont want the final build to
increment that number.
When you build an object using this option, the only available build modes are Build and Build &
Swap.
To build an object without incrementing the version number, open the Options dialog box, select
the Version category, and select the Retain current version number option.

Manually specifying the version number

If you want to reset the auto-generated version number, you can manually specify the objects
version number. Open the Object Designer, select the object name in the Shape pane, and then
enter the objects major and minor version numbers in the Configuration pane.
Migration
When you import a new major version of an object template into Wonderware Application Server,
existing instances of that object can be automatically migrated. This allows you to preserve their
configuration in the new object version.
This is very easy if the new object version uses the same attributes as the previous version. In this
case, all attribute values are automatically copied over from the old versions instances to the new
versions instances.
However, you must create custom migration code if:
The new version has attributes that the old version does not have, and vice versa; and/or
The security classification of an attribute has changed in the new version.
In this scenario, the custom migration code handles the mapping of attribute values between the
old and new version. For example, if you have changed an attributes name from Attribute1 to
AttributeA, but the attribute still has the same purpose, the migration code could copy the value
of Attribute1 (in the old version) to AttributeA (in the new version). This code has to be written in
the Migrate event handler in configtime. See page 8-18 for an example of the migration code.
Migrate tool in the ArchestrA Object Toolkit

If you are developing a new version of an existing object, you can use the Migrate tool in the
ArchestrA Object Toolkit to help you structure the code for migrating the existing object. This tool
will generate a list of which attributes were added, removed, or have changed.
You simply select a previous object version (must have the same object name and vendor name),
and the ArchestrA Object Toolkit inserts a code region containing the names of all attributes that
have changed between the previous version and the current version. You can then add migration
code for each attribute.
Wonderware Training
Use the following steps to create a migration code section for a previous version:
a. On the ArchestrA Object toolbar, click the Migrate button.
b. Open the .aaPDF file of the previous object version (or the .aaPRI file if you are developing a
reusable primitive), and then click Open. You can now view the auto-generated migration
analysis results.
c. In Object Design View, expand the Configtime folder, and then double-click Migrate. The
migration results section opens in the code editor.
Note that the ArchestrA Object Toolkit has inserted a new code region showing the differences
between the two versions. Enter any required migration code for the previous version here.
The ArchestrA Object Toolkit has also automatically updated the ObjectAttributes.Migrate property
to include the version number of the object that you selected in step b above. This tells Application
Server that your application object supports migrating from that version. For more information on
this property, see the ArchestrA Object Toolkit Reference Guide.
You can repeat this process for multiple previous versions of an object. The ArchestrA Object
Toolkit generates a separate code region for each previous version. This allows you to have
migration code for multiple previous versions in the same object.

ConfigtimeMigrate event
The ConfigtimeMigrate event is triggered when importing a template into a Galaxy that contains
a previous version (major) of the template. The template of the previous version must be derived
or instantiated for Migrate to execute. This event handler is where you can write any code to
implement custom migration of attributes.
The ArchestrA Object Toolkit automatically generates code to register the delegate
<objectname>Configtime_ConfigtimeMigrate for this event. Using the MigrateHandler parameter,
a user can access the previous version's attribute information in this delegate.
Syntax
public event MigrateDelegate ConfigtimeMigrate;
Example migration code

You can find a short example of migration code in the ArchestrA Object Toolkit by looking at the
code region of the Migrate configtime event handler. In this example, major version 1 of the object
had an attribute named Eg_001, which was renamed to Example_001 in the current version.
The migration code transfers the value and settings of the old attribute to the new attribute.
//Check major version of previous template

if (migrate.MajorVersion() == 1)
{
//Attribute "Eg_001" has been renamed to "Example_001".
//Transfer attribute value, lock and security classification
Example_001 = migrate.GetValue("Eg_001"); //Gets value
Example_001.Locked = migrate.GetLocked("Eg_001"); //Gets lock status
Example_001.Security = migrate.GetSecurity("Eg_001"); //Gets Security
Classification
//Transfer primitive values

SetValue("Example_001.TrendHi", migrate.GetValue("Eg_001.TrendHi"));
SetValue("Example_001.TrendHi", EATTRIBUTEPROPERTY.idxAttribPropLocked,
migrate.GetLocked("Eg_001.TrendHi"));
//Automatically migrate all child primitives

migrate.AutoMigrateChildPrimitives = true;
}
Note the if condition at the beginning of the code. Using similar conditions, you can have
additional, separate migration code sections for other previous major versions of the object.
Additional Guidelines for Migrating Objects

Note the following when developing migration code for your objects:
Make sure that your migration code is aware of the presence or absence of child virtual
primitives.
When migrating attributes within a reusable primitive, the migration code must use the full
primitive name to access the attribute in the original object being migrated from. You can
use the OriginalPrimitiveFullName property in the MigrateHandler class for this purpose.
For example:
migrate.GetValue(migrate.OriginalPrimitiveFullName + ".Attribute1")
Wonderware Training
ArchestrA IDE Import Preferences

When you import an object into the Application Server, the Import Preferences dialog box, shown
below, appears so you can specify how to handle version mismatches and name conflicts.
The options in this dialog box are divided into three sections. When migrating a new major version
of your object template, you need to pay attention to the middle section.
Top section Specifies whether an object (derived template or instance) can be imported
if an object with the same tagname already exists in the Galaxy and that object is derived
from the same Codebase (same base template). This basically deals with importing
different configuration versions of derived templates and instances.
Middle section Specifies whether a base template can be imported if it has a different
revision number in its Codebase than a related template in the Galaxy (new minor or
major version of the same base template) and importing it would require objects to be
migrated to a newer implementation version.
If you select Migrate and an object requires migration, older versions of the objects
being imported or already existing in the Galaxy will be migrated to the newer version:
If an imported object has an older implementation version than an existing related
object in the Galaxy, it will be migrated to the newer version when it is imported.
If an imported object has a newer implementation version than existing related
objects in the Galaxy, they will be migrated to the newer implementation that was
just imported.
If you select Skip, objects that require migration will not be imported.
Bottom section Specifies how to resolve a name conflict if an object being imported has
the same tagname as an existing one in the Galaxy but is derived from a different
Codebase. This basically deals with name conflicts when importing an entirely different
object.

Wonderware Training
Section 4 Dependent Files
Section Objectives
Explain how set up dependent file associations by using rules and by setting the
associations manually
Explain how to configure additional search paths for dependent files
This section provides an overview of dependent files and explains how to configure them in the
Overview of dependent files

If your project contains references to custom files or libraries/assemblies, you must associate
these dependent files with the object definition. This ensures that they are included when you
build the object. The associated files become part of the .aaPDF object package file. When you
later import the object on the target system, each associated file is automatically registered on that
system based on its type.
If you know that the required files will already be present on the target system, you can also tell the
ArchestrA Object Toolkit to specifically ignore these files. In that case, the files are not included in
the object package. This is handy for references to standard Windows or ArchestrA assemblies.
There are two ways to configure associated files:
For files that are set up as references in Visual Studio (for example, custom or third-party
assemblies), you set up rules using the Dependent File Manager. All files covered by a
rule are then automatically added to the objects Associated Files list in the Object
Designer. For more information, see Setting up rules for dependent files below.
For files not set up as project references in Visual Studio (for example, custom data files),
you set up the association manually in the Associated Files list in the Object Designer.
For more information, see Configuring associated files manually on page 8-24.
Setting up rules for dependent files

If you have files set up as project references in Visual Studio (for example, custom or third-party
assemblies), you need to associate the files with your object by setting up rules in the ArchestrA
Object Toolkits Dependent File Manager (shown on the next page).
Rules are regular expressions that can cover multiple references. You must set up rules for all
project references that you have set up in Visual Studio before you can build your object. All files
that are linked to the references covered by a rule are automatically added to the objects
Associated Files list in the Object Designer (shown on page page 8-24).
Rules are checked in the order that they appear in the Dependent File Manager. After the
ArchestrA Object Toolkit finds a rule that matches a particular reference, it ignores any
subsequent rules that might also match that reference.
To open the Dependent File Manager, click the Dependent File Manager button on the ArchestrA
Object toolbar.

The Dependent File Manager is shown below.
You can set up rules before or after you have added the relevant references to your project in
Visual Studio.
If you have added references to your project, the references automatically appear in the
Dependent Files list at the bottom of the window. You can create rules for these very easily
without having to type the reference again. To set up a rule for these, select the file and click either
the All Objects or This Object button, depending on where you want the rule to apply. A new rule
for this reference then appears in the corresponding section of the Rules list and you can
configure it as described on the next page.
Note: Files shown in gray are already covered by a rule. References not currently covered by a
rule are shown in black.
To set up a new rule for files that you have not yet added as references in Visual Studio, click
either This Object or All Objects in the Rules list, depending on where you want the rule to apply,
and then click the Add button ( ). You can then configure the rule as describe on the next
page.
Note: The System folder of the Dependent File Manager always contains a set of default rules for
references to core system libraries. You cannot edit the rules in this folder.
Wonderware Training
Configuring rules
The following parameters are available for setting up rules for dependent files in the Dependent
File Manager.
Parameter Description
Reference The referenced dependent file(s) to which this rule should apply. You can enter a .NET regular
expression. For example, if you are using references to MyMathLib.Core.dll and
MyMathLib.Data.dll, you can enter MyMathLib* to cover both.
Select the Ignore check box if you do not want to add the dependent files(s) to the object
package file generated by the build process. You would select this option if the files will already
be present on the target system. A red X appears in the Rules list for these references.
Vendor The name of the vendor
Type The file type
One of the following file types which determine if and how files covered by this rule are
registered on the target system:
Dictionary An ArchestrA Dictionary (.aaDCT) file
NETFrameworkAssembly Strongly named .NET Framework Assembly. The file is
installed into the Global Assembly Cache (GAC)
ComDLL COM in-proc server DLL. The file is registered on the target system using
regsvr32.
Normal A normal file. Nothing is done on the target system except install the file.
ComEXE COM local server EXE. The file is executed on the target system with the /
RegServer parameter.
NTService A file that runs as a Windows service
MergeRegistryScript A .reg file with registry information. The file is imported into the
registry.
MsiMergeModule A bundled subcomponent of an installer.
NETFrameworkAssemblyNIG NET Framework Assembly. The file is not installed into
the Global Assembly Cache.
Unknown Only applicable if you selected the Ignore check box
The Browser check box is reserved for future use.

The Contains Embedded DEF check box specifies that the file contains the objects aaDEF file
as an embedded resource. Typically, you dont need to use this setting because the aaDEF file is
managed by the ArchestrA Object Toolkit automatically.
You can configure a default set of rules for all projects, and you can configure specific rules for a
single project.
When you open the Dependent File Manager while no ArchestrA Object Toolkit project is
opened, you can configure only the default rules for all projects.
When you open the Dependent File Manager while an ArchestrA Object Toolkit project is
opened, you can configure both the default rules for all projects as well as specific rules
for the current project.
You can also configure additional search paths for dependent files. See Configuring additional
search paths for dependent files on page 8-25.

Configuring associated files manually

To associate files with your object that are not set up as project references in Visual Studio (for
example, custom data files), you set up the association manually in the Object Designers
Associated Files list, shown below. Files listed here are included in the object package file when
you build the object, and optionally registered on the target system when you import the object.
To access the associated files list, open the Object Designer, select the object in the Shape pane,
and expand the Associated Files section.
To add an associated file click the Add button, and then configure the file in the Associated File
dialog box, shown below.
Note: For descriptions of the files types you can select, see Configuring rules on page 8-23.
Wonderware Training
Configuring additional search paths for dependent files

You can configure additional search paths for dependent files. This gives you more flexibility
because you can store your development files in multiple locations.
To configure additional search paths, open the Options dialog box and click Search Paths.

Wonderware Training
Appendix A
SimpleAnalog Object
A-2 Appendix A SimpleAnalog Object
Wonderware Training
Appendix A SimpleAnalog Object A-3
Lab 14 Creating the SimpleAnalog Object

Introduction
In each of the previous labs, you have focused on some specific feature of the ArchestrA Object
Toolkit. Now you will have the opportunity to put all those pieces together to build a new object
from scratch, and review the most important concepts in the development of an application object.
In this lab, you will create a new object named SimpleAnalog. This object is a simplified version of
the $AnalogDevice object provided with the Wonderware System Platform. The SimpleAnalog
object represents a basic analog input device providing supervisory capabilities for instruments or
equipment that have a key continuous variable. This key variable is available through the PV
attribute, which is associated with an input source. The PV can then be scaled, applied a
deadband, historized, and alarmed. You will write all the configtime and runtime functionality to
implement this object, including a custom editor, so the final result will look like the figure on the
next page.
Objectives
Apply the most important concepts in the development of an application object using the

PV
INPUTPRIM
PV.Input
VIRTUALHISTPRIM
PVHistory
PV.EngUnits
PV.Deadband
PV.LevelAlarmed
Hi.Limit
Hi.Condition
VIRTUAL VIRTUALALMPRIM
LOCAL HiAlarm
PRIMITIVE Lo.Limit AnalogMeter Level
SimpleAnalog LevelAlarms Lo.Condition (Providedby
VIRTUALALMPRIM Instructor)
LoAlarm
PV.Scaled
RawMin
VIRTUAL RawMax
REUSABLE EngUnitsMin
PRIMITIVE EngUnitsMax
Scaling
_RawAttrName
_CalcEUVal
CUSTOMEDITOR

legend to these graphics.
Wonderware Training
Appendix A SimpleAnalog Object A-5

Following is a summary of the general steps you will complete for this lab.
Note: There are no detailed steps for this lab on the following pages. Only general guidance is
given to allow you to put into practice the concepts learned until now.
Create a new solution for the SimpleAnalog object, and following the figure on the previous page,
design the object and write the necessary configtime and runtime logic to implement a behavior
similar to that of the $AnalogDevice object. More specifically, the SimpleAnalog object should
behave as described below.
To test the behavior of the object, you can use the provided AnalogMeter object, which can be
imported from C:\Wonderware Training\AnalogMeter.aaPKG. This object contains an attribute
called Level, which represents the measurement of a level meter in counts, ranging from 0 to
4095. Use this attribute as an input source to your SimpleAnalog object, scaling this raw count
value into an engineering units range of your choosing.
Runtime behavior
State Change Behavior

Startup None
Going On Scan The PV is set to NaN and its quality is set to INITIALIZING.
On Scan Get the raw value of the input source.
If scaling is not enabled, use the input source raw value to update the PV, but only if
the difference between the raw value and the current PV is greater than the deadband.
If scaling is enabled, perform linear scaling. Linear scaling uses the following equation:
ScaledValue = ((RawInputValue-RawMin)/(RawMax-RawMin) *(EngUnitsMax-
EngUnitsMin)) + EngUnitsMin
If the difference between the scaled value and the current PV is greater than the
deadband, update the PV.
Use the input source quality to update the PV quality.
Use the input source timestamp to update the PV timestamp.
If alarms are enabled, calculate the alarm conditions. For level alarms, use the
following formulas:
If PV > Hi.Limit, set the Hi alarm condition. Otherwise, clear the Hi alarm condition.
If PV < Lo.Limit, set the Lo alarm condition. Otherwise, clear the Lo alarm condition.
Going Off Scan The PV is set to NaN and its quality is set to BAD.
All alarm conditions are cleared.
Off Scan The object is passive
Shutdown None
Configuration behavior
The user should be able to configure all attributes writable in configtime using a custom
editor in the ArchestrA IDE.
Adding and deleting virtual primitives should be possible using the custom editor in the
ArchestrA IDE.

Development Considerations
There are several ways to implement the required functionality, but in this section some
suggestions and considerations are discussed.
Since the Scaling primitive is reusable, a different Visual Studio solution must be created for it.
There are two main challenges in this primitive:
1. Find a way to obtain the raw input value from the container object.
2. Give the scaled value back to the container in a way that it will allow it to apply the deadband.
To solve the first problem, the easiest and most flexible way to do this is to create an attribute in
the Scaling primitive that will hold the name of the attribute in the container object providing the
raw value. The idea here is that the developer of the container object should explicitly provide the
raw value attribute name to the reusable primitive, similar to the way it is done in the alarm and
history primitives. This way, the reusable primitive can avoid having to look for this name using
restrictive naming conventions, or predefined assumptions. For this purpose, a hidden attribute
_RawAttrName has been added to the Scaling primitive on page A-4. It is the responsibility of the
container object's developer to set this attribute during configtime.
Regarding the second problem, the challenge here is to enforce the deadband. For example, it
would be fairly easy for the Scaling primitive to scale the value and then assign this result to the
parent's PV attribute. But then, how does the deadband get enforced in this case? To do this, the
reusable primitive would need to know the deadband, which starts complicating things, and adds
one more assumption to the development of the Scaling primitive. Remember that a reusable
primitive can potentially be used in several objects, so it should be fairly generic. In this case, the
easiest and more generic way to provide the scaled result to the container object is to go the other
way around: allow the container object to grab the scaled result from the reusable primitive. In that
way, the parent object can take care of enforcing the deadband. What this means for the Scaling
primitive, is that the only thing it needs to do is to calculate the scaled value, and store it in an
attribute that the container object can access. For this purpose, a hidden attribute _CalcEUValue
has been added to the Scaling primitive on page A-4. It is the responsibility of the container
object's code to obtain this value in runtime and use it to populate the PV.
There is one very important point of attention needed when assigning the PV value: when the
object goes On Scan, the PV has a value of NaN and a quality of Initializing. From the deadband
calculation standpoint, that means there is no previous value to compare against. So typically, if
the quality of the PV is Initializing, there is no need to check the new PV value against the
deadband.
Be careful about the execution order of the different primitives in the object. For the object to
exhibit the above behavior, the primitives should execute in the following order:
1. Input
2. Scaling
3. SimpleAnalog (topmost primitive)
4. LevelAlarms
In this regard, remember that:
By default, the Input primitives are always executed first.
By default, the topmost primitive always executes last. This means that, by default,
Scaling will execute before SimpleAnalog.
The previous point means that LevelAlarms also executes before SimpleAnalog by
default. Therefore, you may need to configure the LevelAlarms primitive to force it to
execute in the desired order.
Wonderware Training

AOT3.1RevA EntireManual1

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

AOT3.1RevA EntireManual1

Transféré par

Droits d'auteur :

Formats disponibles

W O N D E R W A R E T R A I N I N G

Invensys, Wonderware, ArchestrA, Factelligence, IntelaTrac, InBatch, InControl, IndustrialSQL Server,

Module 2 Application Objects Development.............................................2-1

Module 3 Utility Primitives ..........................................................................3-1

Module 4 Error Handling and Debugging..................................................4-1

Module 5 Virtual Primitives.........................................................................5-1

Module 6 Custom Primitives.......................................................................6-1

Module 7 Object Editor................................................................................7-1

Module 8 Advanced Features .....................................................................8-1

ArchestrA Object Toolkit

Appendix A SimpleAnalog Object .................................................................A-1

Section 1 Course Introduction

ArchestrA Object Toolkit

Module 2 Application Objects Development

Module 3 Utility Primitives

Section 3 Quality and Timestamp Handling

Module 4 Error Handling and Debugging

Module 5 Virtual Primitives

Module 6 Custom Primitives

Module 7 Object Editor

ArchestrA Object Toolkit

Module 8 Advanced Features

Wonderware software solutions

Wonderware offers the following software solutions:

ArchestrA Object Toolkit

ArchestrA Object Toolkit

Wonderware individual software products

Wonderware System Platform

Wonderware InTouch HMI

Wonderware HMI Reports

Wonderware Information Server

Wonderware Operations Software

Wonderware Performance Software

Wonderware InBatch Software

Wonderware Equipment Operations Module

ArchestrA Object Toolkit

Wonderware Manufacturing Execution Module

Toolkit Enables developers to:

Wonderware Device Integration Servers

Wonderware Enterprise Integration Application

ArchestrA Object Toolkit

Section 2 System Platform Review

ArchestrA Object Toolkit

System Platform architecture

3rd Party Software 3rd Party

Lab 1 Creating the Galaxy

ArchestrA Object Toolkit

Summary Lab Instructions

Create a new Galaxy (page 1-19)

Import and set up Galaxy objects (page 1-20)

Detailed Lab Instructions

Create a new Galaxy

2. Click New Galaxy.

ArchestrA Object Toolkit

Import and set up Galaxy objects

9. Leave the default settings and click OK.

12. Double-click the GRPlatform instance to open its editor.

14. Click to save and close the editor.

ArchestrA Object Toolkit

18. Click OK.

Section 3 ArchestrA Object Toolkit Overview

ArchestrA Object Toolkit introduction