0% found this document useful (0 votes)

604 views

His T Client

Software described in this documentation is furnished under a license or nondisclosure agreement. No copyright or patent liability is assumed with respect to the use of the information. The information is subject to change without notice.

Uploaded by

JMMARITO

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

604 views

His T Client

Uploaded by

JMMARITO

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 732

Wonderware ActiveFactory Software Users Guide

Invensys Systems, Inc.

Revision C Last Revision: 12/13/06

Copyright
2006 Invensys Systems, Inc. All Rights Reserved. All rights reserved. No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Invensys Systems, Inc. No copyright or patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this documentation, the publisher and the author assume no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. The information in this documentation is subject to change without notice and does not represent a commitment on the part of Invensys Systems, Inc. The software described in this documentation is furnished under a license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of these agreements.

Invensys Systems, Inc. 26561 Rancho Parkway South Lake Forest, CA 92630 U.S.A. (949) 727-3200 http://www.wonderware.com For comments or suggestions about the product documentation, send email to [email protected].

Trademarks
All terms mentioned in this documentation that are known to be trademarks or service marks have been appropriately capitalized. Invensys Systems, Inc. cannot attest to the accuracy of this information. Use of a term in this documentation should not be regarded as affecting the validity of any trademark or service mark. Alarm Logger, ActiveFactory, ArchestrA, Avantis, DBDump, DBLoad, DT Analyst, FactoryFocus, FactoryOffice, FactorySuite, FactorySuite A2, InBatch, InControl, IndustrialRAD, IndustrialSQL Server, InTouch, InTrack, MaintenanceSuite, MuniSuite, QI Analyst, SCADAlarm, SCADASuite, SuiteLink, SuiteVoyager, WindowMaker, WindowViewer, Wonderware, and Wonderware Logger are trademarks of Invensys plc, its subsidiaries and affiliates. All other brands may be trademarks of their respective owners.

Contents

Welcome.......................................... 31
Documentation Conventions.............................................31 Technical Support .............................................................32

Chapter 1 Introduction ...................................... 33

About ActiveFactory Software ..........................................33 Desktop Applications......................................................34 Microsoft Office Add-Ins ................................................34 Controls...........................................................................34 About the IndustrialSQL Server Historian .....................35 Client/Server Architecture................................................36 Analyzing Process Data ....................................................37

Contents

Common Properties for Tag Values.............................247 Display Options Tab.................................................247 Format Tab ...............................................................248 Criteria Tab ..............................................................249 Order Tab..................................................................251 Analyzing Tag Data.........................................................252 Analog Tag Analysis.....................................................253 Batch Analysis ..............................................................260 Scatter Analysis............................................................264 Discrete Tag Analysis...................................................268 Analog Values at Discrete Transition Analysis ..........273 Analog/Discrete Pair Analysis .....................................277 Creating a Direct Query..................................................280 Configuring Workbook Options ......................................283 Configuring Global Formatting Options .....................283 Referencing Formatting Options in a Query ..............285 Using a Named Range for Formatting Options ..........287 Changing Formatting Options in Named Range........288 Configuring Time Zone Options ..................................289 Configuring Data Source Options................................290 Configuring General Options.......................................291 Setting the Base Date and Base Time Parameters ....292 Using "Binding" Options ..............................................293 Creating a Bound Report .........................................294 Considerations for Changing Binding Values.........296 Time Options for Queries.............................................297 Bound times ..............................................................297 Relative time.............................................................297 Absolute time ............................................................297 Publishing Reports ..........................................................298 Publishing a Static Workbook Report .........................299 Publishing a Dynamic Workbook Report ....................300 ActiveFactory Workbook Function Reference................302 Function Arguments ....................................................308 ActionType ................................................................308 AggCalc .....................................................................308 DataSource................................................................308 DateTime ..................................................................308 Description................................................................308 DescriptionFilter ......................................................308 DetectDatetime.........................................................309 DetectorType.............................................................309 DisplayAsWide .........................................................309
ActiveFactory Software Users Guide

Contents

DisplayDatetime....................................................... 309 DisplayFlags ............................................................. 309 DisplayMilliseconds ................................................. 311 DisplayQuality.......................................................... 311 EdgeDetection........................................................... 311 EngUnit .................................................................... 312 EURange................................................................... 312 HistoryVersion.......................................................... 312 Interpolation ............................................................. 313 Logged ....................................................................... 313 MaxLength................................................................ 313 Messages ................................................................... 313 OptionRange ............................................................. 314 OrderBy .................................................................... 314 QualityRule............................................................... 314 RawRange ................................................................. 314 ReplacePoorQuality.................................................. 314 Reset.......................................................................... 315 RetrievalMode .......................................................... 315 RowLimit .................................................................. 315 RowOrRes ................................................................. 315 ScanRate ................................................................... 315 SnapshotTagRange .................................................. 316 SnapshotTagType..................................................... 316 State .......................................................................... 316 StateCalculation....................................................... 316 Status ........................................................................ 316 SQLQuery ................................................................. 316 Storage ...................................................................... 316 SummaryPeriod........................................................ 317 SummaryType .......................................................... 317 TagCriteria ............................................................... 317 TagFilter ................................................................... 317 TagRange .................................................................. 317 Time1 ........................................................................ 317 Time2 ........................................................................ 317 TimeDeadband .........................................................318 TimestampRule ........................................................ 318 ValueCriteria ............................................................ 318 ValueDeadband ........................................................ 318 Error Messages for Functions...................................... 319 Migrating History Data Retrieval Functions ............. 319 Viewing IndustrialSQL Server Historian Details ......... 321

ActiveFactory Software Users Guide

Contents

Chapter 6 ActiveFactory Report .......................... 323

About Add-ins and Templates ........................................323 Getting Started................................................................324 Manually Loading/Unloading the Add-In ...................327 Managing Server Connections.....................................328 About Field Codes.........................................................328 Showing/Hiding Field Codes....................................329 Opening an Existing Report Document .........................330 Running a Report Document ..........................................331 Saving Report Documents...............................................332 Saving a Report Document ..........................................332 Saving a Configured Report Document as a Report Template...................................................................332 Saving a Run Report Document as an HTML File.....334 Inserting a SQL Query....................................................336 Editing a Query ............................................................339 Using Date and Time Options ........................................340 Inserting Date and Time Field Codes .........................341 About Date and Time Wildcards .................................341 #time Wildcard .........................................................342 #date Wildcard..........................................................342 #ReportTime Wildcard .............................................343 Inserting Date and Time Wildcards ............................344 Configuring Report Options............................................345

Chapter 7 Introduction to Controls and Objects ...... 347

About the ActiveFactory Controls and Objects..............347 About Properties, Methods, and Events.........................348 Getting Started with the Controls..................................349 Using the Controls in Different Environments .............349 Using the Controls within InTouch HMI Software ....350 Using the Controls in Microsoft Office ........................351 Mapping for Numerical Data Types ............................351

Contents

SetMenuItemEnabled ..............................................456 SetTagColor ..............................................................457 SetTagFormat...........................................................458 SetTagColorDlg ........................................................458 SetTagOffsetMS .......................................................459 SetTagPenStyle ........................................................460 SetTagPenWidth ......................................................461 SetTagPrecision ........................................................461 SetTagVisible............................................................462 SetTimeSpan ............................................................463 SetToolbarButtonEnabled .......................................463 UnsetCurrentTagXAxisTag .....................................465 ZoomIn ......................................................................465 ZoomOut....................................................................465 aaHistClientTrend Events ...........................................466 CurrentTagChanged ................................................466 DatesChanged...........................................................467 StateChanged ...........................................................467 TagDisplayChanged .................................................467 TaglistChanged.........................................................468 aaHistClientTrend Enumerations..................................468 aaChartType Enumeration ..........................................469 aaDashStyle Enumeration...........................................469 aaDataPointLabelingType Enumeration ....................470 aaDateModeEnumeration Enumeration.....................470 aaInterpolationType Enumeration..............................470 aaQualityRules Enumeration......................................470 aaRetrievalMode Enumeration ...................................471 aaRetrievalVersion Enumeration................................472 aaStateCalculation Enumeration................................472 aaTargetRegionExcursionType Enumeration ............472 aaTimeStampRules Enumeration ...............................473 aaTraceGradientType Enumeration ...........................473 aaTrendGradientType Enumeration...........................473 aaTrendType Enumeration..........................................474 aaTrendValueFormat Enumeration............................474 aaUpdateToCurrentTimeState Enumeration.............474 aaValueAxisLabelEnumeration Enumeration ...........475 Using aaHistClientTrend in a Multi-Monitor Environment.................................................................475

ActiveFactory Software Users Guide

Contents

Chapter 9 aaHistClientQuery Control ................... 477

Using aaHistClientQuery at Runtime ........................... 477 Using aaHistClientQuery in an Application.................. 477 Adding aaHistClientQuery to an InTouch Window ... 478 aaHistClientQuery Properties..................................... 479 ActiveServer ............................................................. 479 AllowQueryTypeChange .......................................... 480 CurrentServer .......................................................... 480 EnableAllQueriesTab ............................................... 480 FavoriteQueriesFolder ............................................. 480 FontBold ................................................................... 481 FontCharset.............................................................. 481 FontItalic .................................................................. 482 FontName ................................................................. 482 FontSize .................................................................... 482 QueryFont................................................................. 483 QueryString .............................................................. 483 Recordset................................................................... 483 Servers ...................................................................... 483 ToolbarConnectVisible ............................................. 484 ToolbarEditVisible ................................................... 484 ToolbarRequeryVisible............................................. 484 ToolbarVisible........................................................... 484 UsePersistedServers ................................................ 485 aaHistClientQuery Methods........................................ 485 AddServer ................................................................. 486 AddTag...................................................................... 486 ClearTags.................................................................. 487 CopyQuery ................................................................ 487 CutQuery .................................................................. 487 FileOpen.................................................................... 487 ManualConnect ........................................................ 488 OpenQuery................................................................ 488 PasteQuery ............................................................... 488 Refresh ...................................................................... 488 RemoveTag ............................................................... 489 SaveQuery................................................................. 489 SaveResults .............................................................. 489 SetDates.................................................................... 489 SetDuration .............................................................. 490 SetQueryType ........................................................... 490 SetQueryType2 .........................................................491 SetTimeSpan ............................................................ 491

ActiveFactory Software Users Guide

Contents

ShowAbout ................................................................492 aaHistClientQuery Events...........................................492 ModeChanged ...........................................................492 QueryChanged ..........................................................493 ServerChanged .........................................................493 aaQueryTypeEnumeration ..........................................493

Chapter 10 aaHistClientTagPicker Control ............. 495

Using aaHistClientTagPicker at Runtime.....................495 Using aaHistClientTagPicker in an Application ...........495 Adding aaHistClientTagPicker to an InTouch Window ......................................................496 aaHistClientTagPicker Properties ..............................497 CurrentServer...........................................................497 DescriptionFilter ......................................................497 ExactMatchFilter .....................................................498 FilterVisible ..............................................................498 HideCaption..............................................................498 IOAddressFilter........................................................498 SelectedPath .............................................................499 SelectedTagCount.....................................................499 Servers ......................................................................499 SingleSelectMode .....................................................500 SplitterOrientation...................................................500 TagNameFilter .........................................................500 TreeVisible ................................................................501 TreeWidth .................................................................501 aaHistClientTagPicker Methods .................................501 ApplyFilter................................................................501 LogOn ........................................................................501 RefreshTags ..............................................................502 SelectedTag...............................................................502 aaHistClientTagPicker Events ....................................503 OnFilterChanged......................................................503 OnGroupChanged.....................................................503 OnTagsPicked...........................................................503 OnTagsSelected ........................................................504 OnServerChanged ....................................................504 OnSelectedTabChanged ...........................................504 aaHistClientTagPickerSplitterOrientation Enumeration ............................................................505

ActiveFactory Software Users Guide

Contents

aaHistClientWorkbookRunner Object ...........................591 aaHistClientWorkbookRunner Object Properties ......591 ErrDescription ..........................................................592 ErrNumber ...............................................................592 OutputFile ................................................................592 SourceFile .................................................................592 ExcelVisible ..............................................................593 aaHistClientWorkbookRunner Methods.....................593 Run ............................................................................593 RunReport.................................................................594 RunReport2...............................................................597 aaHistClientReportRunner Object .................................601 aaHistClientReportRunner Object Properties............601 ErrDescription ..........................................................601 ErrNumber ...............................................................601 OutputFile ................................................................602 SourceFile .................................................................602 WordVisible...............................................................602 aaHistClientReportRunner Object Methods...............603 Run ............................................................................603

Chapter 17 Workbook and Report Automation Objects.......................................... 605

ActiveFactoryWorkbook Object ......................................605 ActiveFactoryWorkbook Object Methods ....................605 AddServer .................................................................606 Auto_Close ................................................................606 Auto_Open ................................................................606 GetLastError ............................................................606 RunReport.................................................................607 ActiveFactory Workbook Menu Methods ................611 ActiveFactory Workbook Functions ........................612 ActiveFactory Workbook Automation Example..........612

ActiveFactory Software Users Guide

Contents

ActiveFactoryReport Object............................................ 616 Report Object Properties.............................................. 616 ReportDate................................................................ 616 ReportTime ............................................................... 617 Report Object Methods................................................. 617 AutoExec ................................................................... 617 AutoExit.................................................................... 617 RunReport................................................................. 617

Chapter 18 aaHistClientGlobalFunctions Object ...... 619

Using aaHistClientGlobalFunctions Object in an Application.................................................................... 619 aaHistClientGlobalFunctions Methods....................... 619 GetDictionaryPath ................................................... 619 GetInstallPath .......................................................... 620 MDACOk................................................................... 620

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types ...................... 621
Common Properties.........................................................621 BackColor...................................................................... 622 BackStyle ...................................................................... 622 BorderStyle................................................................... 623 CausesValidation .........................................................623 Container ...................................................................... 623 ContextMenuEnabled .................................................. 623 DataBindings................................................................ 624 DragIcon ....................................................................... 624 DragMode ..................................................................... 624 Enabled ......................................................................... 625 Font ............................................................................... 625 ForeColor ...................................................................... 625 Height ........................................................................... 626 HelpContextID ............................................................. 626 Index ............................................................................. 626 Left ................................................................................ 626 Name ............................................................................. 627 Object ............................................................................ 627 Parent ........................................................................... 627 TabIndex ....................................................................... 627 TabStop ......................................................................... 628 Tag................................................................................. 628

ActiveFactory Software Users Guide

Contents

Initial Capitals
Bold Monospace

Paths and filenames. Menus, commands, dialog box names, and dialog box options. Code samples and display text.

ActiveFactory Software Users Guide

Technical Support
Wonderware Technical Support offers a variety of support options to answer any questions on Wonderware products and their implementation. Before you contact technical support, refer to the relevant section(s) in this guide for a possible solution to any problem you have with the IDE. If you need to contact technical support for help, have the following information ready:

The type and version of the operating system you are using. For example, Microsoft Windows XP, SP1. Details of how to recreate the problem. The exact wording of the error messages you saw. Any relevant output listing from the Log Viewer or any other diagnostic applications. Details of what you did to solve the problem(s) and your results. If known, the Wonderware Technical Support case number assigned to your problem, if this is an ongoing problem.

ActiveFactory Software Users Guide

Chapter 1
Introduction

The Wonderware ActiveFactory software provides a number of client tools to address specific data representation and analysis requirements. These tools remove the requirement to be familiar with the SQL and provide intuitive point-and-click interfaces to access, analyze, and graph both current and historically acquired time-series data.

About ActiveFactory Software

Whether you are an operator, process engineer, or manager, the ActiveFactory software can help you organize, explore, analyze, present, and disseminate your process data in a wide variety of formats. All of this can be performed from your desktop computer. The ActiveFactory software is a full-featured suite of client applications that maximize the value of the data in the IndustrialSQL Server historian. The ActiveFactory software integrates tightly with the most popular Microsoft Office tools. With ActiveFactory software, you can:

Explore your data graphically to find important information. Analyze the data to produce relevant information. Develop and execute ad hoc queries against any data stored in the IndustrialSQL Server database. Visualize the current process state. Produce rich automated reports.

ActiveFactory Software Users Guide

Chapter 1 Introduction

Desktop Applications
ActiveFactory client tools include the following stand-alone applications:

ActiveFactory Trend. Enables trending of historical and real time data over time. Powerful features allow data to be compared with other data from different periods. Alarms and limit excursions are readily visible. It is also possible to add and view annotations in your trends. For more information, see Chapter 3, ActiveFactory Trend.

ActiveFactory Query. This point-and-click tool enables complex queries to be created and executed against any IndustrialSQL Server historian. Knowledge of the database structure or SQL is not required. For more information, see Chapter 4, ActiveFactory Query.

Microsoft Office Add-Ins

ActiveFactory Workbook. This add-in to Microsoft Excel enables almost any type of analysis and display of data from an IndustrialSQL Server historian using the Excel spreadsheet format (.xls). For more information, see Chapter 5, ActiveFactory Workbook.

ActiveFactory Report. This add-in to Microsoft Word allows sophisticated reporting from an IndustrialSQL Server historian using the Word document format (.doc). For more information, see Chapter 6, ActiveFactory Report.

Controls
aaHistClientTrend and aaHistClientQuery are controls that provide essential functionality of ActiveFactory Trend and ActiveFactory Query for use in container applications, such as InTouch HMI software and Internet Explorer. You can also use ActiveFactory "building block" controls (such as aaHistClientTagPicker, aaHistClientTimeRangePicker, and so on) in your custom applications. For more information, see Introduction to Controls and Objects on page 347.

ActiveFactory Software Users Guide

About the IndustrialSQL Server Historian

The IndustrialSQL Server historian is a real-time relational database for plant data. The historian acquires and stores process data at full resolution and provides real-time and historical plant data together with configuration, event, summary, and associated production data to client applications on the desktop. The historian combines the power and flexibility of Microsoft SQL Server with the high speed acquisition and efficient data compression characteristics of a real-time system. The IndustrialSQL Server historian appears to client applications as a Microsoft SQL Server. The IndustrialSQL Server database server receives SQL queries and then locates, processes, and returns the data. In the IndustrialSQL Server historian, plant data is stored in special history "extension" tables. The historian surpasses the functionality of Microsoft Transact-SQL by providing time domain extensions that allow for more useful retrieval of time-series data from these tables. For example, the extension tables support cyclic and delta retrieval. For cyclic retrieval, evenly spaced data at a specified resolution is returned. For delta retrieval, data is returned for each time the value of a tag changed. The combination of normal SQL Server tables and the extension tables provides a powerful way to access meaningful data stored in the database. Since the historian is a relational database, queries can join data across multiple tables to retrieve data efficiently. Some examples of database queries possible with the historian are:

Average vibration of a motor each day over the last month. Annotation for a discrete tag that was made six months ago. The limit of an analog tag in the context of a normal production mode. The limit of the same analog tag in the context of an accelerated production mode. The values for 50 specified analog tags at a point in time when the value of x was greater than 10. The path to the storage location for a specific tag. 20 evenly distributed data values from the total values stored for an analog tag between 8:00 and 8:30 a.m. on September 12, 2004.

ActiveFactory Software Users Guide

Chapter 1 Introduction

All data values at 20 minute intervals from the total values stored for an analog tag between 8:00 and 8:30 a.m. on September 12, 2004. All values of an analog tag stored on January 8, 2004, where the value of the analog tag changed by 10 engineering units. The data for this analog tag was stored if the value changed by 5 engineering units. All values for tags associated with an event boiler trip on January 8, 2004.

Client/Server Architecture
The IndustrialSQL Server client/server architecture allows for flexible and easy-to-use client applications on the desktop, while ensuring the integrity and security of the data on the server. The computing power of both the client and the server are exploited by optimizing processor intensive operations on the server and minimizing data to be transmitted on the network to improve system performance. The following illustration shows one possible network architecture where the IndustrialSQL Server historian is used as the link between the process network and the business LAN/WAN:

ActiveFactory Software Users Guide

Analyzing Process Data

Process data is any type of information that is relevant to the execution of a process. The following types of information are considered part of process data:

Real-time data - What is the current value of this tag? Historical data - What was the value of this tag every second last Monday? Summary data - What is the average of each of these five tags? Business data - How much does this particular material cost? Event data - When did that boiler trip? Configuration data - How many I/O Servers am I using and what are their types?

To improve performance and quality, while reducing cost, all of this acquired information must be able to be analyzed. Plant data is typically analyzed to determine:

Process analysis, diagnostics, and optimization. Materials management, such as raw materials usage. Predictive and preventive maintenance of equipment. Product and process quality (SPC/SQC). Health and safety; environmental impact (EPA/FDA). Production reporting. Failure analysis.

ActiveFactory Software Users Guide

Chapter 1 Introduction

ActiveFactory Software Users Guide

Chapter 2
Common Client Components

Some of the ActiveFactory client applications and controls use a common set of client components.

Server Connection Configuration

To use an ActiveFactory client application, you must first connect to an IndustrialSQL Server historian using a valid user account that has the right to retrieve data. You can use either your Windows user account (integrated security) or a valid SQL Server user account, depending on how the IndustrialSQL Server historian is configured. You can also access the server using HTTP. For more information on HTTP access, see Using HTTP as the Server Connection Protocol on page 43. Ask your administrator what type of user account you must use to access the server. If you are accessing the server over HTTP, the administrator must provide you with the URL and virtual directory name, as well. Server connections are shared among the ActiveFactory applications. For example, once you have configured a server connection in the Trend application, you can use it in the Query application as well. When you start an ActiveFactory application, you are not automatically logged on to every server that you configured before. You are only logged on to a server when you do the following:

You open a file that causes data to be retrieved for a tag on that server.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

You expand a server in the Tag Picker to view its tag list. You manually log on to the server.

Creating a New Server Connection

You can create a new server configuration. To create a new connection, you need your assigned IndustrialSQL Server historian username and password.
To create a new server connection 1

On the Tools menu, click Servers. The Server List Configuration dialog box appears.

The Server list window shows a list of connected servers or servers that were configured in the past.
2 3

In the Server box, type the name of the server to which you want to connect. Make sure that you know what options to choose to access the server. For more information, see Server Connection Configuration on page 39. To log on to the server using integrated security, select the Use Integrated security check box and then skip to step 8. To log on to the server using SQL Server credentials, clear the Use Integrated security check box and configure the following login details. Then, skip to step 8.

ActiveFactory Software Users Guide

Server Connection Configuration

Login ID: Enter your assigned IndustrialSQL Server historian username. If your system administrator has not assigned you a username and password, you may use one of the default user accounts, which are automatically configured during a typical IndustrialSQL Server installation. Password: Enter the password that is associated with the username. Select the Remember password check

box to specify for the system to remember your password.

To log on to the server over HTTP using integrated security, select both the Use Integrated security check box and the Use HTTP check box and then configure the required options. Then, skip to step 9. Login ID: Enter your Windows user name.
Password: Enter your Windows password. Select the Remember password check box to specify for the

system to remember your password.

Domain: Enter the domain name in which your

Windows account is validated. The domain name is only valid for HTTP connections to the IndustrialSQL Server historian when integrated security is used.
Base URL: The URL for the server. Virtual directory: The name of the virtual directory on

the server. For more information on HTTP access, see Using HTTP as the Server Connection Protocol on page 43.
7

To log on to the server over HTTP using SQL Server authentication, clear the Use Integrated security check box, select the Use HTTP check box, and then configure the required options. Then, skip to step 9. Login ID: Enter your assigned IndustrialSQL Server historian username. If your system administrator has not assigned you a username and password, you may use one of the default user accounts, which are automatically configured during a typical IndustrialSQL Server historian installation.
Password: Enter the password that is associated with the username. Select the Remember password check

box to specify for the system to remember your password.

Base URL: The URL for the server. Virtual directory: The name of the virtual directory on

the server.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

In the Timeouts in seconds area, configure the time allocated for the database connection and the query execution. Connection: The connection timeout in seconds. Valid values are 1 to 600.
Query: The query timeout in seconds. Valid values are

1 to 600.
9

Click Add.

10 Click LogOn to log on to the server. 11 Repeat Steps 2 through 10 to add additional servers. 12 Click Close. An error message appears if a connection

cannot be made to a server.

Editing a Server Connection

You can edit an existing server connection.
To edit a server connection 1 2 3

On the Tools menu, click Servers. The Server List Configuration dialog box appears. In the Server List box, select the name of the server to edit. In the Server connection area, edit the details for the server. For more information, see Creating a New Server Connection on page 40. Click Update.

4 5

Click Close. An error message appears if a connection cannot be made to the server, but the server is added to the list.

Removing a Server Connection

You can remove a server connection you no longer need. Make sure you select the server you want to delete. After you delete a server, you cannot undelete it.
To remove a server connection 1 2 3 4

On the Tools menu, click Servers. The Server List Configuration dialog box appears. In the Server List box, select the name of the server to remove. Click Remove. Click Close.

ActiveFactory Software Users Guide

Server Connection Configuration

Using HTTP as the Server Connection Protocol

The ActiveFactory software can use HTTP as the transport protocol, instead of other typical network protocols, such as TCP. HTTP (which is layered on top on TCP) usually uses port 80 and is generally open in Internet (or intranet) firewalls, so that communications can take place between the servers and the clients. If the IndustrialSQL Server historian and the ActiveFactory clients (aaTrend.exe, aaQuery.exe, aaHistClientTrend, aaHistClientQuery, and so on) are on two different sides of a firewall and TCP is the protocol, port 1433 must be opened in the firewall software/appliance or else communications cannot take place between the server and clients. Thus, the HTTP feature allows clients to access historians located behind firewalls without requiring additional ports to be opened. The Microsoft SQLXML technology is used to provide HTTP transport to the SQL Server, as well as XML access to the data. If you enable SQL Server access over HTTP, be aware of the limitations of this technology. For more information, see the following web resource: http://msdn.microsoft.com/library/default.asp?url=/library/en -us/xmlsql/ac_xml1_59m4.asp

Guidelines for Accessing SQL Server over HTTP

Accessing SQL Server over HTTP provides the most benefit if you want to simply view data from a pre-configured client file over the Internet (or intranet). For example, you might want to open a pre-configured trend file over the Internet/intranet and view the data. Accessing SQL Server over HTTP is not recommended if you are configuring a client file, such building and saving a trend file. The retrieval of tag information over HTTP can be very slow if there is a large number of tags in the historian database (for example, over 5,000, depending on the system).

Software Requirements for HTTP Access

To access SQL Server over HTTP, the following software must be installed and configured:

Microsoft Internet Information Services (IIS) Server Microsoft SQLXML

For the required versions of the software and installation instructions, see the ActiveFactory software ReadMe file.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

No software or special configuration is required on the client, other than what is generally required to support the ActiveFactory client installation.

Authentication for HTTP Access

The authentication mode is determined by the settings for IIS Server. The IIS Server allows for three modes:
No authentication. For this mode, the SQLXML

configuration in the IIS Server always uses a specified user name and password; no user name and password is required to be provided by the client. Either integrated security or SQL server authentication can be used.
Integrated security. The IIS Server must be set up to use

integrated security to authenticate clients. From the client application, you must choose Integrated security in the Server Configuration dialog box, and provide a user name, password, and a domain for authentication.
Basic authentication. For this mode, the IIS Server simply

passes on a user name and password supplied by the client to the SQL Server. This mode is not recommended unless you also use Secured Sockets Layer (SSL) security, which encrypts all the data going over the connection. The integrated security and basic authentication modes require that the client provide a user account, which is passed by the IIS Server to the SQL Server. Note that the configuration of the IIS Server governs the mode of authentication that is required of clients. For example, if the IIS Server is configured to use integrated security, then client users must access the server using integrated security. There is no security in the access mechanism. Using HTTPS provides an additional level of security, but may impact performance.

Executing SQL Statements over HTTP

Whereas TCP is a connection-oriented protocol, and is stateful, HTTP is stateless. That is, a single request is made from the client to the server, and the server then responds to the request (provided that no errors occur). The entire transaction is stateless; no state is preserved from one request to another. A request is made, and a response is received, and no state is retained. Although HTTP is stateless, the concept of a "logged in" state to the server has been preserved to be consistent. Therefore, a client can be considered to be "logged on" to or "logged off" of an HTTP-accessed server.
ActiveFactory Software Users Guide

Server Connection Configuration

Stateless SQL statements that execute in a native SQL Server access environment execute when SQL Server is accessed over HTTP. However, stateful SQL statements do not function unless they are part of a collection of statements submitted together. If HTTP access is used, and no data rows are returned for a query, no column headers are produced.

SQL Cursors The stateless nature of SQL Server access over HTTP affects the use of SQL cursors.
In a native SQL Server access environment, a connection is made, a cursor is created, and used subsequently until the connection is terminated. The establishment of the connection, creation of the cursor, use of the cursor, and disconnection can all be performed as separate requests. If the SQL Server is accessed HTTP, the establishment of the connection, the execution of any SQL statements that follow, and the disconnection must all be part of a single HTTP request.

Batch Statements The stateless nature of SQL Server access over HTTP affects the use of "batch" SQL statements. For HTTP access, the last SQL statement submitted in a batch must be capable of returning a result set.
For example, the following query does not return a result set over HTTP. This is because the last statement executed does not produce a result set.
SET QUOTED_IDENTIFIER OFF Select ContactName FROM Customers SET QUOTED_IDENTIFIER ON

To address this problem, make sure that the last statement produces a result set. For the example query, the last statement was removed to produce the expected results:
SET QUOTED_IDENTIFIER OFF Select ContactName FROM Customers

To get the same effect as the original batch of statements, you must modify the query so that the results are stored into a temporary table before the SET QUOTED_IDENTIFIER ON statement occurs and then return those results. For example:
CREATE TABLE #temp (Name NVARCHAR(255)) SET QUOTED_IDENTIFIER OFF INSERT INTO #temp SELECT ContactName FROM Customers

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

SET QUOTED_IDENTIFIER ON

If you have any batch queries in which the last SQL statement in the batch does not return a result set, you must restructure the query.

SELECT Name FROM #temp

Column Aliases For SQL Server access over HTTP, you must use include column aliases in SQL statements when no columns exist.
For example, when used with native SQL Server access, the following query yields the counts of all tags in the database.
SELECT COUNT(*) FROM Tag

However, the same statement does not produce results in SQL over HTTP. You need to modify the query to use column aliases. For example:
SELECT COUNT(*) as n FROM Tag

Another example is:

SELECT n=COUNT(*) FROM Tag

SQL Statements in the Trend and Query Applications

The queries used by the ActiveFactory Trend and Query applications execute properly if SQL Server access over HTTP is used. However, if you execute a custom query using the ActiveFactory Query application, be aware that not all queries that execute in the native SQL access environment execute in the SQL over HTTP environment without modifications. Those that require multiple requests in a native SQL environment (such as those using cursors) do not execute at all. For more information, see Executing SQL Statements over HTTP on page 44. Also, if you are using the Tag Picker to search for tags, the response time can be quite slow if you are accessing a large database. This is due to the additional overhead required to access the data with SQL statements in the SQL over HTTP environment.

Error Reporting
If you are accessing SQL Server over HTTP, query-related errors are not provided. This is a limitation of the SQLXML technology. The only error condition that can be deduced is when no data (not even the table headers) is returned for a request. For this condition, a generic error is returned that prompts you to check the SQL query. If your query is not valid, no specific error message appears, and no data is returned.

ActiveFactory Software Users Guide

Server Connection Configuration

Reliability and Performance

Accessing SQL Server over HTTP is as reliable as the physical connection on which the data exchange occurs. Just as you can expect that a busy network may cause HTTP requests to fail or be intermittent, for the same busy network, SQL over HTTP exhibits those symptoms as well.
Important The guidelines provided here may not be achievable for your particular environment, given the wide range of factors related to network bandwith and availablity and the nature of your ActiveFactory applications.

In general, equivalent operations take three to five times longer if you use SQL over HTTP, as compared to native SQL Server access. Also, it can be considerably slower if you are accessing the server from an external system over the Internet, depending on the Internet connection method. For example, if you are using a dial-up connection. The primary use for HTTP access is for visualization of data. For this type of use, you can expect acceptable performance when updating at refresh rates of one refresh per second. Even over the Internet, visualization at rates of one time every second may be achieved during off-peak hours, and rates of one time every five seconds may result in smooth operation of your applications. Databases that contain about 5000 tags can generally be browsed without problems using the Tag Picker, or when used in constructing trends or queries. However, larger databases are likely to slow down navigation in the Tag Picker when used across the Internet. You may also experience slowed performance if the IIS Server and the SQL Server are not running on the same computer.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Example Server Configuration for HTTP Access

The following illustration shows how to configure a server to use HTTP for the database access protocol. For this example, the "ActiveFactoryDatabase" virtual directory was created during the installation of the SQLXML software. The local host is a computer named QAINT151.

For more information on configuring a server, see Creating a New Server Connection on page 40.

ActiveFactory Software Users Guide

Server Connection Configuration

The following illustration shows the dialog box configured for integrated security. Note that even though integrated security is used, the login ID and the password are enabled. This is because this refers to the integrated security on the IIS Server.

Considerations for VPN Access

Check with your system administrator regarding how to access the server over a virtual private network (VPN). For example, you may need to provide a fully qualified domain name when specifying the server:
host-a.example.wonderware.com.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Status Bar
The status bar allows you to view the status of the connection to the IndustrialSQL Server historian and any other status messages that may be sent by the client.

To show the status bar On the View menu, click Status Bar so that a check mark

appears.
To hide the status bar On the View menu, click Status Bar so that no check mark

appears. The icon at the right side of the status bar indicates the status of the servers that are being used by the ActiveFactory client. The following table describes the status colors and their meanings:
Color Status Meaning

Gray Green Yellow Orange Red

No servers are configured. Connections (log ons) have been established to all servers in the server configuration list. Connections (log ons) have been established to most of the servers in the list. No connections (log ons) have been established to most of the servers in the list. No connections (log ons) have been established to any of the servers in the list.

Double-click the icon to access the Server List Configuration dialog box. For more information, see Server Connection Configuration on page 39.

ActiveFactory Software Users Guide

Tag Picker

Tag Picker
The Tag Picker shows which tag groups and tags exist in the database. It shows all of the tags that are visible to the currently logged on user based on his or her permissions. Using the Tag Picker, you can quickly search the database for tags of a certain type and/or for tags that match a particular search pattern. You can then select the ones you want to include for the client application or control.

Servers pane

Tags pane

Filter pane

The Tag Picker is comprised of the following three panes:

Servers pane Tags pane Filter pane

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Using the Servers Pane

The Servers pane shows a list of IndustrialSQL Server folders. The Servers pane allows you to navigate through the folder structure (namespace) of one or more IndustrialSQL Server historians and select a group (folder) of tags.

The Servers pane shows the following items:

Category Description

Servers

All objects that make up the basic IndustrialSQL Server system, such as tags, I/O Servers, defined engineering units, storage locations, and so on. All objects that are visible to all clients. If you have administrative permissions, you can create, rename, and delete groups in the public groups folder. All objects that are visible to the user that is currently logged on. Users can create, rename, and delete groups in the private groups folder.

Public Groups

Private Groups

Showing/Hiding the Servers Pane

To show the Servers pane Right-click in the Servers pane and then click Servers pane so that a check mark appears. To hide the Servers pane Do one of the following:

Right-click in the Servers pane and then click Servers pane so that no check mark appears. Click the Close button.

ActiveFactory Software Users Guide

Tag Picker

Editing Groups
You can add groups just as you would add a new folder in the Windows Explorer. For example, you can create the "BoilerTags" group under in the existing "Private Groups" group. You can also delete, cut, copy, paste, and drag objects from one folder to another.

Adding a Group You can add a group.

To add a group 1

Right-click on the folder under which you want to create a group and then click New Group. A new folder appears in the Tag Picker. Type a name for the folder and press ENTER.

Adding a Tag to a Group When you add tags to a new group, the original reference still appears in the default system group. Any tag can belong to any number of groups, and any group can contain any number of tags.
To add a tag to a group 1 2 3

Select the system group folder that contains the tag that you want to add to your new group. In the Tags pane, select the tag to add. Do any of the following: Drag the desired tag from the Tags pane into the folder.

Use the Copy and Paste commands on the Edit menu to copy the tag to the target folder. Right-click on the desired tag in the Tags pane. Use the Copy and Paste commands in the shortcut menu to copy the tag to the target folder.

Deleting a Group or Tag Reference When you delete a private group or tag reference in a private group, the group folder, any subfolders that the group folder may contain, and all references to tags are deleted. The tags themselves are not deleted, and the original references still appear in the default system group. You cannot delete public folders or the tag references contained in them.
To delete a group or tag 1 2

Select the group or tag in the pane. Do one of the following:

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Right-click on the group or tag and then click Delete. Press the DELETE key.

Renaming a Group You can rename a group that you have created in the Tag Picker. However, you cannot rename a public folder.
To rename a group 1 2

Select the group in the pane. Do one of the following: Right-click on the group and then click Rename.

Press the F2 key.

Type a new name for the group and press ENTER.

Viewing Server Details

You can view information such as the version number, time zone, and security mode for any server in the Servers pane.
To view server details 1

In the Servers pane, right-click on a server and then click Server details. The Server Details dialog box appears.

Click OK.

ActiveFactory Software Users Guide

Tag Picker

Using the Tags Pane

The Tags pane shows all the tags for the currently selected group in the Servers pane.

To select multiple tags in the list, hold the CTRL and/or SHIFT key while clicking. To view only tags of a certain type, click the appropriate tab at the bottom of the pane. To sort the table by a particular column, click the column heading.

Using the Filter Pane

Use the Filter pane to reduce the tags listed in the Tags pane according to criteria that you specify. You can filter the tags according to name, description, and I/O address.

The filter mechanism allows for the following "wildcard" characters as part of the filter criteria:
Wildcard Character

Filter Function

% _

Any string of zero or more characters. Any single character.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Wildcard Character

Filter Function

[]

Any single character within the specified range or set. For example:

[a-f] [abcdef]

[^]

Any single character not within the specified range or set. For example:

[^a - f] [^abcdef]

For example, to find all tagnames ending with "level," type "%level." Filter criteria are not case-sensitive. When the Servers pane and the Filter pane are both visible, the filter conditions apply to the selected group in the Servers pane. When the Servers pane is hidden, the filter applies to all of the tags for the selected IndustrialSQL Server historian.
To apply a filter 1 2 3 4 5

In the Server box, specify or verify the server. This box is not available if the Servers pane is visible. In the Tag name box, enter the string to match for the tagname. In the Description box, enter the string to match for the description. In the I/O Address box, enter the string to match for the I/O address. Select the Exact match check box to search for tags that exactly match the entire string that you provided for the tagname and/or description options. For example, if you specify "level" as the tagname and do not select Exact match, any tagname that contains the string "level" appears. For example, "ReactLevel," "ProdLevel," and "$AccessLevel." The Exact match option does not apply to the I/O address.

6 7

Click Apply to apply the filter criteria. Click Clear to clear the Filter pane.

ActiveFactory Software Users Guide

Tag Picker

Showing/Hiding the Tag Picker

To show the Tag Picker

Do one of the following: On the View menu, click Tag Picker so that a check mark appears.

Click the Show Tag Picker toolbar button so that it is highlighted.

To hide the Tag Picker

Do one of the following: On the View menu, click Tag Picker so that no check mark appears.

Click the Show Tag Picker toolbar button so that it is not highlighted.

Tag Picker Views

By default, all client applications (except for the Workbook add-in) start up with the Tag Picker in the horizontal view. You can view the Servers and Tags pane in a vertical view instead.

To change the Tag Picker to the vertical view

Right-click in the Tag Picker and then click Vertical orientation so that a check mark appears.

To change to the horizontal view

Right-click in the Tag Picker and then click Vertical orientation so that no check mark appears.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

Time Picker
The time picker allows you to select a time range by specifying a start time, end time, and/or duration. An error appears next to the start or end time controls if you specify an invalid time period. For example, an end time before a start time.
To specify a time period 1

On the Time toolbar, specify the start time, end time, and/or duration. To select a date from a calendar, click the down arrow on the start time or end time list. To select a predefined duration, click the down arrow on the duration list.

Start Time

Duration

End Time

When you change one of the options, one of the other options is recalculated automatically. While you change the option, a blue frame appears around the option that will be recalculated as a result of the change. The relation between changed and updated options is as follows:
You change... The time picker updates...

Start time End time Duration

End time (based on duration) Start time (based on duration) Start time (based on end time)

If you change multiple options in a row, which option is updated depends on which two other options you changed last. For example, if you change the start time and then the end time, the duration is calculated accordingly. If you change the start time and then the duration, the end time is calculated, and so on.
2

Press ENTER.

To specify a time period relative to the current time 1

Do one of the following: On the Chart menu, click Update to Current Time so that a check mark appears.

Click the Update to Current Time toolbar button so that it is highlighted.

ActiveFactory Software Users Guide

Viewing Program and License Information

In the duration list of the Time toolbar, click a duration or enter one manually. The start time is automatically calculated as the current time minus the duration you selected, and the trend display is updated with the new time period.

Viewing Program and License Information

For each Wonderware client application, you can view program information, such as the version of the program, copyright information, and licensing information.
To view program information 1

On the Help menu, click About <client name>. The About dialog box appears, showing version and copyright information. Click OK.

To view license information 1 2

On the Help menu, click License Status. The License Status dialog box appears, showing license information. Click OK.

ActiveFactory Software Users Guide

Chapter 2 Common Client Components

ActiveFactory Software Users Guide

Chapter 3
ActiveFactory Trend

Trend is a client application that allows you to query tags from an IndustrialSQL Server database and plot them on a graphical display. Trend supports two different chart types: a regular trend curve and an XY scatter plot. After you add tags to a trend chart, you can manipulate the display in a variety of ways, including panning, zooming, and scaling. You can customize any trend by configuring display options and set general options for use with all trends. Before Trend can be used to query tag information from the database, the server must be running and you must have security access. This section describes the basic procedures for working with regular trends. Most of this information also applies to XY scatter plots. For information specific to XY scatter plots, see Working with Scatter Plots on page 138.

Getting Started with Trend

When you start the Trend application for the first time, you are immediately prompted to connect to a server. If you are opening an existing Trend file that includes at least one server configuration and the log in was successful, you are not prompted to log in. For more information, see Server Connection Configuration on page 39.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

After you establish a connection with the server, the Trend main window appears.
Tag Picker Scaling Toolbar Main Toolbar Time Toolbar

Status Bar

Tag List

Chart

For information on using the tag picker and the time picker, see Chapter 2, Common Client Components. To show or hide toolbars or components, use the corresponding commands on the View menu.

Working with Trend Files

This section describes how to create, open, and save trend files. A trend file contains all of the configuration data required to trend one or more tags, such as the tags, time axes, colors, zoom level, and so on. Any mix of analog, discrete, or event tags is allowed. There is no pre-set limit to the number of tags that you can have in a trend; however, keep in mind performance limitations for data retrieval for your computer system. For information on migrating trend files from previous versions of the ActiveFactory software, see Importing .CRV Data on page 160.

ActiveFactory Software Users Guide

Working with Trend Files

Creating a New Trend

Creating a new trend chart resets all trend settings to the default values.
To create a new trend

Do one of the following: On the File menu, click New.

Click the New Trend toolbar button.

To configure the new trend, see Configuring a Trend on page 64. By default, the new trend is in standard trend mode. To create an XY scatter plot, see Viewing Data in a Scatter Plot on page 139.

Opening an Existing Trend

To open an existing trend 1

Do one of the following: On the File menu, click Open.

Click the Open Trend toolbar button.

The standard Windows Open dialog box appears.

2 3

Browse to and select the trend file to open. All trend files have the .aaTrend extension. Click Open. The trend appears in the chart.

Note You can also double-click the .aaTrend file in the Windows Explorer to start up Trend. To open a recent trend

On the File menu, point to Recent Files, and then click the name of the file to open.

Saving a Trend
To save a trend 1

Do one of the following: On the File menu, click Save.

Click the Save Trend toolbar button.

If you are saving the trend for the first time, the standard Windows Save As dialog box appears. Otherwise, the trend is simply saved to disk using the existing file name.
2 3

In the Save As dialog box, type a name for the trend. All trend files have the .aaTrend extension. Click OK.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

To save a trend as another name 1 2 3

On the File menu, click Save As. The standard Windows Save As dialog box appears. In the Save As dialog box, enter a name for the trend. All trend files have the .aaTrend extension. Click OK.

Closing a Trend
To close a trend

Do one of the following: On the File menu, click Close.

Click the Close Trend toolbar button.

Undoing/Redoing Actions
The trend application supports 64 levels of undo/redo. You can undo/redo all of the actions for scaling and moving, as well as for adding and removing tags in the trend.
To undo an action

Do one of the following: On the Edit menu, click Undo.

Click the Undo toolbar button.

To redo an action

Do one of the following: On the Edit menu, click Redo.

Click the Redo toolbar button.

Configuring a Trend
When you configure a trend, you must select the tag(s) for which you want to query the trend data. This data is queried from the IndustrialSQL Server database(s) to which you are currently logged on. After you select tags for the trend, you can set the start date and end date for the trend.
To configure a trend 1

Use the Tag Picker to find tags in the IndustrialSQL Server database(s) that you want to include in your trend. For more information on the Tag Picker, see Tag Picker on page 51.

ActiveFactory Software Users Guide

Viewing Tag Definition Information

Drag and drop tags from the Tag Picker to the Tag List. You can add as many tags as your system resources allow. Select the time period for the query using the time picker. For more information, see Time Picker on page 58.

Viewing Tag Definition Information

Use the Tag List to view information for the tags that you have added to the trend chart.
To view tag information 1

In the Tag List window, scroll to the name of the tag for which you want to view definition information.

The grid shows the following information:

Name Description Server Color Units Minimum Maximum IO Address

The name of the tag. The description for the tag. The name of the server that contains the tag. The line color of the tag. The unit of measure of the tag value. Examples: seconds, psi, lbs. The minimum value of the raw acquired value. The maximum value of the raw acquired value The complete I/O address for the tag, including I/O Server name, application, topic, and item name. The amount of time that the trend curve will be shifted from the actual time.

Time Offset

Select or clear the check box to show or hide the tag in the trend chart. This allows you to hide a tag without removing it from the list of tags.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Viewing Data in the Trend Chart

This section describes how to use Trend to show historical and live data for trends, as well as how to manipulate the trend display. Information for individual tags appears in the Tag List below the chart. The name of the currently selected tag, its retrieval mode and resolution or cycle count (if applicable) appear along the bottom of the chart.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Refreshing the Trend Chart

You can refresh the Trend Chart to see the most recent information.
To refresh the chart 1

Set the Update to Current Time toolbar button depending on whether you want the trends time period to be updated to the current time when refreshing the chart. If the button is not available, the time period remains the same as before the update. If the button is available, the time period is updated so that it ends with the current time. Do any of the following: On the Chart menu, click Refresh.

Click the Refresh toolbar button. Press F5.

The trend chart is updated with current data from the database.

Deleting a Tag
You can delete a tag. Deleting a tag removes it from the chart.
To delete a tag from the trend 1 2

In the Tag List, select the tag to delete. Delete the tag by doing any of the following: On the Chart menu, click Delete Tag. At the prompt, click Yes.

Right-click on the tag in the Tag List. In the menu that appears, click Delete. Press the DELETE key on your keyboard.

Configuring Trend Options for a Tag

You can configure trend options for one or more tags in the Tag List window. Trend options include the appearance of the trend pen, its target region, and the retrieval mode used to retrieve data for the tag.

Configuring Display Options

You can configure the pen style, value axis scale, value display options, and time offset for each tag in the chart.
To configure display options for a tag 1

In the Tag List window, Do one of the following:

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Right-click on the name of the tag and then click Configure. Double-click on the name of the tag.

The <ServerName:Tagname> dialog box appears with the General tab selected.

In the Pen Configuration area, configure how the curve looks in the chart for the selected tag.

Color

The line color of the tag. Click the colored square to select the color from a palette or define a custom color. The thickness of the trend curve. The style of the trend curve. For example, a solid or dashed line.

Width Style

In the Value axis range area, configure the limits for the value axis on the chart.

Top Bottom

The maximum axis value for the tag, in engineering units. The minimum axis value for the tag, in engineering units.

In the Type list, select the type of trend curve to draw. Options are Auto, Line, Step line, and Point. A line curve is best suited for continuously-changing analog data. A step-line curve is best suited for discrete data and for analog data that is not continuous. When you select the Auto option, the curve type is determined as follows:

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

For tags retrieved from an IndustrialSQL Server 9.0 (or higher) historian, the type is based on the tags effective interpolation setting, which may be specified in the Trend applications retrieval settings or on the IndustrialSQL Server historian. Tags that use stair-step interpolation are trended as a step line, and tags that use linear interpolation are trended as a line. For tags retrieved from earlier IndustrialSQL Server historian versions, the curve type is based on the tag type: step line for integer tags, and line for real tags.

The following illustration shows the same data drawn using each type of curve. The line curve is shown in green, the step line curve is shown in orange, and the point curve is shown in red.

From the Decimal places list, select the number of decimal places to display for the data value. This applies only to analog tags. Valid values are 0 through 15. From the Format list, select how the values for the tag appear, either in decimal format or scientific format. Configure either the time offset or start time for the data. For more information on time offsets, see Using Absolute or Relative Times on page 110.

6 7

Time offset Shown only for absolute mode. The amount of time that the trend curve will be shifted from the actual time. For information on the offset notation, see Time Offset Formats on page 114. Start time Shown only for relative mode. The starting timestamp for the tag data in the chart.

Click OK.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Defining a Target Region for a Tag

For each analog or discrete tag in a trend, you can define a target region. The target region is a highlighted area of the chart into which tag values should fall during normal operation. Values that fall outside these normal limits can be highlighted in a special color, making it easy to detect them. The following chart shows an example of a target region (the area tinted in blue). The red spikes indicate limit excursions:

In a regular trend, you can only use target regions in relative time mode. A target region is defined by region items, that is, pairs of high and low values at specific time offsets. To determine the target region, a boundary is drawn that connects all of the high values, and another boundary that connects all of the low values. The area between these two boundaries constitutes the target region. For example, assume that you define the following region items:

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

On a trend chart in relative time mode, these points look like this:

The connecting boundaries look like this:

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

The area between these boundaries constitutes the target region:

The target region has the same color as the tags trend curve. It is only shown when the tag is currently selected in the tag list. Also, target regions are not visible if you are using stacked traces. You define and save target regions separately for each tag. Target regions are saved in the trend file. If you delete a tag from the trend, its target region is deleted as well. To use the same target region for multiple tags or in different trends, either copy and paste it or create a CSV file with the target region data that you can load for each tag. For more information, see the procedures below. The following section explains how to set up a target region for a tag. To specify whether and how values outside the target region should be highlighted, and to set the target regions opacity, see Configuring Target Region Properties on page 136.
To configure a target region for a trend tag 1

In the Tag List window, Do one of the following: Right-click on the name of the tag and then click Configure.

Double-click on the name of the tag.

The <ServerName:Tagname> dialog box appears with the General tab selected.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Click the Target Region tab.

Edit region items by using any of the following procedures: To edit region items manually To load region items from a CSV file To paste region items in CSV format from another application To paste region items from another tag To enable or disable a tags target region Click OK. The target region appears in the trend chart, spanning the time period that you defined using the region items time offsets.

To edit region items manually

Do any of the following: To add an item, click Add. A new item appears in the list. Double-click each cell to edit it. To delete an item, right-click it and click Cut. To delete all items, click Clear All. To move an item up or down in the list, select it and then click the up or down arrows.

To load region items from a CSV file 1 2

Click Load file. A standard Open dialog box appears. Select the desired file and click Open. The list is populated with the entries from the CSV file. Note the following format requirements for the CSV file:

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Each row must contain a region item composed of three values: the time offset, the low value, and the high value. The format of the time offset is the same as for time offsets in relative time mode. For more information, see Time Offset Formats on page 114. The Trend application tries to determine the CSV delimiter and the decimal and time separators automatically. If one of the values contains a delimiter or separator character, that value must be enclosed in double quotation marks.

To paste region items in CSV format from another application 1 In the other application, open the file that contains the

region items in CSV format. Copy the CSV data to the clipboard.
2

In the Trend application, right-click the list of region items, and then click Paste. The list is populated with the pasted entries. The format of the copied data must follow the same conventions as content in CSV files. For more information, see the previous section.

To paste region items from another tag 1 In the Tag List window, double-click the name of the tag

whose region items you want to copy. The

<ServerName:Tagname> dialog box appears with the General tab selected. 2 3

Click the Target Region tab. In the list of region items, select the item(s) you want to copy. To select multiple items, hold down SHIFT and/or CTRL while clicking. Right-click the selected items and click Copy. Click OK to close the dialog box. Repeat steps 1 and 2 for the tag where you want to paste the region items. Right-click the list of region items and click Paste. The list is populated with the pasted entries.

4 5 6

To enable or disable a tags target region 1 In the Tag List window, double-click the name of the tag. The <ServerName:Tagname> dialog box appears with the General tab selected. 2

Click the Target Region tab. Select or clear the Show target region check box to enable or disable the tags target region.

Note Regardless of this setting, the target region for a tag is only shown when that tag is currently selected in the tag list. 3

Click OK.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Configuring Retrieval Options for a Tag

You can configure retrieval options separately for each tag in a trend. Tags can either use the retrieval style specified in the trend options, a different predefined retrieval style, or custom retrieval settings. Most of the retrieval settings that you configure here only apply if you are retrieving data from an IndustrialSQL Server historian with a version of 9.0 or later. If you are using an earlier IndustrialSQL Server version, see Configuring Other Options on page 126 and Understanding Relations between Retrieval Styles, Application Settings and Tag Settings on page 693 for details.
To configure retrieval options for a tag 1

In the Tag List window, do one of the following: Right-click on the name of the tag and then click Configure.

Double-click on the name of the tag.

The <ServerName:Tagname> dialog box appears with the General tab selected.
2 3

Click the Retrieval tab. Do one of the following: To have the tag use the same retrieval settings as specified in the trend options, click Style selected at option level in the Retrieval style list. This is the default setting when you add a tag to a trend.

To use a predefined retrieval style, click its name in the Retrieval style list. For more information on retrieval styles, see Working with Retrieval Styles on page 684.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

To use custom retrieval settings, click Custom style in the Retrieval style list.

Specify any additional settings required. If you are using custom retrieval settings, select a retrieval mode and specify all the settings that are relevant to it. For more information, see Understanding Retrieval Modes on page 649.

If you are using one of the predefined styles, you can edit all settings that are not covered by the style definition. For information on which settings are covered by style definitions, see Working with Retrieval Styles on page 684. Because a style definition can contain multiple sets of retrieval settings with different retrieval modes, some of the settings available for editing here may turn out to be irrelevant for the retrieval mode that actually gets used for a given query. However, because there is no way to know in advance which retrieval mode will be used, the settings are still available for editing.

For more information on the various retrieval options, see Understanding Retrieval Options on page 673.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Scrolling through Tags in a Trend

You can change which tag is currently selected by using toolbar buttons. When using single tag mode, this allows you to scroll through tags without having the Tag List visible.
To change the currently selected tag

Do one of the following: On the Chart menu, click either Next Tag or Previous Tag to "scroll" to the desired tag.

Click the Previous Tag or Next Tag toolbar buttons to scroll to the desired tag.

Highlighting a Tag
You can select and highlight a tag in the chart. To remove the highlighting, follow the same procedure so that no check mark or highlighting appears.
To highlight a tag 1 2

Select the desired tag in the Tag List. Do one of the following: On the Chart menu, click Highlight Tag so that a check mark appears.

Click the Highlight Tag toolbar button so that it is highlighted.

The tag is highlighted in the chart.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Showing a Single Tag in the Trend

When you initially create a tag list for a trend, all the tags are included in the display. Setting the trend to single tag mode allows you to exclude all tags but one from being displayed in the trend chart, without removing them from the tag list.
To display a single tag in the trend

Do one of the following: On the Chart menu, click Single Tag Mode so that a check mark appears.

Click the Single Tag toolbar button so that it is highlighted.

To view multiple tags again in the chart, follow the same procedure so that no check mark or highlighting appears.

Stacking Traces
You can view individual trends, or "traces," for multiple tags in the chart by stacking them in the display.
To stack tags in the trend

Do one of the following: On the Chart menu, click Stacked Traces.

Click the Stacked Traces toolbar button.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Showing Live Data

A trend can be configured to show live data. Live data is data that is retrieved continuously in real time for a fixed duration that is relative to the current time (for example, the last hour). When retrieving live data, the Trend application retrieves data incrementally with every update. For example, if you set the update rate to ten seconds, then every ten seconds, the Trend application retrieves data for the last ten seconds and updates the chart with that data. Additionally, it periodically retrieves data for the entire chart time span to refresh the entire chart. You can specify both the update rate and the refresh interval for the entire chart. For more information, see Configuring General Properties on page 129. If the connection to the historian is lost while retrieving live data, any data that was retrieved up to that point is still shown on the chart until the next full refresh occurs. If the historian is still unavailable at that time, the old data is cleared from the trend chart.
Note When retrieving live data, the timestamp rule for data retrieval is forced to End. For more information on this setting, see Timestamp Rule on page 680. To display "live" data 1

Do one of the following: On the Chart menu, click Update to Current Time so that a check mark appears.

Click the Update to Current Time toolbar button so that it is highlighted.

2 3

In the Duration list of the Time toolbar, click a duration or enter one manually. Do one of the following: On the Chart menu, click Live Mode so that a check mark appears.

Click the Live Mode toolbar button.

To display "static" data

Do one of the following: On the Chart menu, click Live Mode so that no check mark appears.

Click the Stop Live Mode toolbar button.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Showing Historical Data in Replay Mode

When you replay historical data, the data is continuously plotted on the chart, starting with the start date. By default, the replay mode uses real-time speed. For example, if you set the chart to update every second, the start time advances one second with each update. You can accelerate or slow down the playback by specifying a playback speed. For example, if you select a playback speed of 2 x (that is, twice the normal speed) and set the chart to update every second, the start time advances two seconds with each update, as compared to one second for a playback speed of 1 x (normal speed) or half a second for a playback speed of 1/2 x (half the normal speed).
To replay historical data 1 2

Configure a query with a time period whose end time is earlier than the current time. Make sure the Update to Current Time toolbar button is not highlighted. If it is highlighted, click it so that it isnt highlighted anymore, or click Update to Current Time on the Chart menu. Do one of the following: On the Chart menu, click Live Mode so that a check mark appears.

Click the Live Mode toolbar button.

The trend curve is dynamically drawn on the chart. The

Replay Mode icon appears at the top center of the chart to

indicate replay mode.

To replay historical data at a slower or faster speed 1 2

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Click the downward arrow next to the Live Mode toolbar button. A list of playback speeds appears.

4 5

Click the playback speed you want to use. Click the Live Mode toolbar button. The trend curve is dynamically drawn on the chart at the specified speed. The Replay Mode icon and the playback speed appear at the top center of the chart to indicate replay mode. To change the speed while replay mode is active, repeat steps 1 and 2.

Note When you replay historical data at an accelerated speed, eventually the time period catches up with the current time. When that happens, the speed is automatically reset to normal, and the trend effectively goes into live mode. For more information, see Showing Live Data on page 79.

Scaling Tags
The scale is the minimum and maximum range of values for the tag. Each tag has its own scale, which is usually quite different from other tags in the chart. Scales for tags on the chart are always displayed along the value axis. Only discrete and analog tags can be scaled; event and string tags cannot be scaled. For discrete tags, the message associated with the 1 value is used as the maximum scale value, and the message associated with the 0 value is used as the minimum scale value.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

In the following chart, two tags are trended in stacked mode. The scale for the ReactLevel tag is from 0 to 3000. The scale for the other tag, ReactTemp, is from 0 to 220. The minimum and maximum values of each scale appear on the value axis.

The initial scale of a tag is determined by its Min/Max EU settings in the IndustrialSQL Server historian. To adjust tag scales, you have two options:

Edit the value axis range individually for each tag. For more information, see Configuring Trend Options for a Tag on page 67. Use the scaling commands to adjust the scale of a single tag or all tags. For more information, see Scaling Tags Up or Down on page 87 and subsequent sections.

You can also change the way in which scale values appear on the value axis. The following sections describe the available options.

Showing a Single Scale on the Value Axis

You can configure the chart to show a single value scale along the value axis. If the chart includes multiple tags, the scale of the currently selected tag in the chart is shown along the value axis. The scale label color matches the pen color of the selected tag. As you scroll through tags in the chart, the value axis always shows the scale of the selected tag. The labels along the value axis are shown even if the current tag is hidden.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

To show a single scale

On the View menu, click Single Scale. How a chart looks when a single scale is applied depends on the number of tags in the chart and whether the chart is in stacked mode. The following chart includes a single tag and is configured for a single scale. Stacked mode is not applied.

The following chart includes a single tag and is configured for a single scale. Stacked mode is applied. Only the minimum and maximum values are shown.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

The following chart includes multiple tags and is configured for a single scale. Stacked mode is not applied.

The following chart includes multiple tags and is configured for a single scale. Stacked mode is applied. The minimum and maximum values for each tag are shown for the corresponding trend curve.

Showing Multiple Scales on the Value Axis

You can configure the chart to show multiple value scales. For multiple scales, only the minimum and maximum values are shown on the value axis. The scale label colors match the pen colors of the corresponding tags. The values of hidden tags are not shown.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

To show multiple scales

On the View menu, click Multiple Scales. How a chart looks when multiple scales are applied depends on the number of tags in the chart and whether the chart is in stacked mode. When stacked mode is applied, there is no difference between using a single scale or multiple scales.

The following chart includes a single tag and is configured to use multiple scales. Stacked mode is not applied.

The following chart includes a single tag and is configured to use multiple scales. Stacked mode is applied.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

The following chart includes multiple tags and is configured to use multiple scales. Stacked mode is not applied. The top and bottom labels show the scale for the first tag in the tag list that is included in the chart. For the second tag in the tag list, the scale labels are shown as second from the top and second from the bottom. As you add tags to the chart, the addition of scale labels continues to progress inward toward the middle of the chart. If there is not enough space on the chart to show all of the scale labels, then the innermost values are not shown.

The following chart includes multiple tags and is configured to use multiple scales. Stacked mode is applied.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

Showing Cursor Values on the Value Axis

You can configure the chart so that the value axis shows the value of each tag at the position of the first X axis cursor. The axis label colors match the pen colors of the corresponding tags. The values of hidden tags are not shown.
To show cursor values on the value axis

On the View menu, click Values At Cursor. The following chart is configured to show cursor values on the value axis. Stacked mode is applied.

Scaling Tags Up or Down

You can scale a single tag or all of the tags in a trend up or down. If you scale a tag down, the range of values increases by one third. For example, if the scale is 10 to 70, it becomes 0 to 80. If you scale a tag up, the range of values decreases by one fourth. For example, if the scale is 0 to 80, it becomes 10 to 70.
To scale a single tag up

Do one of the following: On the Chart menu, point to Scale Tag and then click Scale Up.

Click the Scale Tag Up toolbar button.

To scale all tags up

Do one of the following: On the Chart menu, point to Scale All Tags and then click Scale Up.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Click the Scale All Tags Up toolbar button.

The following example shows a single tag scaled up:

To scale a single tag down

Do one of the following: On the Chart menu, point to Scale Tag and then click Scale Down.

Click the Scale Tag Down button.

To scale all tags down

Do one of the following: On the Chart menu, point to Scale All Tags and then click Scale Down.

Click the Scale All Tags Down button.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

The following example shows a single tag scaled down:

Automatically Scaling Tags

When a tag is automatically scaled, the value axis range is automatically adjusted to reflect the actual data currently being displayed for the trend. For example, if the default value axis range is 0 to 3000, and the data ranged from 1827 to 2059, the scale might be automatically adjusted to a range of 1800 to 2100. The adjusted scale does not exactly match the actual minimum and maximum data values for the chart. The calculation rounds the values so as to make the chart easier to read. Also, a percentage allocation is added to the final values so that the adjusted scale fits within the boundaries of the trend chart. Therefore, the adjusted scale is a round number slightly above the actual data values. You can automatically scale a single tag or all of the tags in a trend. For information on resetting scales back to the original default, see Returning Tags to Their Original Scale on page 90. Autoscaling is not performed continually for a trend. If the trended data includes points outside of the scale region, an indicator appears to remind you to perform a second autoscale operation.
To automatically scale a single tag

Do one of the following: On the Chart menu, point to Scale Tag and then click Auto Scale.

Click the Auto Scale Tag toolbar button.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

To automatically scale all tags

Do one of the following: On the Chart menu, point to Scale All Tags and then click Auto Scale.

Click the Auto Scale All Tags toolbar button.

The following example shows a tag automatically scaled:

Returning Tags to Their Original Scale

You can return the value axis scale for a single tag or all of the tags in a trend to the original scale.
To return a single tag to original scale

Do one of the following: On the Chart menu, point to Scale Tag and then click Original Scale.

Click the Tag Original Scale toolbar button.

To return all tags to original scale

Do one of the following: On the Chart menu, point to Scale All Tags and then click Original Scale.

Click the All Tags Original Scale toolbar button.

Moving Tags Up or Down in the Chart

You can move a single tag or all of the tags in a trend up or down in the trend chart. The scale is adjusted to reflect the move.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

To move a single tag up

Do one of the following: On the Chart menu, point to Scale Tag and then click Move Up.

Click the Move Tag Up toolbar button.

To move all tags up

Do one of the following: On the Chart menu, point to Scale All Tags and then click Move Up.

Click the Move All Tags Up toolbar button.

The following example shows a single tag moved up in the trend chart:

Using Rubber Band Scaling

Rubber band scaling allows you to lasso an area of the trend chart with the mouse cursor to automatically adjust the time and value axis scales based on the area that you lassoed. If you are using stacked traces, rubber band scaling is limited to the time axis.
To use rubber band scaling 1

Do one of the following: On the Chart menu, click Rubber Band Scaling so that a check mark appears.

Click the Rubber Band Scaling toolbar button.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Unless you are using stacked traces, rubber band scaling affects both the time and the value axes. Time axis scaling always applies to all tags in the chart. Value axis scaling can apply to all tags or the currently selected tag only. If you want value axis scaling to apply to all tags, Do one of the following: On the Chart menu, click Apply Rubber Band To All Tags so that a check mark appears.

Click the Apply Rubber Band to All Tags toolbar button so that it is highlighted.

If you are using stacked traces, rubber band scaling affects the time axis only, and this setting has no effect.
3

Drag a box around the area you want to use for the new scale.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

The trend chart is automatically redrawn using the new zooming values that you selected with the mouse.

Rubber band mode remains in effect until you turn it off by clicking either the Rubber Band Scaling menu command or toolbar button.

Panning in the Trend Chart

By default, the chart is panned to the left or right by the time span percentage set for the chart. This time span applies to both left and right panning and is a percentage of existing data coverage on the chart. The default time span is 75 percent; that is, when you pan right or left, the chart pans by three quarters of the total time span. For example, if the time axis for the chart spans one hour, the chart is panned to the left or right by 45 minutes. For more information on configuring the panning scale, see Configuring Axis Properties on page 132.
To pan left

Do one of the following: On the Chart menu, click Pan Left.

Click the Pan Left toolbar button.

To pan right

Do one of the following: On the Chart menu, click Pan Right.

Click the Pan Right toolbar button.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

If the time scale is set into the future, then white space appears. During a pan, the time picker changes to reflect the currently displayed selection.

Using Axis Cursors

Each trend chart has two value cursors and two time cursors. These cursors pinpoint tag values in the chart. The values shown for the axis cursors are updated continuously as the cursors are moved or as the trend curve moves in live mode.
Value at Time Cursor 1 Value at Time Cursor 2 Difference between time axis cursors Difference between value axis cursors Value at Value Cursor 1 Value at Value Cursor 2

Time Cursor 1

Time Cursor 2

Value Cursor 1

Value Cursor 2

You can show or hide the value and time cursors, as well as the values at the cursors. You can also show or hide the value cursor difference.

ActiveFactory Software Users Guide

Viewing Data in the Trend Chart

To configure the line and font colors for the cursors and cursor value displays, see Configuring Axis Properties on page 132.

Moving a Cursor
To move a cursor 1 2

Select the cursor with your mouse.

Drag the cursor to the desired spot on the chart. As you move the cursor in the trend chart, the value for the tag where the cursor and the tag curve meet appears.

Showing/Hiding the Axis Cursors

To show the time axis cursors

Do one of the following: On the View menu, click Time Axis Cursors so that a check mark appears.

Click the Time Axis Cursors toolbar button.

To show the value axis cursors

Do one of the following: On the View menu, click Value Axis Cursors so that a check mark appears.

Click the Value Axis Cursors toolbar button.

To hide the cursors, follow the same procedure so that no check mark or highlighting appears.

Showing/Hiding the Cursor Difference

To show the cursor difference

On the View menu, click Cursor Difference so that a check mark appears. To hide the cursor difference, follow the same procedure so that no check mark appears.

Zooming
When you use zooming in the trend chart, the zoom value depends on whether you are using time axis cursors. If you are not using time axis cursors, zooming is based on the total value for the time axis. The trend chart is zoomed in or out based on the current percentage set for the zooming scale. All zooms are positioned along the middle line of the trend chart.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

If you are using time axis cursors, zooming in sets the time period to the period between the cursors. Zooming out works as described above. For information on setting the zooming percentage, see Configuring Axis Properties on page 132.
To zoom in

Do one of the following: On the Chart menu, click Zoom In.

Click the Zoom In toolbar button.

To zoom out

Do one of the following: On the Chart menu, click Zoom Out.

Click the Zoom Out toolbar button.

Showing/Hiding the Chart Grid

You can show/hide the horizontal and vertical chart lines.
Chart Grid

To show the horizontal lines

Do one of the following:

ActiveFactory Software Users Guide

Viewing Trend Data in a Table Format

On the View menu, click Horizontal Grid so that a check mark appears. Click the Horizontal Grid toolbar button so that it is highlighted.

To show the vertical lines

Do one of the following: On the View menu, click Vertical Grid so that a check mark appears.

Click the Vertical Grid toolbar button so that it is highlighted.

To hide the lines, click the appropriate menu command so that no check mark appears or click the toolbar button so that it is not highlighted.

Viewing Trend Data in a Table Format

You can view a table of all data points used in a chart. This data log can be either in a narrow or a wide format. In both cases, the log only shows values for tags that arent hidden.

ActiveFactory Software Users Guide

Chapter 3 ActiveFactory Trend

Viewing the Data Log in a Narrow Format

To view the data log 1

On the View menu, point to Data Log and then click Narrow. The Data log dialog box appears.

Data appears for the following columns:

Time

The timestamp for the returned value. For delta retrieval, this is typically the time at which the value was acquired by the IndustrialSQL Server. For cyclic retrieval, this is the specific time requested or calculated (using a SQL function). The unique name of the tag within the IndustrialSQL Server system. The server from which data is being retrieved. The value of the tag at the timestamp. The basic data quality indicator associated with the data value.

Tag Name Server Value Quality

3 4

ActiveFactory Software Users Guide

Viewing Trend Data in a Table Format

To show messages for discrete tags (for example, ON or OFF), on the Options menu, click Show Messages For Discretes. You can copy and paste data to the Windows clipboard by right-clicking in the data and selecting the appropriate option from the menu that appears. To save the data as a .csv file, on the File menu, click Save As. To set up a printout of the data, on the File menu, click Page Setup. Setting up the page works like in any other Windows application. To preview a printout of the data, on the File menu, click Print Preview. Using the preview window works like in any other Windows application. printing options works like in any other Windows application.

7 8

10 To print the data, on the File menu, click Print. Specifying

11 To exit the dialog box, on the File menu, click Exit. Or, click the Close button.

ActiveFactory Software Users Guide

100

Chapter 3 ActiveFactory Trend

Viewing the Data Log in a Wide Format

To view the data log 1

On the View menu, point to Data Log and then click Wide. The Data log dialog box appears.

Data appears for the following columns:

Time

To include only the data that is between the time axis cursors on the chart, on the Options menu, click Data From Between Cursors. To include all of the data on the chart, on the Options menu, click Data From Between Graph Start/End. To show actual values for discrete tags (for example, 1 or 0), on the Options menu, click Show Actual Values For Discretes. When retrieving data for discrete tags in ValueState mode, you must select this option to see correct time-in-state information. To show messages for discrete tags (for example, ON or OFF), on the Options menu, click Show Messages For Discretes. You can copy and paste data to the Windows clipboard by right-clicking in the data and selecting the appropriate option from the menu that appears.

3 4

ActiveFactory Software Users Guide

Viewing Trend Data in a Table Format

101

7 8

To save the data as a .csv file, on the File menu, click Save As. To set up a printout of the data, on the File menu, click Page Setup. Setting up the page works like in any other Windows application. To preview a printout of the data, on the File menu, click Print Preview. Using the preview window works like in any other Windows application. printing options works like in any other Windows application.

10 To print the data, on the File menu, click Print. Specifying

11 To exit the dialog box, on the File menu, click Exit.

Viewing Statistics
You can view statistics for the data that is retrieved and displayed for a trend. Display statistics include range, average, minimum, maximum, sum, standard deviation, and query properties. Examples of query properties are query time range, start time, end time, and number of rows returned.
To display data statistics 1

On the View menu, click Statistics. The Statistics dialog box appears.

Statistics appear in columns as follows.

Type Tag Name Server Samples Minimum Time at Minimum

The type of tag. The name of the tag. The server that contains the tag. The number of samples in the trend. Minimum value for the data that is plotted in the chart. The timestamp of the minimum value.

ActiveFactory Software Users Guide

102

Chapter 3 ActiveFactory Trend

Maximum Time at Maximum Average Standard Deviation Range Timespan From To

Maximum value for the data that is plotted in the chart. The timestamp of the maximum value. Average value for the data. Standard deviation for the data. Value range for the data. The total amount of time that is spanned by the data. The starting date for the data. The ending data of the data.

To include only the data that is between the time axis cursors on the chart, on the Options menu, click Data From Between Cursors. To include all of the data on the chart, on the Options menu, click Data From Between Graph Start/End. To show actual values for discrete tags (for example, 1 or 0), on the Options menu, click Show Actual Values For Discretes. To show messages for discrete tags (for example, ON or OFF), on the Options menu, click Show Messages For Discretes. You can copy and paste data to the Windows clipboard by right-clicking in the log and selecting the appropriate option from the menu that appears. To save the data as a .csv file, on the File menu, click Save
As.

3 4

7 8

To set up a printout of the data, on the File menu, click Page Setup. Setting up the page works like in any other Windows application. To preview a printout of the data, on the File menu, click Print Preview. Using the preview window works like in any other Windows application. printing options works like in any other Windows application.

10 To print the data, on the File menu, click Print. Specifying

11 To exit the dialog box, on the File menu, click Exit.

ActiveFactory Software Users Guide

Using Annotations

103

Using Annotations
You can use Trend to make an annotation for a tag at any point in time. An annotation is simply a user comment about a tag. For example, you might want to save a comment about a very high spike in a trend. You can create an annotation for the value of the tag at the spike. All annotations are saved to the database and can be retrieved again at a later time. You can create a private annotation (that only you can see) or a public annotation (which is viewable by all trend users). Private annotations are only available to the users who created them and have suitable access. For each annotation, an annotation mark (solid circle) is added to the trend. This annotation mark can be viewed on the trend if the trend properties are set to allow it. When you make an annotation, the following information is stored in the Annotation table in the Runtime database of the IndustrialSQL Server historian:

Name of the tag for which the annotation is associated. The date/time of the annotation. The time of the annotation is based on the position of where it was created on the time axis. The value of the tag at the time of the annotation. The annotation text.

The user name is linked to the Annotation table through the UserKey column.

Adding an Annotation
Annotations are inserted in the chart at the location where the mouse button is clicked and are associated with the selected tag's value where the mouse button is clicked.
To add an annotation 1 2

Select the tag for which you want to add an annotation. You can do this by selecting the tag in the Tag List pane. Do one of the following: On the Chart menu, click Add Annotation.

ActiveFactory Software Users Guide

104

Chapter 3 ActiveFactory Trend

Right-click in the chart. In the shortcut menu that appears, click Add Annotation.

The Add Annotation dialog box appears.

3 4 5 6

In the Tag list, click the name of the tag for which you want to add the annotation. In the Time list, click the timestamp of the tag value for which you want to add the annotation. In the Text window, type in your comment. In the Visibility area, specify if you want the annotation to be visible to others. Click Private to have annotations only visible to you.Click Public to have annotations visible to anyone who is able to log on to the database. Click OK. An annotation marker (dot) appears on the chart at the point on the chart where the annotation was made. If you

ActiveFactory Software Users Guide

Using Annotations

105

hover with the mouse on the marker, the details for the annotation appear on the chart.

Viewing the Annotation List

To view a list of annotations 1

On the View menu, click Annotation List. The Annotations dialog box appears.

The table in the window shows the following information.

Type Tag Name Server Content User

Specifies whether the annotation is public. The unique name of the tag within the IndustrialSQL Server system. The name of the server that stores the tag values. The annotation text. The name of the database user. This is the user that created the annotation.

ActiveFactory Software Users Guide

106

Chapter 3 ActiveFactory Trend

Time

The timestamp of the tag value for which the user has made an annotation.

Created On The date that the annotation was created.

To sort the table according to the information in a particular column, click the column heading. Click again to reverse the sorting order.

Editing an Annotation
To edit an annotation 1 2 3

On the View menu, click Annotation List. The Annotations dialog box appears. Select the annotation in the list. On the Annotations menu, click Edit. The Edit Annotation dialog box appears.

4 5

Edit the annotation as desired. Click OK.

Deleting an Annotation
Deleting an annotation removes the annotation from the trend.
To delete an annotation 1 2 3

On the View menu, click Annotation List. The Annotations dialog box appears. Select the annotation in the list. On the Annotations menu, click Delete. Confirm the deletion.

ActiveFactory Software Users Guide

Using Annotations

107

Click OK.

Saving the Annotations List as a .CSV File

To save the list of annotations as a .csv (text) file 1 2 3 4 5

On the View menu, click Annotation List. The Annotations dialog box appears. On the File menu, click Save As. The standard Windows Save As dialog box appears. In the File name box, type a name for the .csv file. Browse to the location in which to save the file.

Click Save. The .csv file contains the same information that appears in the Annotations dialog box.

Printing Annotations
To print the list of annotations 1

On the View menu, click Annotation List. The Annotations dialog box appears.

ActiveFactory Software Users Guide

108

Chapter 3 ActiveFactory Trend

To configure the printing options, on the File menu, click Page Setup. The Page Setup dialog box appears.

3 4

Configure the setup options and then click OK. To preview the printout, on the File menu, click Print Preview. The Print preview dialog box appears. need one for annotations.

Verify the preview and then click Close.

ActiveFactory Software Users Guide

Trending Events

109

To print the annotations, on the File menu, click Print. The Print dialog box appears.

Configure the printing options and then click OK.

Trending Events
A trend can be configured to show event data. An event is the set of attributes describing the moment of satisfaction of a set of criteria on historical tag values in the IndustrialSQL Server historian. Attributes of an event include the date and time that the event occurred and the criteria that were satisfied. An event tag is a name for an event definition in the system. Whereas these tag types are the definitions of types of variables to be stored, an event tag is a named reference for the description of how a specific change is detected and what to do if it is detected. You can select and trend event tags in the same way as any other tag in the system. Events can also be displayed along with analog and discrete tags.

ActiveFactory Software Users Guide

110

Chapter 3 ActiveFactory Trend

Each occurrence of an event appears on the chart with a diamond-shaped indicator.

Using Absolute or Relative Times

The following date modes are available for the trend chart:

Absolute time Relative time

The date mode selection is saved as part of the chart definition when you save the .aaTrend file.

Using Absolute Time

For the absolute date mode, the start and end dates in the data query are used for the start and end times in the chart, respectively.
To use absolute time

On the View menu, click Absolute Time.

ActiveFactory Software Users Guide

Using Absolute or Relative Times

111

For example, the following chart shows five minutes of data in absolute time. The query for the data starts at 12:00:00 and ends at 12:05:00, and the time axis values reflect these times.

In absolute date mode:

The times shown for the time axis cursors, if enabled, are absolute times. The times shown in the Time Bar are absolute times.

The Tag List shows the time offset for the chart data, relative to 0. In this example, there is no offset configured.

The Tag Properties dialog box shows the time offset option. For more information, see Configuring Trend Options for a Tag on page 67.

ActiveFactory Software Users Guide

112

Chapter 3 ActiveFactory Trend

Using Relative Time

For the relative time mode, a base value (such as 0:00:00.0) is used for the start time of the chart, and the end time is calculated based on the time span for the query. Switching to relative mode does not change the data shown in the chart or the actual start and end time of the trend query. Only the time axis is updated.
To use relative time

On the View menu, click Relative Time. For example, the following chart shows five minutes of data in relative mode. The query for the data starts at 12:00:00 and ends at 12:05:00, but the time axis shows a start time of 0:00:00 and an end time of +0:05:00.

In relative time mode:

The times shown for the time axis cursors, if enabled, are relative times. For more information on the display format for times, see Time Offset Formats on page 114. The times shown in the Time Bar are relative times. The first offset time is the base time (for example, 0:00:00.000), and the second time is the time span of the specified offset. The first offset time is always set to 0:00:00 when you transition into relative mode.

ActiveFactory Software Users Guide

Using Absolute or Relative Times

113

The Tag List shows the actual start time for the tag data.

The Tag Properties dialog box shows the start time option. For more information, see Configuring Trend Options for a Tag on page 67.

Switching Between Absolute and Relative Time: Example

When you change the time mode, the Time Bar and individual tag time settings convert between absolute times and relative offsets. The following table summarizes the states for the Time Bar and three tag offsets/dates for some example data. Tag1 is the currently selected tag. In this example, the actions performed for the different steps are:
1

At exactly 2005-07-04 10:00, 2 hours is selected from the Time Bar while the Update to Current Time option is enabled. The chart is in absolute mode. The chart is switched to relative time mode. The start and end values are changed in the Time Bar. The chart is switched back to absolute time mode.
2 3 4

2 3 4 Step: 1

Mode: Time Bar Start: Time Bar End: Tag1: Tag2: Tag3: Time Axis Start: Time Axis End:

Absolute 2005-07-04 8:00 2005-07-04 10:00 - 24:00 0:00 +3:30 2005-07-03 8:00 2005-07-03 10:00

Relative 0:00 2:00 2005-07-03 8:00 2005-07-04 8:00 2005-07-04 11:30 0:00 2:00

Relative -0:15 0:45 2005-07-03 8:00 2005-07-04 8:00 2005-07-04 11:30 -0:15 0:45

Absolute 2005-07-04 7:45 2005-07-04 8:45 - 24:00 0:00 +3:30 2005-07-03 7:45 2005-07-03 8:45

ActiveFactory Software Users Guide

114

Chapter 3 ActiveFactory Trend

Time Offset Formats

The supported notations for specifying a time offset are: [ws][][dws]hh:mm[:ss[.fff]][ws] -OR[ws][]HH:mm[:ss[.fff]][ws] -OR[ws][]d[.FF][ws] Items in square brackets ([ and ]) are optional. Colons and periods (: and .) are literal characters. The notation variables are as follows.
Item Description

ws dws d hh HH mm ss fff FF

White space. Minus sign indicating a negative time. Positive time is assumed. Days, with trailing white space. Days Hours, ranging from 0 to 23. Hours of 24 or greater. Minutes, ranging from 0 to 59. Seconds, ranging from 0 to 59. Fractional seconds, from 1 to 7 decimal digits. Fractional days.

Time offsets are shown in the application in either a short or long form: Short form: Long form: HH:mm:ss.ff or d hh:mm:ss.fff d <label> hh:mm:ss.fff

In the short form:

d is omitted for offsets less than or equal to 48 hours .fff is omitted for offsets greater than 60 seconds :ss.fff is omitted for offsets greater than 24 hours

Thus, for periods of less than 60 seconds, the short form is never longer than 11 characters. For the short form, the hours in HH format (rollover at 48 instead of 24) are shown only if days are not to be displayed anywhere on the time axis.

ActiveFactory Software Users Guide

Using Absolute or Relative Times

115

The <label> is the localized word for days or day. The period (.) and colon (:) are replaced with the appropriate characters from the regional settings.

Using Time Offsets to Compare Data

You can use a time offset to compare the same data from different time periods. For example, you may want to compare data from a shift at 10:00 a.m. to data from a shift at 11:00 a.m. The time offset feature allows you to adjust the time period for one of the shifts so that the data appears as if it occurred during the same time period as the other shift. Using a time offset allows you to easily see the differences between the data on the trend chart. For information on configuring a time offset, see Configuring Trend Options for a Tag on page 67.
To use a time offset 1

Create a trend for batch of data that you want to use as the basis for comparison. In this example, the chart is configured to show data for the ReactLevel tag between 6/22/2005 10:00:00 AM and 6/22/2005 11:00:00 AM.

Add the same tag again to the trend chart for the same time period. In this example, the ReactLevel tag was added again to the chart.

ActiveFactory Software Users Guide

116

Chapter 3 ActiveFactory Trend

Because the data is identical, you only see a single trend curve in the chart.

4 5

Determine the time span for the data you want to compare with the base batch of data. To specify the time offset for the data to compare, double-click on the tag in the Tag List. The Tag Properties dialog box appears.

ActiveFactory Software Users Guide

Using Absolute or Relative Times

117

In the Time offset box, configure the amount of time that the data shown in the chart is to be offset from the actual query time. For more information on the format, see Time Offset Formats on page 114. In this example, this data is to be compared with the base batch that occurred an hour before, so the time offset is set to one hour.

Click OK. In this example, the data for the ReactLevel tag between 6/22/2005 11:00:00 AM and 6/22/2005 12:00:00 AM includes an annotation made around 11:30:00 AM.

ActiveFactory Software Users Guide

118

Chapter 3 ActiveFactory Trend

Stack the traces so that you can see both sets of data separately and then select the first tag that you added to the chart. In this example, the trend curve for the later set of data (shown in green) appears on the chart, even though the time axis reflects the time of the base batch of data (shown in orange).

ActiveFactory Software Users Guide

Using Absolute or Relative Times

119

To view the chart in relative mode, on the View menu, click Relative Time. The time axis now shows the time span for the base batch starting at 0:00:00 instead of the actual time.

You can also use the offset to compare a trend curve against another curve either forward or backward in time. To do this, set the time offset of the master batch of data so that the start time is the same as the start time for the batch of data you want to compare.

ActiveFactory Software Users Guide

120

Chapter 3 ActiveFactory Trend

In the following example, the time offset for the complete batch is set to a value of -01.00.44. The complete batch appears as the top curve in the chart. The incomplete curve at the bottom of the chart is plotted in live mode next to the complete curve at the top.

Configuring Trend Application Options

The trend options allow the user to configure the trend application. These options apply to all saved trend files. Categories of trend options that can be set include:

Retrieval Colors Time Zones Miscellaneous Other

Configuring Retrieval Options

You can define data retrieval options at the application level. These options are used for all tags that dont have their own settings defined.

ActiveFactory Software Users Guide

Configuring Trend Application Options

121

Application-level retrieval options are not saved in trend files. Therefore, trend files with tags that rely on application-level retrieval settings may look different depending on the retrieval options that are configured in the Trend application that they are opened in. To make sure that your tags are using specific retrieval options, define these options individually for each tag. For more information, see Configuring Retrieval Options for a Tag on page 75. Most retrieval settings that you configure here only apply if you are retrieving data from an IndustrialSQL Server historian with a version of 9.0 or higher. If you are using an earlier IndustrialSQL Server version, see Configuring Other Options on page 126 and Understanding Relations between Retrieval Styles, Application Settings and Tag Settings on page 693 for details.
To configure retrieval options 1

On the Tools menu, click Options. The Options dialog box appears with the Retrieval tab selected.

Do one of the following: To use a predefined retrieval style, click its name in the Retrieval style list. For more information on retrieval styles, see Working with Retrieval Styles on page 684.

To use custom retrieval settings, click Custom style in the Retrieval style list.

Specify any additional settings required.

ActiveFactory Software Users Guide

122

Chapter 3 ActiveFactory Trend

If you are using custom retrieval settings, select a retrieval mode and specify all the settings that are relevant to it. For more information, see Understanding Retrieval Modes on page 649. If you are using one of the predefined styles, you can edit all settings that are not covered by the style definition. For information on which settings are covered by style definitions, see Working with Retrieval Styles on page 684. Because a style definition can contain multiple sets of retrieval settings with different retrieval modes, some of the settings available for editing here may turn out to be irrelevant for the retrieval mode that actually gets used for a given query. However, because there is no way to know in advance whether this will be the case, the settings are still available for editing.

For more information on the various retrieval options, see Understanding Retrieval Options on page 673. By default, the retrieval settings that you specify here are used for all tags on all trend charts. However, you can override these settings individually for each tag. For more information, see Configuring Retrieval Options for a Tag on page 75.

Configuring Color Options

The trend color options control how the trend pen looks for each new tag as it is added to the chart. By default, Trend includes 256 different pen styles, which are numbered from 1 to 256. An unused style is applied each time you add a tag to the trend chart. The trend assigns the lowest pen style that is available. For example, the first pen style is a solid red line, so the first tag you place in a chart has this style. You can change the default pen styles. Changing the options does not affect tags that are already in the trend chart.
To configure color options 1

On the Tools menu, click Options. The Options dialog box appears.

ActiveFactory Software Users Guide

Configuring Trend Application Options

123

Click the Colors tab.

To use the default pen styles for the tags in a trend, select the Use default colors for new tags check box. Skip to step 10. To configure one or more pen styles, clear the Use default colors for new tags check box. Select a pen number from the list. Click the Color box and select or configure a color for the pen line. In the Width list, select the width, in pixels, of the pen line. In the Style box, select the style of the pen, either a solid line or one of a variety of dashes. Repeat steps 5 through 8 for each pen style you want to configure.

4 5 6 7 8 9

10 Click OK.

Configuring Time Zone Options

You can configure Trend so that data appears with timestamps that reflect any time zone. For example, you may want to configure Trend so that it reflects the same time as the server.
To configure time zone options 1

On the Tools menu, click Options. The Options dialog box appears.

ActiveFactory Software Users Guide

124

Chapter 3 ActiveFactory Trend

Click the Time Zones tab.

The grid shows the current time zone and daylight savings time settings for the following entities:
Entity Description

Application

The ActiveFactory Trend application. You can select the time zone for the data as it appears in the Trend application.

Client

The physical computer on which the Trend application is installed. The time zone displayed for the client is for informational purposes only and cannot be changed using the Trend application.

The IndustrialSQL Server historian(s) to which the Trend application is currently connected. The time zone displayed for the server(s) is for informational purposes only and cannot be changed using the Trend application.

ActiveFactory Software Users Guide

Configuring Trend Application Options

125

In the Time zone list, click the name of the time zone to use for the Trend application. The time zone for the Trend application in the grid shows the new time zone picked. For example, consider a SCADA application that monitors a pipeline between Houston, Texas and Lake Forest, California. The Trend application is installed on a computer located in Houston, Texas. Therefore, the time zone entry for the Client entity displays Central Standard Time. The server is also located in Houston, Texas. The time zone entry for the Server entity also displays Central Standard Time. You want to send a trend file to an engineer located at the start of the pipeline in Lake Forest to aid in troubleshooting a problem. You can set the time zone of the Trend application to reflect the time of Lake Forest, California (Pacific Standard Time), so that the trend that you send to the engineer displays data in a time zone that is relevant to him/her.

Click OK.

Configuring Miscellaneous Options

To configure miscellaneous options 1 2

On the Tools menu, click Options. The Options dialog box appears. Click the Miscellaneous tab.

Select the Always on top check box to always display Trend as the top-most program on the computer desktop.
ActiveFactory Software Users Guide

126

Chapter 3 ActiveFactory Trend

4 5

Select the Display all tag timestamps in all data logs check box to include the timestamps for all tags in the data log. In the Discrete log format area, configure how the values for discrete tags appear in the data log. Select Display actual numeric values to show the numeric value for the discrete tag, either 1 for the TRUE state or 0 for the FALSE state. Select Display associated messages to show the text associated with the TRUE or FALSE state of the discrete tag. For example, On or Off, Started or Stopped. In the Tag defaults area, configure how tag values appear in the chart. Changes to these settings are not applied until the next tag is added to the chart.

Decimal places The number of values that appear to the right of the decimal period. Format The format for tag values, either decimal format or scientific format. For the scientific format, the value appears with an E denoting the exponent.

By default, when you start the Trend application, it automatically reopens the trend files that were open when you closed it. Clear the Open documents on startup check box to disable this behavior. Click OK.

Configuring Other Options

To configure other options 1

On the Tools menu, click Options. The Options dialog box appears.

ActiveFactory Software Users Guide

Configuring Trend Application Options

127

Click the Other tab.

In the Source area, specify the IndustrialSQL Server tables from which data will be retrieved.

Manual history tables

Normal SQL Server tables that are used to store data. These are the ManualAnalogHistory and ManualDiscreteHistory tables. Logical tables that are populated from the IndustrialSQL Server data files. These tables support the IndustrialSQL Server time domain extensions for handling data. Select this option to retrieve data from both the manual and extension tables.

Extension tables

Both

ActiveFactory Software Users Guide

128

Chapter 3 ActiveFactory Trend

In the Legacy retrieval area, specify the retrieval mode for data that is retrieved from IndustrialSQL Server historians with a version earlier than 9.0. For information on how these settings interact with a retrieval style that you may have selected, see Understanding Relations between Retrieval Styles, Application Settings and Tag Settings on page 693.

Use Delta retrieval for less than specified intervals Interval for Analogs

Select this check box to use delta retrieval mode for query time periods that are less than a specified amount.

The time period, in minutes, for which delta values are retrieved for analog tags. For greater time periods, cyclic retrieval is used instead. Valid values are 0 to 10,000. The default is 15. The time period, in minutes, for which delta values are retrieved for analog tags. For greater time periods, cyclic retrieval is used instead. Valid values are 0 to 10,000. The default is 15. The maximum number of values to return per tag. Valid values are 0 to 30,000. The default is 10,000.

Interval for Discretes

Maximum values to retrieve per tag

Click OK.

Configuring Trend File Properties

The trend properties allow you to configure the trend file. Trend file properties are saved with the trend file. Categories of trend properties that can be set include:

General Limits Colors Axes Annotations Target Regions

ActiveFactory Software Users Guide

Configuring Trend File Properties

129

Configuring General Properties

To configure general properties 1 2

On the Chart menu, click Properties. The Trend Properties dialog box appears. Click the General tab.

In the Refresh interval box, specify the time period, in seconds, at which the chart is refreshed if set to live mode. Valid values are .25 to 300. The default is 1. In the Refresh entire chart every XX intervals box, specify the number of refresh intervals after which the entire chart is refreshed. The chart is not only refreshed with the new live data, but all the data in the chart is refreshed. Valid values are 1 to 100,000. The default is 100. In the Printing area, configure options for chart printing.

Title Show title Suppress tag list

The title of the chart. Show the title in the printout. Do not include the tag list in the printout.

Click OK.

ActiveFactory Software Users Guide

130

Chapter 3 ActiveFactory Trend

Configuring Color Properties

To configure color properties 1 2

On the Chart menu, click Properties. The Trend Properties dialog box appears. Click the Colors tab.

Click the Time axis label color box to select or configure the color for the time labels that appear at the bottom of the chart. In the Background area, configure the colors or image to use for the background of the entire chart area.

Color

Click to select or configure a main color. If you are using a gradient fill, this is the starting color for the gradient. Click to select the ending color for the gradient. The gradient starts with the main color and fade to the gradient end color.

Gradient end color

ActiveFactory Software Users Guide

Configuring Trend File Properties

131

Gradient type

The starting point for the flow of the gradient. Valid values are Center, Diagonal Left, Diagonal Right, Horizontal Center, Left Right, Top Bottom, and Vertical Center. For example, if you select green as main color, white as the gradient end color, and center as the gradient type, the center of the chart is green and fades to white towards the surrounding edges. The name of the image to use as the background. The image is resized to fit within the chart area. The color of the pixel in the lower left corner of the image is used as the transparency mask for the image. Click the ellipses button to browse for and select an existing image. If you want to publish the trend to the ActiveFactory Reporting Website, specify the image path as a UNC path that is accessible from the Reporting Website clients. Otherwise, the image doesnt appear on the clients.

Image

In the Plot area, configure the colors or image to use for the chart plotting area. Options are the same as for the Background colors. In the Border area, configure the color for the border of the chart.

Color Width Type

Click to select or configure a color. The width, in pixels, of the border line. The style of the border line.

7 8

In the Grid area, configure the color for the grid lines of the chart. Options are the same as for Border. In the Highlighting area, configure the color and pen width to be used for tag highlighting.

Highlight color Pen width

Click to select or configure a color for highlighting the tag curve. Specify how wide (in pixels) a highlighted curve should be.

Click OK.

ActiveFactory Software Users Guide

132

Chapter 3 ActiveFactory Trend

Configuring Axis Properties

To configure axis properties 1 2

On the Chart menu, click Properties. The Trend Properties dialog box appears. Click the Axes tab.

In the X axis area, configure the properties for the horizontal axis.

Number of values

The number of values that are shown along the time axis. The values are shown at evenly-spaced points along the axis. The number of values remain the same even if you zoom in and out. The valid range is from 2 to 15, with a default of 6. The number of grid lines that appear between each tag value plotted on the chart. The valid range is from 1 to 20, with a default of 3. Click to select or configure the color for each time axis cursor. The width of each time axis cursor.

Grid lines per value

Color Width

ActiveFactory Software Users Guide

Configuring Trend File Properties

133

Style

The line style for each time axis cursor.

When panning, The percentage used for the pan by panning scale. The panning scale range is from 1 to 100. When zooming, The percentage used for the zoom. zoom by The zoom factor range is from 1 to 100.

In the Y axis area, configure the properties for the vertical axis.

Number of values

The number of values that are shown along the value axis. The timestamps are shown at evenly-spaced points along the axis. The number of values remain the same even if you zoom in and out. The valid range is from 2 to 15, with a default of 6. The number of grid lines appearing between each tag value that is plotted on the chart. The valid range is from 1 to 20, with a default of 3. Click to select or configure the color for each value axis cursor. The width of each value axis cursor. The line style for each value axis cursor.

Grid lines per value

Color Width Style

Click OK.

Configuring Limit Properties

To configure limit properties 1

On the Chart menu, click Properties. The Trend Properties dialog box appears.

ActiveFactory Software Users Guide

134

Chapter 3 ActiveFactory Trend

Click the Limits tab.

Select the Show Limits check box to show horizontal lines on the chart at the limit values configured for analog tags.
Limit excursion

Limit line

ActiveFactory Software Users Guide

Configuring Trend File Properties

135

For each type of limit (HiHi, Hi, Lo, and LoLo), configure the properties of the line.

Limit line

Select this check box to include a line on the chart for the limit value. For example, if an analog tag has a Hi limit of 1800, a horizontal line is drawn at the 1800 mark on the vertical axis. Select this check box to indicate the portion of the trace that is outside of the limit. The color of the line. The width of the line. The style of the line.

Limit excursion Color Width Style

Click OK.

Configuring Annotation Properties

To configure annotation properties 1 2

On the Chart menu, click Properties. The Trend Properties dialog box appears. Click the Annotations tab.

Select the Retrieve annotations check box to retrieve annotation information and show them on the chart.

ActiveFactory Software Users Guide

136

Chapter 3 ActiveFactory Trend

In the Annotations area, configure how annotations are shown on the chart.

Show annotations Show only the annotations for for tags on the trend the tags currently charted in the trend. Show annotations for all tags Show all annotations for all tags. For those tags not currently charted on the trend, the annotation marker appears at the top of the chart at the point in time on chart at which the annotation was made. Show only public annotations. You can see your private annotations and the public annotations of other IndustrialSQL Server historian users. Show both public and private annotations. You can see your private annotations, as well as both the public annotations and private annotations of others.

Show public annotations

Show annotations for all users

Click OK.

Configuring Target Region Properties

To configure target region properties 1

On the Chart menu, click Properties. The Trend Properties dialog box appears.

ActiveFactory Software Users Guide

Configuring Trend File Properties

137

Click the Target Regions tab.

3 4

In the Opacity box, enter the opacity with which you want the target region to appear on the trend chart. In the Excursion annunciation type list, specify whether values that fall outside the target region should be highlighted. Select Show with special color to highlight parts of the trend graph that are outside the target region in a special color. To select the color, click the color box next to Target region excursion color. Select None if you dont want any special highlighting. Click OK.

ActiveFactory Software Users Guide

138

Chapter 3 ActiveFactory Trend

Working with Scatter Plots

In addition to regular trends, you can display data in XY scatter plots. While a regular trend shows the variation of a tags value over time, a scatter plot shows the variation of a tags value over the variation of another tags value. This allows you to see correlations between the two tags. For example, you could show how product yield varies depending on the reactor temperature in a manufacturing process, and use this information to determine the optimum temperature:

In this example, the X axis represents the reactor temperature as historized by the ReactTemp tag (the X axis tag). The Y axis represents the product yield as historized by the ProductGood tag (the Y axis tag). For each available data sample of either tag during the chosen time period, a corresponding value for the other tag is matched or interpolated and plotted on the chart. For more information, see How Are Value Pairs Matched? on page 142.

ActiveFactory Software Users Guide

Working with Scatter Plots

139

Plotted over time, the two tags looks like this:

Compared to this type of display, the scatter plot shows the correlation much more clearly. The following sections show you how to configure a scatter plot and manipulate the display. Many of these features work just like in a regular trend. Therefore, these sections mainly explain the specific differences when working with scatter plots. For more information on basic trend operations, see the rest of this chapter.

Viewing Data in a Scatter Plot

Scatter plots show value pairs. Just as in a geometric coordinate system, every data point in scatter plot must have an X value that determines its horizontal position as well as a Y value that determines the vertical position. On a regular trend, there is no such thing as an X value that corresponds to the Y value of a tag; instead, the horizontal position of a tags value on the chart is determined by the values timestamp. On a scatter plot, however, both the X and the Y values must be supplied as tag data. Therefore, you must assign an X axis tag to every tag that you want to view in the scatter plot. Tags without a corresponding X axis tag are visible in the tag list, but not in the chart. For more information on how X and Y values are matched, see How Are Value Pairs Matched? on page 142
To configure a scatter plot 1

Click the New Chart toolbar button. A new trend chart appears.

ActiveFactory Software Users Guide

140

Chapter 3 ActiveFactory Trend

Do one of the following: On the Chart menu, point to Chart Type and click XY Scatter Plot.

Click the XY Scatter Plot toolbar button.

The chart switches into scatter plot mode.

Add tags to the chart by double-clicking them in the Tag Picker or dragging them onto the Tag List. For more information on the Tag Picker, see Tag Picker on page 51. You must add all tags that you want to use as X or Y axis tags. Note the following:

One tag can serve as the X axis tag for multiple other tags. If you want to view the same tag against different X axis tags, add it to the tag list multiple times. While you can add string or event tags, they serve no purpose in a scatter plot. Therefore, these tags are automatically marked as hidden.

4 5

Specify a time period for the chart using the time toolbar. For more information, see Time Picker on page 58. Assign an X axis tag to every tag that you want to view in the scatter plot:
a

Double-click the tagname in the tag list. The <ServerName:Tagname> dialog box appears with the General tab selected. In the X axis tag list, click the name of the tag that you want to use as the X axis tag for this tag. To remove an existing X axis tag association, click the blank entry instead. Configure other tag options as required. For more information, see Configuring Trend Options for a Tag on page 67. Click OK.

Data for the X/Y tag pairs is retrieved for the specified time period and plotted in the chart. The oldest value pair appears as a triangle-shaped point, and the latest value pair as a diamond-shaped point. Tags that dont have an X axis tag assigned to them are shown in italics at the end of the tag list.
To quickly assign an X axis tag to a tag

If you dont need to configure any other tag settings, you can use the following steps to quickly assign an X axis tag to a tag that you want to display in a scatter plot (the Y axis tag).
1

Add the Y axis tag to the chart.

ActiveFactory Software Users Guide

Working with Scatter Plots

141

With the Y axis tag selected in the tag list, drag the X axis tag from the Tag Picker onto the X axis of the chart. Alternatively, use these steps:
2 1 2

Add the X and Y axis tags to the chart. In the tag list, click the X axis tags name and drag it onto the X Axis Tag column of the Y axis tag.

Scaling Tags in a Scatter Plot

Scaling tags in a scatter plot works much like scaling tags in a regular trend. For more information, see Scaling Tags on page 81. Note the following:

Scaling a tag affects the display of all tags that use it as their X axis tag. The display of all other tags remains unchanged. If you want to plot multiple tags against the same X axis tag, but with different X axis scales, you must add the X axis tag to the chart multiple times and assign each tag a different instance of the X axis tag. You can then scale the various instances of the X axis tag individually. Rubber band scaling always affects all tags in the chart. It applies to both X axis and Y axis tags. It is not possible to use rubber band scaling for a single tag. Rubber band scaling does not affect the charts time period. The scale of the X axis changes as you select different tags in the tag list. It reflects the scale of the X axis tag associated with the selected tag, or the scale of the tag itself if it doesnt have an X axis tag. The multiple scales option has no effect on the X axis. It is not possible to use cursor values as axis labels in a scatter plot. Stacking traces is not possible in a scatter plot.

Configuring Axes in a Scatter Plot

Configuring the axes of a scatter plot works much like configuring the axes of a regular trend. For more information, see Configuring Axis Properties on page 132. Note the following:

On the Axes tab of the Trend Properties dialog box, the X time axis area only applies to regular trends. For scatter plots, use the X value axis area instead.

ActiveFactory Software Users Guide

142

Chapter 3 ActiveFactory Trend

How Are Value Pairs Matched?

To plot a data point, the scatter plot must determine which Y value belongs to a given value of the X axis tag and vice versa. This is easy if there are data samples available with the same timestamp for both the X axis tag and the Y axis tag. If there is a sample available for one tag (Tag 1) at time T, but not for the other tag (Tag 2), the missing value is calculated based on the following rules:

If Tag 2 uses a curve type of Point or Step Line, then the data point uses the latest sample of Tag 2 that is earlier than T. If Tag 2 uses a curve type of Line, then the data point uses the result of a linear interpolation between the two samples of Tag 2 that surround T.

For example, assume you have the following samples available for two tags. Tag 1 uses a trace type of Step Line. Tag 2 uses a trace type of Line. A dash indicates that there is no sample at that point in time.
Time Value of Tag 1 Value of Tag 2

t1 t2 t3 t4

xt1 xt3 xt4

yt1 yt2 yt4

According to the rules above, the missing value of Tag 1 at t2 is assumed to be xt1. The missing value of Tag 2 at t3 is calculated using a linear interpolation between yt2 and yt4. If either tag has a NULL sample at a given point in time, the data point is considered empty, which may result in a gap in the curve.

ActiveFactory Software Users Guide

Working with Scatter Plots

143

Quality Calculation for Data Points

In the chart display, data points of uncertain, bad, or unknown quality are visually highlighted with special indicators. The overall quality of a data point in a scatter plot depends on the quality of the two tag values of which it is composed. The following table shows the overall quality that results from each possible combination of tag qualities, assuming that both tag values arent NULL. The top row contains the quality of the first tag, the left column contains the quality of the other tag.
Good Good Unknown Uncertain Bad Unknown Uncertain Bad

Good Unknown Uncertain Bad

Unknown Unknown Uncertain Bad

Uncertain Uncertain Uncertain Bad

Bad Bad Bad Bad

For example, if one tag has good quality and the other tag has bad quality, the data point is highlighted with the indicator for bad quality.

Panning and Zooming in a Scatter Plot

Panning and zooming affect the time period used in a chart. For a scatter plot, this means that panning or zooming moves, enlarges or reduces the time period for which data is retrieved. This may result in more or fewer data points being available for display. Depending on the nature of the data, this may or may not change the visual appearance of the chartunlike in a regular chart, where panning or zooming inevitably changes the display. To reflect this, the panning commands in the Chart menu are called Pan Earlier and Pan Later in a scatter plot, as opposed to Pan Left and Pan Right in a regular trend. However, they still work the same way. The zooming options are identical. For more information, see Panning in the Trend Chart on page 93 and Zooming on page 95.

Defining a Target Region for a Scatter Plot

Just like in a regular trend, you can configure a target region for each tag displayed in a scatter plot. For an overview of what a target region does, see Defining a Target Region for a Tag on page 70.

ActiveFactory Software Users Guide

144

Chapter 3 ActiveFactory Trend

Configuring a target region for a scatter plot tag is very similar to configuring one for a regular trend. The main difference is that the target region isnt defined by high and low boundaries at certain points in time, but by a series of X/Y value pairs. The target region is determined by connecting the X/Y points in the order they are given. For some examples, see Examples for Target Regions in Scatter Plots.
To configure a target region for a scatter plot tag 1

Follow the procedure given under To configure a target region for a trend tag on page 72. The only difference is that when importing a CSV file or pasting clipboard data, each row must contain a region item that is composed of two items instead of three. The first item is the X value, the second item is the Y value.

Examples for Target Regions in Scatter Plots

When defining a scatter plot target region, listing the same X/Y points in different order can result in very different target regions. For example, assume that you define the following X/Y points:

The resulting target region looks like this:

ActiveFactory Software Users Guide

Working with Scatter Plots

145

Because the points are connected in the order they are defined, reordering the points results in a different target region. Assume that you reorder the same points like this:

The resulting target region looks like this:

You can also create target regions with a hole in the middle. For example, use the following points:

ActiveFactory Software Users Guide

146

Chapter 3 ActiveFactory Trend

The resulting target region looks like this:

Configuring Scatter Plot Properties

You can set up a scatter plot to show time labels on the data points and use an opacity gradient for line traces to indicate the sequence of data points in time. Also, you can override the tags data retrieval settings so that full or delta mode retrieval is always used in scatter plots.
To configure scatter plot properties 1

On the Chart menu, click Properties. The Trend Properties dialog box appears.

ActiveFactory Software Users Guide

Working with Scatter Plots

147

Click the XY Scatter Plot tab.

In the Data point labeling area, configure the following options:

Type of labeling

Select Time labels on current tag to show time labels on the data points in the scatter plot. Select None if you dont want labels. The number of time labels that appear on the chart. The valid range is from 2 to 15, with a default of 6. The labels are spaced evenly over the time period between the earliest and the latest data point in the chart. (Therefore, they may not be spaced evenly in distance.)

Number of labels

ActiveFactory Software Users Guide

148

Chapter 3 ActiveFactory Trend

In the Trace gradient area, configure the following options:

Type of gradient

Select Opacity gradient if you want the opacity of the line trace in a scatter plot to change based on the timestamp of the data points that it connects. For example, the trace could be fully opaque at the most recent data point and almost transparent at the oldest data point. Select None if you want the trace to have the same opacity at all data points. The opacity of the trace at the oldest data point. 0 means transparent, 100 means fully opaque. The opacity of the trace at the most recent data point.

Starting percent Ending percent

Select the Always use Full or Delta retrieval check box if you always want to use Full or Delta mode retrieval for all tags in a scatter plot regardless of the retrieval settings that are configured at the application or tag level. Full retrieval is used when retrieving data from an IndustrialSQL Server historian with a version of 9.0 or higher. Delta retrieval is used for earlier server versions. We recommend to keep this option enabled unless the nature of your data makes full retrieval impractical. Click OK.

Other Considerations for Working with Scatter Plots

Also note the following when working with scatter plots:

Retrieval: If a tag is neither associated with an X axis tag nor acting as an X axis tag itself, no data is retrieved for it. Therefore, the data logs dont show any data for such tags. Cursors: You can work with cursors just like in a regular trend. However, the cursor commands in the View menu are called X Value Axis Cursors and Y Value Axis Cursors instead of Time Axis Cursors and Value Axis Cursors. Curve type: If a tag has a curve type of Line or Step Line, its data points are connected in chronological order. Depending on the nature of the data, changing the curve type to Point may result in a clearer display.

ActiveFactory Software Users Guide

Outputting Trend Data

149

Switching between chart types: Trend options that arent applicable to a scatter plot are disabled and/or ignored when you switch the chart type from regular trend to scatter plot. However, their values are generally retained so that they are still available if you switch the chart type back to regular trend.

Outputting Trend Data

You can output trend data to a printer, a .csv file, or to an image file, such as .bmp, .png., .jpeg, and .gif. You can also copy and paste the trend graph and associated tag list to the Windows Clipboard.

Printing Trend Data

Before you print a chart, you can specify print options and preview the printout. Use the following commands:

To set up the print page: On the File menu, click Page

Setup.

To preview the print output: On the File menu, click Print Preview. To print the chart: On the File menu, click Print.

The available options for these commands work like in any other Windows application.
Note When you print a chart, only the data that is currently displayed in the application appears in the printout. For example, if part of the tag list is not displayed in the application, then that portion does not appear in the printout.

Printing Trend Sets

A trend set is a saved grouping of trend files. You can specify a common trend duration (for example, the last 24 hours) to apply to all of the files in the set. This allows you to easily print information for the same duration from multiple trend files at the same time. Trend sets are only used for printing.

ActiveFactory Software Users Guide

150

Chapter 3 ActiveFactory Trend

Creating a Trend Set

To create a trend set 1

On the File menu, click New Trend Set. The Trend set configuration dialog box appears.

2 3 4

On the File menu, click Add. The standard Windows Open dialog box appears. Select the trend file(s) to add to the set. Click Open. The added files appear in the Trend set configuration dialog box.

ActiveFactory Software Users Guide

Outputting Trend Data

151

In the Duration list, select the time period for the trend set. The duration is applied to all of the files in the set. Data that is outside of the scope of the trend set duration is ignored. To save the trend set, on the File menu, click Save As. The standard Windows Save As dialog box appears. In the File name box, type a name for the file. Click Save.

6 7 8

Editing a Trend Set

To edit a trend set 1 2 3

On the File menu, click Open Trend Set. The standard Windows Open dialog box appears. Select the .aaTrendSet file. Click Open. The Trend set configuration dialog box appears.

4 5

Add or delete trend files as required. To exit, on the File menu, click Exit.

Deleting Files in a Trend Set

To delete a file 1 2

Select the file in the Trend files window. On the File menu, click Delete.

ActiveFactory Software Users Guide

152

Chapter 3 ActiveFactory Trend

Printing a Trend Set

To print a trend set

On the File menu, click Print. If you double-click a trend set in Windows Explorer, the trend set opens in the ActiveFactory Trend application, the associated trends are printed, and then the application closes automatically. You can also print a trend set from a command prompt by executing the trend set filename, including the extension:

aatrend /s <fully qualified filename>

To have the Trend application automatically close after the trend set is printed, omit the /s parameter.

Saving Trend Data to a .CSV File

When you save trend data, all data is exported to comma separated values (.csv) format. The .csv file includes all timestamps and values for the tags on the current trend chart at the time of the save.
To save trend data 1 2 3 4

On the File menu, click Save Data. The standard Windows Save As dialog box appears. Browse to the location in which you want to save the file. In the File name box, type a name for the trend data file.

Click Save. You can view the data in any spreadsheet application that can open .csv files. For example, Microsoft Excel.

ActiveFactory Software Users Guide

Outputting Trend Data

153

Saving the Trend Chart to an Image File

You can save a trend chart to a .bmp, .gif, .jpeg, .svg, or .png image file.
To save the trend chart 1 2 3 4 5

On the File menu, click Save Image. The standard Windows Save As dialog box appears. Browse to the location in which you want to save the file. In the File name box, type a name for the trend image file. In the Save as Type box, select an image type. Click Save.

E-mailing a Trend File

To e-mail a trend file, you must have a valid SMTP server and account configured and an e-mail application correctly installed and configured with a suitable e-mail account. When you e-mail a trend, the actual trend file (.aaTrend) is attached.
To e-mail a trend file 1

On the File menu, point to Send To and then click Mail Recipient. The e-mail program starts up and a new message appears that includes the trend file as an e-mail attachment. For example:

Use the e-mail program to send the trend file.

ActiveFactory Software Users Guide

154

Chapter 3 ActiveFactory Trend

Copying a Trend Chart to the Windows Clipboard

When you copy a trend chart, only the data that is currently displayed in the application is copied. For example, if part of the associated tag list is not displayed in the application, then that portion is not copied.
To copy a trend chart 1 2 3 4

Click in the trend chart so that it has focus. On the Edit menu, click Copy. Open the target application (for example, Microsoft Word).

Paste in the chart. The trend chart is pasted as a graphic in the target application.

Publishing Trends to the ActiveFactory Reporting Website

You can publish trends to the ActiveFactory Reporting Website. When you publish a trend, the trend report information is stored in special tables in the IndustrialSQL Server historian, and the file is copied to a folder on the ActiveFactory Reporting Website. When you publish a trend, website users can view the trend you published with only an Internet browser. Published trends are of two types:

Static. For a static trend report, website users see the same trend, but cannot alter the trend configuration in any way. They can, however, perform some basic navigation functions, like panning and zooming. On Demand. For an on demand report, website users see the same trend, but can fully manipulate the trend, including changing the configuration. However, any changes made to the original trend are not saved.

Published trend files contain the configuration information for the trend, but not the actual data values that are trended. For both types of reports, when the trend appears in the website, data is retrieved from the IndustrialSQL Server historian database and appears in the trend chart.

ActiveFactory Software Users Guide

Publishing Trends to the ActiveFactory Reporting Website

155

The ActiveFactory Reporting Website must be associated with the same IndustrialSQL Server historian as the trend you want to publish. If a trend references multiple IndustrialSQL Server historians, the ActiveFactory Reporting Website must be associated with at least one of the IndustrialSQL Server historians as the trend you want to publish.

Publishing a Static Trend Report

To publish a static trend report 1 2

Create a trend and save it as an .aaTrend file. On the File menu, point to Publish, and then click Static Trend. The Publish Report dialog box appears.

The Report name box shows the name of the trend report as it appears in the website. This name is automatically created based on the name of the file that you are publishing.
3

In the Server list, click the name of the IndustrialSQL Server historian on which to store the report publishing information. In the Report site list, select the URL of the Reporting Website to which you want to publish the trend. The reporting website may or may not be physically located on the IndustrialSQL computer.

In the Report type area, click Static.

ActiveFactory Software Users Guide

156

Chapter 3 ActiveFactory Trend

6 7

In the Folder list, click the name of the physical folder on the report site where the static report is posted. Click OK. The Report successfully published dialog box appears.

Note The ActiveFactory Reporting Website periodically scans the publishing folders for changes. A short delay may occur prior to the published report being shown in the website. 8

To view the ActiveFactory Reporting Website, click Browse. Otherwise, click Done.

Publishing a Dynamic Trend Report

To publish a dynamic trend report 1 2

Create a trend and save it as an .aaTrend file. On the File menu, point to Publish, and then click Dynamic Trend. The Publish Report dialog box appears.

The Report name box shows the name of the trend report as it appears in the website. This name is automatically created based on the name of the file that you are publishing.
3

In the Server list, click the name of the IndustrialSQL Server historian on which to store the report publishing information.

ActiveFactory Software Users Guide

Using Trend with a Tablet PC

157

In the Report site list, select the URL of the ActiveFactory Reporting Website to which you want to publish the trend. The report site may or may not be physically located on the IndustrialSQL computer.

5 6 7

In the Report type area, click On demand. In the Report group list, click the name of the physical folder on the report site where the static report is posted. In the Lockdown options area, select the check boxes for the functionality you want to allow in the published trend report. For example, if you want website users to be able to change the report using the Tag Picker, select the Show tagpicker check box.

Click OK. The Report successfully published dialog box appears.

Note The ActiveFactory Reporting Website periodically scans the publishing folders for changes. A short delay may occur prior to the published report being shown in the website. 9

To view the ActiveFactory Reporting Website, click Browse. Otherwise, click Done.

Using Trend with a Tablet PC

When you run the Trend application on a Tablet PC, you can capture an image of the application window or the chart area, annotate the image using various drawing tools, and save, print or e-mail the results.

Annotating a Chart
To annotate a chart or the application window 1 2

Create a trend chart. On the Tools menu, click Annotate Chart or Annotate Application. The Annotate Layout dialog box appears.

ActiveFactory Software Users Guide

158

Chapter 3 ActiveFactory Trend

Use the stylus to write annotations on the image. For more information, see Making Chart Annotations.

Save or e-mail the file. For more information, see Saving, Printing and E-Mailing an Annotated Chart on page 159.

Making Chart Annotations

To make annotations to the chart, use the following tools:

Pen: To draw and write comments. Highlighter: To highlight areas of the chart using a semi-transparent color. Eraser: To delete parts of an annotation.

Each of these tools has certain options such as size, color, or transparency.

To set these options, click the downward arrow next to each tools icon and then click the command for the option. To restore these options to their default settings, on the Tools menu, click Restore Defaults.

ActiveFactory Software Users Guide

Using Trend with a Tablet PC

159

Selecting, Copying and Deleting Chart Annotations

To select annotations 1 2

Click the Lasso icon in the toolbar. While holding down the stylus button, draw an area around the annotation(s) that you want to select. You can now cut, copy or delete the selected annotations.

To cut, copy, and paste annotations

Use the standard Windows Cut, Copy, and Paste commands.

To delete annotations

Do one of the following: To delete all annotations on a chart, on the Edit menu, point to Clear and then click All.

To delete annotations that you selected using the lasso, on the Edit menu, point to Clear and then click Selection.

Saving, Printing and E-Mailing an Annotated Chart

Once you have made annotations to a chart, you can save it as an image file, print it, or e-mail it.
To save an annotated chart 1 2

On the File menu, click Save. A standard Windows Save As dialog box appears. Enter a name and format for the file and click OK.

To print an annotated chart 1 2

On the File menu, click Print. A standard Windows Print dialog box appears. Specify any printing options and click OK.

To e-mail an annotated chart Note You only need to configure the e-mail server one time. If you have already done this, go to step 3. 3

On the Edit menu, click E-Mail Configuration. The E-Mail Configuration dialog box appears.

ActiveFactory Software Users Guide

160

Chapter 3 ActiveFactory Trend

Enter the host name of the SMTP e-mail server to use for sending e-mail. If you are unsure, ask your administrator for assistance. Click OK. On the File menu, click E-Mail. The New Message dialog box appears. Enter sender and recipient addresses and write a message. An image file of the annotated trend is automatically added as an attachment. Click Send to send the e-mail.

5 6

Importing .CRV Data

You can import data from a .crv file and display it in the trend chart. This allows you to migrate trend files from versions before ActiveFactory 9.0 software.
To import .crv data 1 2

On the Tools menu, click Import. The Open dialog box appears. Select the .crv file to open and then click Open.

ActiveFactory Software Users Guide

161

Chapter 4
ActiveFactory Query

Query is a client application that allows you to retrieve data from an IndustrialSQL Server historian database or any SQL Server database and return the results in a table format. If you are querying the IndustrialSQL Server historian database, you can choose from a number of predefined query types and easily select the options for each type, eliminating the need to know SQL syntax. The SQL query is created for you. You can also write custom queries if you know SQL syntax and the schema of database you are using.

Getting Started with Query

When you start up the Query application, you are immediately prompted to connect to the server. However, if you are opening an existing Query file that includes at least one server configuration and the log in was successful, you are not prompted to log in. For more information, see Server Connection Configuration on page 39.

ActiveFactory Software Users Guide

162

Chapter 4 ActiveFactory Query

After you establish a connection with the server, the Query program appears, showing the main window:
Main Toolbar Tag Picker Query Toolbar Columns Pane

Status Bar

Results Pane

The Query application user interface consists of the following components:

Main Toolbar Query Toolbar Tag Picker (may not appear depending on the query type) Columns Pane Results Pane Status Bar

For information on using the common toolbars and the Tag Picker, see Chapter 2, Common Client Components.

ActiveFactory Software Users Guide

Getting Started with Query

163

Query Toolbar
Use the query toolbar to select the query type, server and database for the query. The Servers list contains the list of connected servers. The Database list is only available if the query type is Custom.

Columns Pane
Use the Columns pane to select details for the query.

Results Pane
Use the Results pane to view the results of the query that you have created. The Results pane includes three tabs:
SQL tab Data tab All Queries tab

ActiveFactory Software Users Guide

164

Chapter 4 ActiveFactory Query

The SQL tab shows the actual SQL statement that is sent to the server.

The Data tab shows the data returned by the SQL statement.

ActiveFactory Software Users Guide

Working with Query Files

165

The All queries tab shows all of the SQL statements that have been created for the selected tag type for the current query. By default, this tab is not shown. To show it, click All queries on the Options menu.

Status Bar
The right side of the status bar shows the status of the IndustrialSQL Server historian. If the Data tab in the Results pane is selected, then the number of rows of result data is also shown in the status bar. For more information on the status bar, see Status Bar on page 50.

Working with Query Files

This section describes how to open and save query files. A query file contains all of the configuration data required to execute a SQL statement against the server.

ActiveFactory Software Users Guide

166

Chapter 4 ActiveFactory Query

Opening an Existing Query File

To open an existing query 1

Do one of the following: On the File menu, click Open.

Click the Open File toolbar button.

The standard Windows Open dialog box appears.

2 3

Browse to and select the query file to open. All query files have the .sql extension. Click Open.

Saving a Query File

The contents of a saved query file depends on which tab is currently selected in the Results pane. If you select the SQL tab or All queries tab, you can save the contents of the tab (the SQL statement) with either an .sql or .txt extension. If you select the Data tab, you can save the contents of this tab (the query results) with either an .csv or .txt extension. The .csv file conforms to the locale settings of the computer and the dates are localized.
To save a query 1

Do one of the following: On the File menu, click Save.

Click the Save File toolbar button.

The standard Windows Save As dialog box appears.

In the Save As dialog box, type a name for the query. You can select to save the query as a SQL script file (the default) or as a text file.

Click OK.

Creating a Query
When you configure a query, you must select the tag or tags for which you want to retrieve data, the type of query, and the server(s) from which to retrieve the data. The data is queried from the database to which you are currently logged on. You can also configure additional parameters that are specific to each query type. There is no limit to the number of tags in a query; you can include as many as your system allows.

ActiveFactory Software Users Guide

Creating a Query

167

To create a query 1

In the Query type list in the toolbar, click the name of the type of query you want to use as a starting point. For more information on the possible types, see Query Types on page 168. In the Server list, click the name of the server from which you want to retrieve data. Use the Tag Picker to find tags in the IndustrialSQL Server historian database that you want to include in your query. For more information on the Tag Picker, see Tag Picker on page 51.

2 3

In the Columns pane, click on each tab and configure the details for the query. The tabs that appear depend on what query type you have selected. For more information on configuring the details for a particular query type, see Query Types on page 168. In the Results pane, click the Data tab to view the resulting data.

Note You do not have to execute the query. The Query application automatically executes the query once you switch to the Data tab, or if you make any changes while the Data tab is shown.

ActiveFactory Software Users Guide

168

Chapter 4 ActiveFactory Query

Query Types
The following types of queries are supported. For each query type, a set of relevant tabs appears in the Columns pane so that you can configure the details for the query. Some of the tabs are the same for multiple query types.

Query Type: Aggregate Values Query Type: Alarm History Query Type: Alarm Limits Query Type: Annotations Query Type: Custom Query Type: Event History Values Query Type: Event Snapshot Query Type: Favorites Query Type: History Values Query Type: IO Server Query Type: Live Values Query Type: Number of Tags Query Type: Server Version Query Type: Storage Query Type: Storage Size Available Query Type: Storage Start Date Query Type: Summary Values Query Type: Tag Details Query Type: Tag Search Query Type: Time Running

Query Type: Aggregate Values

You can view aggregated values for specified tags. Aggregations supported are count, minimum, maximum, sum, average, and standard deviation. Aggregations are calculated using the standard SQL Server aggregation functions. To retrieve aggregated values from the IndustrialSQL Server historians summary tables, use the Summary Values query type. For more information, see Query Type: Summary Values on page 189.

ActiveFactory Software Users Guide

Query Types

169

To view aggregate values 1 2 3

In the Query Type list in the toolbar, click Aggregate values. Use the Tag Picker to select one or more tags. In the Columns pane, click on each tab and configure the parameters for the query. See Format Tab on page 196.

See Time Tab on page 195. See Criteria Tab on page 169. See Calculations Tab on page 170. See Retrieval Tab on page 197. See Source Tab on page 198.

To view the results, click the Data tab in the Results pane.

Criteria Tab
Use the Criteria tab to specify the filtering criteria for the data value(s) to be returned.

To configure value criteria 1

To configure criteria for a discrete tag, select the first Value check box and set the criteria to be either a 1 or a 0. Skip to Step 4. To configure criteria for an analog tag:
a

Select the first Value check box and set the criteria for the data value. For example, the value must be greater than ( > ) 1500.

ActiveFactory Software Users Guide

170

Chapter 4 ActiveFactory Query

(Optional) Select the second Value check box and set another criteria for the data value. For example, the value must be less than ( < ) 2000. Skip to Step 4.

c 3 4

(Optional) Select the Value not null check box to filter out NULL values from the results. (Optional) In the Quality list, click the quality criteria for the data. Only data values that match the quality you specify (Good, Bad, Doubtful) are returned. (Optional) In the Criteria applicability list, select the moment at which the edge detection criteria is met. first true: Returns only rows that are the first to successfully meet the criteria (return true) after a row did not successfully meet the criteria (returned false). This is also known as leading edge detection.
no longer true: Returns only rows that are the first to

fail the criteria (return false) after a row successfully met the criteria (returned true). This is also known as trailing edge detection.
true: Returns all rows that successfully meet the

criteria; no edge detection is implemented at the specified resolution.

first true or no longer true: All rows satisfying both

the leading and trailing conditions are returned.

Calculations Tab
Use the Calculations tab to configure the aggregations to perform on the values for the selected tag(s).

Display calculated values for each tag separately: If

selected, one row of calculated values is returned for each tag. If this check box is not selected, then all values for all specified tags are included for a single aggregation.
Count: The total number of values for the tag. Minimum: The minimum value for the tag. Maximum: The maximum value for the tag. Average: The average value for the tag.

ActiveFactory Software Users Guide

Query Types

171

Sum: The sum of all values for the tag. Standard deviation: The statistical standard deviation of

all values for the tag.

Decimal places: The number of decimal places to display

for the data value. This applies only to analog tags.

Query Type: Alarm History

You can query the database to return the alarm history for a tag. You can further scope the query to only return the tag values that are beyond an alarm limit. For example, if the Hi alarm limit for the ReactLevel tag is 1800, the alarm history can include all values that were above 1800 Hi limit.
To view alarm history 1 2

In the Query Type list in the toolbar, click Alarm history. If you want to only retrieve alarm history for particular tag(s), use the Tag Picker to select one or more tags. For example, if you want to search for alarm history for all analog tags, select the All Analog Tags public group and then select all analog tags in the Tags pane. In the Columns pane, click on each tab and configure the parameters for the query: See Columns tab on page 172.

See Time Tab on page 195. See Alarm Limits tab on page 173. See Retrieval Tab on page 197. See Source Tab on page 198. See Order Tab on page 199.

To view the results, click the Data tab in the Results pane.

ActiveFactory Software Users Guide

172

Chapter 4 ActiveFactory Query

Columns tab
Use the Columns tab to configure the columns that are returned for the results.

Options are as follows:

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Description: The description of the tag. Decimal places: The number of decimal places to display

for the data value. This applies only to analog tags.

Date and time: The timestamp for the returned value. For

delta retrieval, this is typically the time at which the value was acquired by the IndustrialSQL Server. For cyclic retrieval, this is the specific time requested or calculated (using a SQL function).
Include milliseconds: Used to include milliseconds in the

timestamp.
Quality: The basic data quality indicator associated with the data value. Quality detail: The internal representation of data

quality.
Quality description: The text string that describes what

the quality detail value means.

OPC Quality: The quality value received from the data

source.

ActiveFactory Software Users Guide

Query Types

173

Alarm Limits tab

Use the Alarm Limits tab to filter the alarm history values.

To configure alarm limits 1 2

Select the Use alarm limits check box to filter the alarm history according to a selected limit. In the Context list, click the name of the context to which the alarm limit belongs. For example, the alarm limit can be valid within the context of an InTouch application. In the table, select the row that contains the limit you want to apply. The columns in the window are: TagName: The unique name of the tag within the IndustrialSQL Server system.
Name: The name for the limit. Value: The value that is used as a specific limit for a

tag. In theory, a tag can have an infinite number of limits defined.

Unit: The unit of measure. Examples are mph, grams,

and pounds.
LimitType: The type of limit; that is, whether it is a

rising (up) or falling (down) limit. 0 = Rising; 1 = Falling.

4 5

Select the Value not null check box to only return values that are not NULL. In the Quality list, select the type of quality for which you want to return results. Quality values are Good (0), Bad (1), Doubtful (16). If you do not want to filter on quality, select Not used.

ActiveFactory Software Users Guide

174

Chapter 4 ActiveFactory Query

Query Type: Alarm Limits

You can view the alarm limits for a tag. For example, the Hi or Lo alarm limit for an analog tag.
To view alarm limits 1 2 3

In the Query Type list in the toolbar, click Alarm limits. If you want to only retrieve annotations for particular tag(s), use the Tag Picker to select one or more tags. In the Columns pane, click the Alarm limits tab.

4 5

Select the Ordered by tag name check box to order the results in alphabetical order by tagname. To view the results, click the Data tab in the Results pane.

The columns in the result set are as follows:

TagName: The unique name of the tag within the

IndustrialSQL Server system.

Name: The name for the limit. Value: The value that is used as a specific limit for a

tag. In theory, a tag can have an infinite number of limits defined.

Unit: The unit of measure. Examples are mph, grams,

and pounds.

Query Type: Annotations

You can view annotations that were made by database users regarding data values of tags.
To view annotations 1 2

In the Query Type list in the toolbar, click Annotations. If you want to only retrieve annotations for particular tag(s), use the Tag Picker to select one or more tags. For example, if you want to search for annotations for all analog tags, select the All Analog Tags public group and then select all analog tags in the Tags pane.

ActiveFactory Software Users Guide

Query Types

175

In the Columns pane, click on each tab and configure the parameters for the query: See Criteria Tab on page 175.

See Time Tab on page 195.

To view the results, click the Data tab in the Results pane.

Criteria Tab
Use the Criteria tab to specify the type of annotations to be retrieved and which columns to show in the results. The Tagname column always appears.

To configure the annotation criteria 1

Select the columns to show in the results: Date and time: The timestamp of the tag value for which the user has made an annotation.
Date created: The date that the annotation was

created.
Content: The annotation text. User name: The name of the database user.

Select the type of annotations to show: Public: Show only public annotations. You can see your private annotations and the public annotations of other IndustrialSQL Server historian users.
All users: Show both public and private annotations.

You can see your private annotations, as well as both the public annotations and private annotations of others.
All tags on server: Show all annotations for all tags.

ActiveFactory Software Users Guide

176

Chapter 4 ActiveFactory Query

Query Type: Custom

You can write custom SQL queries to execute against the database.
To create a custom query 1 2 3

In the Query Type list in the toolbar, click Custom. In the Results pane, type the SQL query in the SQL tab.

To view the results, click the Data tab in the Results pane. You can use the Custom query type to retrieve data from any database. For example, the following query retrieves from the Northwind database the list of employees who live in London. (The Northwind database is a sample database that is shipped with Microsoft SQL Server.)
USE Northwind SELECT * FROM Employees

WHERE City = 'London'

Query Type: Event History Values

You can view all the events that occurred for specified event tags.
To view event history 1 2 3

In the Query Type list in the toolbar, click Event history. Use the Tag Picker to select one or more event tags. In the Columns pane, click on each tab and configure the parameters for the query. See Columns Tab on page 177.

See Time Tab on page 195. See Order Tab on page 199.

To view the results, click the Data tab in the Results pane.

ActiveFactory Software Users Guide

Query Types

177

Columns Tab
Use the Columns tab to configure the columns to show in the results.

To configure the columns 1

event history data was acquired. This is the time for when the event actually occurred.
2 Include milliseconds: Used to include milliseconds in

the timestamp.
Detect date time: The timestamp reflecting when the

event was detected by the event system. Configure how to filter the results: Limit to XX rows: The number of intial consecutive rows to return out of the total number of rows in the record set, starting with the first row in the record set. For example, if there are a total of 150 rows, and you set this value to 100, only the first 100 rows in the records set will be returned.

Query Type: Event Snapshot

You can view the data values for selected analog, discrete, or string tags that have the same timestamp as a detected event. This provides you with a snapshot of selected data values at the time of an event.
To view event snapshot information 1 2 3

In the Query Type list in the toolbar, click Event snapshot. Use the Tag Picker to select one or more event tags that have a snapshot event action. In the Columns pane, click on each tab and configure the parameters for the query.

ActiveFactory Software Users Guide

178

Chapter 4 ActiveFactory Query

See Tag Set Tab on page 178. See Columns Tab on page 178. See Time Tab on page 195. See Order Tab on page 199.

To view the results, click the Data tab in the Results pane.

Tag Set Tab

Use the Tag Set tab to select the tag(s) for which the data values are stored as a snapshot. (This is not the event tag.)

To configure the tag set 1

In the Snapshot tag type list, click the type of snapshot, either Analog, Discrete, or String. The Snapshot tags window shows all of the snapshot tags for the type you have selected. In the Snapshot tags window, select the snapshot tag.

Columns Tab
Use the Columns tab to configure the columns to show in the results.

ActiveFactory Software Users Guide

Query Types

179

To configure the columns 1

Select the columns to show in the results: Tag name: The unique name of the tag within the IndustrialSQL Server system.
Description: The description of the tag. Date and time: The timestamp for the returned value. For delta retrieval, this is typically the time at which the value was acquired by the IndustrialSQL Server. For cyclic retrieval, this is the specific time requested or calculated (using a SQL function). Include milliseconds: Used to include milliseconds in

the timestamp.
Decimal places: The number of decimal places to

display for the data value. This applies only to analog tags.
2 Detect date time: The timestamp reflecting when the

event was detected by the event system.

Quality: The basic data quality indicator associated with the data value. Quality detail: The internal representation of data

quality.
Quality description: The text string that describes

what the quality detail value means. Configure how to filter the results: Limit to XX rows: The number of intial consecutive rows to return out of the total number of rows in the record set, starting with the first row in the record set. For example, if there are a total of 150 rows, and you set this value to 100, only the first 100 rows in the records set will be returned.
Quality: The type of quality for which you want to return results. Quality values are Good (0), Bad (1), Doubtful (16). If you do not want to filter on quality, select Not used.

ActiveFactory Software Users Guide

180

Chapter 4 ActiveFactory Query

Query Type: Favorites

You can load a saved SQL query file (.sql) and execute it against the database.
To execute a saved query 1 2 3

In the Query Type list in the toolbar, click Favorites. In the Columns pane, click the Favorites tab. In the Favorite queries folder box, type the path to the query file. To browse to the folder, click the ellipsis button.

All .sql files in the folder appear in the Favorite queries window.
4 5 6

Select the query to execute in the window. To view the query, click the SQL tab in the Results pane. To view the results, click the Data tab in the Results pane.

Query Type: History Values

You can retrieve history data for specified tags. You can retrieve data for multiple types of tags in the same query. However, if you want to use a string value criterion, you can only retrieve string tags in the query. For more information, see Criteria Tab on page 183.
To view history data 1 2 3

In the Query Type list in the toolbar, click History values. Use the Tag Picker to select one or more tags. In the Columns pane, click on each tab and configure the parameters for the query. See Columns Tab on page 181.

See Time Tab on page 195. See Format Tab on page 196. See Criteria Tab on page 183. See Retrieval Tab on page 184. See Source Tab on page 198.

ActiveFactory Software Users Guide

Query Types

181

See Order Tab on page 199.

To view the results, click the Data tab in the Results pane.

Columns Tab
Use the Columns tab to configure the columns to show in the results. The Value (numeric value) and vValue (string value) columns are always shown.

Note Some of the columns are not available when you select Wide query format on the Format tab.

Options are as follows:

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Description: The description of the tag. Decimal places: The number of decimal places to display

for the data value. This applies only to analog tags.

Date and time: The timestamp for the returned value. For delta retrieval, this is typically the time at which the value was acquired by the IndustrialSQL Server. For cyclic retrieval, this is the specific time requested or calculated (using a SQL function). Include milliseconds: Used to include milliseconds in the

timestamp.
Quality: The basic data quality indicator associated with

the data value.

ActiveFactory Software Users Guide

182

Chapter 4 ActiveFactory Query

Quality description: The text string that describes what

the quality detail value means.

OPC Quality: The quality value received from the data

source.
State time: The time that the tag spent in the specified

value state (when using ValueState retrieval).

wwStateCalc: The state calculation type used to calculate

the state time when using ValueState retrieval (for example, average time or total time). For more information, see State Calculation on page 683.
wwRetrievalMode: The retrieval mode used for the tag. For more information, see Understanding Retrieval Modes on page 649. wwCycleCount: The cycle count used in data retrieval. For more information, see Cycle Count (X Values over Equal Time Intervals) on page 674. wwTimeDeadband: The time deadband used in data

retrieval. For more information, see Time Deadband on page 676.

wwTimeStampRule: The timestamp rule used in data

retrieval. For more information, see Timestamp Rule on page 680.

wwVersion: The history version of the value. For more

information, see History Version on page 678.

wwEdgeDetection: The type of edge detection used in the

query.
wwTagKey: The unique identifier of the tag on the IndustrialSQL Server historian. wwInterpolationType: The interpolation type used to

calculate the value. For more information, see Interpolation Type on page 678.
wwResolution: The resolution used in data retrieval. For

more information, see Resolution (Values Spaced Every X ms) on page 675.
wwValueDeadband: The value deadband used in data

retrieval. For more information, see Value Deadband on page 677.

wwQualityRule: The quality rule used in data retrieval.

For more information, see Quality Rule on page 682.

ActiveFactory Software Users Guide

Query Types

183

wwTimeZone: The time zone that the values timestamp

refers to.
PercentGood: The percentage of rows with good quality in

relation to the total number of rows in the retrieval cycle.

Criteria Tab
Use the Criteria tab to specify the filtering criteria for the data value(s) to be returned.

To configure value criteria 1

To configure criteria for a discrete tag, select the first Value check box and set the criteria to be either a 1 or a 0. Skip to Step 5. To configure criteria for an analog tag:
a

c 3

To configure criteria for a string tag:

Note If you use a string criterion, you can only retrieve data for string tags in the query. No data is returned for tags of other types that you may have selected. This is due to a limitation in the IndustrialSQL Server historian. a a

Select the Use StringHistory check box. Select the third Value check box and specify text that the returned string value must match. You can specify whether the returned value must equal, start, end, or contain the specified text. For example, you can specify that the value must contain the text alert. Skip to Step 5.

ActiveFactory Software Users Guide

184

Chapter 4 ActiveFactory Query

4 5

fail the criteria (return false) after a row successfully met the criteria (returned true). This is also known as trailing edge detection.
true: Returns all rows that successfully meet the

criteria; no edge detection is implemented at the specified resolution.

first true or are no longer true: All rows satisfying

both the leading and trailing conditions are returned.

Retrieval Tab
Use the Retrieval tab to configure data retrieval options.

For an explanation of the retrieval options, see Understanding Retrieval Modes on page 649 and Understanding Retrieval Options on page 673.

ActiveFactory Software Users Guide

Query Types

185

Query Type: IO Server

You can retrieve basic configuration information for all I/O Servers configured for use with the IndustrialSQL Server historian.
To retrieve I/O Server information 1 2

In the Query Type list in the toolbar, click IO server. In the Columns pane, click the IO Server tab.

Select the columns to show in the results: Description: The description of the I/O Server.
Application name: The application name of the I/O Server. This name is usually the same as the executable file name. Topic name: The name of the topic. Topic timeout: The time span, in milliseconds, in which a data point must be received on the topic. If no data point is received in this time span, the topic will be considered "dead." The IndustrialSQL Server will disconnect and then attempt to reconnect to the topic.

4 5

In the Computer list, click the name of the computer on which the I/O Servers run. To view the results, click the Data tab in the Results pane.

ActiveFactory Software Users Guide

186

Chapter 4 ActiveFactory Query

Query Type: Live Values

You can retrieve real-time data values for specified tags.
To view live data 1 2 3

In the Query Type list in the toolbar, click Live values. Use the Tag Picker to select one or more tags. In the Columns pane, click on each tab and configure the parameters for the query. See Columns Tab on page 186.

See Time Tab on page 195.

To view the results, click the Data tab in the Results pane.

Columns Tab
Use the Columns tab to configure the columns to show in the results.

Options are as follows:

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Description: The description of the tag. Decimal places: The number of decimal places to display

for the data value. This applies only to analog tags.

Date and time: The timestamp for the returned value. For

timestamp.
Quality: The basic data quality indicator associated with

the data value.

ActiveFactory Software Users Guide

Query Types

187

Quality description: The text string that describes what

the quality detail value means.

OPC Quality: The quality value received from the data

source.

Query Type: Number of Tags

You can retrieve the total number of tags of a certain type for the currently selected IndustrialSQL Server historian.
To retrieve the number of tags 1 2

In the Query Type list in the toolbar, click Number of tags. In the Columns pane, click the Count tab.

3 4

In the Tag type list, click the type of tag for which you want to return the total number. To view the results, click the Data tab in the Results pane.

Query Type: Server Version

You can retrieve the version number for the currently selected IndustrialSQL Server historian.
To retrieve the server version 1 2

In the Query Type list in the toolbar, click Server version. To view the results, click the Data tab in the Results pane.

Query Type: Storage

You can retrieve configuration information regarding the directories in which a selected IndustrialSQL Server historian is storing history files. The different storage types are circular, alternate, buffer, and permanent.
To retrieve storage information 1

In the Query Type list in the toolbar, click Storage.

ActiveFactory Software Users Guide

188

Chapter 4 ActiveFactory Query

In the Columns pane, click the Storage tab.

Select the columns to show in the results: Path: The path to the storage location. The circular storage location must be a local drive on the server machine, and the path must be specified using normal drive letter notation (for example, c:\InSQL\Data\Circular). The alternate, buffer, and permanent storage locations can be anywhere on the network, provided that the IndustrialSQL Server service user has full access to those network locations. For the Windows 2000 operating system, remote storage locations may be specified either as mapped drives or by using UNC notation. For the Windows Server 2003 operating system, the locations must be specified using UNC notation.
Maximum storage size: The limit, in megabytes, for the

amount of data that will be stored to the specified location. The maximum size applies to circular and alternate storage only. If the maximum size is set to 0, all available space at the storage location will be used.
Minimum storage size threshold: The minimum amount of disk space, in megabytes, at which the system will attempt to start freeing up space. The threshold applies to circular and alternate storage only. Typically, the minimum threshold should be the size of the average history block (before any compression) multiplied by 1.5.

4 5

In the and computer list, click the name of the computer on which the storage node resides. To view the results, click the Data tab in the Results pane.

The Storage Type column always appears.

ActiveFactory Software Users Guide

Query Types

189

Query Type: Storage Size Available

You can retrieve the amount of space, in MB, that remains for each of the storage locations. The amount of space remaining is monitored by system tags on the server.
To retrieve the storage size 1 2

In the Query Type list in the toolbar, click Storage Size. To view the results, click the Data tab in the Results pane.

Query Type: Storage Start Date

You can retrieve the start date for the oldest history block in the system.
To retrieve the storage start date 1 2

In the Query Type list in the toolbar, click Storage Start Date. To view the results, click the Data tab in the Results pane.

Query Type: Summary Values

You can view the summarized values of specified tags as calculated by the event system. To view aggregated data as calculated by the standard SQL Server aggregation functions, use the Aggregate Values query type. For more information, see Query Type: Aggregate Values on page 168.
To view summary values 1 2 3

In the Query Type list in the toolbar, click Summary values. Use the Tag Picker to select one or more tags. In the Columns pane, click on each tab and configure the parameters for the query. See Columns Tab on page 190. See Time Tab on page 195. See Calculations Tab on page 191. See Order Tab on page 199. To view the results, click the Data tab in the Results pane.

ActiveFactory Software Users Guide

190

Chapter 4 ActiveFactory Query

Columns Tab
Use the Columns tab to select which columns to include in the query results.

Options are as follows:

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Description: The description of the tag. Decimal places: The number of decimal places to display

for the data value. This applies only to analog tags.

Date and time: The date applicable to the results of the

calculation. It is either the time of the beginning or end of the calculation period, as specified by the summary operation definition.
Include milliseconds: Used to include milliseconds in the

timestamp.
Quality: The basic data quality indicator associated with the data value. Resolution: The sampling rate, in milliseconds, for

retrieving the data in cyclic mode. The system will return values stored over the requested time period at the interval specified by the resolution. For example, if you specify a 5000 ms resolution, the system will query for all data during the time period and then only return those values that occur at each 5000 ms interval, starting with the start date and ending with the end date.
Timestamp: The timestamp used when storing the result

of the calculation. This can either be the time of when the calculation period starts or the time when it ends.
Event tag: The unique name of the tag within the

IndustrialSQL Server system.

ActiveFactory Software Users Guide

Query Types

191

Calculations Tab
Use the Calculations tab to specify which calculated values to retrieve from the database.

In the Limit to XX rows list, specify the number of intial consecutive rows to return out of the total number of rows in the record set, starting with the first row in the record set. For example, if there are a total of 150 rows, and you set this value to 100, only the first 100 rows in the records set will be returned. In the Calculation type list, click the type of calculation: Sum, Maximum, Minimum, or Average. In the Calculation frequency list, click the period, in seconds, for which the calculation is performed. Select the Show check boxes to show the calculation type and/or frequency in the result set.

2 3 4

Query Type: Tag Details

You can view the configuration details for specified tags.
To view tag details 1 2 3

In the Query Type list in the toolbar, click Tag details. Use the Tag Picker to select one or more tags. In the Columns pane, click on the Columns tab.

Select which columns to include in the query results. The options that are available in this tab depend upon the type of tag you have selected. For example, a detector type only applies to event tags. The Tagname column is always shown.

ActiveFactory Software Users Guide

192

Chapter 4 ActiveFactory Query

Description: The description of the tag. Date created: The date that the tag was created. Address: The tag address, which is made up of the

application name of the I/O Server, the name of the topic, and the address string of the tag.
Storage rate: The rate at which the tag is stored if the storage type is cyclic. Acquisition rate: For polled tags of acquisition type 1,

the poll rate in milliseconds.

Storage type: The type of storage defined for the tag. 0 = Not stored; 1 = Cyclic; 2 = Delta; 17 = The storage type has been changed from cyclic to "not stored." 18 = The storage type has been changed from delta to "not stored." Acquisition type: The method by which the tag's value

is acquired. If the tag value is acquired from an I/O Server, the name of the I/O Server, topic, and item must be specified. 0 = Not acquired; 1 = Acquired via an I/O Server; 2 = Acquired via MDAS or a manual update; 3 = System driver.
Messages: The message associated with the FALSE

state of the discrete tag. A discrete tag set to 0 is in the FALSE state. Also, the message associated with the TRUE state of the discrete tag. A discrete tag set to 1 is in the TRUE state.
Maximum characters: The maximum number of

characters for the string.

Raw value range: The minimum value of the raw acquired value. Also, the maximum value of the raw acquired value. Engineering units: The unit of measure. Examples are

mph, grams, and pounds.

Engineering units range: The minimum value of the

tag, measured in engineering units. Also, the maximum value of the tag, measured in engineering units.
Detector type: The name given to the type of detector. Action type: The name given to the type of action. Detector string: The script that contains the criteria

for event detection. Detector scripts are executed on the local IndustrialSQL Server.
Action string: The script that specifies the event

action. Action scripts are executed on the local IndustrialSQL Server.

ActiveFactory Software Users Guide

Query Types

193

Scan rate: The interval, in milliseconds, at which the

system will check to see if the event conditions specified by the detector have occurred. This value must be greater than or equal to 500 milliseconds, and less than or equal to 1 hour (3600000 ms).
Status: The flag used by the event system at system

startup and during runtime to determine if the event tag has been modified. 0 = Posted. Any changes have been detected and effected by the system. 1 = New. An event tag has been inserted, but is not yet executing. 2 = Modification. An event tag has been updated, but the older one is already executing. 98 = Disabled. 99 = Disabling requested. The event tag does not execute, even though the definition still exists in the schema. Note that there may be a delay of up to 30 seconds before a change in an event tag is seen by the running system.
Logged: Used to specify whether or not to log events

for this tag into the EventHistory table. Event logging can only be turned off if no associated actions are configured.
5

To view the results, click the Data tab in the Results pane.

Query Type: Tag Search

You can search for tags by name or criteria for the names.
To search for tags 1 2

In the Query Type list in the toolbar, click Tag search. In the Tag Picker, select the type of tag that you want to search for. For example, if you want to search for an analog tag, select the All Analog Tags public group. In the Columns pane, click on the tab and configure the parameters for the query: See Search Tab on page 194.

ActiveFactory Software Users Guide

194

Chapter 4 ActiveFactory Query

To view the results, click the Data tab in the Results pane.

Search Tab
Use the Search tab to search for a tag in the database.

1 2

In the Tag type list, click the type of tag to search for, either Analog, Discrete, Event, String, or Summary. For summary tags, further restrict the search by specifying a particular calculation type or frequency. Calculation type: The type of calculation: Sum, Maximum, Minimum, or Average.
Calculation frequency: The period, in seconds, for

which the calculation is performed.

Select the Show check boxes to show the calculation type and/or frequency in the result set.

ActiveFactory Software Users Guide

Query Types

195

Query Type: Time Running

You can retrieve the amount of time, in minutes, that the IndustrialSQL Server historian has been running since the last startup.
To retrieve the time 1 2

In the Query Type list in the toolbar, click Time running. To view the results, click the Data tab in the Results pane.

Common Tabs for Query Types

This section describes the configuration tabs that are common to multiple query types.

Time Tab
Use the Time tab to specify the time options for the query.

The grid shows the time zone and daylight savings time settings for the following entities:
Entity Description

Application

The ActiveFactory Query client application. The timestamps of the returned data reflect this time zone. To change this time zone, see the procedure below. The client computer on which the Query application is installed. The IndustrialSQL Server historian to which the Query application is currently connected. You can be connected to more than one server.

Client <ServerName>

ActiveFactory Software Users Guide

196

Chapter 4 ActiveFactory Query

To configure the time period and time zone 1

In the Time area, use the time picker to select the start and end times for the query. For more information, see Time Picker on page 58. To return the data with a timestamp that reflects the time zone setting of the IndustrialSQL Server historian, select the Use time zone of the server check box.

To return the data with a timestamp that reflects a time zone setting, different than that of the local client computer, click the name of the appropriate time zone to use in the Time Zone list. For example, consider a SCADA application that monitors a pipeline between Houston, Texas and Lake Forest, California. The Query application is installed on a computer in Houston, Texas. You want to send a query file to an engineer located at the start of the pipeline in Lake Forest to aid in troubleshooting a problem. You can set the time zone of the Query application to reflect the time of Lake Forest, California (Pacific Standard Time), so that the query that you send to the engineer displays data in a time zone that is relevant to him/her.

Format Tab
Use the Format tab to specify how the results of the query are presented.

Options are as follows:

Narrow query format: In this format, there is one row for a single tag's value for a particular timestamp. Wide query format: In this format, there is one row for one

or more tag values for a single timestamp, thus providing a "wide" view of the data. To use the wide query format, you must specify the timestamp and one or more tagnames as the column names in the query syntax. The results will contain a column for the timestamp and columns for the value of each specified tag at that timestamp.

ActiveFactory Software Users Guide

Query Types

197

Retrieval Tab
Use the Retrieval tab to specify the granularity of the data to be returned.

To configure the retrieval mode 1

In the Mode area, select the retrieval mode. Cyclic: Cyclic based retrieval is the retrieval of stored data for the given time period based on a specified cyclic retrieval resolution, regardless of whether or not the value of the tag(s) has changed.
Delta: Delta retrieval, or retrieval based on exception,

is the retrieval of only the changed tag values for a tag(s) for the given time interval. That is, duplicate values are not returned.
2

If you selected the cyclic retrieval mode, configure additional options in the Cyclic area. XX values over equal time intervals: The number of rows to be returned for a specified time period. For cyclic retrieval, the rows are spaced evenly across the time period, and the default row count is 100 rows. For cyclic retrieval, the row count is applied for each tag in a query.
Values spaced every XX ms: The sampling rate, in milliseconds, for retrieving the data in cyclic mode. The system will return values stored over the requested time period at the interval specified by the resolution. For example, if you specify a 5000 ms resolution, the system will query for all data during the time period and then only return those values that occur at each 5000 ms interval, starting with the start date and ending with the end date.

If you selected the delta retrieval mode, configure additional options in the Delta area. Limit to: The total number of consecutive rows to be returned, starting from the first row in the record set.
Time deadband: The minimum time, in milliseconds,

between returned values for a single tag. Applies only to delta retrieval.

ActiveFactory Software Users Guide

198

Chapter 4 ActiveFactory Query

Value deadband: The percentage of full scale (range),

in engineering units. Any value changes that are less than this percentage will not be returned. Applies only to delta retrieval. The default is 0.

Source Tab
Use the Source tab to specify the data version and type of table for the query.

To configure the source 1

In the Source area, specify the IndustrialSQL Server tables from which data will be retrieved. Manual history tables: Normal SQL Server tables that are used to store data. These are the ManualAnalogHistory and ManualDiscreteHistory tables. Extension tables: Logical tables that are populated from the IndustrialSQL Server data files. These tables support the IndustrialSQL Server time domain extensions for handling data. Both: Select this option to retrieve data from both the manual and extension tables. In the Version area, specify what version of data should be retrieved. Original value: The original value as it was received from the data source (for example, the I/O Server) to the IndustrialSQL Server.
Latest value: The latest value that is stored in the

IndustrialSQL Server with the same timestamp as the original value. Multiple versions are created as the result of data inserts and updates.

ActiveFactory Software Users Guide

Query Types

199

Order Tab
Use the Order tab to specify how the results are ordered.

To configure the ordering 1

In the left window, select a column to add to the ordering criteria. Then click the arrow button to move the column to the right column. Repeat to add all of the desired columns to the ordering criteria. To move a column up or down in the ordering, select the column in the right window and then click the up or down buttons. The results are first ordered according to the column that is listed first in the window, then ordered according to the column that is listed second, and so on. In the Order area, select whether you want the results to be ordered in ascending or descending order.

ActiveFactory Software Users Guide

200

Chapter 4 ActiveFactory Query

ActiveFactory Software Users Guide

201

Chapter 5
ActiveFactory Workbook

ActiveFactory Workbook is an add-in to Microsoft Excel that allows you to query one or more IndustrialSQL Server historian or SQL Server databases and return results to a spreadsheet. Using ActiveFactory Workbook, you can easily create reports using IndustrialSQL Server historian data without needing in-depth knowledge of SQL scripting. The reports that you create with ActiveFactory Workbook can be saved, allowing you to run a report again at any time.

ActiveFactory Software Users Guide

202

Chapter 5 ActiveFactory Workbook

Getting Started
If ActiveFactory Workbook is installed, an additional menu is added to Microsoft Excel. This ActiveFactory menu contains all of the commands you use to create a report using IndustrialSQL Server historian data. Also, you can use the ActiveFactory toolbar to access some of the commands.
ActiveFactory toolbar ActiveFactory menu

Managing Server Connections

You must specify one or more IndustrialSQL Server historians and/or SQL Servers as the data sources for ActiveFactory Workbook.
To manage server connections 1 2

On the ActiveFactory menu, click Connection Management. The Server List Configuration dialog box appears. Configure the server(s) and then click Close. For more information, see Server Connection Configuration on page 39.

ActiveFactory Software Users Guide

Getting Started

203

Opening an Existing Workbook File

Within a workbook file, referenced links may be different than the instance of Excel you are currently using if:

The file you are opening was saved using a previous version of ActiveFactory Workbook The file you are opening was saved using a different computer.

If Microsoft Excel detects that links need updating, a message box appears.

You can either update the links or keep them the same. No matter which option you select, the ActiveFactory Workbook add-in automatically updates only the ActiveFactory Workbook reference within the file to use the current add-in location. You can update the links or keep them the same. If you update the links, click Continue in the dialog box that appears.
To open an existing workbook file 1 2 3

On the File menu, click Open. The Open dialog box appears. Select the name of the file to open. Click Open.

Manually Loading/Unloading the Add-In

When you install the ActiveFactory software after installing Microsoft Excel, the Workbook add-in is automatically loaded into Excel so that the Workbook menu and toolbar appear in the application. However, if you need to manually load or unload the add-in, follow this procedure.

ActiveFactory Software Users Guide

204

Chapter 5 ActiveFactory Workbook

To manually load the add-in 1

On the Tools menu, click Add-Ins. The Add-Ins dialog box appears.

If the ActiveFactory Workbook add-in is not listed in the Add-Ins available window, click Browse and select the HistClient.xla file. By default, the HistClient.xla file is installed in the C:\Program Files\Common Files\ArchestrA folder.

3 4

Select the ActiveFactory Workbook check box in the Add-Ins available window. Click OK.

To manually unload the add-in 1 2 3

On the Tools menu, click Add-Ins. The Add-Ins dialog box appears. Clear the ActiveFactory Workbook check box in the Add-Ins available window. Click OK.

ActiveFactory Software Users Guide

Creating a Report: Overview

205

Creating a Report: Overview

Follow these general steps to create reports using ActiveFactory Workbook.
1

Configure a connection to one or more servers. For more information, see Managing Server Connections on page 202. Understand how functions, formulas, and array formulas work. For more information, see Working with Functions, Formulas, and Cells on page 206. Determine how you want to set up or use workbook options. For more information, see Configuring Workbook Options on page 283. Configure tags for which you want to return data. For more information, see Selecting Tags for Reports on page 214. Create a data report for the selected tags. For information on retrieving configuration data using wizards, see Retrieving Tag Configuration Information on page 218.

For information on retrieving current and historical data values using wizards, see Retrieving Tag Values on page 225. For information on generating analysis graphs and data using wizards, see Retrieving Tag Values on page 225. For information on retrieving data using a manually created SQL query, see Creating a Direct Query on page 280.

Configure other advanced optional features. For more information, see Configuring Workbook Options on page 283. Save the report. Optionally publish the report to the ActiveFactory Reporting Website. For more information, see Publishing Reports on page 298.

7 8

ActiveFactory Software Users Guide

206

Chapter 5 ActiveFactory Workbook

Working with Functions, Formulas, and Cells

An Excel function is a predefined formula that performs a calculation. For example, a function can add two numbers and return the results:
=SUM(number1,number2, ...)

An array formula is a type of function that can perform multiple calculations and then return either a single result or multiple results. Array formulas act on two or more sets of values called array arguments. The arguments are the inputs to the function and are required to be in a particular order. Most of the formulas created using ActiveFactory Workbook are array formulas. For example:
=wwAnalogTagDetails(DataSource, TagRange, Description, EngUnit, EURange, RawRange, Storage, OptionRange)

When the specific inputs are provided and the array formula is executed, the results appear in one or more cells. You can click anywhere in the array results to see the associated formula. You can manually create or edit array formulas in the same way that you create or edit other formulas, except you press CTRL+SHIFT+ENTER to enter or update the array formula.

Note There are certain limitations when working with arrays. For more information, see the following link: http://support.microsoft.com/kb/166342/

ActiveFactory Software Users Guide

Working with Functions, Formulas, and Cells

207

Refreshing a Function or Array Formula

You can refresh any function or array formula in the worksheet.
To refresh 1 2

Select the function to refresh. If you want to refresh an array formula, select any cell in the array. Do one of the following: On the ActiveFactory menu, click Refresh Function. Click the Refresh Function toolbar button. The function is executed and the results are returned.

Editing a Function
To edit a function 1 2

Select the function to edit. If you want to edit an array formula, select any cell in the array. Do one of the following: On the ActiveFactory menu, click Edit Function. Click the Edit Function toolbar button. If applicable, the appropriate wizard opens, allowing you to edit the query.

Converting a Function to Values

To convert a function to values 1 2

Select the function to convert. If you want to convert an array formula, select any cell in the array. Do one of the following: On the ActiveFactory menu, click Convert Function to Values. Click the Convert Function to Values toolbar button.

Refreshing a Sheet
You can refresh all of the formulas for a selected worksheet.
To refresh a worksheet 1 2

Select any cell in the sheet. Do one of the following: On the ActiveFactory menu, click Refresh Sheet.

Click the Refresh Sheet toolbar button.

The query is executed and the worksheet is updated with the returned results.

ActiveFactory Software Users Guide

208

Chapter 5 ActiveFactory Workbook

Converting a Sheet to Values

To convert all of the functions in a sheet to values 1 2

Select the sheet to convert. Do one of the following: On the ActiveFactory menu, click Convert Sheet to Values.

Click the Convert Sheet to Values toolbar button.

Manually Inserting a Function

You can manually insert functions instead of using the function wizards. In Excel, functions are not automatically inserted as array formulas. By default, only a single cell contains a value from the result set. You must enter the formula as an array formula (by pressing CTRL+SHIFT+ENTER) so that all values in the result set appear.
To manually insert a function 1

In the worksheet, type values to use for the function arguments. For example, you might type MyInSQL for the data source name and ReactLevel and ReactTemp as the tags for which to retrieve live values.

ActiveFactory Software Users Guide

Working with Functions, Formulas, and Cells

209

On the Insert menu, click Function. The Insert Function dialog box appears.

3 4

In the Or select a category list, click User Defined. In the Select a function list, select any of the ActiveFactory Workbook functions. All of these functions are prefixed with ww. For more information regarding these functions and their arguments, see ActiveFactory Workbook Function Reference on page 302.

Click OK. The Function Arguments dialog box appears.

For each of the arguments, assign a cell value that contains the input. For example, assigning A1 to the DataSource argument causes MyInSQL to be used for the data source.

ActiveFactory Software Users Guide

210

Chapter 5 ActiveFactory Workbook

Click OK. The function is inserted into the spreadsheet.

Note If the function returns a date/time value, the date/time appear in the Julian format, unless a different format is configured for the cell. 8 9

Select the returned value. On the ActiveFactory menu, click Refresh Function. The formula is converted to an array and you can see all of the return values.

ActiveFactory Software Users Guide

Working with Functions, Formulas, and Cells

211

Manually Editing a Function

To manually edit a function 1

In your worksheet, select the function to edit so that it appears in the formula bar.

In the formula bar, edit the argument value(s) for the function. For example, you can add an additional tag by expanding the cell range.

ActiveFactory Software Users Guide

212

Chapter 5 ActiveFactory Workbook

Press CTRL+SHIFT+ENTER on your keyboard to enter the array formula.

On the ActiveFactory menu, click Refresh Function to resize the results. You can then see all the return values.

Copying a Function
You can copy and paste functions to different locations in the worksheet. This is useful when creating additional functions that are only slightly different than existing functions.
To copy a function 1

In the worksheet, select the range of cells that contains the array formula. To select all of the array cells, insert the mouse cursor in the array and then press CTRL+/ on your keyboard, where / is the forward slash. Press CTRL+C to copy the function.

ActiveFactory Software Users Guide

Working with Functions, Formulas, and Cells

213

3 4

Insert the mouse cursor in the new location for the function.

Press CTRL+V to paste the function. For information on manually editing a function, see Manually Editing a Function on page 211.

Selecting Cells
Various option boxes require you to specify a worksheet cell for either input or for output. You can easily select the cell or range of cells that you want to use, eliminating the need to type the formula for the cell location.
To select a cell in the worksheet 1

Click the button to the right of the option box that requires a cell location.

The cell selector dialog box appears.

In the spreadsheet, use your mouse to select the desired cell(s). The cell notation appears in the dialog box.

Click the Notation button to insert the notation into the option box.

Verifying the Date/Time Format in Microsoft Excel

When you query the database for history values, you must specify the time range for the query. If you choose to use specific dates, you must make sure that the date/time format that you specify match the Microsoft Excel date/time format settings for the result cells.
To verify the date/time format 1

In the spreadsheet, select the cells to contain the timestamps for the returned data.

ActiveFactory Software Users Guide

214

Chapter 5 ActiveFactory Workbook

2 3

On the Format menu, click Cells. The Format Cells dialog box appears. Click the Number tab.

4 5 6

In the Category window, click Date. In the Type list, verify the date format. Click OK.

Selecting Tags for Reports

When you configure a report, you can either type the tagname(s) directly in the worksheet or you can pick the tag and have it inserted for you. You can include the following types of tags in your worksheet:

Analog, discrete, string, and event tags. For more information, see Selecting Analog, Discrete, String, or Event Tags on page 215. Summary tags. A summary tag is a tag for which an aggregation calculation (minimum, maximum, average, and sum) was configured on the server. For more information, see Selecting Summary Tags on page 216. Event snapshot tags. A snapshot tag is a tag for which a snapshot action has been configured on the server. A snapshot action logs into dedicated SQL Server tables the data values for selected analog, discrete, or string tags that have the same timestamp as the detected event. For more information, see Selecting Event Snapshot Tags on page 217.

ActiveFactory Software Users Guide

Selecting Tags for Reports

215

Selecting Analog, Discrete, String, or Event Tags

To select analog, discrete, string, or event tags 1

On the ActiveFactory menu, point to Tag Selection, and then click Tag Selection. The Tag Selection dialog box appears.

2 3 4

For instructions on how to use most of the options in this dialog box, see Tag Picker on page 51. Select the Include description check box to include tag descriptions in the results. In the Select cell range to insert tags list, click the name of the workbook cell into which you want to insert the tags. For more information, see Selecting Cells on page 213. Click OK. The tag is inserted into the selected cell.

ActiveFactory Software Users Guide

216

Chapter 5 ActiveFactory Workbook

Selecting Summary Tags

To select summary tags 1

On the ActiveFactory menu, point to Tag Selection, and then click Summary Tag Selection. The Summary Tag Selection dialog box appears.

2 3

In the Servers list, click the name of the server to use. In the Filter area, configure the criteria by which the tags are filtered and displayed in the Select tags to insert into workbook window. These tags are the tags that have one or more summary operations configured for them. Summarization frequency: The period, in seconds, for which the calculation is performed.
Calculation type: The type of calculation: Sum,

Maximum, Minimum, or Average.

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Description: The description of the tag. 4 5

Select the Include description check box to include tag descriptions in the results. In the Select cell range to insert tags list, click the name of the workbook cell into which you want to insert the tags. For more information, see Selecting Cells on page 213. Click OK.

ActiveFactory Software Users Guide

Selecting Tags for Reports

217

The tag are inserted into the selected cell.

Selecting Event Snapshot Tags

To select event snapshot tags 1

On the ActiveFactory menu, point to Tag Selection, and then click Event Snapshot Tag Selection. The Event Snapshot Tag Selection dialog box appears.

2 3

ActiveFactory Software Users Guide

218

Chapter 5 ActiveFactory Workbook

4 5

Snapshot tag type: The type of snapshot, either analog,

discrete, or string. Select the Include description check box to include tag descriptions in the results. In the Select cell range to insert tags list, click the name of the workbook cell into which you want to insert the tags. For more information, see Selecting Cells on page 213. Click OK. The tags are inserted into the selected cell.

Retrieving Tag Configuration Information

You can retrieve configuration information for analog, discrete, string, and event tags. For analog tags, alarm limit information can also be retrieved.

Retrieving Configuration Details for a Tag

You can retrieve configuration details for tags, such as a description. The configuration details that can be retrieved depend on the type of tag. For example, the minimum and maximum values are only applicable for an analog tag.

ActiveFactory Software Users Guide

Retrieving Tag Configuration Information

219

To retrieve tag details 1

On the ActiveFactory menu, point to Tag Configuration, and then click Tag Details. The Tag Details - Step 1 of 3 dialog box appears.

2 3

In the Server list, click the name of the server to use. In the Select cell(s) containing tag name(s) list, specify the location of the worksheet cell(s) that contains the tag name(s). Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. If you want to use a named tag range variable instead, click Binding Options and then configure the range. For more information, see Using "Binding" Options on page 293. Click Next. The Tag Details - Step 2 of 3 dialog box appears.

ActiveFactory Software Users Guide

220

Chapter 5 ActiveFactory Workbook

In the Select cell for output list, specify the location of the worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. Select the Enter the results as an array-formula check box to insert the results as an array formula. An array formula can perform one or more calculations and then return either a single result or multiple results. An array formula allows for the resending of the query, since the query parameters are included in the cells that contain the query results. For more information, see Working with Functions, Formulas, and Cells on page 206. Select the Select cells to specify format options check box to specify a range of cells that contain formatting information. The formatting information in the cells will be applied to the query results. For more information, see Selecting Cells on page 213. Click Next. The Tag Details - Step 3 of 3 dialog box appears.

This dialog box displays different options, depending on the type of tag you have selected.
10 For analog tags, configure the following options: Description: The description of the tag. Raw value range: The minimum value of the raw acquired value. Also, the maximum value of the raw acquired value. Engineering units: The unit of measure. Examples are

mph, grams, and pounds.

ActiveFactory Software Users Guide

Retrieving Tag Configuration Information

221

Engineering units range: The minimum value of the

tag, measured in engineering units. Also, the maximum value of the tag, measured in engineering units.
Storage rate and type: The type of storage defined for

the tag, either cyclic or delta. The storage rate is the rate at which the tag is stored if the storage type is cyclic.
11 For discrete tags, configure the following options: Description: The description of the tag. Storage rate and type: The type of storage defined for

the tag, either cyclic or delta. The storage rate is the rate at which the tag is stored if the storage type is cyclic.
Messages: The messages associated with the

TRUE/FALSE or ON/OFF state of the tag.

12 For string tags, configure the following options: Description: The description of the tag. Maximum tag name length permitted: The maximum

number of characters for the string.

13 For event tags, configure the following options: Description: The description of the tag. Time deadband: The minimum time, in milliseconds,

between stored events. If more than one event occurs during the deadband, only the most recent are stored. The system does not store another event until the specified time has elapsed. A time deadband of 0 indicates that the system stores all events.
Detector type: The name given to the type of detector. Action type: The name given to the type of action. Status: The flag used by the event system at system startup and during runtime to determine if the event tag has been modified. 0 = Posted. Any changes have been detected and effected by the system. 1 = New. An event tag has been inserted, but is not yet executing. 2 = Modification. An event tag has been updated, but the older one is already executing. 98 = Disabled. 99 = Disabling requested. The event tag does not execute, even though the definition still exists in the schema. Note that there may be a delay of up to 30 seconds before a change in an event tag is seen by the running system.

ActiveFactory Software Users Guide

222

Chapter 5 ActiveFactory Workbook

Logged: Used to specify whether or not to log events for this tag into the EventHistory table. Event logging can only be turned off if no associated actions are configured. Scan rate: The interval, in milliseconds, at which the

system will check to see if the event conditions specified by the detector have occurred. This value must be greater than or equal to 500 milliseconds, and less than or equal to 1 hour (3600000 ms).
14 Click Finish. The details appear in the spreadsheet.

ActiveFactory Software Users Guide

Retrieving Tag Configuration Information

223

Retrieving Analog Tag Alarm Limits

If a tag is configured to have alarm limits, you can retrieve that information. Examples of limits are Hi, HiHi, Lo, and LoLo alarm limits.
To retrieve analog tag alarm limits 1

On the ActiveFactory menu, point to Tag Configuration, and then click Analog Tag Alarm Limits. The Alarm Values Step 1 of 2 dialog box appears.

2 3

ActiveFactory Software Users Guide

224

Chapter 5 ActiveFactory Workbook

Click Next. The Alarm Values - Step 2 of 2 dialog box appears.

ActiveFactory Software Users Guide

Retrieving Tag Values

225

Click Finish. The details appear in the spreadsheet.

Retrieving Tag Values

You can retrieve the following types of values for tags:

"Live" values. History values. Aggregate values. Summary System Values. Event Shapshot Values.

Retrieving Live Values

You can retrieve the current data values for specified tags.
To retrieve live values 1

In cells in your worksheet, enter one or more tagnames (one tagname per cell). For more information, see Selecting Tags for Reports on page 214.

ActiveFactory Software Users Guide

226

Chapter 5 ActiveFactory Workbook

On the ActiveFactory menu, point to Tag Values, and then click Live Values. The Live Values - Step 1 of 3 dialog box appears.

3 4

In the Server list, click the name of the server to use. Select the Support multiple data types check box to allow for the selection of dissimilar data types for the same query. That is, a mix of analog, discrete, string, and/or event tags. In the Select cell(s) containing tag name(s) list, specify the location of the worksheet cell(s) that contains the tag name(s). Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. If you want to use a named tag range variable instead, click Binding Options and then configure the range. For more information, see Using "Binding" Options on page 293.

ActiveFactory Software Users Guide

Retrieving Tag Values

227

Click Next. The Live Values - Step 2 of 3 dialog box appears.

In the Select cell for output list, specify the location of the worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. Select the Enter the results as an array-formula check box to insert the results as an array formula. An array formula can perform one or more calculations and then return either a single result or multiple results. An array formula allows for the resending of the query, since the query parameters are included in the cells that contain the query results. For more information, see Working with Functions, Formulas, and Cells on page 206. to specify a range of cells that contain formatting information. The formatting information in the cells will be applied to the query results. For more information, see Selecting Cells on page 213.

10 Select the Select cells to specify format options check box

ActiveFactory Software Users Guide

228

Chapter 5 ActiveFactory Workbook

11 Click Next. The Live Values - Step 3 of 3 dialog box

appears.

12 Configure the criteria for the query. Tag name: The unique name of the tag within the

IndustrialSQL Server system.

Date time: The timestamp for the returned value. For delta retrieval, this is typically the time at which the value was acquired by the IndustrialSQL Server. For cyclic retrieval, this is the specific time requested or calculated (using a SQL function). Include milliseconds: Used to include milliseconds in

the timestamp.
Quality: The basic data quality indicator associated

with the data value.

Replace poor quality values: The text string of "poor"

will replace the current value if the value has a quality <> 0 or 133.
Detect date time: Only applicable to event tags. The

timestamp reflecting when the event was detected by the event system.
OPC Quality: The quality value received from the data source. Only available if you selected the Support multiple data types check box in the Live Values - Step 1 of 3 dialog box (see step 4 above).

ActiveFactory Software Users Guide

Retrieving Tag Values

229

13 Click Finish.

Retrieving History Values

You can retrieve history data for specified analog, discrete, string, and/or event tags. However, you cant retrieve data for event tags and other types of tags in the same query. To retrieve data for event tags, create a separate query that only includes event tags.
To retrieve history values 1

In cells in your worksheet, enter one or more tagnames (one tagname per cell).

ActiveFactory Software Users Guide

230

Chapter 5 ActiveFactory Workbook

On the ActiveFactory menu, point to Tag Values, and then click History Values. The History Values - Step 1 of 4 dialog box appears.

3 4

In the Servers list, click the name of the server to use. In the Select cell(s) containing tag name(s) list, specify the location of the worksheet cell(s) that contains the tag name(s). Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. If you want to use a named tag range variable instead, click Binding Options and then configure the range. For more information, see Using "Binding" Options on page 293.

ActiveFactory Software Users Guide

Retrieving Tag Values

231

Click Next. The History Values - Step 2 of 4 dialog box appears.

ActiveFactory Software Users Guide

232

Chapter 5 ActiveFactory Workbook

10 Click Next. The History Values - Step 3 of 4 dialog box

appears.

11 Configure the criteria for the query.

See Display Options Tab on page 233. See Format Tab on page 248. See Retrieval Tab on page 234. See Order Tab on page 251. See Criteria Tab on page 249.
12 Click Next. The History Values - Step 4 of 4 dialog box

appears.

ActiveFactory Software Users Guide

Retrieving Tag Values

233

13 Configure the time for the query. For more information

on configuring these options, see Time Options for Queries on page 297.
14 Click Finish.

Display Options Tab

Use the Display Options tab to configure the columns to display in the results. By default, the Display Options tab only shows basic display options. For a description of these options, see Display Options Tab on page 247. To see additional options, click the More >> button. The following options appear:
wwRetrievalMode: The retrieval mode used for the tag. For more information, see Understanding Retrieval Modes on page 649. wwCycleCount: The cycle count used in data retrieval. For more information, see Cycle Count (X Values over Equal Time Intervals) on page 674.

When retrieving data from an IndustrialSQL Server historian with a version earlier than 9.0, the wwRowCount column is returned instead of the wwCycleCount column.

ActiveFactory Software Users Guide

234

Chapter 5 ActiveFactory Workbook

wwTimeDeadband: The time deadband used in data

retrieval. For more information, see Time Deadband on page 676.

wwTimeStampRule: The timestamp rule used in data

retrieval. For more information, see Timestamp Rule on page 680.

wwVersion: The history version of the value. For more

information, see History Version on page 678.

wwEdgeDetection: The type of edge detection used in the

query.
wwTagKey: The unique identifier of the tag on the IndustrialSQL Server historian. wwInterpolationType: The interpolation type used to

calculate the value. For more information, see Interpolation Type on page 678.
wwResolution: The resolution used in data retrieval. For

more information, see Resolution (Values Spaced Every X ms) on page 675.
wwValueDeadband: The value deadband used in data

retrieval. For more information, see Value Deadband on page 677.

wwQualityRule: The quality rule used in data retrieval.

For more information, see Quality Rule on page 682.

wwTimeZone: The time zone that the values timestamp

refers to.
PercentGood: The percentage of rows with good quality in

relation to the total number of rows in the retrieval cycle.

wwStateCalc: The state calculation type used to calculate

the state time when using ValueState retrieval (for example, average time or total time). For more information, see State Calculation on page 683.

Retrieval Tab
Use the Retrieval tab to configure the data retrieval mode and additional retrieval options. For a detailed description of retrieval modes and options, see Understanding Retrieval Modes on page 649 and Understanding Retrieval Options on page 673.

ActiveFactory Software Users Guide

Retrieving Tag Values

235

Retrieving Aggregate Values

You can retrieve aggregated values for one or more analog tags. Values are calculated using the standard SQL Server aggregation functions. To retrieve aggregated values from the IndustrialSQL Server historians summary tables, see Retrieving Values for Summarized Tags on page 240.
To retrieve aggregate values 1 2

In cells in your worksheet, enter one or more tagnames (one tagname per cell). On the ActiveFactory menu, point to Tag Values, and then click Aggregate Values. The Aggregate Values - Step 1 of 4 dialog box appears.

3 4

ActiveFactory Software Users Guide

236

Chapter 5 ActiveFactory Workbook

Click Next. The Aggregate Values - Step 2 of 4 dialog box appears.

ActiveFactory Software Users Guide

Retrieving Tag Values

237

10 Click Next. The Aggregate Values - Step 3 of 4 dialog box

appears.

11 Configure the criteria for the query.

See Format Tab on page 248. See Calculations Tab on page 238. See Resolution Tab on page 239. See Criteria Tab on page 249.
12 Click Next. The Aggregate Values - Step 4 of 4 dialog box

appears.

13 Configure the time for the query. For more information

on configuring these options, see Time Options for Queries on page 297.

ActiveFactory Software Users Guide

238

Chapter 5 ActiveFactory Workbook

14 Click Finish.

Calculations Tab
Use the Calculations tab to specify which calculated values to retrieve from the database.

To specify the calculation 1

In the Calculation type list, click the type of calculation: Sum, Maximum, Minimum, Average, Range, or Standard deviation. The calculation you choose determines which retrieval mode is used. Delta retrieval is used for the Minimum, Maximum, and Range calculations. Cyclic retrieval is used for the other calculations.

ActiveFactory Software Users Guide

Retrieving Tag Values

239

Resolution Tab
Use the Resolution tab to specify the "granularity" of the data to be returned.

To configure the resolution 1

If cyclic retrieval is used for the calculation you selected, configure the following options in the Cyclic area. XX values over equal time intervals: The number of rows to be returned for a specified time period. For cyclic retrieval, the rows are spaced evenly across the time period, and the default row count is 100 rows. For cyclic retrieval, the row count is applied for each tag in a query.
Values spaced every XX ms: The sampling rate, in milliseconds, for retrieving the data in cyclic mode. The system will return values stored over the requested time period at the interval specified by the resolution. For example, if you specify a 5000 ms resolution, the system will query for all data during the time period and then only return those values that occur at each 5000 ms interval, starting with the start date and ending with the end date. Full: All records between the start and end dates are returned. This option is only available for cyclically-stored tags. Interpolate: Linear interpolation is used between

stored values. Interpolation only applies for values of cyclically-stored analog tags where no criteria has been specified. Also, the resolution must be set to return all values or to return values spaced according to a time interval.
2

If delta retrieval is used for the calculation you selected, configure the following options in the Delta area. All rows: Return all rows in the record set.

ActiveFactory Software Users Guide

240

Chapter 5 ActiveFactory Workbook

First XX rows: The total number of consecutive rows to be returned, starting from the first row in the record set. Value deadband: The percentage of full scale (range),

in engineering units. Any value changes that are less than this percentage are not returned. Applies only to delta retrieval.
Time deadband: The minimum time, in milliseconds,

between returned values for a single tag. Applies only to delta retrieval.

Retrieving Values for Summarized Tags

You can retrieve summary values for tags that have been configured to be summarized by the IndustrialSQL Server event subsystem.
To retrieve summary system values 1 2

In cells in your worksheet, enter one or more tagnames (one tagname per cell). On the ActiveFactory menu, point to Tag Values, and then click Summary System Values. The Summary Values - Step 1 of 4 dialog box appears.

3 4

ActiveFactory Software Users Guide

Retrieving Tag Values

241

If you want to use a named tag range variable instead, click Binding Options and then configure the range. For more information, see Using "Binding" Options on page 293. Click Next. The Summary Values - Step 2 of 4 dialog box appears.

ActiveFactory Software Users Guide

242

Chapter 5 ActiveFactory Workbook

10 Click Next. The Summary Values - Step 3 of 4 dialog box

appears.

11 Configure the criteria for the query.

See Display Options Tab on page 247. See Summary Options Tab on page 243.
12 Click Next. The Summary Values - Step 4 of 4 dialog box

appears.

13 Configure the time for the query. For more information

on configuring these options, see Time Options for Queries on page 297.

ActiveFactory Software Users Guide

Retrieving Tag Values

243

14 Click Finish.

Summary Options Tab

Use the Summary Options tab to specify the criteria for the type of summary data to return.

To configure the summary criteria 1 2

In the Calculation type list, click the type of calculation: Sum, Maximum, Minimum, or Average. In the Calculation frequency list, click the period, in seconds, for which the calculation is performed.

ActiveFactory Software Users Guide

244

Chapter 5 ActiveFactory Workbook

Retrieving Values for Event Snapshot Tags

You can retrieve values for snapshot tags associated with a particular event tag.
To retrieve event snapshot values 1

In cells in your worksheet, enter one or more tagnames (one tagname per cell). You must specify both the event tag that is associated with the snapshot action and the snapshot tag. For information on selecting an event tag, see Selecting Analog, Discrete, String, or Event Tags on page 215. BBB For information on selecting a snapshot tag, see Selecting Event Snapshot Tags on page 217. Select the tag(s) associated with the event tag you selected.

On the ActiveFactory menu, point to Tag Values, and then click Event Snapshot Values. The Event Snapshot Values Step 1 of 4 dialog box appears.

3 4

ActiveFactory Software Users Guide

Retrieving Tag Values

245

Click Next. The Event Snapshot Values - Step 2 of 4 dialog box appears.

ActiveFactory Software Users Guide

246

Chapter 5 ActiveFactory Workbook

10 Click Next. The Event Snapshot Values - Step 3 of 4 dialog

box appears.

11 Configure the criteria for the query.

For more information, see Display Options Tab on page 247.

12 Click Next. The Event Snapshot Values - Step 4 of 4 dialog

box appears.

13 Configure the time for the query. For more information

on configuring these options, see Time Options for Queries on page 297.

ActiveFactory Software Users Guide

Retrieving Tag Values

247

14 Click Finish.

Common Properties for Tag Values

The data retrieval wizards use some of the same tabs.

Display Options Tab

Use the Display Options tab to configure the columns to display in the results.

Note The availability of options depends on the type of tag(s) selected for the query.

Options are as follows:

Tag name: The unique name of the tag within the

IndustrialSQL Server system.

ActiveFactory Software Users Guide

248

Chapter 5 ActiveFactory Workbook

the timestamp.
Quality: The basic data quality indicator associated with the data value. Replace poor quality values: The text string of "poor"

will replace the current value if the value has a quality <> 0 or 133.
Detect date time: Only applicable to event tags. The

timestamp reflecting when the event was detected by the event system.
OPC Quality: The quality value received from the data

source. For an event tag, if data is returned in the narrow format and the manual history data option is enabled, the Date time option is selected by default, and you cannot change it. If the manual history data option is disabled, the Date time option is available.

Format Tab
Use the Format tab to specify the order in which tags and data are returned and how the results of the query are presented. The retrieval options you choose determine what appears on the Criteria tab. For more information on this tab, see Criteria Tab on page 249.

The retrieval options are as follows.

ActiveFactory Software Users Guide

Retrieving Tag Values

249

Value based criteria (narrow tables): Data values are

returned if they match certain criteria applied to the Value or vValue column. For example, if any possible value > 5000. You can also specify quality criteria for the value. For example, if the data quality for any possible value = Good.
Tag based criteria (wide tables): Data values are returned

if they match certain criteria applied to the column for a tagname. For example, if Tagname1 > 5000. The presentation options are as follows:
Narrow query format: In this format, there is one row for a

single tag's value for a particular timestamp.

Wide query format: In this format, there is one row for

one or more tag values for a single timestamp, thus providing a "wide" view of the data. To use the wide query format, you must specify the timestamp and one or more tagnames as the column names in the query syntax. The results will contain a column for the timestamp and columns for the value of each specified tag at that timestamp.

Criteria Tab
Use the Criteria tab to specify the filtering criteria for the data value(s) to be returned. The filtering criteria options are determined by what you selected for the display format for the returned data, either "narrow" or "wide." For more information, see Format Tab on page 248. For tag based criteria (wide tables), data values are returned if they match certain criteria applied to the column for a tagname. For example, if Tagname1 > 5000. A NULL value indicates that a column entry has no assigned value. A NULL value is not the same as a numeric value of 0 or an empty string.

ActiveFactory Software Users Guide

250

Chapter 5 ActiveFactory Workbook

For value based criteria (narrow tables), data values are returned if they match certain criteria applied to the Value or vValue column. For example, if any possible value > 5000. You can also specify quality criteria for the value. For example, if the data quality for any possible value = Good.

The value based criteria options that are available in the Criteria tab depend upon what types of tags you have selected for the query, either analog, discrete, string, or a mix of these types.
To configure value criteria 1

To configure criteria for a discrete tag, select the first Value check box and set the criteria to be either a 1 or a 0. Skip to Step 5. To configure criteria for an analog tag:
a

Select the first Value check box and set the criteria for the data value. For example, the value must be greater than ( > ) 1500. (Optional) Select the second Value check box and set another criteria for the data value. For example, the value must be less than ( < ) 2000. Skip to Step 5. If you are retrieving history values, select the Use StringHistory check box. In this case, you can only retrieve data for string tags in the query. No data is returned for tags of other types that you may have selected. This is due to a limitation in the IndustrialSQL Server historian.

c 3 a

To configure criteria for a string tag:

Select the third Value check box and specify text that the returned string value must match. You can specify whether the returned value must equal, start, end, or contain the specified text. For example, you can specify that the value must contain the text "alert."

ActiveFactory Software Users Guide

Retrieving Tag Values

251

c 4 5

Skip to Step 5.

(Optional) Select the Value not null check box to filter out NULL values from the results. (Optional) In the Quality list, click the quality criteria for the data. Only data values that match the quality you specify (Good, Bad, Doubtful) are returned. (Optional) In the OPC Quality list, click the OPC quality criteria for the data. Only data values that match the quality you specify (Good, Bad, Doubtful) are returned. (Optional) In the Criteria applicability list, select the moment at which the edge detection criteria is met. first true: Returns only rows that are the first to successfully meet the criteria (return true) after a row did not successfully meet the criteria (returned false). This is also known as "leading" edge detection.
no longer true: Returns only rows that are the first to

fail the criteria (return false) after a row successfully met the criteria (returned true). This is also known as "trailing" edge detection.
true: Returns all rows that successfully meet the

criteria; no edge detection is implemented at the specified resolution.

first true or no longer true: All rows satisfying both

the leading and trailing conditions are returned.

Order Tab
Use the Order tab to specify how the results are ordered.

To configure the ordering 1

ActiveFactory Software Users Guide

252

Chapter 5 ActiveFactory Workbook

To move a column up or down in the ordering, select the column in the right window and then click the up or down buttons. The results are first ordered according to the column that is listed first in the window, then ordered according to the column that is listed second, and so on. In the Order area, select whether you want the results to be ordered in ascending or descending order.

Analyzing Tag Data

In addition to creating value reports, you can use ActiveFactory Workbook to generate statistics, charts, and graphs that are useful for analysis.
Analog Tag Analysis. Create graphs and trends, calculate

statistics, and return information regarding configuration and limits.

Batch Analysis. Graph a single analog tag over two time

periods.
Scatter Analysis. Create a scatter plot of two analog tags. Discrete Tag Analysis. Create graphs and trends, calculate statistics, and return information regarding configuration. Analog Values at Discrete Transition Analysis. Graph analog

tag values at discrete tag transitions.

Analog/Discrete Pair Analysis. Graph analog vs. discrete

tags. Wizards are provided to guide you though selecting the required options to create the output.

ActiveFactory Software Users Guide

Analyzing Tag Data

253

Analog Tag Analysis

Use the Analog Tag Analysis wizard to generate graphs and statistics for an analog tag.
To analyze an analog tag 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Analog tag analysis. Click Next. The Tag Analysis - Step 2 of 5 dialog box appears.

4 5

In the Servers list, click the name of the server to use. In the Analog tag list, specify the name of the tag to analyze. Click the ellipsis button to open the Tag Picker and browse for the tag. For more information, see Tag Picker on page 51.

ActiveFactory Software Users Guide

254

Chapter 5 ActiveFactory Workbook

Click Next. The Tag Analysis - Step 3 of 5 dialog box appears.

In the Starting time list, enter the starting time for the query. Click the arrow button to select a date from a calendar. In the Duration lists, specify the duration and the duration unit. For example, 10 minutes. The duration is used to calculate the end date for the query. Click Next. The Tag Analysis - Step 4 of 5 dialog box appears.

10 Configure the resolution for the data to be returned. Number of rows: The number of rows to be returned

for a specified time period using cyclic retrieval. The rows are spaced evenly across the time period, and the default row count is 50 rows. The row count is applied for each tag in a query.

ActiveFactory Software Users Guide

Analyzing Tag Data

255

Values spaced every: The sampling rate, in

milliseconds, for retrieving the data in cyclic mode. The system will return values stored over the requested time period at the interval specified by the resolution. For example, if you specify a 5000 ms resolution, the system will query for all data during the time period and then only return those values that occur at each 5000 ms interval, starting with the start date and ending with the end date.
11 Click Next. The Tag Analysis - Step 5 of 5 dialog box

appears.

12 Select the analysis options to include. Plot trend (tag vs. time): If selected, the value of the

tag over time will be plotted in a trend chart.

Statistics: If selected, tag statistics will be included in the output. Pie graph: If selected, a pie graph will be created. Limit 1: The highest limit as was configured in

InTouch. If no InTouch limits are set for the tag, then this value is equal to the maximum engineering unit.
Limit 2: The lowest limit as was configured in

InTouch. If no InTouch limits are set for the tag, then this value is equal to the minimum engineering unit.
Minimum: The minimum value for the tag. Maximum: The maximum value for the tag. Average: The average value for the tag. Sum: The sum of all values for the tag. Range: The difference between the maximum and the

minimum value for the tag.

Standard deviation: The statistical standard deviation of all values for the tag.

ActiveFactory Software Users Guide

256

Chapter 5 ActiveFactory Workbook

Resolution: The sampling rate for retrieving the data

that is used for calculating the aggregations (Minimum, Maximum, etc.)

13 Click Finish.

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Tag A4: Row or resolution A5: Start Time A6: Duration A7: Low Limit A8: High Limit
Note The assignments are not absolute and may change in future releases. 14 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell C2:

ActiveFactory Software Users Guide

Analyzing Tag Data

257

=wwAnalogWideHistory(A1,A2,"Row" & A4,"Rel",A6 & "(" & A5 & ")",FALSE," ",TRUE,FALSE)

each results cell for the aggregation column (column F): For delta stored tags, the resolution you specified in the wizard is used:
=wwAggregateWide(A1,A2,"Res60000","Rel",A6 & "(" & A5 & ")","Min","")

For cyclic stored tags, the storage rate is used as the retrieval resolution:
=wwAggregateWide(A1,A2,"ResFull","Rel",A6 & "(" & A5 & ")","Min","") 15 Optionally alter the results by changing values that

For example, you can change the tagname from ReactLevel to ReactTemp.

ActiveFactory Software Users Guide

258

Chapter 5 ActiveFactory Workbook

Change the limits to the correct limits so that the statistics and trend chart reflect the data.

ActiveFactory Software Users Guide

Analyzing Tag Data

259

The information for the analysis headings and units is stored in cells outside of the maximum range for a formula array. To see this information, scroll down in the worksheet to near row 6000.

You can also change the duration in column A1 and watch the data in the report change.

ActiveFactory Software Users Guide

260

Chapter 5 ActiveFactory Workbook

Batch Analysis
Use the Batch Analysis wizard to graph one analog tag over two time periods.
To create a batch analysis 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Batch analysis. Click Next. The Tag Analysis - Step 2 of 4 dialog box appears.

4 5

ActiveFactory Software Users Guide

Analyzing Tag Data

261

Click Next. The Tag Analysis - Step 3 of 4 dialog box appears.

In the Starting time list, enter the starting time for the first time period. Click the arrow button to select a date from a calendar. In the Starting time for second time period list, enter the starting time for the second time period. Click the arrow button to select a date from a calendar. In the Duration lists, specify the duration and the duration unit. For example, 10 minutes. The duration is used to calculate the end dates for the query. appears.

10 Click Next. The Tag Analysis - Step 4 of 4 dialog box

11 Configure the resolution for the data to be returned. Number of rows: The number of rows to be returned

for a specified time period. For cyclic retrieval, the rows are spaced evenly across the time period, and the default row count is 50 rows. For cyclic retrieval, the row count is applied for each tag in a query.

ActiveFactory Software Users Guide

262

Chapter 5 ActiveFactory Workbook

Values spaced every: The sampling rate, in

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Tag A3: Start Time 1 Chart Legend A4: Row or resolution A5: Start Time A6: Duration A8: Start Time 2 Chart Legend A9: Start Time 2

ActiveFactory Software Users Guide

Analyzing Tag Data

263

13 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell C2:
=wwAnalogWideHistory(A1,A2,"Res" & A4,"Rel",A6 & "(" & A5 & ")",FALSE," ",TRUE,FALSE)

Cell E2:
=wwAnalogWideHistory(A1,A2,"Res" & A4,"Rel",A6 & "(" & A9 & ")",FALSE," ",TRUE,FALSE) 14 Optionally alter the results by changing values that

appear in the first column of the worksheet. If the calculation mode is set to automatic, any changes you make to the values in this column are immediately reflected in the worksheet. For example, decrease the resolution and time period by 50%.
Note If you reduce the resolution by half, but do not adjust the time range (duration), only half of the time is reflected in the trend chart. If you want to make changes to the input parameters that affect the total number of returned rows, you must modify the chart to reference the new cell ranges. You must also refresh the worksheet functions.

ActiveFactory Software Users Guide

264

Chapter 5 ActiveFactory Workbook

Scatter Analysis
Use the Scatter Analysis wizard to create a scatter plot of two analog tags.
To create a scatter plot 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Scatter analysis. Click Next. The Tag Analysis - Step 2 of 4 dialog box appears.

4 5

In the Servers list, click the name of the server to use. In the Analog tags list, specify the name of the tags to analyze. Click the ellipsis button to open the Tag Picker and browse for the tag. For more information, see Tag Picker on page 51.

ActiveFactory Software Users Guide

Analyzing Tag Data

265

Click Next. The Tag Analysis - Step 3 of 4 dialog box appears.

In the Starting time list, enter the starting time for the query. Click the arrow button to select a date from a calendar. (optional) To show data for a second time period in the same scatter plot, enter a second starting time in the Starting time for second time period list. Click the arrow button to select a date from a calendar. Using a second time period allows you to view differences in operation for two time periods.

In the Duration lists, specify the duration and the duration unit. For example, 10 minutes. The duration is used to calculate the end date for the query. appears.

10 Click Next. The Tag Analysis - Step 4 of 4 dialog box

11 Configure the resolution for the data to be returned.

ActiveFactory Software Users Guide

266

Chapter 5 ActiveFactory Workbook

Number of rows: The number of rows to be returned

ActiveFactory Software Users Guide

Analyzing Tag Data

267

12 Click Finish.

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Tag 1 A3: Tag 2 A4: Row or resolution A5: Start Time 1 A6: Duration A7: Start Time 2
13 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell B2:
=wwAnalogWideHistory(A1,A2:A3, "Row" & A4,"Rel",A6 & "(" & A5 & ")",FALSE," ",FALSE,FALSE)

Cell D2:
=wwAnalogWideHistory(A1, A2:A3, "Row" & A4,"Rel",A6 & "(" & A7 & ")",FALSE," ", FALSE, FALSE)
ActiveFactory Software Users Guide

268

Chapter 5 ActiveFactory Workbook

14 Optionally alter the results by changing values that

appear in the first column of the worksheet. If the calculation mode is set to automatic, any changes you make to the values in this column are immediately reflected in the worksheet.

Discrete Tag Analysis

Use the Discrete Tag Analysis wizard to create graphs and trends, calculate statistics, and return configuration information.
To analyze a discrete tag 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Discrete tag analysis. Click Next. The Tag Analysis - Step 2 of 5 dialog box appears.

In the Servers list, click the name of the server to use.

ActiveFactory Software Users Guide

Analyzing Tag Data

269

In the Discrete tag list, specify the name of the tag to analyze. Click the ellipsis button to open the Tag Picker and browse for the tag. For more information, see Tag Picker on page 51. Click Next. The Tag Analysis - Step 3 of 5 dialog box appears.

10 Configure the resolution for the data to be returned. Number of rows: The number of rows to be returned

ActiveFactory Software Users Guide

270

Chapter 5 ActiveFactory Workbook

Values spaced every: The sampling rate, in

appears.

12 Configure the analysis options. Plot trend (tag vs. time): If selected, the value of the

tag over time will be plotted in a trend chart.

Statistics: If selected, tag statistics will be included in the output. Pie graph: If selected, a pie graph will be created.

ActiveFactory Software Users Guide

Analyzing Tag Data

271

13 Click Finish.

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Tag A4: Row or resolution A5: Start Time A6: Duration
14 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell B2:
=wwDiscreteWideHistory(A1,A2,"Res" & A4,"Rel",A6 & "(" & A5 & ")","",TRUE,FALSE)

Cell H2 (time in state)

=SUMIF(C2:C11, "0",D3:D12)

Cell H4 (number of transitions)

=COUNTIF(C3:C12, 0)

Columns E and F contain both transitions for each of the dates in Column B.
ActiveFactory Software Users Guide

272

Chapter 5 ActiveFactory Workbook

15 Optionally alter the results by changing values that

The information for the analysis headings and units is stored in cells outside of the maximum range for a formula array. To see this information, scroll down in the worksheet to near row 6000.

ActiveFactory Software Users Guide

Analyzing Tag Data

273

Analog Values at Discrete Transition Analysis

Use the Analog Values at Discrete Transition Analysis wizard to graph analog tag values at discrete tag transitions.
To analyze an analog tag at a discrete transition 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Analog values at discrete transition analysis. Click Next. The Tag Analysis - Step 2 of 4 dialog box appears.

4 5

In the Servers list, click the name of the server to use. In the Analog tag and Discrete tag lists, specify the names of the tags to analyze. Click the ellipsis button to open the Tag Picker and browse for the tags. For more information, see Tag Picker on page 51.

ActiveFactory Software Users Guide

274

Chapter 5 ActiveFactory Workbook

Click Next. The Tag Analysis - Step 3 of 4 dialog box appears.

10 Configure the resolution for the data to be returned. Number of rows: The number of rows to be returned

ActiveFactory Software Users Guide

Analyzing Tag Data

275

Values spaced every: The sampling rate, in

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Discrete Tag A3: Analog Tag A4: Row or resolution A5: Start Time A6: Duration

ActiveFactory Software Users Guide

276

Chapter 5 ActiveFactory Workbook

12 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell B2:
=wwDiscreteWideHistory(A1,A2,"Row" & A4,"Rel",A6 & "(" & A5 & ")","",TRUE, FALSE)

Each cell in F2:

=wwAnalogWideHistory(A1,A3,"Row1",B2,B2,FALSE, " ",TRUE,FALSE)

where the "B2, B2," portion of the function is the associated column used to determine the analog value at the time of the discrete tag transition. There are "hidden" values that appear in a font that matches the worksheet background. These values are used for the chart.

ActiveFactory Software Users Guide

Analyzing Tag Data

277

13 Optionally alter the results by changing values that

Analog/Discrete Pair Analysis

Use the Analog/Discrete Pair Analysis wizard to graph analog vs. discrete tags.
To analyze an analog-discrete pair 1

On the ActiveFactory menu, click Tag Analysis. The Tag Analysis dialog box appears.

2 3

Select Analog-Discrete pair analysis. Click Next. The Tag Analysis - Step 2 of 4 dialog box appears.

In the Servers list, click the name of the server to use.

ActiveFactory Software Users Guide

278

Chapter 5 ActiveFactory Workbook

In the Analog tag and Discrete tag lists, specify the names of the tags to analyze. Click the ellipsis button to open the Tag Picker and browse for the tags. For more information, see Tag Picker on page 51. Click Next. The Tag Analysis - Step 3 of 4 dialog box appears.

In the Starting time list, enter the starting time for the query. Click the arrow button to select a date from a calendar. In the Duration lists, specify the duration and the duration unit. For example, 10 hours. The duration is used to calculate the end date for the query. Click Next. The Tag Analysis - Step 4 of 4 dialog box appears.

10 Configure the resolution for the data to be returned. Number of rows: The number of rows to be returned

ActiveFactory Software Users Guide

Analyzing Tag Data

279

Values spaced every: The sampling rate, in

Information that you specified using the wizard are assigned to cells in the worksheet. For this particular example: A1: Server A2: Discrete tag A3: Analog tag A4: Row or resolution to use for the analog tag A5: Start time A6: Duration A7: Row or resolution to use for the discrete tag

ActiveFactory Software Users Guide

280

Chapter 5 ActiveFactory Workbook

12 Click in the workbook to view the functions that are

inserted to create the analysis report. In this example, click in the following cells to view the functions. Cell B2:
=wwDiscreteWideHistory(A1,A2,"Row" & A4,"Rel",A6 & "(" & A5 & ")"," ",TRUE, FALSE)

Cell F2:
=wwAnalogWideHistory(A1,A3,"Row" & A7,B2,B12,FALSE," ",TRUE, FALSE) 13 Optionally alter the results by changing values that

appear in the first column of the worksheet. If the calculation mode is set to automatic, any changes you make to the values in this column are immediately reflected in the worksheet.

Creating a Direct Query

You can either type in a SQL query (if you know SQL syntax) or use the query builder to create a query. The results are output to the workbook.
To perform a direct query 1

On the ActiveFactory menu, click Direct Query. The Direct Query dialog box appears.

In the Servers list, click the name of the server to use.

ActiveFactory Software Users Guide

Creating a Direct Query

281

In the Query window, type the SQL query to execute against the database. You can also click the query button to start the Query client tool. You can use the Query client to build a query, which is inserted into the Query window. For more information, see Chapter 4, ActiveFactory Query.

Select the Enter the results as an array-formula check box to insert the results as an array formula. An array formula can perform one or more calculations and then return either a single result or multiple results. An array formula allows for the resending of the query, since the query parameters are included in the cells that contain the query results. For more information, see Working with Functions, Formulas, and Cells on page 206. Select the Specify format options (select cells) check box to specify a range of cells that contain formatting information. The formatting information in the cells will be applied to the query results. For more information, see Selecting Cells on page 213. In the Select cell for output list, specify the location of the worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213.

ActiveFactory Software Users Guide

282

Chapter 5 ActiveFactory Workbook

Click OK.

To edit the query, click in the cell that contains the red triangle.

ActiveFactory Software Users Guide

Configuring Workbook Options

283

Configuring Workbook Options

You can configure global settings related to formatting, time zone usage, data sources, and other general options. You can also set values for formatting and date/time options and then reference them from functions in your workbook. Finally, you can set up custom filters for your reports.

Configuring Global Formatting Options

Formatting is applied to all of the data inserted as a result of using the Workbook wizards.
To configure formatting options 1 2

On the ActiveFactory menu, point to Options and then click Options. The Options dialog box appears. Click the Format tab.

Configure the column headings. Display heading: Display the column heading for the results in the worksheet.
Bold: Display the column heading in a bold font. Italics: Display the column heading in an italicized

font.
4

Select the Auto-fit results check box to adjust the worksheet columns so that the entire result text for a column appears. Configure the formatting for numerical values. Number format: If set to General, the numerical value displayed reflects the original value retrieved from the database. If set to Fixed, the retrieved value is rounded to a specified number of decimal places.

ActiveFactory Software Users Guide

284

Chapter 5 ActiveFactory Workbook

Decimal places: For a number format of Fixed, the

number of decimal places to display for the data value. This applies only to analog tags.
6 7 8

In the Date/time format list, click the formatting for the timestamps. In the Result alignment list, click the alignment for the returned data within the worksheet cells. Select the Check that specified tag(s) exist(s) check box to validate that the tag exists in the database prior to the function being executed. Select the Paste format options on worksheet check box to insert the default formatting options in the worksheet.

Note The inserted formatting information is not automatically updated if you change the options. 10 In the Select output cell list, specify the location of the

worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213.
11 Click OK.

If you select to output the formatting information, it appears in the sheet.

ActiveFactory Software Users Guide

Configuring Workbook Options

285

Referencing Formatting Options in a Query

Before you can reference the formatting options, you must have inserted them into a location in your worksheet. For more information, see Configuring Global Formatting Options on page 283. The following procedure assumes that you are using a wizard to create the query.
To reference formatting options in a query 1

In the wizard, select the Select cells to specify format

options.

ActiveFactory Software Users Guide

286

Chapter 5 ActiveFactory Workbook

Either type in the cell range that contains the formatting option values displayed in your spreadsheet or select the cells. For more information, see Selecting Cells on page 213.

The query results are formatted according to the option settings. Note that the function references the formatting option cells.

ActiveFactory Software Users Guide

Configuring Workbook Options

287

Using a Named Range for Formatting Options

Instead of referencing multiple cells that contain formatting options, you can give the group of cells a name and then reference just that name.
To use a named range 1

Insert the formatting options into a location in your worksheet. For more information, see Configuring Global Formatting Options on page 283. Select the cells that contain the options. In the Name Box list, type a name for the cell range.

2 3

Press Enter on your keyboard. You can then specify the named range in your queries.
4

ActiveFactory Software Users Guide

288

Chapter 5 ActiveFactory Workbook

The formula references the named range instead of the worksheet cells.

Changing Formatting Options in Named Range

If you have formatting options configured as a named range and are referencing the named range in a query, you can simply change the value in one or more cells and apply the changes.
To change a format option for a named range 1

Select one of the cells in the named range and change the value. For example, change the Italic Heading option from FALSE to TRUE. Select the cell containing the function that refers to the format named range. On the ActiveFactory menu, click Refresh Function.

2 3

Note The Refresh Sheet command refreshes the data values, but not the formatting.

The new formatting options are applied to the results.

ActiveFactory Software Users Guide

Configuring Workbook Options

289

Configuring Time Zone Options

The time zone settings are applied to all functions.
To configure time zone options 1 2

On the ActiveFactory menu, point to Options and then click Options. The Options dialog box appears. Click the Time Zone tab.

The grid displays the current time zone and daylight savings time settings for the following entities:
Entity Description

Application

The ActiveFactory Workbook application. You can select the time zone for the data as it appears in the Workbook application.

Client

The physical computer on which the Workbook application is installed. The time zone displayed for the client is for informational purposes only and cannot be changed using the Workbook application.

The IndustrialSQL Server historian(s) to which the Workbook application is currently connected. The time zone displayed for the server(s) is for informational purposes only and cannot be changed using the Workbook application.

ActiveFactory Software Users Guide

290

Chapter 5 ActiveFactory Workbook

In the Time zone list, click the name of the time zone to use for the Workbook application. The time zone for the Workbook application in the grid displays the new time zone picked. For example, consider a SCADA application that monitors a pipeline between Houston, Texas and Lake Forest, California. The Workbook application is installed on a computer located in Houston, Texas. Therefore, the time zone entry for the Client entity displays Central Standard Time. The server is also located in Houston, Texas. The time zone entry for the Server entity also displays Central Standard Time. You want to send a Workbook file to an engineer located at the start of the pipeline in Lake Forest to aid in troubleshooting a problem. You can set the time zone of the Workbook application to reflect the time of Lake Forest, California (Pacific Standard Time), so that the workbook that you send to the engineer displays data in a time zone that is relevant to him/her.

Click OK.

Configuring Data Source Options

The data source settings are applied to all functions.
To configure data source options 1 2

On the ActiveFactory menu, point to Options and then click Options. The Options dialog box appears. Click the Source tab.

In the Version (Legacy) area, specify what version of data should be retrieved. This setting is only relevant when retrieving data from an IndustrialSQL Server historian with a version earlier than 9.0.

ActiveFactory Software Users Guide

Configuring Workbook Options

291

Original: The original value as it was received from

the data source (for example, the I/O Server) to the IndustrialSQL Server.
Latest: The latest value that is stored in the

IndustrialSQL Server with the same timestamp as the original value. Multiple versions are created as the result of data inserts and updates.
4

Select the Retrieve history data from both manual and extension tables check box to retrieve data from both the manual and extension tables. Manual history tables: Normal SQL Server tables that are used to store data. These are the ManualAnalogHistory and ManualDiscreteHistory tables.
Extension tables: Logical tables that are populated

from the IndustrialSQL Server data files. These tables support the IndustrialSQL Server time domain extensions for handling data.
5

Click OK.

Configuring General Options

To configure general options 1 2

On the ActiveFactory menu, point to Options and then click Options. The Options dialog box appears. Click the General tab.

Select the Do not update functions when opening worksheet check box to prevent the functions from being refreshed when the worksheet is opened. Click OK.

ActiveFactory Software Users Guide

292

Chapter 5 ActiveFactory Workbook

Setting the Base Date and Base Time Parameters

The base date and base time parameters can be used within the history and aggregate functions instead of actual dates/times. The base date and base time are stored with the current workbook and affect only the active workbook. By using these parameters, you can create generic reports that accommodate any date/time; simply change the base date and base time for the workbook.
To set the base date and time 1

On the ActiveFactory menu, point to Options, and then click Set Base Date/Time. The Set Base Date/Time dialog box appears.

2 3

In the Base date list, configure the base date. If you want to insert the wwBaseDate() function in a cell, select the Insert wwBaseDate() function in selected cell check box and specify location of the worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. In the Base time list, configure the base time. If you want to insert the wwBaseTime() function in a cell, select the Insert wwBaseTime() function in selected cell check box and specify location of the worksheet cell(s) that will contain the output. Click on the button to select the cell(s) using your mouse. For more information, see Selecting Cells on page 213. Click OK. You are prompted to confirm the base date and base time.

4 5

ActiveFactory Software Users Guide

Configuring Workbook Options

293

Click OK. If you selected to insert the base date and/or base time, they appear in the spreadsheet.

Using "Binding" Options

In Excel, a group of cells (a range) can be referenced by a single name. A report that you create using ActiveFactory workbook can contain the named ranges "AFTagBinding," "AFStartBinding," and "AFEndBinding." The AFTagBinding range is a placeholder for one or more tags in the query. This range can accept different sets of tags assigned to it, allowing you to programmatically control the tags used for the query without altering the actual query string. This is very useful if you are publishing reports on demand; you can "bind" a set of tags or times to the report at runtime. The AFStartBinding and AFEndBinding ranges work the same as the AFTagBinding range, except that they are used as placeholders for the date and time specification. The binding values can be used in the following ways:

Publish the workbook report as a dynamic report to the ActiveFactory Reporting Website. The website user can select the report and then select a group of tags. When the report is run, the binding ranges are updated with the user-selected information, the queries are executed, and the finished report appears in the browser. Programmatically update the ranges using the RunReport method of either the ActiveFactory Workbook add-in or the WorkbookRunner object.

ActiveFactory Software Users Guide

294

Chapter 5 ActiveFactory Workbook

Creating a Bound Report

To create a "bound" report 1

Start one of the workbook data retrieval wizards. For example, the History Values wizard.

2 3

Click Binding Options to show the binding options. Click Use bound tags in the range named 'AFTagBinding' of type and then select the type of tag from the list. If the AFTagBinding range does not already exist for the current workbook, a new sheet is added to the workbook. You are prompted to confirm the creation.

ActiveFactory Software Users Guide

Configuring Workbook Options

295

Click OK. The AFBindings sheet is created for the current workbook.

You specify to use the AFStartBinding and AFEndBinding ranges when you select the date/time for the query.

ActiveFactory Software Users Guide

296

Chapter 5 ActiveFactory Workbook

Click Finish. The named ranges are used in the report instead of specific tags and/or starting and ending times.

Considerations for Changing Binding Values

If a graph is configured to display information for n number of tags and the tag binding range is programmatically edited to include more tags than that number, the graph does not include the additional tags. The data in the function, however, is updated to include all the tags. When you develop the report layout, be sure to allow adequate space for additional rows or columns that might appear as the result of changing the binding values or how the add-in RunReport method resizes the functions. The resizing logic is:

Check each filled cell in the sheet and determine if the cell contains an ActiveFactory function. If a cell contains a function, determine if it is an array function. If so, determine if the cell is the first cell in the array. If so, determine how many rows the array formula occupies and how many it needs to occupy as the result of the resizing. Add additional rows as needed.

If the add-in cannot add rows or additional columns, the function is not updated. The function occupies a single cell, indicated by red background as unable to be resized.

ActiveFactory Software Users Guide

Configuring Workbook Options

297

Time Options for Queries

You have three choices when setting the starting and ending timestamps for a workbook query: bound times, relative time, and absolute times.

Bound times
For a "bound" time, the values that are currently assigned to the AFStartBinding and AFEndBinding named ranges are used for the start and end times. For more information, see Using "Binding" Options on page 293. The Bound times option only appears if the Bound Tags of Type option is selected in a data retrieval wizard.

Relative time
You can define a query that uses a relative time in the past for the starting date. For example, the last five minutes from the current time.
To set a relative time 1

In the from list, select the date to use as the start date. Now: Use the current date and time.
Today: Use the current date and a time that you

specify.
Specify date: Use the date and time that you specify. BaseDate: Use the date and time as set by the global

base date and time options for the workbook. For more information, see Setting the Base Date and Base Time Parameters on page 292.
2 3

If necessary, specify a date and/or time. In the plus/minus list, select plus to go forward in time or minus to go backward in time, and then set the duration.

Absolute time
Absolute time uses fixed start and end dates that you specify. You can either specify a time range or a single point in time. If you specify a single point in time, only a single tag value at that point in time is retrieved.
To set an absolute time range

Do one of the following:

ActiveFactory Software Users Guide

298

Chapter 5 ActiveFactory Workbook

Select the top option to reference cells in the workbook sheet that contain the start and/or end date. Click the button to the right of the box to select the cell. For more information, see Selecting Cells on page 213. Select the bottom option to configure the start and/or end date. Click the button to the right of the box to select a date from a calendar.

To set a single point in time 1 2

Select the Single Value check box. Do one of the following: Select the top option to reference a cell in the workbook sheet that contains the date and time. Click the button to the right of the box to select the cell. For more information, see Selecting Cells on page 213.

Select the bottom option to specify the date and time directly. Click the button to the right of the box to select a date from a calendar.

Publishing Reports
You can publish spreadsheet reports to the ActiveFactory Reporting Website. When you publish a report, the report information is stored in special tables in the IndustrialSQL Server historian, and the file is copied to a folder on the ActiveFactory Reporting Website. When you publish a report, website users can view the report you published with only the browser software. Published report are of two types:

Static. For a static report, data is retrieved at the time the report is published to the Reporting Website. After that, its content remains static and doesnt change when users access it. Dynamic. For a dynamic report, new data is retrieved from the database every time a user requests the report.

Note the following restrictions when publishing reports:

Dont publish shared workbooks.

ActiveFactory Software Users Guide

Publishing Reports

299

If you create reports that use the wwHistory2 and wwWideHistory2 data retrieval functions introduced in ActiveFactory 9.2 (for example, reports created using the History Values wizard), dont publish them to an ActiveFactory 9.1 (or earlier) Reporting Website. These functions are only supported on a Reporting Website running on Wonderware Information Server 3.0 or later. The Reporting Website must be associated with the same IndustrialSQL Server historian(s) as the spreadsheet you want to publish.

Publishing a Static Workbook Report

For a static report, data is retrieved at the time the report is published to the Reporting Website. After that, its content remains static and doesnt change when users access it. If you want current data to be retrieved every time a user requests the report, use a dynamic on-demand report instead.
To publish a static workbook report 1 2

Create a workbook sheet and save it as an .xls file. On the ActiveFactory menu, point to Publish, and then click Static Report. The Publish Report dialog box appears.

The Report name box displays the name of the workbook report as it appears in the website. This name is automatically created based on the name of the file that is being published.
3

In the Server list, click the name of the IndustrialSQL Server historian on which to store the report publishing information.

ActiveFactory Software Users Guide

300

Chapter 5 ActiveFactory Workbook

In the Report site list, select the URL of the Reporting Website to which you want to publish the report. The report site may or may not be physically located on the IndustrialSQL Server computer.

5 6 7

In the Report type area, click Static. In the Folder list, click the name of the physical folder on the report site where the static report is posted. Click OK. The Report successfully published dialog box appears.

Note The ActiveFactory Reporting Website periodically scans the publishing folders for changes; a short delay may occur prior to the published report being displayed in the website. 8

To view the ActiveFactory Reporting Website, click Browse. Otherwise, click Done.

Publishing a Dynamic Workbook Report

Dynamic Workbook reports include on-demand reports and scheduled reports. On-demand reports are executed at a users request. Scheduled reports are executed automatically on a defined schedule.
To publish a dynamic workbook report 1 2

Create a workbook sheet and save it as an .xls file. On the File menu, point to Publish, and then click Dynamic Report. The Publish Report dialog box appears.

The Report name box displays the name of the report as it appears in the website. This name is automatically created based on the name of the file that is being published.

ActiveFactory Software Users Guide

Publishing Reports

301

In the Server list, click the name of the IndustrialSQL Server historian on which to store the report publishing information. In the Report site list, select the URL of the Reporting Website to which you want to publish the report. The report site may or may not be physically located on the IndustrialSQL Server computer.

In the Report type area, click either On demand or Scheduled, depending on the type of report you want to publish. If you selected On demand, in the Report Group list, click the name of the physical folder on the report site where the on demand report is posted. Skip to Step 9.

If you selected Scheduled, in the Schedules list, click the name of the time period that the scheduled report is run and posted to the Reporting Website.

8 9

To run the scheduled report immediately without waiting for the selected time period to elapse first, click Run now. Click OK. The Report successfully published dialog box appears.

Note The ActiveFactory Reporting Website periodically scans the publishing folders for changes. Therefore, a short delay may occur prior to the published report being displayed in the website. 10 To view the ActiveFactory Reporting Website, click Browse. Otherwise, click Done.

ActiveFactory Software Users Guide

302

Chapter 5 ActiveFactory Workbook

ActiveFactory Workbook Function Reference

This section describes the ActiveFactory Workbook functions and their arguments. For a description of the arguments, see Function Arguments on page 308. Required arguments are shown in a bold font.
Function Name Syntax Comments

wwAggregate

=wwAggregate( DataSource, TagRange, RowOrRes, Time1, Time2, AggCalc, ValueCriteria, OptionRange )

Returns an array. This function retrieves values from the AnalogHistory table for specified tags and then performs aggregate calculations. A single value is returned for each of the selected tags. Quality and value criteria can be specified. Use a row count of 0 to ensure that all stored values are included in the calculations.

wwAggregateWide

=wwAggregateWide( DataSource, TagRange, RowOrRes, Time1, Time2, AggCalc, TagCriteria, OptionRange )

Returns an array. This function retrieves values from the AnalogWideHistory table for specified tags and then returns an aggregate value for each tag. Use a row count of 0 to ensure that all stored values are included in the calculations.

wwAlarmLimits

=wwAlarmLimits( DataSource, TagRange, OptionRange )

Returns an array.

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

303

Function Name

Syntax

Comments

wwAnalogHistory

=wwAnalogHistory( DataSource, TagRange, RowOrRes, Time1, Time2, Interpolation, RetrievalMode, TimeDeadband, ValueDeadband, ValueCriteria, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwAnalogLive( DataSource, TagRange, DisplayTagname, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwAnalogTagDetails( DataSource, TagRange, Description, EngUnit, EURange, RawRange, Storage, OptionRange ) =wwAnalogWideHistory( DataSource, TagRange, RowOrRes, Time1, Time2, Interpolation, TagCriteria, DisplayDatetime, DisplayMilliseconds, OptionRange ) =wwBaseDate()

Returns an array. If the retrieval mode is set to delta, then a time deadband and value deadband may be specified.

wwAnalogLive

Returns an array.

wwAnalogTagDetail s

Returns an array.

wwAnalogWideHisto ry

Returns an array. The cyclic retrieval mode is used.

wwBaseDate

Returns a string. Inserts the current base date into a cell.

wwBaseTime

=wwBaseTime()

Returns a string. Inserts the current base time into a cell. The base time can be used in conjunction with the base date to specify "relative" time periods for queries.

ActiveFactory Software Users Guide

304

Chapter 5 ActiveFactory Workbook

Function Name

Syntax

Comments

wwDiscreteHistory

=wwDiscreteHistory( DataSource, TagRange, RowOrRes, Time1, Time2, RetrievalMode, TimeDeadband, ValueCriteria, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality OptionRange ) =wwDiscreteLive( DataSource, TagRange, DisplayTagname, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwDiscreteTagDetails( DataSource, TagRange, Description, Messages, Storage, OptionRange ) =wwDiscreteWideHistory( DataSource, TagRange, RowOrRes, Time1, Time2, TagCriteria, DisplayDatetime, DisplayMilliseconds, OptionRange ) =wwEventHistory( DataSource, TagRange, Time1, Time2, ValueCriteria, DetectDatetime, Datetime, OptionRange ) =wwEventSnapshot( DataSource, EventTagRange, SnapshotTagRange, SnapshotTagType, Time1, Time2, DetectDatetime, DisplayQuality, ReplacePoorQuality, OptionRange )

Returns an array. If the retrieval mode is set to delta, then a time deadband may be specified.

wwDiscreteLive

Returns an array.

wwDiscreteTagDetai ls

Returns an array.

wwDiscreteWideHis tory

Returns an array. The delta retrieval mode is used.

wwEventHistory

Returns an array. The first 100 rows are returned. Returns an array.

wwEventSnapshot

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

305

Function Name

Syntax

Comments

wwEventTagDetails

=wwEventTagDetails( DataSource, TagRange, Description, TimeDeadband, DetectorType, ActionType, Status, Logged, ScanRate, Reset, OptionRange ) =wwHistory( DataSource, TagRange, RowOrRes, Time1, Time2, Interpolation, RetrievalMode, TimeDeadband, ValueDeadband, ValueCriteria, EdgeDetection, HistoryVersion, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, DisplayOPCQuality, DisplayAsWide, OrderBy, OptionRange ) wwHistory2( DataSource, TagRange, RowOrRes, Time1, Time2, Interpolation, RetrievalMode, TimeDeadband, ValueDeadband, RowLimit, TimestampRule, QualityRule, State, StateCalculation, ValueCriteria, EdgeDetection, HistoryVersion, ReplacePoorQuality, DisplayAsWide, UseStringHistory, OrderBy, DisplayFlags ) =wwLive( DataSource, TagRange, DisplayTagname, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, DisplayOPCQuality, OptionRange ) =wwQuery( DataSource, SQLQuery, OptionRange )

Returns an array.

wwHistory

Returns an array. Use with IndustrialSQL Server 8.0 historian.

wwHistory2

Returns an array. Use with IndustrialSQL Server 9.0 historian or later.

wwLive

Returns an array. Use with IndustrialSQL Server 8.0 historian or later.

wwQuery

Returns an array. Returns the results of a SQL statement.

ActiveFactory Software Users Guide

306

Chapter 5 ActiveFactory Workbook

Function Name

Syntax

Comments

wwRefreshFunction

=wwRefreshFunction()

Refreshes the array-formula of the selected cell. Returns a Boolean value indicating the success or failure of the refresh operation.

wwStringHistory

=wwStringHistory( DataSource, TagRange, Time1, Time2, ValueCriteria, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwStringLive( DataSource, TagRange, DisplayTagname, DisplayDatetime, DisplayMilliseconds, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwStringTagDetails( DataSource, TagRange, Description, MaxLength, OptionRange ) =wwSummaryTags( DataSource, TagFilter, DescriptionFilter, Description, SummaryPeriod, SummaryType, OptionRange )

Returns an array. The first 100 rows are returned.

wwStringLive

Returns an array.

wwStringTagDetails

Returns an array.

wwSummaryTags

Returns an array. Returns tags that have been configured to generate summary data. Filters can be used to show which tags are configured for different summary durations or type (min, max, avg, sum).

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

307

Function Name

Syntax

Comments

wwSummaryTagVal ues

=wwSummaryTagValues( DataSource, TagRange, SummaryType, SummaryPeriod, Time1, Time2, DisplayDatetime, DisplayQuality, ReplacePoorQuality, OptionRange ) =wwTagSearch( DataSource, TagType, TagFilter, DescriptionFilter, Description, OptionRange )

Returns an array.

wwTagSearch

Returns an array. This function is not inserted into a worksheet cell when executed using the Tag Search menu command. Returns an array. Use with IndustrialSQL Server 8.0 historian.

wwWideHistory

=wwWideHistory( DataSource, TagRange, RowOrRes, Time1, Time2, Interpolation, RetrievalMode, TagCriteria, EdgeDetection, HistoryVersion, DisplayDatetime, DisplayMilliseconds, OrderBy, OptionRange ) =wwWideHistory2( DataSource, TagRange, RowOrRes, Time1, Time2, InterpolationType, RetrievalMode, TimeDeadband, ValueDeadband, RowLimit, TimestampRule, QualityRule, State, StateCalculation, TagCriteria, EdgeDetection, HistoryVersion, OrderBy, DisplayFlags )

wwWideHistory2

Returns an array. Use with IndustrialSQL Server 9.0 historian or later.

ActiveFactory Software Users Guide

308

Chapter 5 ActiveFactory Workbook

Function Arguments
The following arguments are used for ActiveFactory Workbook functions.

ActionType
The unique identifier for a particular type of action. Event tags and actions are linked via this key. The event subsystem relies on the following values, which are added during installation: 1 = No action; 2 = Generic SQL; 3 = Snapshot; 4 = E-mail; 5 = Deadband; 6 = Summary. TRUE = Include the action type in the results. FALSE = Do not include the action type in the results.

AggCalc
Specifies what aggregate calculation is performed for the specified tagname. Valid values are: MIN = Calculate the minimum value. Delta retrieval is used. MAX = Calculate the maximum value. Delta retrieval is used. AVG = Calculate the average value. Cyclic retrieval is used. SUM = Calculate the total value. Cyclic retrieval is used. RNG = Calculate the range between MIN and MAX. Delta retrieval is used. STD = Calculate the standard deviation. Cyclic retrieval is used.

DataSource
The name of the server to use. You can also specify the worksheet cell containing the server to use.

DateTime
The date/time stamp.

Description
TRUE = Include the tag description in the results. Only the tags that meet the filtering criteria are included. FALSE = Do not include the tag description in the results.

DescriptionFilter
Type a description filter (or reference a cell).
Note Both % and * are valid wild-card characters.

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

309

DetectDatetime
TRUE = Include the date and time stamp of the event detection in the results. FALSE = Do not include the date/time in the results.

DetectorType
The unique identifier for a particular type of detector. Event tags and detectors are linked via this key. The event system relies on the following values, which are added during installation: 1 = System; 2 = External event; 3 = Generic SQL; 4 = Analog specific value; 5 = Discrete specific value; 6 = Time-based (schedule). TRUE = Include the detector type in the results. FALSE = Do not include the detector type in the results.

DisplayAsWide
TRUE = Return the results in the "wide" table format. That is, return a column of values for each tag specified in the function. FALSE = Return the results in the "narrow" table format. That is, return one value for each tag per row in the result set.

DisplayDatetime
TRUE = Include the date and time stamp in the results. FALSE = Do not include the date/time in the results.

DisplayFlags
Determines which data columns to include in the results. This parameter is an integer representing a bit pattern where each bit represents a data column. If the bit is set to 1, the column is included in the results. When you use this parameter with the wwHistory2 function, the bits are as follows (bit 0 is the rightmost bit):
Integer equivalent

Bit

Display option

18 17 16 15 14

wwStateCalc wwInterpolationType Value timestamp Show milliseconds in timestamp Quality

262144 131072 65536 32768 16384

ActiveFactory Software Users Guide

310

Chapter 5 ActiveFactory Workbook

Bit

Display option

Integer equivalent

13 12 11 10 9 8 7 6 5 4 3 2 1 0

OPC quality Quality detail wwRetrievalMode wwTagKey wwCycleCount wwResolution wwTimeDeadband wwValueDeadband wwTimestampRule wwQualityRule wwVersion wwTimeZone wwEdgeDetection PercentGood

8192 4096 2048 1024 512 256 128 64 32 16 8 4 2 1

When you use this parameter with the wwWideHistory2 function, the bits are as follows (bit 0 is the rightmost bit):
Integer equivalent

Bit

Display option

13 12 11 10 9 8 7 6 5 4 3 2

wwStateCalc wwInterpolationType Value timestamp Show milliseconds in timestamp wwRetrievalMode wwCycleCount wwResolution wwTimeDeadband wwValueDeadband wwTimestampRule wwQualityRule wwVersion

8192 4096 2048 1024 512 256 128 64 32 16 8 4

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

311

Bit

Display option

Integer equivalent

1 0

wwTimeZone wwEdgeDetection

2 1

For additional information on each display option, see Display Options Tab on page 233. To enable multiple display options, add up their integer equivalents and use the result as the value for this parameter. For example, if you want to use the wwHistory2 function and show the value timestamp with milliseconds as well as the history version, add the following values:
Integer equivalent

Bit

Display option

16 15 3

Value timestamp Show milliseconds in timestamp wwVersion

65536 32768 8

In this case, the parameter value is 98312 (65536 + 32768 + 8).

DisplayMilliseconds
TRUE = Include the milliseconds in results. By default, Microsoft Excel does not return milliseconds. FALSE = Do not include the milliseconds in the results.

DisplayQuality
TRUE = Include the quality value in the results. FALSE = Do not include the quality value in the results.

EdgeDetection
The moment at which the edge detection criteria is met. Valid values are:
Value Description

-1 0

No edge detection. None. Returns all rows that successfully meet the criteria; no edge detection is implemented at the specified resolution.

ActiveFactory Software Users Guide

312

Chapter 5 ActiveFactory Workbook

Value

Description

Leading. Returns only rows that are the first to successfully meet the criteria (return true) after a row did not successfully meet the criteria (returned false). Trailing. Returns only rows that are the first to fail the criteria (return false) after a row successfully met the criteria (returned true). Both. All rows satisfying both the leading and trailing conditions are returned.

EngUnit
TRUE = Include the engineering units in the results. FALSE = Do not include the engineering units in the results.

EURange
TRUE = Include the engineering range in the results. FALSE = Do not include the engineering range in the results.

HistoryVersion
Specifies the history version for data retrieval. For more information, see History Version on page 678. When used with the wwHistory2 or wwWideHistory2 functions, valid values are:
Value Description

0 1

Retrieve the latest values available for a tag. Retrieve the original values historized for a tag.

When used with other functions, valid values are:

Value Description

0 1 2

Not specified. Retrieve the original values historized for a tag. Retrieve the latest values available for a tag.

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

313

Interpolation
Specifies the interpolation type for data retrieval. When used with the wwHistory2 or wwWideHistory2 functions, valid values are:
Value Description

0 1 254

Use stair-step interpolation. Use linear interpolation. Use the tags interpolation setting specified at the IndustrialSQL Server historian level.

For more information on each option, see Interpolation Type on page 678. When used with other functions, valid values are: TRUE = Linear interpolation is performed between stored values. Interpolation is only an option for history functions that use cyclic retrieval for analog tag values and where no criteria is specified. If these conditions are not satisfied, interpolation is not performed. FALSE = Interpolation not performed.

Logged
Determines whether events are logged to the EventHistory table in the IndustrialSQL Server historian. 0 = Events are not logged; 1 = Events are logged. TRUE = Include the log setting in the results. FALSE = Do not include the log setting in the results.

MaxLength
TRUE = Include the maximum length of the string tag in the results. FALSE = Do not include the maximum length in the results.

Messages
TRUE = Include the messages associated with the discrete tag in the results. FALSE = Do not include the messages in the results.

ActiveFactory Software Users Guide

314

Chapter 5 ActiveFactory Workbook

OptionRange
Reference to a range of cells that contains formatting options, which are applied to the query results. The option range must be nine contiguous cells with the following acceptable values:
Option Valid values

Date Format Display Heading Bold Heading Italic Heading Result Alignment Number Format Decimal Places (only applied if the Number Format = Fixed) Fit Results Check tags exist

Any valid Excel date format. For example: hh:mm:ss. TRUE/FALSE TRUE/FALSE TRUE/FALSE right/left/center General/Fixed Integer value (0-10)

TRUE/FALSE TRUE/FALSE

If a heading currently exists, and the Display Heading option is set to FALSE, the heading is not deleted. Also, none of the other heading options are applied.

OrderBy
Text string that specifies the result order. For example: ORDER BY DateTime Desc.

QualityRule
Specifies the quality rule for data retrieval. Valid values are options 0, 1, and 3 of the aaQualityRules Enumeration. For more information, see aaQualityRules Enumeration on page 470.

RawRange
TRUE = Include the raw range for the tag in the results. FALSE = Do not include the raw range in the results.

ReplacePoorQuality
TRUE = Poor data quality is replaced with word "poor." FALSE = Data quality not replaced (default).

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

315

Reset
Setting this value has no effect. Provided for backward-compatibility only. Valid values are: TRUE, FALSE.

RetrievalMode
Specifies the type of data retrieval. When used with the wwHistory2 or wwWideHistory2 functions, valid values are options 0 to 11 of the aaRetrievalMode enumeration. For more information, see aaRetrievalMode Enumeration on page 471. When used with other functions, valid values are: TRUE = Cyclic retrieval. All stored data for the specified time interval is returned. This is the default retrieval mode. FALSE = Delta retrieval. Only values that changed during the specified time interval are returned.

RowLimit
Specifies the maximum number of rows for data retrieval. The row limit applies to each query. For more information, see Row Limit on page 682.

RowOrRes
Specifies whether the number of rows returned are based on data resolution or a row count. A resolution is the sampling interval between rows returned for the specified time period. A row count is the number of rows to be returned . You can either select a cell containing the RowOrRes value or type in the value. Examples are: Row50 = 50 evenly spaced rows returned. Row44 = 44 evenly spaced rows returned. Res1000 = n number of rows at a 1 second resolution. ResFull = n number of rows at a full resolution. The lowest storage rate of the selected tags is used. This is not an option for tags stored by exception (delta storage).

ScanRate
The scan rate is the interval, in milliseconds, at which the system will check to see if the event conditions specified by the detector have occurred. This value must be greater than or equal to 500 milliseconds, and less than or equal to 1 hour (3600000 ms). TRUE = Include the scan rate for the event tag in the results. FALSE = Do not include the scan rate in the results.

ActiveFactory Software Users Guide

316

Chapter 5 ActiveFactory Workbook

SnapshotTagRange
The range of cells that contains the names of snapshot tags for the query.

SnapshotTagType
Specifies the type of snapshot tag. Valid values are: Analog, Discrete, String.

State
Specifies the state for which Time-in-State data is retrieved for a tag. This parameter is only relevant for Time-in-State retrieval mode. It specifies the unique tag state for which Time-in-State information is calculated based on the calculation type specified by the StateCalculation parameter.

StateCalculation
Specifies the calculation type for Time-in-State data retrieval. Valid values are options 0 to 4 of the aaStateCalculation Enumeration. For more information, see aaStateCalculation Enumeration on page 472.

Status
The flag used by the event system at system startup and during runtime to determine if the event tag has been modified. 0 = Posted. Any changes have been detected and effected by the system. 1 = New. An event tag has been inserted, but is not yet executing. 2 = Modification. An event tag has been updated, but the older one is already executing. 98 = Disabled. 99 = Disabling requested. The event tag does not execute, even though the definition still exists in the schema. Note that there may be a delay of up to 30 seconds before a change in an event tag is seen by the running system. TRUE = Include the status for the event tag in the results. FALSE = Do not include the status in the results.

SQLQuery
The cell address of a custom SQL query.

Storage
TRUE = Include the storage type (and rate, if cyclic) for the tag in the results. FALSE = Do not include the storage type or rate in the results.

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

317

SummaryPeriod
The time period between summary calculations. Valid values are any of the configured summary periods.

SummaryType
Type of aggregation to be performed. Valid values are: Min, Max, Avg, Sum.

TagCriteria
Enables criteria to be applied to each of the tags for the query. For example, "AND Tag1 > 33"

TagFilter
The filter string for the tag search. You can also specify a cell address that contains the filter string.
Note Both % and * are valid wild-card characters.

TagRange
Contiguous range of cells containing the tagname(s) for the query. You can also specify a range of cells that contains the tagnames.

Time1
Determines the dates for the query, in conjunction with the Time2 argument. (starting time) = Absolute time. You can either enter the starting time or reference a cell containing a valid start time. The value of the Time2 argument is used to specify the end time. REL = Relative time. The value of the Time2 argument are used to specify a reference from the base date. This argument accepts date/times as real (double) numbers, in addition to dates.

Time2
Determines the dates for the query, in conjunction with the Time1 argument. If the Time1 argument contains the starting time, specify the end time of the query. If the Time1 argument is set to REL (relative time), specify the time relative to the base date. The required form is: ###T(##:##:##) where ### = Number of time units from the date/time.

ActiveFactory Software Users Guide

318

Chapter 5 ActiveFactory Workbook

T = Time unit (d=days, h=hours, m=minutes, and s=seconds). (##:##:##) = Time that the time units are relative to. This time and the base date are used together to determine the date/time. To specify the now as the date/time, leave the parentheses empty. Examples are: +20m(5:00) -20m() -20m(#Time) Starting at 5:00 of the BaseDate, ending 20 minutes later. Starting 20 minutes ago, ending now. Uses the configured base time.

This argument accepts date/times as real (double) numbers, in addition to dates.

TimeDeadband
The minimum time, in milliseconds, between returned values for a single tag. Applies only to delta retrieval.

TimestampRule
Specifies the timestamp rule for data retrieval. Valid values are options 0, 1, and 3 of the aaTimeStampRules Enumeration. For more information, see aaTimeStampRules Enumeration on page 473.

ValueCriteria
Enables a criterion to be specified for the tagname value. The criterion acts as a calculation filter. For example, if you are performing aggregate calculations on the tag "SysTimeSec" and want the aggregation based only on values > 20, set this parameter to: "value > 20 AND value IS NOT NULL" "quality = 0" "value > 20 AND quality = 0"

ValueDeadband
The percentage of full scale (range), in engineering units. Any value changes that are less than this percentage are not returned. Applies only to delta retrieval.

ActiveFactory Software Users Guide

ActiveFactory Workbook Function Reference

319

Error Messages for Functions

The following table lists the error messages produced by the ActiveFactory software for functions.
Error Message Description

NoServer NoConnection QueryError

No server is configured. There is no connection the server. A general error occurred while data was being retrieved, most likely due to a SQL syntax problem. No records were returned. The tag range argument does not contain valid tags. The function argument "CalcType" is invalid. The function argument "Cyclic" is invalid. The function argument "Resolution" is invalid.

NoRecords InvalidTags CalcType InvalidCyclic Resolution

For unexpected errors, the actual exception message text is returned.

Migrating History Data Retrieval Functions

Workbooks created with earlier versions of ActiveFactory software may contain calls to the wwHistory and wwWideHistory functions. Instead of manually updating these calls to use the new wwHistory2 and wwWideHistory2 functions, you can automatically update them using the History Values wizard.
To migrate history data retrieval functions 1 2

Open the workbook containing the function calls you want to migrate. Click the cell containing the call to wwHistory or wwWideHistory.

ActiveFactory Software Users Guide

320

Chapter 5 ActiveFactory Workbook

On the ActiveFactory menu, click Edit Function. The History Values - Step 1 of 4 dialog box appears.

4 5

Select the Upgrade function to newer format check box. Click Next. Go through the rest of the wizard as described in Retrieving History Values on page 229. After you finish the wizard, the function call is updated to use the new function.

ActiveFactory Software Users Guide

Viewing IndustrialSQL Server Historian Details

321

Viewing IndustrialSQL Server Historian Details

You can view details for all of the IndustrialSQL Server historians that have been configured for use within ActiveFactory Workbook.
To view server details 1

On the ActiveFactory menu, click IndustrialSQL Server Details. The Server Details dialog box appears.

2 3 4

In the Server list, click the name of the server for which you want to view details. Review the information for the server. Click OK.

ActiveFactory Software Users Guide

322

Chapter 5 ActiveFactory Workbook

ActiveFactory Software Users Guide

323

Chapter 6
ActiveFactory Report

ActiveFactory Report is an add-in to Microsoft Word that allows you to query one or more IndustrialSQL Server historian or SQL Server databases and return results to a Word document.

About Add-ins and Templates

ActiveFactory Report is an add-in to Microsoft Word. An add-in is a supplemental program that runs within the Microsoft Word application and provides custom features and specialized commands. If the ActiveFactory Report add-in is installed, an additional menu is added to Microsoft Word. After the add-in is loaded, the ActiveFactory menu contains all of the commands you use to create a report document or report template using data from an IndustrialSQL Server historian or a normal SQL Server database.
Note You can manually load/unload the ActiveFactory Report add-in. For more information, see Manually Loading/Unloading the Add-In on page 327.

The ActiveFactory Report default template, HistClient.dot, is a blank template to use as the starting point for any report documents or additional templates that you want to create.

ActiveFactory Software Users Guide

324

Chapter 6 ActiveFactory Report

Getting Started
Use this section to get started with ActiveFactory.
To get started with ActiveFactory Report 1

Create a new Word document based on the HistClient.dot template by doing any of the following. From the Start menu on the Windows Taskbar, point to Programs, point to the Wonderware program group, point to the ActiveFactory program group, and then click Report.

Open Word. On the ActiveFactory menu, click Open Report. In the New dialog box that appears, select to create a new blank document and then click OK. Open Word. On the File menu, click New. Right-click on the HistClient.dot file in Windows Explorer and then click New. By default, the HistClient.dot file is installed in the C:\Program Files\Common Files\ArchestrA and c:\Program folders.
Files\Microsoft Office\OFFICE11\STARTUP

A new blank document appears in Microsoft Word. The ActiveFactory menu appears in the menu bar.
ActiveFactory menu

Configure the connection to one or more servers. For more information, see Managing Server Connections on page 328.

ActiveFactory Software Users Guide

Getting Started

325

3 4

Create headings, explanatory paragraphs, sections, and so on, just as you would a normal Word document. Use the commands on the ActiveFactory menu to insert queries into your report document to retrieve data from the database when the report document is run. The results appear in the final report document. For more information, see Inserting a SQL Query on page 336. Optionally add date and time fields to your report document. For more information, see Inserting Date and Time Field Codes on page 341. The following example shows a configured report document that shows status information for an IndustrialSQL Server historian, as well as the date and time that the report document was run.

ActiveFactory Software Users Guide

326

Chapter 6 ActiveFactory Report

Run the report document. For more information, see Running a Report Document on page 331. When you run the report document, you can optionally save the file as a report template, which you can then use as a basis for other report documents, instead of the default HistClient.dot report template.

Note Running a report document replaces all of the field codes with actual data.

The ActiveFactory Report add-in fills in the report document with the data and the resulting report document appears. For example:

Save the run report document. For more information, see Saving Report Documents on page 332.

ActiveFactory Software Users Guide

Getting Started

327

Manually Loading/Unloading the Add-In

When you install the ActiveFactory software, the Report add-in is automatically loaded into Microsoft Word so that the ActiveFactory menu appears in the application. However, if you need to manually load or unload the add-in, the instructions are provided.
To manually load the add-in 1

On the Tools menu, click Templates and Add-Ins. The Templates and Add-Ins dialog box appears.

If the ActiveFactory add-in is not listed in the Checked items are currently loaded window, click Add and select the HistClient.dot file. By default, the HistClient.dot file is installed in the C:\Program Files\Common Files\ArchestrA and
C:\Program Files\Microsoft Office\OFFICE11\STARTUP folders.

3 4

Select the HistClient.dot check box in the Checked items are currently loaded window. Click OK.

To manually unload the add-in 1 2 3

On the Tools menu, click Add-Ins. The Add-Ins dialog box appears. Clear the HistClient.dot check box in the Checked items
are currently loaded window.

Click OK.

ActiveFactory Software Users Guide

328

Chapter 6 ActiveFactory Report

Managing Server Connections

You must specify one or more IndustrialSQL Server historians and/or SQL Servers as data sources for ActiveFactory Report.
To manage server connections 1 2

About Field Codes

A field code is a special string of text in a Microsoft Word document that includes instructions for data processing. Field codes can process data from inside the same document or from external sources. For ActiveFactory Report, field codes are used to contain the instructions for retrieving data from the database and returning the results to the report document. Field codes are present in report templates and report documents that have not yet been run. The following graphic shows how field codes appear when turned on and before the report document has been run. Field codes appear between the curly brackets { }.

ActiveFactory Software Users Guide

Getting Started

329

In the following graphic, the field codes are hidden. For more information on showing or hiding the field codes, see Showing/Hiding Field Codes on page 329.

Showing/Hiding Field Codes

To show/hide the field codes using the ActiveFactory menu On the ActiveFactory menu, click Toggle Field Codes. To show/hide the field codes using Word options 1

On the Tools menu, click Options. The Options dialog box appears.

ActiveFactory Software Users Guide

330

Chapter 6 ActiveFactory Report

Click the View tab.

3 4

In the Show area, select or clear the Field codes check box. Click OK.

Opening an Existing Report Document

For information on opening a new report document, see Getting Started on page 324.
To open an existing report document 1 2

On the File menu, click Open. The Open dialog box appears. Browse to the report to open.

ActiveFactory Software Users Guide

Running a Report Document

331

Running a Report Document

To run a report document 1 2

Open an existing report. On the ActiveFactory menu, click Run Report. When you run the report document, you can optionally save the document as a report template, which you can then use as a basis for other report documents, instead of the default HistClient.dot report template.

Note Running a report document replaces all the field codes with actual data.

The field codes are replaced with data and the resulting report document appears. For example:

ActiveFactory Software Users Guide

332

Chapter 6 ActiveFactory Report

Saving Report Documents

You can save a report document as:

A static .doc file. A new report template file. An HTML file.

You must save a report document as a report template prior to running the report document.

Saving a Report Document

You can save the report document at any time.
To save a report document 1

If you want to save a finished report document, run the report document so that data is retrieved and displayed in the report document. For more information, see Running a Report Document on page 331. On the ActiveFactory menu, click Save Report. The Save As dialog box appears. In the File name box, type a name for the report document. In the Save as type box, select Word Document. Click Save. The saved report document appears in Microsoft Word.

2 3 4 5

Saving a Configured Report Document as a Report Template

You can save a configured report document as a report template. However, the report document must not yet be run so that the field codes are still present in the report document.
To save a report document as a report template 1 2 3

On the ActiveFactory menu, click Save Report. The Save As dialog box appears. In the File name box, type a name for the report template. In the Save as type box, select Document Template.

ActiveFactory Software Users Guide

Saving Report Documents

333

Click Save. The .dot file appears in Microsoft Word.

You can then copy the report template file into the Microsoft Word template directory and use it to create report documents or as a basis to create new report template files.

ActiveFactory Software Users Guide

334

Chapter 6 ActiveFactory Report

Saving a Run Report Document as an HTML File

You can save a run report document as an HTML file so that it can be viewed in a browser. This type of report document is a static report document and can be published to a web site such as the ActiveFactory Reporting Website.
To save the results as HTML 1

If you have not done so already, run the report document so that the results appear.

2 3 4

On the ActiveFactory menu, click Save Results as HTML. The Save As dialog box appears. In the File name box, type a name for the report document. In the Save as type box, select Web Page.

ActiveFactory Software Users Guide

Saving Report Documents

335

Click Save. The .htm file appears in Microsoft Word.

On the File menu, click Web Page Preview to see the report document in a web browser.

ActiveFactory Software Users Guide

336

Chapter 6 ActiveFactory Report

Inserting a SQL Query

You can either type in a SQL query or launch the Query application to allow you to build the query using a point-and-click interface. If you want to use the Query application, you must configure at least one server connection. For more information, see Getting Started with Query on page 161. You can insert a query into either a report document or a report template.
To insert a SQL query 1 2

Click in the location in the report document or report template where you want to insert the query. On the ActiveFactory menu, click Insert Query. The Direct Query dialog box appears.

In the Servers list, click the name of the server to use.

ActiveFactory Software Users Guide

Inserting a SQL Query

337

In the Query box, type the SQL query that are executed against the database. You can also click the Query button to start the Query client tool. You can use the Query client to build a query, which is inserted into the Query box. For more information, see Chapter 4, ActiveFactory Query.

Configure how to display the results in the report document after it has been run. Show results in a single cell: Displays only the value in the first column of the first record in the returned record set. For example, if you queried the tagname and the description for a tag, only the value for the tagname is returned and displayed.
Show results in a table: Formats the returned data in

a Word table.
6

If you chose to format the results in a table, configure the table options. Include column headings: Use the column names for the returned data as column headings in the table.
Show headings on every page: Allow the column

headings to appear automatically on each page of the report document after it has been run, if the data table spans more than one page.

ActiveFactory Software Users Guide

338

Chapter 6 ActiveFactory Report

Format table: Click to pick the table format from a list. The Table AutoFormat dialog box appears. For more

information on this dialog box, see the Microsoft Word documentation.

Click OK. The query is inserted into the report document or report template.
7

ActiveFactory Software Users Guide

Inserting a SQL Query

339

Editing a Query
You can edit an existing query in a report template or in a report document that has not yet been run. (After a report document is run, all queries are converted to actual data.) You can either edit a query manually by typing changes in the query string or by using the Direct Query dialog box to select different options. Both methods require that the field codes for the report document or template are visible. For more information, see About Field Codes on page 328.
To edit a query using the Direct Query dialog box 1 2

In the report document or template, show the field codes so that you can see the query string. Select the query string so that it is highlighted.

ActiveFactory Software Users Guide

340

Chapter 6 ActiveFactory Report

On the ActiveFactory menu, click Edit Query. The Direct Query dialog box appears.

The selected query string appears in the Query window.

Either edit the query directly, or click the Query button to start the Query client tool. For more information, see Chapter 4, ActiveFactory Query. Change any of the options for the results. For more information, see Inserting a SQL Query on page 336. Click OK.

5 6

Using Date and Time Options

The following date and time options are available for a report.

Field codes for the report date and time. These codes provide an easy way to display the date and/or time that the report document was run in the body of the finished report document. For more information, see Inserting Date and Time Field Codes on page 341. Variables for relative date/time parameters in the WHERE clause for queries. For more information, see About Date and Time Wildcards on page 341.

ActiveFactory Software Users Guide

Using Date and Time Options

341

Inserting Date and Time Field Codes

You can insert field codes that are replaced with the date and time when the report document runs. Date and time field codes can be inserted into either a report template or in a report document that has not yet been run. (After a report document is run, all field codes are converted to actual data.)
To insert a date field On the ActiveFactory menu, click Insert Report Date. To insert a time field On the ActiveFactory menu, click Insert Report Time.

The appropriate field code is added to the report document or template.

When the report document is run, the date and/or time appear. For example:

For more information on viewing field codes, see Showing/Hiding Field Codes on page 329.

About Date and Time Wildcards

If you need to create recurring reports that cover the same time period, you can use date and time variables (called wildcards) in the report template. For example, you might want to produce a daily report that always covers the time period for the first shift, which starts at 8:00 a.m. The wildcards are:

#time Wildcard. Used as a placeholder for the current (today's) date, but a specified time. #date Wildcard. Used as a placeholder for a specific date and a specified time. #ReportTime Wildcard. Used as a placeholder for a defined report time to be used with either #date or #time.
ActiveFactory Software Users Guide

342

Chapter 6 ActiveFactory Report

The values used for the #date and #ReportTime wildcards are set for the entire report using the Report Options dialog box. For more information, see Configuring Report Options on page 345. These wildcards are handled by ActiveFactory Report; queries that include them do not work in other query tools, such as ActiveFactory Query or Microsoft Query Analyzer.

#time Wildcard
The #time wildcard is used to represent the current date (today) in the query. The use of this wildcard allows you to run the report document on any day and retrieve the data for the same time period. For example, the WHERE clause for a query for the last eight hours of today's data, starting at 5:00 p.m., is as follows:
WHERE DateTime >= '#time(5:0:0)-8h'

The time specification for the query is indicated in the parentheses. The valid duration units for the time offset are:

AND DateTime <= '#time(5:0:0)'

s = seconds mi = minutes h = hours d = days w = weeks mm = months

#date Wildcard
The #date wildcard is used to represent a specific date in the query. This wildcard is similar to the #time wildcard, but whereas the #time wildcard is a placeholder for the current date, the #date wildcard is a placeholder for a specific date. For example:
WHERE DateTime >= '#date(5:0:0)-8h'

This WHERE clause indicates to use the last eight hours of data, starting at 5:00 p.m., for the date that is specified by the Report Date option in the Report Options dialog box. For more information, see Configuring Report Options on page 345. The time specification for the query is indicated in the parentheses.

AND DateTime <= '#date(5:0:0)'

ActiveFactory Software Users Guide

Using Date and Time Options

343

The valid duration units for the time offset are:

s = seconds mi = minutes h = hours d = days w = weeks mm = months

#ReportTime Wildcard
The #ReportTime wildcard is used to represent the report time in the query. This wildcard can be used with the #time and #date wildcards. For example:
WHERE DateTime >= '#time(#ReportTime)-8h'

This WHERE clause indicates to use the last eight hours of data, for today's date, for the time that is specified by the Report Time option in the Report Options dialog box. Another example is:
WHERE DateTime >= '#date(#ReportTime)-8h'

AND DateTime <= '#time(#ReportTime)'

AND DateTime <= '#date(#ReportTime)'

This WHERE clause indicates to use the last eight hours of data for the date and time specified by the Report Date and Report Time options, respectively, in the Report Options dialog box. For more information, see Configuring Report Options on page 345. The valid duration units for the time offset are:

s = seconds mi = minutes h = hours d = days w = weeks mm = months

ActiveFactory Software Users Guide

344

Chapter 6 ActiveFactory Report

Inserting Date and Time Wildcards

For more information on wildcards, see About Date and Time Wildcards on page 341.
To use date and time wildcards 1 2

On the ActiveFactory menu, click Options. Configure the report to use wildcards and set the base date and base time. For more information, see Configuring Report Options on page 345. On the ActiveFactory menu, click Insert Query. In the Query window, type the SQL query or use the Query client to build the query. For more information, see Chapter 4, ActiveFactory Query.

3 4

Click OK. The Additional Time Options dialog box appears.

ActiveFactory Software Users Guide

Configuring Report Options

345

6 7

Click Yes, insert wildcards. In the Wildcards for date area, configure which date is substituted for the date in the query. Date when report is run: The day that the report document is run is used as the base date for the query. This option is used for the #.
Date as specified in Report Options: The date specified

in the report options is used as the base date for the query. For more information, see Configuring Report Options on page 345.
8

In the Wildcards for time area, configure which time is substituted for the base time in the query. (list box): A base time for the query.
Time specified in Report Options: The time specified in

the report options is used as the base time for the query. For more information, see Configuring Report Options on page 345. Click OK. The wildcards is inserted into the query for the date/time parameters and then updated with the appropriate date/time when the report document is run.
9

Configuring Report Options

To configure general report options 1

On the ActiveFactory menu, click Options. The Report Options dialog box appears.

ActiveFactory Software Users Guide

346

Chapter 6 ActiveFactory Report

In the Date and time area, configure the base time and date used for the report wildcards. Every time this report document is run, the same date and time are used. For more information on the wildcards, see About Date and Time Wildcards on page 341. Report date: The date to be used as the base date for a relative date/time in the query. Click the arrow button to access a calendar.
Report time: The time to be used as for a relative date/time in the query.

Select the Suppress messages when report is running check box to stop dialog box messages from being displayed when the report is running. Select the Use date/time wildcards check box to allow for the use of wildcards in a query. You are prompted to specify the wildcards during the query configuration. In the Maximum rows per query list, specify the maximum number of rows returned for the query. Click OK.

5 6

ActiveFactory Software Users Guide

347

Chapter 7
Introduction to Controls and Objects

ActiveFactory controls and objects can be run in any application that can function as a .NET or an ActiveX control container, such as InTouch HMI software, Visual Basic, Visual C#, Visual C++, web pages, and so on. For InTouch HMI software, you can select these controls from within WindowMaker when you create your runtime graphical user interface. ActiveFactory objects and controls must be installed on the computer running the application that you want to use them in. For example, if you want to use the aaHistClientTrend control in InTouch HMI software, you must install the Trend files on the InTouch computer. Technically, the ActiveX versions of the controls can be used within Internet Explorer. However, because Internet Explorer is a native .NET control container, use the native controls instead of the ActiveX versions.

About the ActiveFactory Controls and Objects

The ActiveFactory controls can be categorized as either application controls, building block controls, or core functionality controls. An application-level control runs within the container application, but functions as if it were a stand-alone application. This type of control does not require extensive scripting to function. Application-level controls include:

aaHistClientTrend Control

ActiveFactory Software Users Guide

348

Chapter 7 Introduction to Controls and Objects

aaHistClientQuery Control

A building block control provides specific functionality for use within an application. Scripting is required to make these controls functional. Building block controls include:

aaHistClientTimeRangePicker Control aaHistClientTagPicker Control aaHistClientSingleValueEntry Control aaHistClientActiveDataGrid Control

The following low-level controls and objects are used by either an application or building block control. Core functionality controls include:

aaTag Object aaServer Object aaServers Object aaHistClientWorkbookRunner Object aaHistClientReportRunner Object

About Properties, Methods, and Events

There are three main aspects of controls: properties, methods and events.

Properties are attributes of the control that you can set. For example, a property can control what background color is used for the trend chart in the Trend control. A method performs a function for a control. For example, a method can set the time span for the query. An event is an occurrence of something within or to the control (such as a mouse click or a data change) that you might want to respond to through scripting (known as an event handler).

ActiveFactory Software Users Guide

Getting Started with the Controls

349

Getting Started with the Controls

When you use an ActiveFactory control in a container application (for example, InTouch HMI software), perform the following for each control:

Name the control. When you first place a control in an application, a name is assigned to it by default. You can change this name to something more meaningful to you. Also, if you use more than one instance of the same control in your application, you must distinguish them by giving them different names. For information on naming a control, see the documentation for your container application (for example, your InTouch User's Guide).

Configure general properties. General properties pertain to how the control appears to the user at runtime. General properties can be configured through a user interface property panel during the design of your application, or at runtime with scripting in the container application.

Use any of the control's properties, methods, and events in scripts in your application.

Using the Controls in Different Environments

There are two versions for each of the ActiveFactory controls: one for use within a ActiveX control containers and one for use within .NET containers. ActiveX control containers include Visual Interdev, Visual Basic, Visual C++, InTouch HMI software, and so on. .NET containers include VB.NET, C#, ASP.NET, and so on. The ActiveX versions are named according to the following convention: aaHistClientXXX Control The .NET versions are named as follows: ArchestrA.HistClient.UI.aaXXXControl For example, the Trend control is implemented as two versions: aaHistClientTrend Control and ArchestrA.HistClient.UI.aaTrendControl.

ActiveFactory Software Users Guide

350

Chapter 7 Introduction to Controls and Objects

If a container supports both .NET and ActiveX controls, such as Internet Explorer, use the .NET version, since that is the native form of the controls for the ActiveFactory software. Embedding the ActiveX versions of the controls in Internet Explorer is not recommended. If you are using Visual Interdev, manually edit the HTML to use the .NET version of the control. The following HTML example shows how to embed the .NET control on an HTML form:
<body> <object id="Trend1" classid="http:aaHistClientUI.dll#ArchestrA.HistClient .UI.aaTrendControl" height="300" width="300" VIEWASTEXT></object> </body> </html>

ActiveX controls that are embedded in HTML are loaded if you launch the .htm file within Windows Explorer (that is, if the URL starts with file://). However, a URL that starts with file:// does not load .NET controls. You must use http://, which means you must create a web share for the folder in which the .htm file resides.

Using the Controls within InTouch HMI Software

Before any control can be used in InTouch HMI software, it must be installed. See the InTouch documentation for information on how to install a control and insert it into an application window. You must assign InTouch tagnames to the properties of a control. Keep in mind that a property must be assigned to the equivalent InTouch tagname type. For example, a message property must be assigned to an InTouch message tagname. Although you can use the Properties dialog box to assign tagnames to properties, it is easier to set the properties directly through QuickScripts. For events, if the window containing a control is closed, its event scripts and any other InTouch QuickScripts containing script functions associated with that control does not execute properly.

ActiveFactory Software Users Guide

Using the Controls in Different Environments

351

Using the Controls in Microsoft Office

To use the ActiveFactory controls on a Visual Basic for Applications (VBA) user form, add them to the forms Controls collection dynamically using a call like the following:
Set NewControl = UserForm1.Controls.Add( <controls ProgID etc.> )

It is not possible to drop them on the user form in the visual editing environment.

Mapping for Numerical Data Types

The following rules explain how data types are handled for the containers in which the ActiveFactory controls can be run. In C# or .NET environments:

Byte = 8 bits Int = 32 bits Long = 64 bits Short = 16 bits

In C++ or IDL environments (versions prior to ActiveFactory 9.0 software):

Byte = 8 bits Int = 32 bits Long = 32 bits Short = 16 bits

The size of long in the C++/IDL environment is the same as the size of int in C#. In InTouch HMI software, an integer value is stored in 32 bits.

ActiveFactory Software Users Guide

352

Chapter 7 Introduction to Controls and Objects

ActiveFactory Software Users Guide

353

Chapter 8
aaHistClientTrend Control

The aaHistClientTrend control allows you to run the ActiveFactory Trend program (or a functional subset) from within the Wonderware InTouch HMI software or a .NET container like Visual Basic .NET or Internet Explorer. For more information on using ActiveFactory Trend, see Chapter 3, ActiveFactory Trend.

Using aaHistClientTrend at Runtime

At runtime, aaHistClientTrend trends configured tag values from the IndustrialSQL Server historian in the container application. You can use aaHistClientTrend just as you would use the ActiveFactory Trend application. For more information on using ActiveFactory Trend, see ActiveFactory Trend on page 61.

Using aaHistClientTrend in an Application

aaHistClientTrend is capable of running with all of the functionality of the ActiveFactory Trend application. You can also use the aaHistClientTrend control's properties, methods, and events in runtime scripts in your application to control the functionality that is available to the runtime user. For example, maybe you want to limit the functionality of aaHistClientTrend to only allow the runtime operator to connect to an IndustrialSQL Server historian, load a set of predefined tags, and then trend them in live mode.

ActiveFactory Software Users Guide

354

Chapter 8 aaHistClientTrend Control

The following InTouch script illustrates how to log on to the server, add a tag to the trend, hide some of the navigation controls for a trend, and start the trend in live mode.
#aaHistClientTrend1.AddServer("MyInSQL", "wwUser", "wwuser", 1); #aaHistClientTrend1.AddTag("MyInSQL", "SysTimeSec"); #aaHistClientTrend1.TagPickerVisible = 0; #aaHistClientTrend1.TimeBarVisible = 0; #aaHistClientTrend1.RealTimeMode = 1;

Adding aaHistClientTrend to an InTouch Window

To add the aaHistClientTrend control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientTrend control. Click OK.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

355

The control appears in the window.

aaHistClientTrend Properties
The aaHistClientTrend properties include:

AddMultipleTags AllowContextMenu AllowGridEditing AlwaysUseFullForXYScatterPlots AnalogPlottingAlgorithm ApplyRubberBandToAllTags AutoRefreshMode BackColor BackGradient BackGradientEndColor BackImage BorderColor BorderStyle BorderWidth ChartType

ActiveFactory Software Users Guide

356

Chapter 8 aaHistClientTrend Control

CurrentServerName CurrentTagColor CurrentTagCycleCount CurrentTagEffectiveRetrievalMode CurrentTagFormat CurrentTagHistoryVersion CurrentTagIndex CurrentTagInterpolationType CurrentTagName CurrentTagNumStyles CurrentTagOffsetMS CurrentTagPenStyle CurrentTagPenWidth CurrentTagPrecision CurrentTagQualityRule CurrentTagResolution CurrentTagRetrievalMode CurrentTagRetrievalStyle CurrentTagRowLimit CurrentTagStartDate CurrentTagState CurrentTagStateCalculation CurrentTagTargetRegionVisible CurrentTagTimeDeadband CurrentTagTimeStampRule CurrentTagTrendType CurrentTagUseAutoCycles CurrentTagUseResolution CurrentTagValAtX1 CurrentTagValAtX2 CurrentTagValueDeadband

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

357

CurrentValOfX1 CurrentValOfX2 CurrentValOfY1 CurrentValOfY2 CurrentXAxisTagIndex CurrentXAxisTagName CurrentXAxisTagServerName CyclicRows DataPointLabelType DateMode DatePickerFormatString DefaultTagFormat DefaultTagPrecision Enabled EnableDeltaRetrieval EnableSummaryData EnableTimeOffsets EndDate FileName GridColor GridHorizontal GridVertical GridVisible HideCurrentTag HighlightCurrentTag HistorySource LiveModeRate LockDown LoginTimeout MaxDeltaSamples MaxMinutesForDeltaAnalog

ActiveFactory Software Users Guide

358

Chapter 8 aaHistClientTrend Control

MaxMinutesForDeltaDiscrete MaxSamplesPerTag MovingAverageMode MovingAverageSamples NumDataPointLabels NumTimeAxisGridPerValue NumTimeAxisValues NumXValueAxisGridLinesPerLabel NumXValueAxisLabels NumYAxisGridPerValue NumYAxisValues PanPercentage PlaybackSpeed PlotColor PlotGradient PlotGradientEndColor PlotImage PrintShowActiveTag PrintShowMarkers PrintShowTitle PrintTitle PublicAnnotations QueryTimeout RealTimeMode RealTimeRate RetrievalOptionsCycleCount RetrievalOptionsHistoryVersion RetrievalOptionsInterpolationType RetrievalOptionsNumStyles RetrievalOptionsQualityRule RetrievalOptionsResolution

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

359

RetrievalOptionsRetrievalMode RetrievalOptionsRetrievalStyle RetrievalOptionsRowLimit RetrievalOptionsState RetrievalOptionsStateCalculation RetrievalOptionsTimeDeadband RetrievalOptionsTimeStampRule RetrievalOptionsUseAutoCycles RetrievalOptionsUseResolution RetrievalOptionsValueDeadband RetrieveAnnotations RetrieveExtensionData RetrieveManualData RTRate Rubberband RubberbandAll RubberBandScaling Servers ShowLimits ShowValuesAtCursor ShowWaitCursor ShowXAxisCursors ShowYAxisCursor SingleTagMode StartDate SummaryDataMode SupressErrors TagGridOrientation TagPicker TagPickerVisible TargetRegionExcursionType

ActiveFactory Software Users Guide

360

Chapter 8 aaHistClientTrend Control

TargetRegionOpacity TimeBarVisible TimeBarVisible2 TimeSelector ToolBarVisible ToolbarVisible2 ToolTipText TraceGradientEndingPercentage TraceGradientStartingPercentage TraceGradientType UpdateToCurrentTimeState UseIniFile ValueAxisLabel Visible XCursor1Color XCursor1Pos XCursor2Color XCursor2Pos YCursor1Color YCursor2Color ZoomOutPercentage

AddMultipleTags
The AddMultipleTags property is a read-write property that enables or disables the automatic refresh of the trend chart each time a tag is added.
Syntax
aaHistClientTrend.AddMultipleTags = discrete; Result = aaHistClientTrend.AddMultipleTags;

Remarks

You can set this property to True and then add multiple tags using a script without refreshing the graph. After adding the final tag, set this property back to False. The graph is automatically refreshed and shows all the tags that you added.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

361

The default is False.

AllowContextMenu
The AllowContextMenu property is a read-write property that enables or disables the Context menu for the control.
Syntax
aaHistClientTrend.AllowContextMenu = discrete; Result = aaHistClientTrend.AllowContextMenu;

Remarks

If this property is set to True, then the context menu appears when the runtime user right-clicks in the control. The default is True.

AllowGridEditing
The AllowGridEditing property is a read-write property that enables or disables the editing of the tag list that appears below the trend chart.
Syntax
aaHistClientTrend.AllowGridEditing = discrete; Result = aaHistClientTrend.AllowGridEditing;

Remarks

If this property is set to True, then the tag list can be edited. The default is True.

AlwaysUseFullForXYScatterPlots
This read-write property determines whether Full or Delta mode retrieval is forced for all tags in a scatter plot regardless of the retrieval settings that are configured at the application or tag level.
Syntax
aaHistClientTrend.AlwaysUseFullForXYScatterPlots = discrete; Result= aaHistClientTrend.AlwaysUseFullForXYScatterPlots;

Remarks

If this property is set to True, then full or delta retrieval is forced. Full retrieval is used when retrieving data from an IndustrialSQL Server historian with a version of 9.0 or higher. Delta retrieval is used for earlier server versions. The default is True. We recommend to keep this option enabled unless the nature of your data makes full retrieval impractical.

ActiveFactory Software Users Guide

362

Chapter 8 aaHistClientTrend Control

AnalogPlottingAlgorithm
The AnalogPlottingAlgorithm property is a read-write property that determines the type of the trend curve for all analog and discrete tags in the trend.
Syntax
aaHistClientTrend.AnalogPlottingAlgorithm = integer; Result = aaHistClientTrend.AnalogPlottingAlgorithm;

Remarks

Provided for backward compatibility. Use the CurrentTagTrendType property instead. Valid values: 0 = Stair-step curve; 1 = Line curve (interpolation).
Return Value

If all analog and discrete tags in the trend use the same curve type, the type is returned; otherwise, a 0 is returned. A return value of 0, therefore, can either mean that all tags use stair-step curves, or that they use different types.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

363

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpTag ScaleUpAllTags ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberbandAll RubberBandScaling

AutoRefreshMode
The AutoRefreshMode property is a read-write property that gets or sets when the Trend control is refreshed with data from the server.
Syntax
aaHistClientTrend.AutoRefreshMode = integer; Result = aaHistClientTrend.AutoRefreshMode;

Remarks

The following table describes the enumerations for this property:

Value Enumeration Description

0 1 2 3

Never OnAddTags OnTimeSpanC hange OnBoth

No automatic or manual refresh occurs. Automatic refresh occurs when tags are added. Automatic refresh occurs when the time span is changed. Automatic refresh occurs both when tags are added and the time span is changed. This is the default.

If you are adding multiple tags, set this property to 0 to prevent a refresh from occurring as each individual tag is added. When you are finished adding tags, set this property back to a non-zero value.

ActiveFactory Software Users Guide

364

Chapter 8 aaHistClientTrend Control

Changing the AutoRefreshMode property to a non-zero value only changes the mode setting and does not cause the trend to be refreshed. The default is 3.

BackColor
The BackColor property is a read-write property that gets or sets the background color of the chart.
Syntax
aaHistClientTrend.BackColor = integer; Result = aaHistClientTrend.BackColor;

Remarks

For information on setting the color value, see Color on page 638. The default is 16777215.

Related Topics
BackGradientEndColor BackImage BackGradient

BackGradient
The BackGradient property is a read-write property that gets or sets the type of background gradient for the chart.
Syntax
aaHistClientTrend.BackGradient = integer; Result = aaHistClientTrend.BackGradient;

Remarks

The gradient starts with the main background color and fade to the gradient end color. Use the BackColor property to set the main background color. Use the BackGradientEndColor property to set the ending gradient color. For more information on the values for the back gradient, see the aaTrendGradientType Enumeration on page 473. The default is 0.

Related Topics
BackColor BackGradientEndColor BackImage

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

365

BackGradientEndColor
The BackGradientEndColor property is a read-write property that gets or sets the background gradient end color of the chart.
Syntax
aaHistClientTrend.BackGradientEndColor = integer; Result = aaHistClientTrend.BackGradientEndColor;

Remarks

The gradient starts with the main background color and fades to the gradient end color. Use the BackColor property to set the main background color. Use the BackGradient property to set the type of gradient fill. For information on setting the color value, see Color on page 638. The default is 16777215.

Related Topics
BackColor BackImage BackGradient

BackImage
The BackImage property is a read-write property that gets or sets the background image for the chart.
Syntax
aaHistClientTrend.BackImage = message; Result = aaHistClientTrend.BackImage;

Remarks

The value of this property is the folder path and filename for the image. Supported image types are .jpeg, .gif, .bmp, and .png. This property has no default.

Related Topics
BackColor BackGradientEndColor BackGradient

BorderColor
The BorderColor property is a read-write property that gets or sets the color for the border of the graph.
Syntax
aaHistClientTrend.BorderColor = integer; Result = aaHistClientTrend.BorderColor;

ActiveFactory Software Users Guide

366

Chapter 8 aaHistClientTrend Control

Remarks

For information on setting the color value, see Color on page 638. The default is 0.

Valid values are 0 through 10. The default is 1.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

Remarks

For information on possible values, see aaInterpolationType Enumeration on page 470. This property is only relevant for the following retrieval modes: Interpolated, Best Fit, Average, and Integral. The default is 3 (use server default).

Related Topics
RetrievalOptionsInterpolationType

CurrentTagName
The CurrentTagName property is a read-only property that gets the name of the tag that is currently selected.
Syntax
Result = aaHistClientTrend.CurrentTagName;

Return Value

The result is a message.

Remarks

This property is not visible at design time. This property has no default.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

371

Related Topics
CurrentServerName CurrentTagColor CurrentTagFormat CurrentTagOffsetMS CurrentTagPenStyle CurrentTagPenWidth CurrentTagPrecision CurrentTagValAtX1 CurrentTagValAtX2

CurrentTagNumStyles
This read-only property returns the number of retrieval styles that are available for the current tag.
Syntax
Result = aaHistClientTrend.CurrentTagNumStyles;

Remarks

The count only includes retrieval styles for which a name is defined for the current locale. If no style names at all are defined for the current locale, the count for the en locale is returned. To return the name of a style with a specific number, use the CurrentTagGetStyle method.

Related Topics
CurrentTagRetrievalStyle RetrievalOptionsNumStyles CurrentTagGetStyle

CurrentTagOffsetMS
The CurrentTagOffsetMS property is a read-write property that gets or sets the amount of time that the trend curve will be shifted from the actual time.
Syntax
aaHistClientTrend.CurrentTagOffsetMS = integer; Result = aaHistClientTrend.CurrentTagOffsetMS;

Remarks

The offset, expressed in milliseconds, can be positive or negative. For more information, see Using Time Offsets to Compare Data on page 115. Setting this property updates the CurrentTagStartDate property accordingly. Due to the limited range for integer values, the maximum offset you can set using this property is about 29 days. For larger offsets, use the CurrentTagStartDate property.

ActiveFactory Software Users Guide

372

Chapter 8 aaHistClientTrend Control

The default is 0. This property is only relevant if the DateMode property is set to absolute mode.

Related Topics
CurrentServerName CurrentTagColor CurrentTagFormat CurrentTagName CurrentTagPenStyle CurrentTagPenWidth CurrentTagPrecision CurrentTagStartDate CurrentTagValAtX1 CurrentTagValAtX2 DateMode

CurrentTagPenStyle
The CurrentTagPenStyle property is a read-write property that gets or sets the style of the trend curve for the currently selected tag. For example, a solid or dashed line.
Syntax
aaHistClientTrend.CurrentTagPenStyle = integer; Result = aaHistClientTrend.CurrentTagPenStyle;

Remarks

Valid values are: 0 1 2 3 4 The default is 0. Solid Dashed Dotted DashDot DashDotDot

Related Topics
CurrentServerName CurrentTagColor CurrentTagFormat CurrentTagName CurrentTagOffsetMS CurrentTagPenWidth CurrentTagPrecision CurrentTagValAtX1 CurrentTagValAtX2

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

373

CurrentTagPenWidth
The CurrentTagPenWidth property is a read-write property that gets or sets the thickness of the trend curve for the currently selected tag.
Syntax
aaHistClientTrend.CurrentTagPenWidth = integer; Result = aaHistClientTrend.CurrentTagPenWidth;

Remarks

Valid values are 0 through 10. The default is 0.

Related Topics
CurrentServerName CurrentTagColor CurrentTagFormat CurrentTagName CurrentTagOffsetMS CurrentTagPenStyle CurrentTagPrecision CurrentTagValAtX1 CurrentTagValAtX2

CurrentTagPrecision
The CurrentTagPrecision property is a read-write property that gets or sets the number of decimal places to display for the data value. This applies only to analog tags.
Syntax
aaHistClientTrend.CurrentTagPrecision = integer; Result = aaHistClientTrend.CurrentTagPrecision;

Remarks

To set the tag to use the decimal format, use the DefaultTagFormat property. The default is 0.

Related Topics
CurrentTagFormat DefaultTagFormat DefaultTagPrecision

CurrentTagQualityRule
This read-write property determines the current tags quality rule for data retrieval. This setting overrides the default setting specified at the application level if the CurrentTagRetrievalStyle property is set to an option other than Style selected at option level.

ActiveFactory Software Users Guide

374

Chapter 8 aaHistClientTrend Control

Syntax
aaHistClientTrend.CurrentTagQualityRule = aaQualityRules; Result = aaHistClientTrend.CurrentTagQualityRule;

Remarks

For information on possible values, see aaQualityRules Enumeration on page 470. This property is relevant for all retrieval modes except the following: Cyclic, Delta, and Full. The default is 3 (use server default).

Related Topics
RetrievalOptionsQualityRule

CurrentTagResolution
This read-write property controls the current tags time interval for calculating the number of cycles in cycle-based data retrieval. This setting overrides the default setting specified at the application level if the CurrentTagRetrievalStyle property is set to an option other than Style selected at option level.
Syntax
aaHistClientTrend.CurrentTagResolution = integer; Result = aaHistClientTrend.CurrentTagResolution;

Remarks

This property is only relevant if the CurrentTagUseAutoCycles property is set to False, and the CurrentTagUseResolution property is set to True. Also, it may be overridden by a retrieval style setting. For more information, see Working with Retrieval Styles on page 684. The value of this property is a time interval in milliseconds. The aaHistClientTrend control divides the query duration by this interval and uses the result as the number of cycles for the query. This property is relevant for all retrieval modes except the following: Delta, Full, and Slope. Valid values: any positive integer or 0. If you specify 0, the cycle count is calculated automatically, just as if the CurrentTagUseAutoCycles property were set to True. The default is 0.

Related Topics
CurrentTagCycleCount CurrentTagUseAutoCycles CurrentTagUseResolution RetrievalOptionsResolution

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

375

CurrentTagRetrievalMode
This read-write property determines the current tags data retrieval mode. This setting overrides the default setting specified at the application level if the CurrentTagRetrievalStyle property is set to an option other than Style selected at option level.
Syntax
aaHistClientTrend.CurrentTagRetrievalMode = aaRetrievalMode; Result = aaHistClientTrend.CurrentTagRetrievalMode;

Remarks

This property may be overridden by a retrieval style setting. For more information, see Working with Retrieval Styles on page 684. For information on possible values, see aaRetrievalMode Enumeration on page 471. The default is 0 (cyclic). Make sure that the specified retrieval mode is supported by the IndustrialSQL Server historian that the tag is stored on.

Related Topics
RetrievalOptionsRetrievalMode

CurrentTagRetrievalStyle
This read-write property determines the current tags retrieval style. This setting overrides the default setting specified at the application level.
Syntax
aaHistClientTrend.CurrentTagRetrievalStyle = string; Result = aaHistClientTrend.CurrentTagRetrievalStyle;

Remarks

You must provide the retrieval style name for the current locale as it is defined in the retrieval style document. For more information, see Location and Structure of Retrieval Styles on page 685. To find out how many retrieval styles are available for the current tag, use the CurrentTagNumStyles property. To determine the name of a retrieval style if you know its position in the list of available styles, use the CurrentTagGetStyle method. Valid values: Custom style (or the translated equivalent for the current locale), Style selected at option level (ditto) and any retrieval style name that is defined for the current locale in the retrieval style document. Values are case-sensitive. If no style names at all are available for the current locale, use the name for the en locale. The default is Style selected at option level (or the translated equivalent).

ActiveFactory Software Users Guide

376

Chapter 8 aaHistClientTrend Control

Related Topics
CurrentTagGetStyle CurrentTagNumStyles RetrievalOptionsRetrievalStyle

CurrentTagRowLimit
This read-write property determines the current tags row limit for data retrieval. This setting overrides the default setting specified at the application level if the CurrentTagRetrievalStyle property is set to an option other than Style selected at option level.
Syntax
aaHistClientTrend.CurrentTagRowLimit = integer; Result = aaHistClientTrend.CurrentTagRowLimit;

Remarks

The row limit applies to each query. For more information, see Row Limit on page 682. This property is relevant for all retrieval modes. Valid values: any positive number or 0 (no row limit). The default is 0.

The result is a DateTime value.

Remarks

This property has no default. Setting this property updates the CurrentTagOffsetMS property accordingly. This property is only applicable if the DateMode property is set to relative. It reflects local time. For information on setting the date/time value, see DateTime on page 638.

Related Topics
CurrentTagOffsetMS DateMode

ActiveFactory Software Users Guide

Chapter 8 aaHistClientTrend Control

If it is set to False, you must specify the number of cycles manually. Use the CurrentTagUseResolution property to specify whether you want to provide a number of cycles or a time interval. Then use the CurrentTagCycleCount property to specify the number of cycles, or the CurrentTagResolution property to specify the time interval. This property is relevant for all retrieval modes except the following: Delta, Full, and Slope. The default is False.

Related Topics
CurrentTagCycleCount CurrentTagResolution CurrentTagUseResolution RetrievalOptionsUseAutoCycles

CurrentTagUseResolution
This read-write property controls the current tags behavior for determining the number of cycles in cycle-based data retrieval. This setting overrides the default setting specified at the application level if the CurrentTagRetrievalStyle property is set to an option other than Style selected at option level.
Syntax
aaHistClientTrend.CurrentTagUseResolution = discrete; Result = aaHistClientTrend.CurrentTagUseResolution;

Remarks

This property is only relevant if the CurrentTagUseAutoCycles property is set to False. If this property is set to False, the aaHistClientTrend control uses a fixed number of cycles when retrieving data using cycle-based retrieval modes. To specify the number of cycles, use the CurrentTagCycleCount property. If it is set to True, the aaHistClientTrend control calculates the number of cycles based on the query duration and a time interval. To specify this interval, use the CurrentTagResolution property. This property is relevant for all retrieval modes except the following: Delta, Full, and Slope. The default is False.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

381

Related Topics
CurrentTagCycleCount CurrentTagResolution CurrentTagUseAutoCycles RetrievalOptionsResolution

CurrentTagValAtX1
The CurrentTagValAtX1 property is a read-only property that gets the value of the current tag at the point at which the curve intersects with the first time axis cursor.
Syntax
Result = aaHistClientTrend.CurrentTagValAtX1;

Return Value

The result is a real value.

Remarks

For more information on cursors, see Using Axis Cursors on page 94. This property has no default.

The result is a real value.

Remarks

For more information on cursors, see Using Axis Cursors on page 94. This property has no default.

ActiveFactory Software Users Guide

382

Chapter 8 aaHistClientTrend Control

Syntax
aaHistClientTrend.CurrentTagValueDeadband = real; Result = aaHistClientTrend.CurrentTagValueDeadband;

Remarks

The deadband is a percentage of the full scale in Engineering Units. Valid values are 0 (no deadband) to 100. This property is only relevant for Delta retrieval mode. For more information on how this setting works, see Value Deadband on page 677. The default is 0 (no deadband).

Related Topics
RetrievalOptionsValueDeadband

CurrentValOfX1
This read-write property gets or sets the position of the first X axis cursor in a scatter plot.
Syntax
aaHistClientTrend.CurrentValOfX1 = real; Result = aaHistClientTrend.CurrentValOfX1;

Remarks

This property contains the value at which the cursor intersects with the current X axis scale. Therefore, the same cursor position may be reflected by different values depending on which tag is selected. To control the position of the first time axis cursor in a regular trend, use the XCursor1Pos property.

Related Topics
CurrentValOfX2 XCursor1Pos

CurrentValOfX2
This read-write property gets or sets the position of the second X axis cursor in a scatter plot.
Syntax
aaHistClientTrend.CurrentValOfX2 = real; Result = aaHistClientTrend.CurrentValOfX2;

Remarks

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

383

To control the position of the second time axis cursor in a regular trend, use the XCursor2Pos property.

Related Topics
CurrentValOfX1 XCursor2Pos

CurrentValOfY1
This read-write property controls the position of the first Y axis cursor.
Syntax
aaHistClientTrend.CurrentValOfY1 = real; Result = aaHistClientTrend.CurrentValOfY1;

Remarks

This property contains the value at which the cursor intersects with the current Y axis scale. Therefore, the same cursor position may be reflected by different values depending on which tag is selected.

The result is an integer value.

ActiveFactory Software Users Guide

384

Chapter 8 aaHistClientTrend Control

Remarks

CurrentXAxisTagName
This read-only property returns the name of the X axis tag that is associated with the currently selected tag.
Syntax
Result = aaHistClientTrend.CurrentXAxisTagName;

Return Value

The result is a message value.

Remarks

If no X axis tag is set for the currently selected tag, this property contains an empty string.

CurrentXAxisTagServerName
This read-only property returns the name of the server for the X axis tag that is associated with the currently selected tag.
Syntax
Result = aaHistClientTrend.CurrentXAxisTagServerName;

Return Value

The result is a message value.

Remarks

If no X axis tag is set for the currently selected tag, this property contains an empty string.

CyclicRows
This property is deprecated and included for backward compatibility only.
Syntax
aaHistClientTrend.CyclicRows = integer; Result = aaHistClientTrend.CyclicRows;

Remarks

To specify the number of cycles for cyclic retrieval, use the CurrentTagCycleCount or RetrievalOptionsCycleCount properties instead.

Related Topics
CurrentTagCycleCount RetrievalOptionsCycleCount

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

385

DataPointLabelType
This property determines whether data point labels are shown in a scatter plot.
Syntax
aaHistClientTrend.DataPointLabelType = aaDataPointLabelingType; Result = aaHistClientTrend.DataPointLabelType;

Remarks

For information on possible values, see aaDataPointLabelingType Enumeration on page 470. The default is 0 (no labels).

DateMode
The DateMode property is a read-write property that gets or sets the date mode for the trend.
Syntax
aaHistClientTrend.DateMode = aaDateModeEnumeration; Result = aaHistClientTrend.DateMode;

Remarks

The default is 0 (absolute mode). For more information on the aaDateModeEnumeration enumeration, see aaDateModeEnumeration Enumeration on page 470. The DateMode property determines the functionality of the Time Bar and how time shifting is anchored as you switch between different time periods.

In absolute mode, the Time Bar has a start time and an end time. In this mode, each tag has its own time offset. The actual time period used for queries is the sum of the tag's "offset" and the start and end time for the Time Bar. The tag offset is set using the CurrentTagOffsetMS property. In relative mode, the Time Bar has a starting time offset and an ending time offset. In this mode each tag has its own starting time. The actual time period used for queries is the sum of the the tag's start time to the offsets of the Time Bar. If you set the DateMode property to use relative time, specify the start time for the current tag using the CurrentTagStartDate property.

In both modes, zoom and pan operations only manipulate the Time Bar properties, not the tag properties.

ActiveFactory Software Users Guide

386

Chapter 8 aaHistClientTrend Control

Related Topics
CurrentTagStartDate CurrentTagOffsetMS

DatePickerFormatString
The DatePickerFormatString property is a read-write property that gets or sets the format string for the time range picker.
Syntax
aaHistClientTrend.DatePickerFormatString = message; Result = aaHistClientTrend.DatePickerFormatString;

Remarks

This value is determined from the regional settings for the operating system. For example, the time setting might be: hh:mm:ss tt where: hh = hour, with a leading zero mm = minute, with a leading zero ss = second, with a leading zero tt = AM or PM For more information, see the regional settings options in Control Panel. This property only changes the format for the time range picker; it does not change the system-wide value. The default is M/d/yyyy h:mm:ss tt.

DefaultTagFormat
The DefaultTagFormat property is a read-write property that gets or sets the format of the trend item for presentation to the client.
Syntax
aaHistClientTrend.DefaultTagFormat = integer; Result = aaHistClientTrend.DefaultTagFormat;

Remarks

Valid values are: 0 = Decimal, 1 = Scientific. The default is 0. If you use the decimal format, use the DefaultTagPrecision property to specify the number of decimal points. Format changes are not applied to trend items already in the chart at the time the format change is made. The default is 0.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

387

Related Topics
CurrentTagFormat CurrentTagPrecision DefaultTagPrecision

DefaultTagPrecision
The DefaultTagPrecision property is read-write property that gets or sets the number of decimal places of the trend item for presentation to the client.
Syntax
aaHistClientTrend.DefaultTagPrecision = integer; Result = aaHistClientTrend.DefaultTagPrecision;

Remarks

Precision changes are not applied to trend items already in the chart at the time the precision change is made. The default is 0.

Related Topics
CurrentTagFormat CurrentTagPrecision DefaultTagFormat

EnableDeltaRetrieval
The EnableDeltaRetrieval property is a read-write property that enables or disables delta retrieval for the trend control.
Syntax
aaHistClientTrend.EnableDeltaRetrieval = discrete; Result = aaHistClientTrend.EnableDeltaRetrieval;

Remarks

The aaHistClientTrend control only takes this property into account when retrieving data from IndustrialSQL Server historians with a version earlier than 9.0. For more information, see Understanding Relations between Retrieval Styles, Application Settings and Tag Settings on page 693. Delta retrieval is used for analog and discrete queries that have a time range that are within the settings of the MaxMinutesForDeltaAnalog and MaxMinutesForDeltaDiscrete properties. Delta retrieval is always used for the "live" retrieval mode. If you set this property to False, this has no effect on live mode. The default is False.

ActiveFactory Software Users Guide

388

Chapter 8 aaHistClientTrend Control

Related Topics
MaxMinutesForDeltaAnalog MaxMinutesForDeltaDiscrete

EnableSummaryData
This property is included for backward compatibility only. Its value is ignored.
Syntax
aaHistClientTrend.EnableSummaryData = discrete; Result = aaHistClientTrend.EnableSummaryData;

Remarks

To retrieve summarized data, use a retrieval style instead. For more information, see Working with Retrieval Styles on page 684.

EnableTimeOffsets
Note This property is included for backward compatibility only. Setting this property has no effect.

The EnableTimeOffsets property is a read-write property that enables or disables time offsets for the trend items.
Syntax
aaHistClientTrend.EnableTimeOffsets = discrete; Result = aaHistClientTrend.EnableTimeOffsets;

Remarks

The default is True.

Related Topics
SetDates StartDate EndDate

EndDate
The EndDate property is a read-only property that gets the timestamp at the right edge of the trend.
Syntax
aaHistClientTrend.EndDate = DateTime; Result = aaHistClientTrend.EndDate;

Remarks

For information on setting the date/time value, see DateTime on page 638. This property has no default.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

389

Related Topics
SetDates StartDate EnableTimeOffsets

FileName
The FileName property is a read-only property that gets the name of the current trend file.
Syntax
Result = aaHistClientTrend.FileName;

Return Value

The result is a message.

Remarks

The default is an empty message value ( "" ).

Related Topics
FileNew FileOpen FileSave

GridColor
The GridColor property is a read-write property that gets or sets the color of the trend grid.
Syntax
aaHistClientTrend.GridColor = integer; Result = aaHistClientTrend.GridColor;

Remarks

For information on setting the color value, see Color on page 638. The default is 13882323.

Related Topics
GridHorizontal GridVertical

GridHorizontal
The GridHorizontal property is a read-write property that shows or hides the horizontal grid.
Syntax
aaHistClientTrend.GridHorizontal = discrete; Result = aaHistClientTrend.GridHorizontal;

Remarks

The default is True.

ActiveFactory Software Users Guide

390

Chapter 8 aaHistClientTrend Control

The default is True.

HideCurrentTag
The HideCurrentTag property is a read-write property that shows or hides the currently selected trend item (tag).
Syntax
aaHistClientTrend.HideCurrentTag = discrete; Result = aaHistClientTrend.HideCurrentTag;

Remarks

The default is False. If there are no tags on the chart, this property returns True.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

391

393

Syntax
aaHistClientTrend.MaxDeltaSamples = integer; Result = aaHistClientTrend.MaxDeltaSamples;

Remarks

The aaHistClientTrend control only takes this property into account when retrieving data from IndustrialSQL Server historians with a version earlier than 9.0. Valid values are 0 to 100,000. The default is 10,000.

MaxMinutesForDeltaAnalog
The MaxMinutesForDeltaAnalog property is a read-write property that gets or sets the maximum minutes filter for analog tags for delta retrieval mode.
Syntax
aaHistClientTrend.MaxMinutesForDeltaAnalog = integer; Result = aaHistClientTrend.MaxMinutesForDeltaAnalog;

Remarks

396

Chapter 8 aaHistClientTrend Control

Related Topics
NumTimeAxisGridPerValue NumYAxisGridPerValue NumYAxisValues

NumXValueAxisGridLinesPerLabel
This read-write property determines the number of grid lines that appear between each scale value label on the X axis of a scatter plot.
Syntax
aaHistClientTrend.NumXValueAxisGridLinesPerLabel = integer; Result = aaHistClientTrend.NumXValueAxisGridLinesPerLabel;

Remarks

The valid range is from 1 to 20. The default is 3.

The valid range is from 2 to 15. The default is 6.

Related Topics
NumXValueAxisGridLinesPerLabel

NumYAxisGridPerValue
This read-write property determines the number of grid lines that appear between each scale value label on the Y axis of a chart.
Syntax
aaHistClientTrend.NumYAxisGridPerValue = integer; Result = aaHistClientTrend.NumYAxisGridPerValue;

Remarks

The valid range is from 1 to 20. The default is 2.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

397

Related Topics
NumTimeAxisGridPerValue NumTimeAxisValues NumYAxisValues

NumYAxisValues
This read-write property determines the number of scale value labels that appear on the Y axis of a chart.
Syntax
aaHistClientTrend.NumYAxisValues = integer; Result = aaHistClientTrend.NumYAxisValues;

Remarks

The values are shown at evenly-spaced points along the axis. The number of values remains the same even if you zoom in and out. The valid range is from 2 to 15. The default is 6.

Related Topics
NumTimeAxisGridPerValue NumTimeAxisValues NumYAxisGridPerValue

PanPercentage
The PanPercentage property is a read-write property that gets or sets the percentage (1 to 100) by which the time axis (x-axis) pans.
Syntax
aaHistClientTrend.PanPercentage = integer; Result = aaHistClientTrend.PanPercentage;

Remarks

The default is 75.

ActiveFactory Software Users Guide

398

Chapter 8 aaHistClientTrend Control

Valid values are 0.5 to 128. The default is 1 (normal speed).

Related Topics
LiveModeRate RealTimeMode RealTimeRate

PlotColor
The PlotColor property is a read-write property that gets or sets the color for the plot area of the graph.
Syntax
aaHistClientTrend.PlotColor = integer; Result = aaHistClientTrend.PlotColor;

Remarks

For information on setting the color value, see Color on page 638. The default is 16777215.

Related Topics
PlotGradientEndColor PlotImage PlotGradient

PlotGradient
The PlotGradient property is a read-write property that gets or sets the type of plot gradient for the chart.
Syntax
aaHistClientTrend.PlotGradient = aaTrendGradientType; Result = aaHistClientTrend.PlotGradient;

Remarks

The gradient starts with the main plot color and fades to the gradient end color. Use the PlotColor property to set the main background color. Use the PlotGradientEndColor property to set the ending gradient color. For more information on the aaTrendGradientType enumeration, see aaTrendGradientType Enumeration on page 473. The default is 0.

Related Topics
PlotColor PlotGradientEndColor PlotImage

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

399

PlotGradientEndColor
The PlotGradientEndColor property is a read-write property that gets or sets the gradient end color for the plot area of the chart.
Syntax
aaHistClientTrend.PlotGradientEndColor = integer; Result = aaHistClientTrend.PlotGradientEndColor;

Remarks

The gradient starts with the main plot color and fades to the gradient end color. Use the PlotColor property to set the main plot color. Use the PlotGradient property to set the type of gradient fill. For information on setting the color value, see Color on page 638. The default is 16777215.

Related Topics
PlotColor PlotImage PlotGradient

PlotImage
The PlotImage property is a read-write property that gets or sets the plot image for the chart.
Syntax
aaHistClientTrend.PlotImage = message; Result = aaHistClientTrend.PlotImage;

Remarks

The value of this property is the folder path and filename for the image. Supported image types are .jpeg, .gif, .bmp, and .png. This property has no default.

Related Topics
PlotColor PlotGradientEndColor PlotGradient

PrintShowActiveTag
The PrintShowActiveTag property is a read-write property that shows or hides the name of the active tag in the chart area of printed trends.
Syntax
aaHistClientTrend.PrintShowActiveTag = discrete;

ActiveFactory Software Users Guide

400

Chapter 8 aaHistClientTrend Control

Result = aaHistClientTrend.PrintShowActiveTag;

Remarks

True = Show the tag; False = Hide the tag. The default is True.

Related Topics
PrintGraphDlg PrintGraph PrintTitle PrintShowTitle

PrintShowMarkers
The PrintShowMarkers property is a read-write property that shows or hides the markers in printed trends.
Syntax
aaHistClientTrend.PrintShowMarkers = discrete; Result = aaHistClientTrend.PrintShowMarkers;

Remarks

True = Show the markers; False = Hide the markers. The default is True.

Related Topics
PrintGraphDlg PrintGraph PrintTitle PrintShowTitle

PrintShowTitle
The PrintShowTitle property is a read-write property that shows or hides the print title in printed trends.
Syntax
aaHistClientTrend.PrintShowTitle = discrete; Result = aaHistClientTrend.PrintShowTitle;

Remarks

True = Show the title; False = Hide the title. The default is True.

Related Topics
PrintGraphDlg PrintGraph PrintTitle

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

401

PrintTitle
The PrintTitle property is a read-write property that gets or sets the print title for the trend.
Syntax
aaHistClientTrend.PrintTitle = message; Result = aaHistClientTrend.PrintTitle;

Remarks

This property has no default.

Related Topics
PrintGraphDlg PrintGraph PrintShowTitle

PublicAnnotations
The PublicAnnotations property is a read-write property that shows or hides all public annotations in the trend chart.
Syntax
aaHistClientTrend.PublicAnnotations = discrete; Result = aaHistClientTrend.PublicAnnotations;

Remarks

The default is True.

ActiveFactory Software Users Guide

402

Chapter 8 aaHistClientTrend Control

RealTimeMode
The RealTimeMode property is a read-write property that enables or disables live or replay mode.
Syntax
aaHistClientTrend.RealTimeMode = discrete; Result = aaHistClientTrend.RealTimeMode;

Remarks

Use the LiveModeRate or RealTimeRate properties to set the rate at which the trend is refreshed in live or replay mode. The default is False.

Related Topics
LiveModeRate RealTimeRate

RealTimeRate
The RealTimeRate property is a read-write property that gets or sets the refresh interval in seconds for live and replay mode.
Syntax
aaHistClientTrend.RealTimeRate = integer; Result = aaHistClientTrend.RealTimeRate;

Remarks

The default is 1. Apart from the different unit of measure, this property serves the same purpose as the LiveModeRate property.

Related Topics
LiveModeRate RealTimeMode

RetrievalOptionsCycleCount
This read-write property controls the aaHistClientTrend controls default number of cycles for cycle-based data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsCycleCount = integer; Result = aaHistClientTrend.RetrievalOptionsCycleCount;

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

403

Remarks

This property is only taken into account if both the RetrievalOptionsUseAutoCycles property and the RetrievalOptionsUseResolution property are set to False. Also, it may be overridden by a retrieval style setting. For more information, see Working with Retrieval Styles on page 684. This property is relevant for all retrieval modes except the following: Delta, Full, and Slope. Valid values: any positive integer or 0. If you specify 0, the cycle count is calculated automatically, just as if the RetrievalOptionsUseAutoCycles property were set to True. The default is 100.

Related Topics
CurrentTagCycleCount RetrievalOptionsResolution RetrievalOptionsUseAutoCycles RetrievalOptionsUseResolution

RetrievalOptionsHistoryVersion
This read-write property determines the aaHistClientTrend controls default history source for data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsHistoryVersion = aaRetrievalVersion; Result = aaHistClientTrend.RetrievalOptionsHistoryVersion;

Remarks

For information on possible values, see aaRetrievalVersion Enumeration on page 472. This property is relevant for all retrieval modes. The default is 0 (latest values).

ActiveFactory Software Users Guide

404

Chapter 8 aaHistClientTrend Control

Syntax
aaHistClientTrend.RetrievalOptionsInterpolationType = aaInterpolationType; Result = aaHistClientTrend.RetrievalOptionsInterpolationType;

Remarks

Related Topics
CurrentTagInterpolationType

RetrievalOptionsNumStyles
This read-only property returns the number of retrieval styles that are available in the control.
Syntax
Result = aaHistClientTrend.RetrievalOptionsNumStyles;

Remarks

Related Topics
CurrentTagNumStyles RetrievalOptionsGetStyle RetrievalOptionsRetrievalStyle

RetrievalOptionsQualityRule
This read-write property determines the aaHistClientTrend controls default quality rule for data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsQualityRule = aaQualityRules; Result = aaHistClientTrend.RetrievalOptionsQualityRule;

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

405

Remarks

ActiveFactory Software Users Guide

406

Chapter 8 aaHistClientTrend Control

RetrievalOptionsRetrievalMode
This read-write property determines the aaHistClientTrend controls default data retrieval mode. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsRetrievalMode = aaRetrievalMode; Result = aaHistClientTrend.RetrievalOptionsRetrievalMode;

Remarks

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

407

Valid values: Custom style (or the translated equivalent for the current locale) and any retrieval style name that is defined for the current locale in the retrieval style document. Values are case-sensitive. If no style names at all are available for the current locale, use the name for the en locale. The default is BestFit-5 (or the translated equivalent).

Related Topics
CurrentTagRetrievalStyle RetrievalOptionsGetStyle RetrievalOptionsNumStyles

RetrievalOptionsRowLimit
This read-write property determines the aaHistClientTrend controls default row limit for data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsRowLimit = integer; Result = aaHistClientTrend.RetrievalOptionsRowLimit;

Remarks

ActiveFactory Software Users Guide

408

Chapter 8 aaHistClientTrend Control

This property has no default.

Related Topics
CurrentTagState RetrievalOptionsStateCalculation

RetrievalOptionsStateCalculation
This read-write property determines the aaHistClientTrend controls default calculation type for Time-in-State data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsStateCalculation = aaStateCalculation; Result = aaHistClientTrend.RetrievalOptionsStateCalculation;

Remarks

Related Topics
CurrentTagStateCalculation RetrievalOptionsState

RetrievalOptionsTimeDeadband
This read-write property determines the aaHistClientTrend controls default time deadband in milliseconds for Delta data retrieval. This setting applies to all tags in a trend whose retrieval style is set to Style selected at option level.
Syntax
aaHistClientTrend.RetrievalOptionsTimeDeadband = integer; Result = aaHistClientTrend.RetrievalOptionsTimeDeadband;

Remarks

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

409

ActiveFactory Software Users Guide

410

Chapter 8 aaHistClientTrend Control

If it is set to False, you must specify the number of cycles manually. Use the RetrievalOptionsUseResolution property to specify whether you want to provide a number of cycles or a time interval. Then use the RetrievalOptionsCycleCount property to specify the number of cycles, or the RetrievalOptionsResolution property to specify the time interval. This property is relevant for all retrieval modes except the following: Delta, Full, and Slope. The default is True.

413

Syntax
aaHistClientTrend.RubberBand = discrete; Result = aaHistClientTrend.RubberBand;

Servers
The Servers property is a read-only property that gets the server list.
Syntax
Result = aaHistClientTrend.Servers;

Remarks

This property has no default.

Return Value

The result is an aaServers object. For more information on the aaServers object, see aaServers Object on page 575.

ShowLimits
The ShowLimits property is a read-write property that shows or hides the limits for a tag.
Syntax
aaHistClientTrend.ShowLimits = discrete; Result = aaHistClientTrend.ShowLimits;

Remarks

The default is True.

ShowValuesAtCursor
The ShowValuesAtCursor property is a read-write property that shows/hides data values at the trend cursors along the value axis.
Syntax
aaHistClientTrend.ShowValuesAtCursor = discrete; Result = aaHistClientTrend.ShowValuesAtCursor;

Remarks

The default is False.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

415

If the ShowValuesAtCursor property is set to True, the ValueAxisLabel property is set to 2, and values at cursors are shown in the chart. If the ShowValuesAtCursor property is set to False, the ValueAxisLabel property is set to 0, and multiple scales are shown in the chart.

Related Topics
SetDates EndDate EnableTimeOffsets

SummaryDataMode
This property is included for backward compatibility only. Its value is ignored.
Syntax
aaHistClientTrend.SummaryDataMode = discrete; Result = aaHistClientTrend.SummaryDataMode;

Remarks

To retrieve summarized data, use a retrieval style instead. For more information, see Working with Retrieval Styles on page 684.

SupressErrors
The SupressErrors property is a read-write property that suppresses or allows errors.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

417

Syntax
aaHistClientTrend.SupressErrors = discrete; Result = aaHistClientTrend.SupressErrors;

Remarks

The default is False.

TagGridOrientation
The TagGridOrientation property is a read-write property that orients the tag list vertically or horizontally.
Syntax
aaHistClientTrend.TagGridOrientation = integer; Result = aaHistClientTrend.TagGridOrientation;

Remarks

0 = Horizontal; 1 = Vertical. The default is 0.

The default is True.

ActiveFactory Software Users Guide

418

Chapter 8 aaHistClientTrend Control

Related Topics
TimeBarVisible ToolBarVisible TagPicker

TargetRegionExcursionType
This read-write property determines whether to highlight values that fall outside the target region of a tag.
Syntax
aaHistClientTrend.TargetRegionExcursionType = aaTargetRegionExcursionType; Result = aaHistClientTrend.TargetRegionExcursionType;

Remarks

For information on possible values, see aaTargetRegionExcursionType Enumeration on page 472. The default is 1 (highlight values in a special color).

Related Topics
CurrentTagTargetRegionVisible LoadTargetRegionFromFile TargetRegionOpacity

TargetRegionOpacity
This read-write property determines the opacity of a tags target region.
Syntax
aaHistClientTrend.TargetRegionOpacity = integer; Result = aaHistClientTrend.TargetRegionOpacity;

Remarks

A value of 0 means transparent, 100 means fully opaque. The default is 20.

Related Topics
CurrentTagTargetRegionVisible LoadTargetRegionFromFile TargetRegionExcursionType

TimeBarVisible
The TimeBarVisible property is a read-write property that shows or hides the time and main toolbars in the Trend control.
Syntax
aaHistClientTrend.TimeBarVisible = discrete; Result = aaHistClientTrend.TimeBarVisible;

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

419

Remarks

The default is True.

Related Topics
TagPickerVisible ToolBarVisible

TimeBarVisible2
The TimeBarVisible2 property is a read-write property that shows or hides the time toolbar in the Trend control.
Syntax
aaHistClientTrend.TimeBarVisible2 = discrete; Result = aaHistClientTrend.TimeBarVisible2;

Remarks

This property is provided for backward compatibility. Alternatively, you can use the TimeBarVisible property, which shows or hides the main toolbar as well as the time toolbar. The default is True.

TimeSelector
The TimeSelector property is a read-only property that gets the Time Range Picker object used in the Trend control.
Syntax
Result = aaHistClientTrend.TimeSelector;

Return Value

The return value is an aaHistClientTimeRangePicker control. For more information on this control, see Chapter 11, aaHistClientTimeRangePicker Control

ToolBarVisible
The ToolBarVisible property is a read-write property that shows or hides the main toolbar in the Trend control.
Syntax
aaHistClientTrend.ToolBarVisible = discrete; Result = aaHistClientTrend.ToolBarVisible;

Using aaHistClientTrend in an Application

421

Result = aaHistClientTrend.TraceGradientStartingPercentage;

Remarks

The starting opacity applies to the earliest data point in the scatter plot. A value of 0 means transparent, 100 means fully opaque. The default is 20. This property is only used if the TraceGradientType property is set to use a gradient.

ActiveFactory Software Users Guide

422

Chapter 8 aaHistClientTrend Control

UseIniFile
Do not use. Obsolete.
Syntax
aaHistClientTrend.UseIniFile = integer; Result = aaHistClientTrend.UseIniFile;

Remarks

The default is 0.

ValueAxisLabel
The ValueAxisLabel property is a read-write property that gets or sets the value axis labeling.
Syntax
aaHistClientTrend.ValueAxisLabel = aaValueAxisLabelEnumeration; Result = aaHistClientTrend.ValueAxisLabel;

Remarks

The default is 0 (MultipleScales). For more information on value axis labeling, see Scaling Tags on page 81. For more information on the aaValueAxisLabelEnumeration enumeration, see aaValueAxisLabelEnumeration Enumeration on page 475. If the ShowValuesAtCursor property is set to True, the ValueAxisLabel property is set to 2, and values at cursors are shown in the chart. If the ShowValuesAtCursor property is set to False, the ValueAxisLabel property is set to 0, and multiple scales are shown in the chart.

The default is 255.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

423

Related Topics
XCursor1Pos XCursor2Color XCursor2Pos YCursor1Color YCursor2Color

XCursor1Pos
The XCursor1Pos property is a read-write property that controls the position of the first time axis cursor.
Syntax
aaHistClientTrend.XCursor1Pos = DateTime; Result = aaHistClientTrend.XCursor1Pos;

Remarks

The value is given as a date/time value. For information on the date/time value format, see DateTime on page 638. To control the position of the first X axis cursor in a scatter plot, use the CurrentValOfX1 property instead. This property has no default.

Related Topics
CurrentValOfX1 CurrentValOfY1 CurrentValOfY2 XCursor1Color XCursor2Color XCursor2Pos YCursor1Color YCursor2Color

XCursor2Color
The XCursor2Color property is a read-write property that gets or sets the color for second time axis cursor.
Syntax
aaHistClientTrend.XCursor2Color = integer; Result = aaHistClientTrend.XCursor2Color;

Remarks

For information on setting the color value, see Color on page 638. The default is 16711680.

ActiveFactory Software Users Guide

424

Chapter 8 aaHistClientTrend Control

Related Topics
XCursor1Color XCursor1Pos XCursor2Pos YCursor1Color YCursor2Color

XCursor2Pos
The XCursor2Pos property is a read-write property that controls the position of the second time axis cursor.
Syntax
aaHistClientTrend.XCursor2Pos = DateTime; Result = aaHistClientTrend.XCursor2Pos;

Remarks

The value is given as a date/time value. For information on the date/time value format, see DateTime on page 638. To control the position of the second X axis cursor in a scatter plot, use the CurrentValOfX2 property instead. This property has no default.

Related Topics
CurrentValOfX2 CurrentValOfY1 CurrentValOfY2 XCursor1Color XCursor1Pos XCursor2Color YCursor1Color YCursor2Color

YCursor1Color
The YCursor1Color property is a read-write property that gets or sets the color for first value axis cursor.
Syntax
aaHistClientTrend.YCursor1Color = integer; Result = aaHistClientTrend.YCursor1Color;

Remarks

For information on setting the color value, see Color on page 638. The default is 32768.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

425

Related Topics
XCursor1Color XCursor1Pos XCursor2Color XCursor2Pos YCursor2Color

YCursor2Color
The YCursor2Color property is a read-write property that gets or sets the color for second value axis cursor.
Syntax
aaHistClientTrend.YCursor2Color = integer; Result = aaHistClientTrend.YCursor2Color;

Remarks

For information on setting the color value, see Color on page 638. The default is 32768.

Related Topics
XCursor1Color XCursor1Pos XCursor2Color XCursor2Pos YCursor1Color

ZoomOutPercentage
The ZoomOutPercentage property is a read-write property that gets or sets the percentage (1 to 100) to zoom by when zooming out on the trend chart.
Syntax
aaHistClientTrend.ZoomOutPercentage = integer; Result = aaHistClientTrend.ZoomOutPercentage;

Remarks

The default is 25.

ActiveFactory Software Users Guide

426

Chapter 8 aaHistClientTrend Control

AddServer AddTag ClearTags CurrentTagGetStyle DeleteCurrentTag FileNew FileOpen FileSave GetMenuItemEnabled GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPenWidth GetTagPrecision GetTagValAtX1 GetTagValAtX2 GetTagVisible GetToolbarButtonEnabled GraphStack LoadCRVString LoadTargetRegionFromFile ManualConnect MoveNextTag MovePrevTag PanLeft PanRight PrintGraph PrintGraphDlg PropertiesDlg RefreshData

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

427

RemoveServer RemoveTag RetrievalOptionsGetStyle SaveData SaveImage SaveSettings ScaleAllTags ScaleAllTagsDlg ScaleAutoAllTags ScaleAutoTag ScaleDownAllTags ScaleDownTag ScaleMoveAllTagsDown ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveTagUp ScaleTag ScaleTagDlg ScaleUpAllTags ScaleUpTag SetCurrentTag SetCurrentTagXAxisTag SetCurrentTagXAxisTagIndex SetDates SetDuration SetMenuItemEnabled SetTagColor SetTagFormat SetTagColorDlg SetTagOffsetMS SetTagPenStyle

ActiveFactory Software Users Guide

428

Chapter 8 aaHistClientTrend Control

SetTagPenWidth SetTagPrecision SetTagVisible SetTimeSpan SetToolbarButtonEnabled UnsetCurrentTagXAxisTag ZoomIn ZoomOut

AboutBox
The AboutBox method shows the About dialog box for the control.
Syntax
[Result=] aaHistClientTrend.AboutBox();

AddAnyTag
The AddAnyTag method verifies and adds a tag to the trend.
Syntax
[Result=] aaHistClientTrend.AddAnyTag(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

Returns True if the tag was added; otherwise returns False.

Remarks

The tag can be on any server. This method first checks if the tag exists before adding it. The AddTag method also adds a tag, but it does not perform the checking and is thus more efficient. If you specify a server name that is part of the current server list, but is currently disconnected, an attempt is made to connect to the server. If the authentication credentials are correct, the server is logged on, and the tag added. If you specify a server name that is not part of the current server list, the runtime user is prompted to add the server name to the server list. A False is returned. If you want to suppress the notification, use the SupressErrors property. For more information, see SupressErrors on page 416.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

429

Returns True if the server can be added; otherwise returns False.

AddTag
The AddTag method adds the specified tag to the trend.
Syntax
[Result=] aaHistClientTrend.AddTag(message serverName, message newTag, integer tType);

Parameters

serverName The name of the server for which to add the tag. newtag The name of the tag to add. tType The type of tag. This parameter is provided for backward compatibility and doesnt have any effect on the outcome of the operation. However, you must still specify one of the following valid values: 1, 2, 3, or 5.
Return Value

Returns True if the tag can be added; otherwise returns False.

ActiveFactory Software Users Guide

430

Chapter 8 aaHistClientTrend Control

Returns True if the tag can be deleted; otherwise returns False.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

431

FileNew
The FileNew method creates a new file and then resets the trend to the default properties.
Syntax
[Result=] aaHistClientTrend.FileNew();

Return Value

Returns True if the file is successfully created; otherwise returns False.

Related Topics
FileOpen FileSave FileName

FileOpen
The FileOpen method opens the specified trend file.
Syntax
[Result=] aaHistClientTrend.FileOpen([message fileName]);

Parameters

fileName The full path to the trend file to open.

Return Value

Returns True if the file can be successfully opened; otherwise, False is returned.
Remarks

Any errors are reported. If an invalid file name or no file name is specified, a dialog box appears in which the runtime user can select a file.

Related Topics
FileNew FileSave FileName

FileSave
The FileSave method saves the trend to the specified file.
Syntax
[Result=] aaHistClientTrend.FileSave([message fileName]);

Parameters

fileName The name of the trend file to save.

ActiveFactory Software Users Guide

432

Chapter 8 aaHistClientTrend Control

Return Value

Returns True if the file can be successfully saved; otherwise, False is returned.
Remarks

Any errors are reported. If an invalid file name or no file name is specified, a dialog box appears in which the runtime user can save the file.

Related Topics
FileNew FileOpen FileName

GetMenuItemEnabled
Use the GetMenuItemEnabled method to check if a specific command in the context menu is enabled.
Syntax
[Result=] aaHistClientTrend.GetMenuItemEnabled(integer itemNumber);

Parameters

itemNumber The index number of the command. Numbering starts at 0.

Return Value

Syntax
[Result=] aaHistClientTrend.GetTagOffsetMS(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The result is an integer value for the tag offset, in milliseconds. For more information, see Using Time Offsets to Compare Data on page 115.
Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
GetTagColor GetTagFormat GetTagPenStyle GetTagPenWidth GetTagPrecision GetTagValAtX1 GetTagValAtX2 GetTagVisible

GetTagPenStyle
The GetTagPenStyle method gets the style of the trend curve for the currently selected tag. For example, a solid or dashed line.
Syntax
[Result=] aaHistClientTrend.GetTagPenStyle(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

Returns the pen style as an integer value. Valid values are: 0 1 2 Solid Dashed Dotted

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

435

3 4 5
Remarks

DashDot DashDotDot Alternate

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
GetTagColor GetTagFormat GetTagOffsetMS GetTagPenWidth GetTagPrecision GetTagValAtX1 GetTagValAtX2 GetTagVisible

GetTagPenWidth
The GetTagPenWidth method gets the thickness of the trend curve for the selected tag.
Syntax
[Result=] aaHistClientTrend.GetTagPenWidth(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The width, in pixels, of the pen as an integer.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPrecision GetTagValAtX1 GetTagValAtX2 GetTagVisible

ActiveFactory Software Users Guide

436

Chapter 8 aaHistClientTrend Control

GetTagPrecision
The GetTagPrecision method gets the number of decimal places to display for the data value. This applies only to analog tags.
Syntax
[Result=] aaHistClientTrend.GetTagPrecision(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The decimal places (precision) for the tag as an integer.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPenWidth GetTagValAtX1 GetTagValAtX2 GetTagVisible DefaultTagFormat DefaultTagPrecision

GetTagValAtX1
The GetTagValAtX1 method gets the value of the specified tag at the point at which the curve intersects with the first time axis cursor.
Syntax
[Result=] aaHistClientTrend.GetTagValAtX1(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The tag value as a real.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

437

Remarks

For more information on cursors, see Using Axis Cursors on page 94. If the specified tag is shown in the chart multiple times, the method uses the first instance that was added. In a scatter plot, this method behaves as if the X axis were a time axis and the X axis cursors were time cursors. For example, if the plot shows data from 3:00 PM to 4:00 PM, and the cursor is exactly at the middle of the X axis, this method returns the value of the tag at 3:30 PM.

Related Topics
CurrentTagValAtX1 CurrentTagValAtX2 CurrentValOfX1 CurrentValOfX2 GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPenWidth GetTagPrecision GetTagValAtX2 GetTagVisible

GetTagValAtX2
The GetTagValAtX2 method gets the value of the specified tag at the point at which the curve intersects with the second time axis cursor.
Syntax
[Result=] aaHistClientTrend.GetTagValAtX2(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The tag value as a real.

Remarks

For more information on cursors, see Using Axis Cursors on page 94. If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

438

Chapter 8 aaHistClientTrend Control

In a scatter plot, this method behaves as if the X axis were a time axis and the X axis cursors were time cursors. For example, if the plot shows data from 3:00 PM to 4:00 PM, and the cursor is exactly at the middle of the X axis, this method returns the value of the tag at 3:30 PM.

Related Topics
CurrentTagValAtX1 CurrentTagValAtX2 CurrentValOfX1 CurrentValOfX2 GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPenWidth GetTagPrecision GetTagValAtX1 GetTagVisible

GetTagVisible
The GetTagVisible method gets whether the selected tag is visible in the trend chart.
Syntax
[Result=] aaHistClientTrend.GetTagVisible(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The visibility as a discrete. False = Not visible; True = Visible.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

439

Related Topics
GetTagColor GetTagFormat GetTagOffsetMS GetTagPenStyle GetTagPenWidth GetTagPrecision GetTagValAtX1 GetTagValAtX2

GetToolbarButtonEnabled
Use the GetToolbarButtonEnabled method to check if a specific button in the toolbar is enabled.
Syntax
[Result=] GetToolbarButtonEnabled(integer buttonNumber);

Parameters

buttonNumber The index number of the toolbar button. Numbering starts at 0.

Return Value

Returns True if the button is enabled; otherwise, False is returned.

GraphStack
This method toggles the chart between stacked mode (one tag curve on top of the other) and non-stacked mode.
Syntax
[Result=] aaHistClientTrend.GraphStack();

Return Value

Returns True if the operation was successful.

LoadCRVString
The LoadCRVString method is an obsolete method. Do not use.
Syntax
[Result=] aaHistClientTrend.LoadCRVString(message crv);

LoadTargetRegionFromFile
This method sets a target region for the currently selected tag based on values read from a CSV file. It replaces any existing target region that may already be defined for the tag.

ActiveFactory Software Users Guide

440

Chapter 8 aaHistClientTrend Control

Syntax
[Result=] aaHistClientTrend.LoadTargetRegionFromFile(message source);

Parameters

source The location of the file containing the target region items. This can be a local file name or a URL.
Return Value

Returns True if the tags target region was set successfully; otherwise, False is returned, and the tags existing target region is left unchanged.
Remarks

For information on file format requirements, see Defining a Target Region for a Tag on page 70 for regular trends and Defining a Target Region for a Scatter Plot on page 143 for scatter plots.

Related Topics
CurrentTagTargetRegionVisible TargetRegionExcursionType TargetRegionOpacity

ManualConnect
The ManualConnect method displays the Server List Connection dialog box.
Syntax
[Result=] aaHistClientTrend.ManualConnect();

MoveNextTag
The MoveNextTag method sets the current tag to the next tag in the tag list.
Syntax
[Result=] aaHistClientTrend.MoveNextTag();

Return Value

Returns True if the operation was successful; otherwise, False is returned. If you call this method while the last tag in the list is selected, the current tag is set to the first tag in the list.

Using aaHistClientTrend in an Application

441

Syntax
[Result=] aaHistClientTrend.MovePrevTag();

Return Value

Returns True if the operation was successful; otherwise, False is returned. If you call this method while the first tag in the list is selected, the first tag remains the current tag.

The pan percentage is set using the PanPercentage property.

ActiveFactory Software Users Guide

442

Chapter 8 aaHistClientTrend Control

Syntax
[Result=] aaHistClientTrend.PrintGraph();

Related Topics
PrintGraphDlg PrintShowTitle PrintTitle

PrintGraphDlg
The PrintGraphDlg method displays the Print dialog box, allowing the runtime user to choose the printer to which to print the trend chart.
Syntax
[Result=] aaHistClientTrend.PrintGraphDlg();

Related Topics
PrintGraph PrintShowTitle PrintTitle

PropertiesDlg
The PropertiesDlg method opens the Trend Properties dialog box.
Syntax
[Result=] aaHistClientTrend.PropertiesDlg();

RefreshData
The RefreshData method refreshes the trend chart by retrieving new data for all tags.
Syntax
[Result=] aaHistClientTrend.RefreshData();

Return Value

Returns True if the trend was successfully updated; otherwise, False is returned.
Remarks

Data is requested from the databases as necessary. This method ensures that all tags within the trend that can be synchronized are synchronized.

RemoveServer
The RemoveServer method removes the specified server from the servers list. If no server is specified, this method removes the entire server list.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

443

Syntax
[Result=] aaHistClientTrend.RemoveServer([message serverName]);

Parameters

serverName The name of the server to remove.

Return Value

Returns True if the server was successfully removed; otherwise, False is returned.

ActiveFactory Software Users Guide

444

Chapter 8 aaHistClientTrend Control

Return Value

Returns the styles name as defined for the current locale. If no style names are defined for the current locale, the name in the en locale is returned.
Remarks

To find out how many retrieval styles are available in the control, use the RetrievalOptionsNumStyles property.

Related Topics
CurrentTagGetStyle RetrievalOptionsNumStyles

SaveData
The SaveData method optionally prompts the runtime user and saves the trend data (in the "wide" format) or image to a file or to the clipboard.
Syntax
[Result=] aaHistClientTrend.SaveData(integer format, message fileName);

Parameters

format The type of output: 0 Saves trend data in tab-delimited format using the file name specified in the fileName parameter. Copies the trend image to the clipboard. Copies the trend image to the clipboard. (Legacy option) Saves the trend image in JPEG format using the file name specified in the fileName parameter. Opens the Save dialog box to save the trend data in CSV or tab-delimited format.

1 2 3

100

fileName The name of the file.

Return Value

Returns True if the operation was successful; otherwise, False is returned.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

445

SaveImage
The SaveImage method saves the trend image to a JPEG file.
Syntax
[Result=] aaHistClientTrend.SaveImage(message fileName);

Parameters

fileName The name of the file. If you leave this value empty and the current trend has no file name, an error message appears when the method is executed. If you leave this value empty and the current trend has a file name, the file is saved using the trends file name with a .JPG extension.
Return Value

Returns True if the file was successfully saved; otherwise, False is returned.

min The minimum value for the value (y-axis) scale.

ActiveFactory Software Users Guide

446

Chapter 8 aaHistClientTrend Control

max The maximum value for the value (y-axis) scale.

Return Value

Returns True if the tags were successfully scaled; otherwise, False is returned.

Related Topics
ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpTag ScaleUpAllTags ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleAllTagsDlg
The ScaleAllTagsDlg method opens a dialog box that allows the user to enter new minimum and maximum scale values for all tags in the chart.
Syntax
[Result=] aaHistClientTrend.ScaleAllTagsDlg();

Return Value

Returns True if the tags were scaled as a result of this operation; otherwise, False is returned (for example, if the user clicked Cancel in the dialog box).

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

447

Related Topics
ScaleAllTags ScaleTag ScaleAutoTag ScaleUpTag ScaleUpAllTags ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleAutoTag
The ScaleAutoTag method sets a suitable y-axis scale for the currently selected tag according to the currently displayed minimum and maximum values.
Syntax
[Result=] aaHistClientTrend.ScaleAutoTag();

Return Value

Returns True if the scale was successfully set; otherwise, False is returned.

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleUpTag ScaleUpAllTags ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleDownAllTags
This method increases the value range of all tags in the chart by one third.
Syntax
[Result=] aaHistClientTrend.ScaleDownAllTags();

ActiveFactory Software Users Guide

448

Chapter 8 aaHistClientTrend Control

Return Value

Returns True if the scaling was successful; otherwise, False is returned.

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpTag ScaleUpAllTags ScaleDownTag ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleDownTag
This method increases the value range of the currently selected tag by one third.
Syntax
[Result=] aaHistClientTrend.ScaleDownTag();

Return Value

Returns True if the scaling was successful; otherwise, False is returned.

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpTag ScaleUpAllTags ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleMoveAllTagsDown
The ScaleMoveAllTagsDown method moves the value scale down for all tags in the chart.

ActiveFactory Software Users Guide

ScaleTagDlg
The ScaleTagDlg method opens a dialog box that allows the user to enter new minimum and maximum scale values for the currently selected tag.
Syntax
[Result=] aaHistClientTrend.ScaleTagDlg();

Return Value

Returns True if the tag was scaled as a result of this operation; otherwise, False is returned (for example, if the user clicked Cancel in the dialog box).

ActiveFactory Software Users Guide

452

Chapter 8 aaHistClientTrend Control

ScaleUpAllTags
This method decreases the value range of all tags in the chart by one fourth.
Syntax
[Result=] aaHistClientTrend.ScaleUpAllTags();

Return Value

Returns True if the scaling was successful; otherwise, False is returned.

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpTag ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ScaleUpTag
This method decreases the value range of the currently selected tag by one fourth.
Syntax
[Result=] aaHistClientTrend.ScaleUpTag();

Return Value

Returns True if the scaling was successful; otherwise, False is returned.

Related Topics
ScaleAllTags ScaleTag ScaleAutoAllTags ScaleAutoTag ScaleUpAllTags ScaleDownTag ScaleDownAllTags ScaleMoveTagUp ScaleMoveAllTagsUp ScaleMoveTagDown ScaleMoveAllTagsDown RubberBandScaling ApplyRubberBandToAllTags

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

453

SetCurrentTag
The SetCurrentTag method sets the specified tag to be the current tag.
Syntax
[Result=] aaHistClientTrend.SetCurrentTag(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag.
Return Value

The return value is a discrete. Returns True if successful; otherwise returns False.
Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

454

Chapter 8 aaHistClientTrend Control

The designated X axis tag is the current tag itself. The designated X axis tag is not an analog or discrete tag.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
CurrentTagIndex SetCurrentTagXAxisTagIndex

SetCurrentTagXAxisTagIndex
This method configures the currently selected tag in a scatter plot to use another tag from the tag list as its X axis tag. The X axis tag is identified by its index.
Syntax
[Result=] aaHistClientTrend.SetCurrentTagXAxisTagIndex(integer index);

Parameters

index The index of the tag that you want to use as the X axis tag for the current tag.
Return Value

The return value is a discrete. Returns True if successful; otherwise returns False. Possible causes of failures include:

No tag is currently selected. No tag matches the specified index. The current tag is not an analog or discrete tag. The designated X axis tag is the current tag itself. The designated X axis tag is not an analog or discrete tag.

Related Topics
CurrentTagIndex SetCurrentTagXAxisTag

SetDates
The SetDates method sets the start and end time for the trend.
Syntax
[Result=] aaHistClientTrend.SetDates(DateTime startTime, DateTime endTime);

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

455

Parameters

startTime The start time for the trend. endTime The end time for the trend.
Remarks

For information on setting the date/time value, see DateTime on page 638. In relative time mode, you must still specify an absolute date/time value. For example, if the start time of your tags is 11/13/2006 8:00 AM and you want the trend to start at an offset of one hour to that start time, specify 11/13/2006 9:00 AM for the startTime parameter.
Return Value

Returns True if the dates were set. Returns False in case of an error.

Related Topics
StartDate EndDate EnableTimeOffsets SetDuration

SetDuration
The SetDuration method sets the time period for the trend based on a duration that is relative to the current time.
Syntax
[Result=] aaHistClientTrend.SetDuration(DateTime duration);

Parameters

duration The time duration from the current time.

Remarks

For information on setting the date/time value, see DateTime on page 638. Calling this method sets the end time to the current time and the start time to the current time minus the specified duration.
Example

In the following example, the duration is set for the past five minutes, relative to the current time.
#aaHistClientTrend1.SetDuration("00:05:00");

ActiveFactory Software Users Guide

456

Chapter 8 aaHistClientTrend Control

Related Topics
StartDate EndDate EnableTimeOffsets SetDates

SetMenuItemEnabled
Use the SetMenuItemEnabled method to control if a specific command in the shortcut menu is enabled.
Syntax
[Result=] aaHistClientTrend.SetMenuItemEnabled(integer itemNumber, integer bEnabled);

Parameters

itemNumber The index number of the command. Numbering starts at 0. bEnabled Specify a non-zero number to enable or zero to disable.
Return Value

Returns True if the menu item is enabled; otherwise, False is returned.

Remarks

If you specify -1 as the itemNumber parameter, the method sets the status of all items in the menu. Item numbers are as follows:
Number Corresponding menu item

0 2 3 5 6 7 8 10 12 13 15 16

File Single Tag Mode Highlight Tag Next Tag Previous Tag Add Annotation Delete Tag Color View Show Scale Tag Scale All Tags

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

457

Number

Corresponding menu item

18 19 21 23 24 25 26 28 29 30 31 32 33

Rubber Band Scaling Apply Rubber Band To All Tags Pan & Zoom Copy Save Data Print Properties Chart Type Tools Live Mode Stacked Traces Refresh Update To Current Time

SetTagColor
The SetTagColor method sets the line color of the tag curve in the trend.
Syntax
[Result=] aaHistClientTrend.SetTagColor(message serverName, message tagName, integer color);

Parameters

serverName The name of the server. tagName The name of the tag. color The color value for the curve.
Return Value

Returns True if successful; otherwise returns False.

Remarks

For information on setting the color value, see Color on page 638. If the tag is shown multiple times in the chart, this property applies to the first instance of the tag that was added.

ActiveFactory Software Users Guide

458

Chapter 8 aaHistClientTrend Control

Related Topics
CurrentTagColor SetTagFormat SetTagColorDlg SetTagOffsetMS SetTagPenStyle SetTagPenWidth SetTagPrecision SetTagVisible

SetTagFormat
The SetTagFormat method sets how the values for the tag appear, either in decimal format or scientific format.
Syntax
[Result=] aaHistClientTrend.SetTagFormat(message serverName, message tagName, long format);

Parameters

serverName The name of the server. tagName The name of the tag. format The format for the tag value. 0 = Decimal; 1 = Scientific.
Return Value

Returns True if successful; otherwise returns False.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
CurrentTagFormat SetTagColor SetTagColorDlg SetTagOffsetMS SetTagPenStyle SetTagPenWidth SetTagPrecision SetTagVisible

SetTagColorDlg
This method opens a dialog box where the user can specify a color for the currently selected tag.
Syntax
[Result=] aaHistClientTrend.SetTagColorDlg();

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

459

Return Value

Returns a discrete value. Returns True if the dialog was shown; otherwise, False is returned (for example, if there are no tags in the trend).

Related Topics
SetTagColor SetTagFormat SetTagOffsetMS SetTagPenStyle SetTagPenWidth SetTagPrecision SetTagVisible

SetTagOffsetMS
The SetTagOffsetMS method sets the amount of time that the trend curve will be shifted from the actual time.
Syntax
[Result=] aaHistClientTrend.SetTagOffsetMS(message serverName, message tagName, integer milliseconds);

Parameters

serverName The name of the server. tagName The name of the tag. milliseconds The offset, in milliseconds, for the shift. The offset can be positive or negative. For more information, see Using Time Offsets to Compare Data on page 115.
Return Value

Returns a discrete value. Returns True if the set was successful; otherwise, False is returned. Due to the limited range for integer values, the maximum offset you can set using this property is about 29 days. For larger offsets, use the CurrentTagStartDate property.
Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

460

Chapter 8 aaHistClientTrend Control

Related Topics
CurrentTagOffsetMS CurrentTagStartDate SetTagColor SetTagFormat SetTagColorDlg SetTagPenStyle SetTagPenWidth SetTagPrecision SetTagVisible

SetTagPenStyle
The SetTagPenStyle method sets the style of the trend curve for the currently selected tag. For example, a solid or dashed line.
Syntax
[Result=] aaHistClientTrend.SetTagPenStyle(message serverName, message tagName, integer penStyle);

Parameters

serverName The name of the server. tagName The name of the tag. penStyle The appearance of the pen. Valid values are: 0 1 2 3 4 5
Return Value

Solid Dashed Dotted DashDot DashDotDot Alternate

Returns True if successful; otherwise returns False.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

461

Related Topics
CurrentTagPenStyle SetTagColor SetTagFormat SetTagColorDlg SetTagOffsetMS SetTagPenWidth SetTagPrecision SetTagVisible

SetTagPenWidth
The SetTagPenWidth method sets the thickness of the trend curve.
Syntax
[Result=] aaHistClientTrend.SetTagPenWidth(message serverName, message tagName, integer width);

Parameters

serverName The name of the server. tagName The name of the tag. width The width, in pixels, of the pen.
Return Value

Returns True if successful; otherwise returns False.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
CurrentTagPenWidth SetTagColor SetTagFormat SetTagColorDlg SetTagOffsetMS SetTagPenStyle SetTagPrecision SetTagVisible

SetTagPrecision
The SetTagPrecision method sets the number of decimal places to display for the data value. This applies only to analog tags.

ActiveFactory Software Users Guide

462

Chapter 8 aaHistClientTrend Control

Syntax
[Result=] aaHistClientTrend.SetTagPrecision(message serverName, message tagName, integer precision);

Parameters

serverName The name of the server. tagName The name of the tag. precision The decimal places (precision) for the tag. Valid values are 0 to 15.
Return Value

Returns True if successful; otherwise returns False.

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

Related Topics
CurrentTagPrecision SetTagColor SetTagFormat SetTagColorDlg SetTagOffsetMS SetTagPenStyle SetTagPenWidth SetTagVisible DefaultTagFormat DefaultTagPrecision

SetTagVisible
The SetTagVisible method sets whether a tag is visible in the trend chart.
Syntax
[Result=] aaHistClientTrend.SetTagVisible(message serverName, message tagName, discrete bVisible);

Parameters

serverName The name of the server. tagName The name of the tag. bVisible False = Not visible; True = Visible.
Return Value

Returns True if successful; otherwise returns False.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

463

Remarks

If the specified tag is shown in the chart multiple times, the method uses the first instance that was added.

ActiveFactory Software Users Guide

464

Chapter 8 aaHistClientTrend Control

Syntax
[Result=] aaHistClientTrend.SetToolbarButtonEnabled(integer buttonNumber, integer bEnabled);

Parameters

buttonNumber The index number of the toolbar button. Numbering starts at 0. bEnabled Specify a non-zero number to enable the button. Set to zero to disable.
Return Value

Returns True if the button can be enabled; otherwise, False is returned. Button numbers are as follows:
Number Corresponding button

0 1 2 3 5 6 7 9 10 11 12 13 14 16 17 19 20 21 22

Open a trend Save the trend Print the trend Copy Configure the servers Configure the trend properties Configure the trend options Select XY Scatter Plot or Trend chart type Enable or disable single tag mode Stack the tag traces Move to the previous tag Move to the next tag Highlight tag Show or hide the time axis cursor Show or hide the value axis cursor Move the current tag up Move the current tag down Scale all tags to their original scale Auto scale all tags

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

465

Number

Corresponding button

23 24 26 27 28

Scale all tags up Scale all tags down Enable rubber band scaling Apply rubber band to all tags View license status

UnsetCurrentTagXAxisTag
This method removes any associated X axis tag from the currently selected tag in a scatter plot.
Syntax
aaHistClientTrend.UnsetCurrentTagXAxisTag();

Remarks

If the current tag is not associated with any X axis tag, this method does nothing.

Related Topics
SetCurrentTagXAxisTag SetCurrentTagXAxisTagIndex

ZoomIn
The ZoomIn method zooms in on the trend chart.
Syntax
[Result=] aaHistClientTrend.ZoomIn();

Return Value

Returns True if the time range for the operation can be set; otherwise, False is returned.
Remarks

The amount of the zoom is controlled by the ZoomOutPercentage property.

Related Topics
ZoomOut ZoomOutPercentage

ZoomOut
The ZoomOut method zooms out on the trend chart.
Syntax
[Result=] aaHistClientTrend.ZoomOut();

ActiveFactory Software Users Guide

466

Chapter 8 aaHistClientTrend Control

Return Value

Returns True if the time range for the operation can be set; otherwise, False is returned.
Remarks

The amount of the zoom is controlled by the ZoomOutPercentage property.

ActiveFactory Software Users Guide

Using aaHistClientTrend in an Application

467

Related Topics
DatesChanged StateChanged TagDisplayChanged TaglistChanged

DatesChanged
The DatesChanged event is triggered when the date for the trend changes. It is also triggered once when the live or replay modes are started, but not on the automatic updates that follow.
Syntax
aaHistClientTrend.DatesChanged();

Related Topics
CurrentTagChanged StateChanged TagDisplayChanged TaglistChanged

StateChanged
The StateChanged event is triggered when a change has been made to the configuration for a tag in the Tag List.
Syntax
aaHistClientTrend.StateChanged();

Related Topics
CurrentTagChanged DatesChanged TagDisplayChanged TaglistChanged

TagDisplayChanged
The TagDisplayChanged event is triggered when the display options for a tag in the Tag List are changed. This includes the following actions:

Showing or hiding the tag Changing the type, color, width, or style of the tags trend curve Changing the tags value format or precision Changing the tags time offset Changing the tags scale Editing the tags target region

ActiveFactory Software Users Guide

468

Chapter 8 aaHistClientTrend Control

Syntax
aaHistClientTrend.TagDisplayChanged(message serverName, message tagName, integer displayItem);

Parameters

serverName The name of the server. tagName The name of the tag. displayItem The identifier for the displayed trend item.
Remarks

To retrieve the value of an event parameter in the InTouch HMI software, refer to #ThisEvent.<Event Name><Parameter Name> inside the script for the respective event. For example, to read the value of the tagName parameter, use a statement like the following:
MyMsgTag = #ThisEvent.TagDisplayChangedtagName;

Related Topics
CurrentTagChanged DatesChanged StateChanged TaglistChanged

TaglistChanged
The TaglistChanged event is triggered when a tag is added or removed from the Tag List.
Syntax
aaHistClientTrend.TaglistChanged();

Related Topics
CurrentTagChanged DatesChanged StateChanged TagDisplayChanged TaglistChanged

aaHistClientTrend Enumerations
The aaHistClientTrend enumerations include:

aaChartType Enumeration aaDashStyle Enumeration aaDataPointLabelingType Enumeration

ActiveFactory Software Users Guide

aaHistClientTrend Enumerations

469

aaDateModeEnumeration Enumeration aaInterpolationType Enumeration aaQualityRules Enumeration aaRetrievalMode Enumeration aaRetrievalVersion Enumeration aaStateCalculation Enumeration aaTargetRegionExcursionType Enumeration aaTimeStampRules Enumeration aaTraceGradientType Enumeration aaTrendGradientType Enumeration aaTrendType Enumeration aaTrendValueFormat Enumeration aaValueAxisLabelEnumeration Enumeration

aaChartType Enumeration
An enumeration used to specify the chart type.
Value Enumeration Description

0 1

Trend XYScatterPlot

Regular trend. XY scatter plot.

aaDashStyle Enumeration
An enumeration used to specify the line style.
Value Enumeration Description

0 1 2 3 4

Dash DashDot DashDotDot Dot Solid

Specifies a line consisting of dashes. Specifies a line consisting of a repeating pattern of dash-dot. Specifies a line consisting of a repeating pattern of dash-dot-dot. Specifies a line consisting of dots. Specifies a solid line.

ActiveFactory Software Users Guide

470

Chapter 8 aaHistClientTrend Control

aaDataPointLabelingType Enumeration
An enumeration used to specify the type of labels that are shown next to data points on a chart.
Value Enumeration Description

0 1

None TimeLabelsOnCurrentTag

No labels. Time labels on the currently selected tag, evenly spaced in time.

aaDateModeEnumeration Enumeration
An enumeration used to specify the time mode for the trend chart.
Value Enumeration Description

0 1

Absolute Relative

Use absolute time. Use relative time.

aaInterpolationType Enumeration
Specifies the interpolation type for data retrieval.
Value Enumeration Description

0 1 2

Stairstep Linear ApplicationSetting

Use stair-step interpolation. Use linear interpolation. Use the default interpolation type specified at the control level. This value is only valid at the tag level, but not at the control level itself. Use the default interpolation type specified at the IndustrialSQL Server historian level.

ServerDefault

For more information on each option, see Interpolation Type on page 678.

aaQualityRules Enumeration
Specifies the quality rule for data retrieval.
Value Enumeration Description

Extended

Include data values with doubtful quality in calculations.

ActiveFactory Software Users Guide

aaHistClientTrend Enumerations

471

Value

Enumeration

Description

1 2

Good ApplicationSetting

Exclude data values with doubtful quality from calculations. Use the default quality rule specified at the control level. This value is only valid at the tag level, but not at the control level itself. Use the default quality rule specified at the IndustrialSQL Server historian level.

ServerDefault

For more information on each option, see Quality Rule on page 682.

aaRetrievalMode Enumeration
Specifies the data retrieval mode.
Value Enumeration Description

0 1 2 3 4 5 6 7 8 9 10 11 12

Cyclic Delta Full Interpolated BestFit Average Min Max Integral Slope Counter ValueState ApplicationSetting

Use Cyclic retrieval mode. Use Delta retrieval mode. Use Full retrieval mode. Use Interpolated retrieval mode. Use Best Fit retrieval mode. Use Time-Weighted Average retrieval mode. Use Minimum retrieval mode. Use Maximum retrieval mode. Use Integral retrieval mode. Use Slope retrieval mode. Use Counter retrieval mode. Use Time-in-State retrieval for tag values. Use the default retrieval mode specified at the control level. This value is only valid at the tag level, but not at the control level itself.

For more information on each option, see Understanding Retrieval Modes on page 649.

ActiveFactory Software Users Guide

472

Chapter 8 aaHistClientTrend Control

aaRetrievalVersion Enumeration
Specifies the history version to retrieve data from.
Value Enumeration Description

0 1

Latest Original

Retrieve the latest values available for a tag. Retrieve the original values historized for a tag. For more information on each option, see History Version on page 678.

aaStateCalculation Enumeration
Specifies the aggregation type to use in Time-in-State data retrieval.
Value Enumeration Description

Min

Calculate the shortest amount of time that the tag was in each unique state over the query period. Calculate the longest amount of time that the tag was in each unique state over the query period. Calculate the average amount of time that the tag was in each unique state over the query period. Calculate the total amount of time that the tag was in each unique state over the query period. Calculate the total percentage of time that the tag was in each unique state over the query period. Use the default aggregation type specified at the control level. This value is only valid at the tag level, but not at the control level itself.

1 2

Max Average

3 4

Total Percent

ApplicationSetting

For more information on each option, see State Calculation on page 683.

aaTargetRegionExcursionType Enumeration
An enumeration used to specify whether values that fall outside a tags target region should be highlighted.
Value Enumeration Description

None

Dont highlight values.

ActiveFactory Software Users Guide

aaHistClientTrend Enumerations

473

Value

Enumeration

Description

ShowWithSpecialColor

Highlight values in a special color.

aaTimeStampRules Enumeration
Specifies the timestamp rule for data retrieval.
Value Enumeration Description

0 1 2

Start End ApplicationSetting

Query results are timestamped at the beginning of each cycle. Query results are timestamped at the end of each cycle. Use the default timestamp rule specified at the control level. This value is only valid at the tag level, but not at the control level itself. Use the default timestamp rule specified at the IndustrialSQL Server historian level.

ServerDefault

For more information on each option, see Timestamp Rule on page 680.

aaTraceGradientType Enumeration
An enumeration used to specify the gradient type applied to the trace in a scatter plot.
Value Enumeration Description

0 1

None OpacityGradient

No gradient. Opacity gradient from the start to the end of the trace.

aaTrendGradientType Enumeration
Specifies the gradient type for the plot area and the background for a trend.
Value Enumeration Description

0 1 2 3

None LeftRight TopBottom Center

No gradient. Gradient from left to right. Gradient from top to bottom. Gradient from center outwards.

ActiveFactory Software Users Guide

474

Chapter 8 aaHistClientTrend Control

Value

Enumeration

Description

4 5 6 7

DiagonalLeft DiagonalRight HorizontalCenter VerticalCenter

Gradient from top left to bottom right. Gradient from top right to bottom left. Gradient from center to left and right edges. Gradient from the center to top and bottom edges.

aaTrendType Enumeration
Specifies the type of line for the trend curve.
Value Enumeration Description

0 1 2

Point Line StepLine

No line. A straight line is drawn directly from point to point on the trend. The line is drawn horizontally to the next point and then vertically up (if ascending) or down (if descending). Automatically determine the curve type. For more information on each option, see Configuring Display Options on page 67.

Auto

aaTrendValueFormat Enumeration
Specifies the value display format of the trend value.
Value Enumeration Description

0 1

Decimal Scientific

The decimal format. The scientific format.

aaUpdateToCurrentTimeState Enumeration
Specifies the state of the Update to Current Time option.
Value Enumeration Description

0 1

Reset Set

Option is disabled. The corresponding toolbar button is not highlighted. Option is enabled. The corresponding toolbar button is highlighted.

ActiveFactory Software Users Guide

Using aaHistClientTrend in a Multi-Monitor Environment

475

aaValueAxisLabelEnumeration Enumeration
Specifies the value display format of the trend value. For more information on the types of scales, see Scaling Tags on page 81.
Value Enumeration Description

0 1 2

MultipleScales SingleScale ValuesAtCursor

Show multiple value scales on the chart. Show a single value scale on the chart. Show data values at the point at which the cursor intersects the data.

Using aaHistClientTrend in a Multi-Monitor Environment

By default, dialog boxes shown by the aaHistClientTrend control appear in the middle of the screen. This may be a problem in multi-monitor configurations where multiple screens are combined into one large logical screen. To avoid this, you can specify a screen position where dialog boxes should appear.
To specify a screen position for dialog boxes 1 2 3

Open the win.ini file in your Windows folder using a text editor. Look for the [HistClient] section. If no such section exists, create one. Add the following lines to the [HistClient] section:
UsedFixedWindowPosition=1 FixedWindowPositionX=<XPos> FixedWindowPositionY=<YPos>

where <XPos> is the horizontal position (in pixels) where you want dialog boxes to appear, and <YPos> is the vertical position. For example, FixedWindowPositionX=300.
4

Save the win.ini file and restart the Trend application. Dialog boxes now appear at the position you specified.

ActiveFactory Software Users Guide

476

Chapter 8 aaHistClientTrend Control

ActiveFactory Software Users Guide

477

Chapter 9
aaHistClientQuery Control

The aaHistClientQuery control allows you to run the ActiveFactory Query program (or a functional subset) from within the Wonderware InTouch HMI software or a .NET container like Visual Basic .NET or Internet Explorer. For more information on using ActiveFactory Query, see ActiveFactory Query on page 161.

Using aaHistClientQuery at Runtime

At runtime, aaHistClientQuery can retrieve data from the IndustrialSQL Server historian database and return the results in a table format. You can use aaHistClientQuery just as you do the ActiveFactory Query application. For more information on using ActiveFactory Query, see ActiveFactory Query on page 161.

Using aaHistClientQuery in an Application

aaHistClientQuery is capable of running with all of the functionality of the ActiveFactory Query application. You can also use the aaHistClientQuery control's properties, methods, and events in runtime scripts in your application to control the functionality that is available to the runtime user. For example, maybe you want to limit the functionality of aaHistClientQuery to only allow the runtime operator to connect to an IndustrialSQL Server historian and run a particular query for a specific set of tags.

ActiveFactory Software Users Guide

478

Chapter 9 aaHistClientQuery Control

Adding aaHistClientQuery to an InTouch Window

To add the aaHistClientQuery control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientQuery control. Click OK. The control appears in the window.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

479

aaHistClientQuery Properties
The properties for the aaHistClientQuery control are:

ActiveServer AllowQueryTypeChange CurrentServer EnableAllQueriesTab FavoriteQueriesFolder FontBold FontCharset FontItalic FontName FontSize QueryFont QueryString Recordset Servers ToolbarConnectVisible ToolbarEditVisible ToolbarRequeryVisible ToolbarVisible UsePersistedServers

ActiveServer
The ActiveServer property is a read-write property that sets or gets the name of the server to which the aaHistClientQuery is connected.
Syntax
aaHistClientQuery.ActiveServer = message; Result = aaHistClientQuery.ActiveServer;

Return Value

The name of the server as a message. If there are no active servers, this property returns a NULL.
Remarks

This property has no default.

ActiveFactory Software Users Guide

480

Chapter 9 aaHistClientQuery Control

AllowQueryTypeChange
The AllowQueryTypeChange property is a read-write property that gets or sets whether the runtime user is allowed to change the query type.
Syntax
aaHistClientQuery.AllowQueryTypeChange = discrete; Result = aaHistClientQuery.AllowQueryTypeChange;

Remarks

The default is True.

CurrentServer
The CurrentServer property is a read-only property that returns the aaServer object of the server to which the aaHistClientQuery is connected.
Syntax
Result = aaHistClientQuery.CurrentServer;

Remarks

If there are no active servers, this property returns a NULL. For more information on the aaServer object, see aaServer Object on page 567. This property has no default.

EnableAllQueriesTab
The EnableAllQueriesTab property is a read-write property that shows or hides the All Queries tab in the Results pane.
Syntax
aaHistClientQuery.EnableAllQueriesTab = discrete; Result = aaHistClientQuery.EnableAllQueriesTab;

Remarks

The default is False.

FavoriteQueriesFolder
The FavoriteQueriesFolder property is a read-write property that gets or sets the location of the favorite queries folder.
Syntax
aaHistClientQuery.FavoriteQueriesFolder = message; Result = aaHistClientQuery.FavoriteQueriesFolder;

Remarks

When the FavoriteQueriesFolder property is set, the query file list in the corresponding folder is transferred to the Favorite Queries list box. This property has no default.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

481

FontBold
The FontBold property is a read-write property that gets or sets the boldface characteristic for the font used for displaying the query text in the SQL and All Queries tab in the Results pane.
Syntax
aaHistClientQuery.FontBold = discrete; Result = aaHistClientQuery.FontBold;

Remarks

True = Use bold; False = Do not use bold. The default is False.

FontCharset
The FontCharset property is a read-write property that gets or sets the character set used for the query and result text.
Syntax
aaHistClientQuery.FontCharset = integer; Result = aaHistClientQuery.FontCharset;

Remarks

This property is an integer value that specifies the character set used by the font. The following are some common settings for the value:
Value Description

0 1 2 77 128 129, 130 134 136 161 162 163 177

The standard Windows character set (ASCII). The system default character set. The symbol character set. Characters used by Macintosh. The Japanese character set. Korean character set. The Chinese character set used in mainland China (Simplified Chinese) The Chinese character set used mostly in Hong Kong SAR and Taiwan (Traditional Chinese). The Greek character set. The Turkish character set. The Vietnamese character set. The Hebrew character set.

ActiveFactory Software Users Guide

482

Chapter 9 aaHistClientQuery Control

Value

Description

178 204 222 238 255

The Arabic character set. The Russian character set. The Thai character set. The Eastern European character set. The extended ASCII character set used with DOS and some Microsoft Windows fonts.

The default is 1.

FontItalic
The FontItalic property is a read-write property that gets or sets whether the query text appears in an italicized font.
Syntax
aaHistClientQuery.FontItalic = discrete; Result = aaHistClientQuery.FontItalic;

Remarks

True = Use italics; False = Do not use italics. The default is False.

FontName
The FontName property is a read-write property that gets or sets the name of the font family used for the query text.
Syntax
aaHistClientQuery.FontName = message; Result = aaHistClientQuery.FontName;

Remarks

The default is Tahoma.

FontSize
The FontSize property is a read-write property that gets or sets the size, in points, of the font used for displaying the query text.
Syntax
aaHistClientQuery.FontSize = integer; Result = aaHistClientQuery.FontSize;

Remarks

The default is 8.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

483

QueryFont
The QueryFont property is a read-write property that gets or sets the font used for displaying the query text.
Syntax
aaHistClientQuery.QueryFont = Font; Result = aaHistClientQuery.QueryFont;

Remarks

This property is not accessible in the InTouch HMI software. For more information on setting the font, see Font on page 639. The default is Tahoma, 8 point (for English versions).

QueryString
The QueryString property is a read-write property that gets or sets the query string.
Syntax
aaHistClientQuery.QueryString = message; Result = aaHistClientQuery.QueryString;

Remarks

If you set the QueryString property, then the query type is automatically set to Custom. This property has no default.

Recordset
The Recordset property is a read-only property that gets the data set for the query.
Syntax
DataSet = aaHistClientQuery.Recordset;

Return Value

Returns a DataSet object. For more information on data sets, see DataSet on page 639.
Remarks

The default is True.

ToolbarVisible
This read-write property shows or hides the entire toolbar.
Syntax
aaHistClientQuery.ToolbarVisible = discrete; Result = aaHistClientQuery.ToolbarVisible;

Remarks

The default is True, that is, the toolbar is visible.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

485

UsePersistedServers
This read-write property controls whether changes to the controls server connections are only valid for the current runtime session, or whether they are saved to the global server list shared by the ActiveFactory applications.
Syntax
aaHistClientQuery.UsePersistedServers = discrete; Result = aaHistClientQuery.UsePersistedServers;

Remarks

If you set this property to True, changes to the configured server connections are saved in the global server list. If you set it to False, changes dont affect the global server list. For example, if you add a server while this property is set to True, the server is added to the global list. If you set the property to False and remove the same server, it disappears from the server list for the current runtime session, but it is not deleted from the global list. The default is False. To initialize the control with the server connections stored in the global list, set the value to True. You can set it back to False afterwards to avoid inadvertent changes by the runtime user. For more information on managing servers, see Server Connection Configuration on page 39.

aaHistClientQuery Methods
The aaHistClientQuery methods are:

AddServer AddTag ClearTags CopyQuery CutQuery FileOpen ManualConnect OpenQuery PasteQuery RemoveTag Refresh SaveQuery

ActiveFactory Software Users Guide

486

Chapter 9 aaHistClientQuery Control

SaveResults SetDates SetDuration SetQueryType SetQueryType2 SetTimeSpan ShowAbout

AddServer
The AddServer method adds a server to the list.
Syntax
[Result=] aaHistClientQuery.AddServer(message serverName, message loginName, message password, [discrete bPersistPassword]);

Parameters

serverName The name of the server. loginName A valid user name for the server. password A valid password for the server. bPersistPassword If set to True, the password is remembered for the next time a connection is attempted. The password is only remembered for a single application; the persisted password is not available to all applications.
Return Value

Returns True if the server can be added; otherwise returns False.

AddTag
The AddTag method adds a tag to the tag collection.
Syntax
[Result=] aaHistClientQuery.AddTag(message serverName, message tagName, integer tagType);

Parameters

serverName The name of the server. tagName The name of the tag to add.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

487

tagType The type of the tag. This parameter is provided for backward compatibility and doesnt have any effect on the outcome of the operation. However, you must still specify one of the following valid values: 1, 2, 3, or 5.
Return Value

Returns True if the tag can be added; otherwise, False is returned.

ClearTags
The ClearTags method removes all of the tags from the query.
Syntax
[Result=] aaHistClientQuery.ClearTags();

Example

In the following example, all tags from the query are deleted, and the ReactLevel tag is added to the query.
#aaHistClientQuery1.ClearTags; #aaHistClientQuery1.AddTag("MyInSQL", "ReactLevel", 1);

CopyQuery
The CopyQuery method copies the current selection in the query text box to the clipboard.
Syntax
[Result=] aaHistClientQuery.CopyQuery();

CutQuery
The CutQuery method deletes the current selection in the query text box and then copies it to the clipboard.
Syntax
[Result=] aaHistClientQuery.CutQuery();

FileOpen
The FileOpen method opens a specified text file containing a SQL query.
Syntax
[Result=] aaHistClientQuery.FileOpen(message fileName);

Parameters

fileName The full path to the file.

ActiveFactory Software Users Guide

488

Chapter 9 aaHistClientQuery Control

Remarks

When this method is called, it automatically sets the query type to Custom. If the SQL tab is active at the time the method is called, the method loads the SQL query from the file into the SQL tab, but doesnt send it to the server. If the Data tab is active, the method loads the query into the SQL tab, sends it to the currently selected server, and shows the results on the Data tab.
Return Value

Returns True if the file can be opened successfully; otherwise returns False (for example, if no file name is specified or the specified file doesnt exist).

ManualConnect
The ManualConnect method opens the Server connection dialog box.
Syntax
[Result=] aaHistClientQuery.ManualConnect();

OpenQuery
The OpenQuery method opens the Open dialog box, so that the runtime user can select an existing query file (.sql) to open.
Syntax
[Result=] aaHistClientQuery.OpenQuery();

PasteQuery
The PasteQuery method pastes the current contents of the clipboard to the query text box.
Syntax
[Result=] aaHistClientQuery.PasteQuery();

Refresh
The Refresh method re-executes the query.
Syntax
[Result=] aaHistClientQuery.Refresh();

Remarks

The focus must be on the Results tab for this method to take effect.

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

489

RemoveTag
The RemoveTag method removes the specified tag from the query.
Syntax
[Result=] aaHistClientQuery.RemoveTag(message serverName, message tagName);

Parameters

serverName The name of the server. tagName The name of the tag to remove.
Return Value

Returns True if the tag was found and can be removed; otherwise, False is returned.

SaveQuery
The SaveQuery method opens the Save As dialog box, so that the runtime user can save the current query to a text file.
Syntax
[Result=] aaHistClientQuery.SaveQuery();

SaveResults
The SaveResults method opens the Save As dialog box, so that the runtime user can save the current Data tab contents to a .txt or .csv file.
Syntax
[Result=] aaHistClientQuery.SaveResults();

SetDates
The SetDates method sets the start and end time for the query.
Syntax
[Result=] aaHistClientQuery.SetDates(DateTime startTime, DateTime endTime);

Parameters

startTime The start time for the query. endTime The end time for the query.
Remarks

For more information on setting the date/time, see DateTime on page 638.

ActiveFactory Software Users Guide

490

Chapter 9 aaHistClientQuery Control

Return Value

Returns True if the dates were set. Returns False in case of an error.

SetDuration
The SetDuration method sets the query period as a duration relative to the current time.
Syntax
[Result=] aaHistClientQuery.SetDuration(real duration); [Result=] aaHistClientQuery.SetDuration(DateTime duration);

Parameters

duration The duration from the current time.

Remarks

When using the ActiveX version of the control (for example, in the InTouch HMI software), the duration parameter can be either a number of days or a date/time string. When using the .NET version of the control, the duration parameter must be a valid DateTime value. In both cases, when you specify a date/time value, the duration is the difference between the specified date/time and the base date of December 30th, 1899, 12:00:00 AM. For more information on the format for date/time values, see DateTime on page 638.
Example

In the following example, the time period is set to the past five minutes, relative to the current time.
#aaHistClientQuery1.SetDuration("00:05:00");

In the following example, the time period is set to the past 36 hours by specifying the number of days.
#aaHistClientQuery1.SetDuration(1.5);

In the following example, the time period is set to the past 36 hours by specifying a date/time value.
#aaHistClientQuery1.SetDuration("12/31/1899 12:00:00");

SetQueryType
The SetQueryType method selects the specified query type and tag type in the TagPicker.
Syntax
[Result=] aaHistClientQuery.SetQueryType(aaQueryTypeEnumeration queryType, aaTagType tagType);

ActiveFactory Software Users Guide

Chapter 9 aaHistClientQuery Control

duration The time duration, either Custom or an enumerated set.

Return Value

Returns True if the time span can be set; otherwise, False is returned.
Remarks

The times can be specified as a duration (Last5Minutes, Last24Hours, etc.) or as a pair of start and end values, in which case the duration must be specified as Custom. For more information on setting the date/time, see DateTime on page 638. For more information on setting the duration, see aaTimeRangeEnumeration Enumeration on page 636.

ShowAbout
The ShowAbout method opens the About dialog box.
Syntax
[Result=] aaHistClientQuery.ShowAbout();

aaHistClientQuery Events
The aaHistClientQuery events are:

ModeChanged QueryChanged ServerChanged

ModeChanged
The ModeChanged event is triggered when the runtime user changes tabs on the Results pane in the control.
Syntax
aaHistClientQuery.ModeChanged(integer mode);

Parameters

mode The type of tab for which changes are detected. 0 = The focus has changed to the Query or All Queries tab; 1 = The focus has changed to the Results tab.
Remarks

To retrieve the value of an event parameter in the InTouch HMI software, refer to #ThisEvent.<Event Name><Parameter Name> inside the script for the respective event. For example, to read the value of the mode parameter, use a statement like the following:
MyIntTag = #ThisEvent.ModeChangedmode;

ActiveFactory Software Users Guide

Using aaHistClientQuery in an Application

493

QueryChanged
The QueryChanged event is triggered when the query is changed.
Syntax
aaHistClientQuery.QueryChanged();

Remarks

When the query changes as a result of a user action with the control (not as a result of entering text), or as a result of changing the query type, the control triggers a query changed event, unless the query is of Custom type. For a Custom query, the change event is triggered each time the user changes the text. The change event is also triggered when the user sets the QueryString property.

ServerChanged
The ServerChanged event is triggered when the server is changed.
Syntax
aaHistClientQuery.ServerChanged();

Remarks

This event is triggered when a logon has successfully completed.

aaQueryTypeEnumeration
Used for specifying the various types of queries for the aaHistClientQuery control.
Value Enumeration Description

0 1 2

TagDetails LiveValues HistoryValues

Retrieve configuration details for the specified tags. Retrieve the realtime value of the specified tags. Retrieve the history of the tag values over time for the specified tags. Allows control over the format, and all of the time domain extensions for the IndustrialSQL Server historian. Retrieve aggregated values of the specified tags. For example, minimum, maximum, sum, average. Retrieve the values calculated by the summary system of the specified tags. Retrieve when specified events have occurred in history.

AggregateValues

4 5

SummaryValues EventHistoryValues

ActiveFactory Software Users Guide

494

Chapter 9 aaHistClientQuery Control

Value

Enumeration

Description

6 7 8 9 10 11 12 13 14 15 16 17 18 19

EventSnapshot AlarmLimits TagSearch Custom Annotations Favorite AlarmHistory ServerVersion StorageStartDate TimeRunning NumberOfTags StorageSizeAvailable IOServer Storage

Retrieve the values of tags associated with events at the time that the events occurred. Retrieve information about the limits configured for analog tags. Search for tags. Indicates to create a custom query. Retrieves comments regarding data points. Indicates to use a pre-existing SQL query. Retrieve alarm data based on limits configured using the IndustrialSQL Server historian. Retrieve the server version. Retrieve the start date of data storage. Retrieve the amount of time the server has been running. Retrieve a tag count for various kinds of tags. Retrieve storage size availibility information. Retrieve information regarding the specified I/O server(s). Retrieve storage details.

ActiveFactory Software Users Guide

495

Chapter 10
aaHistClientTagPicker Control

The aaHistClientTagPicker control allows you to view the hierarchy of objects in the IndustrialSQL Server historian database (for example, tags, InTouch nodes, events, and so on) in a hierarchical format. For more information on using the aaHistClientTagPicker, see Tag Picker on page 51.

Using aaHistClientTagPicker at Runtime

The aaHistClientTagPicker control functions the same as the Tag Picker that appears in the Trend and Query applications. For more information on using the Tag Picker, see Tag Picker on page 51.

Using aaHistClientTagPicker in an Application

Use the aaHistClientTagPicker control's properties, methods, and events to create scripts that set up a database connection and customize how the aaHistClientTagPicker control behaves during runtime. For example, you can configure the Filter pane so that does not appear during runtime. All properties, methods, and events can be controlled through scripting. In addition, some of these properties and methods are exposed through the aaHistClientTagPicker property panel available during application development.

ActiveFactory Software Users Guide

496

Chapter 10 aaHistClientTagPicker Control

Adding aaHistClientTagPicker to an InTouch Window

To add the aaHistClientTagPicker control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientTagPicker control.

Click OK. The control appears in the window.

ActiveFactory Software Users Guide

Using aaHistClientTagPicker in an Application

497

aaHistClientTagPicker Properties
The aaHistClientTagPicker properties are:

CurrentServer DescriptionFilter ExactMatchFilter FilterVisible HideCaption IOAddressFilter SelectedPath SelectedTagCount Servers SingleSelectMode SplitterOrientation TagNameFilter TreeVisible TreeWidth

CurrentServer
The CurrentServer property is a read-write property that gets or sets the selected server in the Servers pane.
Syntax
aaHistClientTagPicker.CurrentServer = aaServer; Result = aaHistClientTagPicker.CurrentServer;

Remarks

The default is False, that is, the caption is shown.

IOAddressFilter
The IOAddressFilter property is a read-write property that gets or sets the I/O address filter criteria.
Syntax
aaHistClientTagPicker.IOAddressFilter = message; Result = aaHistClientTagPicker.IOAddressFilter;

Remarks

The default is an empty message value ( "" ).

ActiveFactory Software Users Guide

Using aaHistClientTagPicker in an Application

499

SelectedPath
Use this read-write property to return the path of the currently selected folder or to show only a specific part of the folder structure on an IndustrialSQL Server historian.
Syntax
aaHistClientTagPicker.SelectedPath = message; Result = aaHistClientTagPicker.SelectedPath;

Remarks

This property serves two purposes:

When you read this property, the path of the currently selected folder in the Servers pane is returned. For example, if the All Analog Tags folder in the Public Groups folder on the Server1 host is selected, this property returns Server1.Public Groups.All Analog Tags. When you write to this property, the Tag Picker only displays the contents of the specified path for a server. For example, if you set this property to Server1.Public Groups, the Servers pane only shows the contents of the Public Groups folder for the Server1 host. To show all folders on a server again, set the property to the server name. For example, to show all folders on the Server1 host, set this property to Server1.

Values are case-sensitive if the IndustrialSQL Server historian is installed on a case-sensitive SQL Server.

SelectedTagCount
This read-only property gets the total count of tags that are selected in the Tag Picker.
Syntax
Result = aaHistClientTagPicker.SelectedTagCount;

Remarks

This property has no default.

Servers
This read-write property gets or sets the list of servers.
Syntax
aaHistClientTagPicker.Servers = aaServers; Result = aaHistClientTagPicker.Servers;

Remarks

This property uses the aaServers object. For more information, see aaServer Object on page 567. This property has no default.

ActiveFactory Software Users Guide

500

TreeWidth
The TreeWidth property is a read-write property that gets or sets the width of the Servers pane when the splitter orientation is vertical or the height of the Servers pane when the splitter orientation is horizontal.
Syntax
aaHistClientTagPicker.TreeWidth = integer; Result = aaHistClientTagPicker.TreeWidth;

Remarks

The default is 80.

aaHistClientTagPicker Methods
The aaHistClientTagPicker methods are:

ApplyFilter LogOn RefreshTags SelectedTag

ApplyFilter
The ApplyFilter method applies the filter as set up by the properties for the name, description, and I/O address filters.
Syntax
[Result=] aaHistClientTagPicker.ApplyFilter();

LogOn
The LogOn method displays a dialog box for connecting to the specified server.
Syntax
[Result=] aaHistClientTagPicker.Logon(aaServer server);

Parameters

server The server to which to connect.

ActiveFactory Software Users Guide

502

Chapter 10 aaHistClientTagPicker Control

Remarks

This methods uses the aaServer object. For more information, aaServer Object on page 567.

RefreshTags
The RefreshTags method applies the current filter conditions to all tags from a server.
Syntax
[Result=] aaHistClientTagPicker.RefreshTags();

Remarks

Use the RefreshTags() method to update the set of filtered tags with any new tags that have been added to the server since the filter was applied. For example, you can add a tag to the server using a script and then use this method to refresh the Tag Picker so that the new tag is shown.

SelectedTag
The SelectedTag method gets the selected tag as identified by the index.
Syntax
[aaTag=] aaHistClientTagPicker.SelectedTag(integer index);

Parameters

index The numerical identifier for the tag. The identifier is zero-based.
Return Value

Returns the tag or, if it is out of bounds, returns NULL. (It does not return a NULL string.)
Remarks

This method works in conjunction with the SelectedTagCount property.

Example

The following InTouch HMI software example gets all of the selected tags using a loop:
DIM i AS INTEGER; DIM count AS INTEGER; Count = #aaHistClientTagPicker3.SelectedTagCount; FOR i = 0 TO count - 1

%ReturnTag = #aaHistClientTagPicker3.SelectedTag( i );
NEXT;

In this example, Count is the number of tags and is gotten using the SelectedTagCount property.

ActiveFactory Software Users Guide

Using aaHistClientTagPicker in an Application

503

The index passed to the SelectedTag() method ranges from 0 to Count - 1. For example:

If the Count was 0, there are no tags selected. If Count is 1, there is one tag selected, and its index is 0. If Count is 5, there are 5 tags, and the indices range from 0 to 4.

Therefore, you must first check to see that Count is not 0. Then you can index appropriately to get the tag.

aaHistClientTagPicker Events
The aaHistClientTagPicker events are:

OnFilterChanged OnGroupChanged OnTagsPicked OnTagsSelected OnServerChanged OnSelectedTabChanged

OnFilterChanged
The OnFilterChanged event is triggered when the filter is changed.
Syntax
aaHistClientTagPicker.OnFilterChanged();

OnGroupChanged
The OnGroupChanged event is triggered when the tag group is changed in the navigation tree in the Servers pane.
Syntax
aaHistClientTagPicker.OnGroupChanged();

OnTagsPicked
The OnTagsPicked event is triggered when the user double-clicks and/or picks one or more tags.
Syntax
aaHistClientTagPicker.OnTagsPicked();

ActiveFactory Software Users Guide

504

Chapter 10 aaHistClientTagPicker Control

Remarks

A selected tag is a tag that is highlighted (clicked one time) with the mouse by a runtime user. A picked tag is a tag that is double-clicked or selected with the mouse to be dragged. A "picked" tag is always selected, but a selected tag is not always picked. The application controls whether to also "pick" a tag when it is selected. For example, in the Query client application, selecting a tag causes a change in the query. This is an instance of when the selection of a tag also results in its being picked. In the Trend client application, selecting a tag does not pick it and place it on to the trend. However, double-clicking on a tag (picking it) does.

OnTagsSelected
The OnTagsSelected event is triggered when the user selects one or more tags.
Syntax
aaHistClientTagPicker.OnTagsSelected();

Remarks

For the differences between a "picked" tag and a "selected" tag, see the OnTagsPicked event.

OnServerChanged
The OnServerChanged event is triggered when the server is changed.
Syntax
aaHistClientTagPicker.OnServerChanged();

OnSelectedTabChanged
The OnSelectedTabChanged event is triggered when the user changes tabs in the Tags pane.
Syntax
aaHistClientTagPicker.OnSelectedTabChanged();

ActiveFactory Software Users Guide

Using aaHistClientTagPicker in an Application

505

aaHistClientTagPickerSplitterOrientation Enumeration
Specifies the orientation of the Servers pane with respect to the Tags pane in the Tag Picker.
Value Enumeration Description

0 1

Horizontal Vertical

The Servers pane is above the Tags pane in the Tag Picker. The Servers pane is to the left of the Tags pane in the Tag Picker.

ActiveFactory Software Users Guide

506

Chapter 10 aaHistClientTagPicker Control

ActiveFactory Software Users Guide

507

Chapter 11
aaHistClientTimeRangePicker Control

The aaHistClientTimeRangePicker control allows you to select a time duration based on a start time, duration and/or end time.

Using aaHistClientTimeRangePicker at Runtime

The aaHistClientTimeRangePicker control functions the same as the Time Picker in the time toolbar that appears in the Trend and Query applications. For more information on using the Time Picker, see Time Picker on page 58.

Using aaHistClientTimeRangePicker in an Application

Use the aaHistClientTimeRangePicker control's properties, methods, and events to customize how the time selector behaves during runtime. For example, you can enable the selection of a list of time durations during runtime. All properties, methods, and events can be controlled through scripting. In addition, some of these properties and methods are exposed through the aaHistClientTimeRangePicker property panel available during application development.

ActiveFactory Software Users Guide

508

Chapter 11 aaHistClientTimeRangePicker Control

Adding aaHistClientTimeRangePicker to an InTouch Window

To add the aaHistClientTimeRangePicker control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientTimeRangePicker control.

Click OK. The control appears in the window.

aaHistClientTimeRangePicker Properties
The properties for the aaHistClientTimeRangePicker are:

DurationMS EndDate Format StartDate TimeDuration

ActiveFactory Software Users Guide

Using aaHistClientTimeRangePicker in an Application

509

DurationMS
This read-write property controls the duration of the time range in milliseconds.
Syntax
aaHistClientTimeRangePicker.DurationMS = integer; Result = aaHistClientTimeRangePicker.DurationMS;

Remarks

When you change this property, the start time is updated based on the new duration and the current end time.

EndDate
This read-only property returns the end date and time of the time range.
Syntax
Result = aaHistClientTimeRangePicker.EndDate;

Return Value

A message value in a valid date/time format is returned.

Format
The Format property is a read-write property that gets or sets the date and time formats for the control.
Syntax
aaHistClientTimeRangePicker.Format = message; Result = aaHistClientTimeRangePicker.Format;

Remarks

To display string literals that contain date and time separators or format strings, you must use escape characters in the substring. For example, to display the date and time as 06/01/2001 12:00 PM, this property must be set to: "dd'/'MM'/'yyyy hh':'mm tt" The following table lists all the valid format strings and their descriptions.
Format String Description

d dd ddd dddd

The one or two-digit day. The two-digit day. Single digit day values are preceded by a zero. The three-character day-of-week abbreviation. The full day-of-week name.

ActiveFactory Software Users Guide

510

Chapter 11 aaHistClientTimeRangePicker Control

Format String

Description

h hh H HH m mm M MM MMM MMMM s ss t tt y yy yyyy

Remarks

The one or two-digit hour in 12-hour format. The two-digit hour in 12-hour format. Single digit values are preceded by a zero. The one or two-digit hour in 24-hour format. The two-digit hour in 24-hour format. Single digit values are preceded by a zero. The one or two-digit minute. The two-digit minute. Single digit values are preceded by a zero. The one or two-digit month number. The two-digit month number. Single digit values are preceded by a zero. The three-character month abbreviation. The full month name. The one or two-digit seconds. The two-digit seconds. Single digit values are preceded by a zero. The one-letter AM/PM abbreviation ("AM" appears as "A"). The two-letter AM/PM abbreviation ("AM" appears as "AM"). The one-digit year (2001 appears as "1"). The last two digits of the year (2001 appears as "01"). The full year (2001 appears as "2001").

The default is M/d/yyyy h:mm:ss tt for English systems.

StartDate
This read-only property returns the start date and time of the time range.
Syntax
Result = aaHistClientTimeRangePicker.StartDate;

ActiveFactory Software Users Guide

Using aaHistClientTimeRangePicker in an Application

511

Return Value

A message value in a valid date/time format is returned.

TimeDuration
This read-write property controls the duration of the time range as one of several predefined durations.
Syntax
aaHistClientTimeRangePicker.Duration = aaTimeRangeEnumeration; Result = aaHistClientTimeRangePicker.Duration;

Remarks

When you change this property, the start time is updated based on the new duration and the current end time. For more information on valid values, see aaTimeRangeEnumeration Enumeration on page 636. The default is 18 (FiveMinutes).

aaHistClientTimeRangePicker Methods
The methods for the aaHistClientTimeRangePicker are:

GetStartAndEndTimes RefreshTimes SetStartAndEndTimes

GetStartAndEndTimes
The GetStartAndEndTimes method retrieves the start and end times for the query.
Syntax
[aaTimeRangeEnumeration=] aaHistClientTimeRangePicker.GetStartAndEndTimes(Date Time startTime, DateTime endTime);

Parameters

startTime The start time for the query. endTime The end time for the query.
Remarks

The date and time formats are set using the Format property. The container may not allow method parameters to return values. This method is not accessible in the InTouch HMI software. Use the StartDate, EndDate, and TimeDuration properties instead.

ActiveFactory Software Users Guide

512

Chapter 11 aaHistClientTimeRangePicker Control

Return Value

The time range enumeration (such as Custom, Last5Minutes, and so on) is returned. For more information, see aaTimeRangeEnumeration Enumeration on page 636.

RefreshTimes
The RefreshTimes method updates the end time to the current time and recalculates the start time based on the new end time and the duration.
Syntax
[Result=] aaHistClientTimeRangePicker.RefreshTimes(discrete bFireEvent);

Parameters

bFireEvent When set to True, a change in dates causes the OnChange event to be triggered.

SetStartAndEndTimes
The SetStartAndEndTimes method sets the time period based on a start time, end time and/or duration.
Syntax
[Result=] aaHistClientTimeRangePicker.SetStartAndEndTimes(DateT ime startTime, DateTime endTime, integer duration);

Parameters

startTime The start time for the query. Only considered if the duration is set to Custom. For other durations, the start time is calculated automatically based on the end time and duration. endTime The end time for the query. Only considered if the duration is set to Custom or an option from 17 to 32 (OneMinute to ThreeMonths). Otherwise, the end time is set based on the duration. duration The time range duration. If the duration is set to Custom, the specified start and end times are used. For other duration options, the time indicated by the duration is used, and the start and/or end times are updated as necessary. For more information on valid values for the duration, see aaTimeRangeEnumeration Enumeration on page 636.
Remarks

The date and time formats are set using the Format property.

ActiveFactory Software Users Guide

Using aaHistClientTimeRangePicker in an Application

513

aaHistClientTimeRangePicker Events
The events for the aaHistClientTimeRangePicker are:

OnChange

OnChange
The OnChange event is triggered when the start date and/or end dates are changed.
Syntax
aaHistClientTimeRangePicker.OnChange();

ActiveFactory Software Users Guide

514

Chapter 11 aaHistClientTimeRangePicker Control

ActiveFactory Software Users Guide

515

Chapter 12
aaHistClientActiveDataGrid Control

The aaHistClientActiveDataGrid control can execute any SQL query that returns a result set from any IndustrialSQL Server historian or Microsoft SQL Server database and return the results in a grid.
Note The aaHistClientActiveDataGrid does not support data definition or data manipulation queries.

The aaHistClientActiveDataGrid provides functionality through a user interface and with scripting using properties, methods, and events. Information is provided on how to configure the aaHistClientActiveDataGrid during application development and describes the aaHistClientActiveDataGrid properties, methods, and events. The runtime functionality of aaHistClientActiveDataGrid is also described.

ActiveFactory Software Users Guide

516

Chapter 12 aaHistClientActiveDataGrid Control

Using aaHistClientActiveDataGrid at Runtime

The aaHistClientActiveDataGrid provides a user interface that allows you to view record-set data as returned from a specified query during runtime.
Navigator bar Data grid

Data Grid
Data appears in a tabular format, where each row represents a record and each column represents an attribute (field). The data is read-only. The data grid displays results based on the SQL statement(s) executed and can be used to query different tables and attributes. For example, if the SQL query executes a join on three tables and includes two attributes from each table, the aaHistClientActiveDataGrid shows the records resulting from the join and only the six attributes specified. The number of columns varies dynamically, depending on how many records are returned. You can resize the columns in the data grid.

Navigating through Records

To navigate through records, do any of the following:

Use the arrow keys on your keyboard. Right-click the grid, point to Navigate and click one of the navigation commands. Use the navigator bar. The navigator bar buttons are as follows:
Button Description

Moves the current record selection to the first record in the grid.

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid at Runtime

517

Button

Description

Moves the current selection to the previous record. Moves the current selection to the next record. Moves the current selection to the last record.
Note Depending on how the aaHistClientActiveDataGrid was configured during development, the navigator bar may not be available during runtime.

Configuring the Database Connection

You can change the database connection for the aaHistClientActiveDataGrid at runtime.
To configure the database connection 1

Right-click in the aaHistClientActiveDataGrid. In the shortcut menu that appears, click Properties. The ActiveDataGrid Properties dialog box appears. If the InSQL Connection tab is not already selected, click the InSQL Connection tab.

ActiveFactory Software Users Guide

518

Chapter 12 aaHistClientActiveDataGrid Control

Configure the connection parameters. For more information, see Server Connection Configuration on page 39.

Note The aaHistClientActiveDataGrid control can only connect to a single server. Multiple servers are not supported. 4

To apply the changes, click Apply or OK. The grid is cleared, and the current SQL statement is re-executed according to the values specified.

Creating or Editing SQL Statements

During runtime, you can create or edit the SQL statement that is executed by the aaHistClientActiveDataGrid. This SQL statement is executed each time the aaHistClientActiveDataGrid is refreshed. If the SQL statement is invalid or if the refresh fails, the data grid is cleared, and an error message appears.
To create or edit a SQL statement 1 2 3

Right-click in the aaHistClientActiveDataGrid. In the shortcut menu that appears, click SQL. The ActiveDataGrid Properties dialog box appears. If the SQL tab is not already selected, click the SQL tab.

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid at Runtime

519

4 5

In the SQL statement window, create or edit the current SQL statement(s) that is executed. To use a pre-configured template, click Templates. If not, skip to Step 9. The Templates dialog box appears.

6 7 8

In the Description list, select the desired template. Click Select. The pre-configured SQL statement syntax appears in the SQL statement(s) window. You can then modify the syntax (for example, change the tagname, start date, and end date). To delete all of the text in the SQL statement window, click Clear.

10 To apply the changes, click Apply or OK.

Refreshing the Data Grid

When you refresh the data grid, the current contents are cleared and the grid is updated by executing the current SQL query.
To refresh the data grid Right-click in the aaHistClientActiveDataGrid. In the shortcut menu that appears, click Refresh.

ActiveFactory Software Users Guide

520

Chapter 12 aaHistClientActiveDataGrid Control

Using aaHistClientActiveDataGrid in an Application

Use aaHistClientActiveDataGrid's properties, methods, and events to create scripts that set up a database connection and customize how the data grid functions during runtime.

Adding aaHistClientActiveDataGrid to an InTouch Window

To add the aaHistClientActiveDataGrid control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientActiveDataGrid control. Click OK.

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

521

The control appears in the window.

aaHistClientActiveDataGrid Properties
The aaHistClientActiveDataGrid properties are:

AllowUserConfiguration AutoRefresh BOF BusinessObjectServer ColumnCount Connected DatabaseName DefaultColumnWidth Domain Enabled EnableShortcutMenu EOF Handle Password RefreshFrequency Row RowCount ServerName

ActiveFactory Software Users Guide

522

Chapter 12 aaHistClientActiveDataGrid Control

ShowErrorDlgs ShowNavigatorBar SQLString UserName VirtualDirectoryName

AllowUserConfiguration
The AllowUserConfiguration property is a read-write property that determines whether the user can access the aaHistClientActiveDataGrid Properties dialog box at runtime by using the controls shortcut menu.
Syntax
aaHistClientActiveDataGrid.AllowUserConfiguration = discrete; Result = aaHistClientActiveDataGrid.AllowUserConfiguration;

Remarks

True = Show the Properties and SQL menu commands on the shortcut menu; False = Hide the Properties and SQL menu commands on the shortcut menu. If this property is disabled, you can use the ShowPropertiesDialog method to let the user access the Properties dialog box. The default is True.

AutoRefresh
The AutoRefresh property is a read-write property that enables or disables automatic refresh of the data in the aaHistClientActiveDataGrid.
Syntax
aaHistClientActiveDataGrid.AutoRefresh = discrete; Result = aaHistClientActiveDataGrid.AutoRefresh;

Remarks

True = Automatic refresh on; False = Automatic refresh off. The default is False. Automatic refresh works by periodically calling the Execute method. The time interval is based on the RefreshFrequency property. The default time interval is 60 seconds.

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

523

The AutoRefresh property is set to False if the last manual call to the Execute method failed. If the AutoRefresh property is set to True, and for some reason later fails, it is automatically set to False, and the aaHistClientActiveDataGrid is reset (cleared).

BOF
The BOF property is a read-only property that returns whether the user has attempted to navigate prior to the first row in the data grid.
Syntax
Result = aaHistClientActiveDataGrid.BOF;

Return Value

The result is a discrete. True is returned if an attempt was made to move prior to the first row in the data grid through a call to the MovePrevious method; otherwise False is returned.

BusinessObjectServer
This read-write property specifies the path to the HTTP server when using HTTP to access the historian.
Syntax
aaHistClientActiveDataGrid.BusinessObjectServer = message; Result = aaHistClientActiveDataGrid.BusinessObjectServer;

Remarks

If this property is set to a non-empty string value, the control uses HTTP access to the historian. If it is set to an empty string, the control uses regular SQL Server access. You can obtain a secured connection by specifying https://<Servername>. For example:
#ActiveDataGrid.BusinessObjectServer ="HTTPS://www.server.com";

For more information on using HTTP to access the historian, see Using HTTP as the Server Connection Protocol on page 43. To enable HTTP access, you must also specify the virtual directory name using the VirtualDirectoryName property.

ActiveFactory Software Users Guide

524

Chapter 12 aaHistClientActiveDataGrid Control

ColumnCount
The ColumnCount property is a read-only property that gets the number of columns in the current result set of the data grid.
Syntax
Result = aaHistClientActiveDataGrid.ColumnCount;

Return Value

Returns the number of columns as an integer. If the data grid is not connected, 0 is returned.
Remarks

The default is 0.

Connected
Use this read-write property to initiate or terminate a connection to the IndustrialSQL Server historian and to check whether a connection is currently active.
Syntax
aaHistClientActiveDataGrid.Connected = discrete; Result = aaHistClientActiveDataGrid.Connected;

Remarks

If set to True, and the ServerName, DatabaseName, UserName, and Password properties are set, the control tries to connect to the IndustrialSQL Server historian and execute the SQL statement specified by the SQLString property. If an error occurs, the Connected property is set to False. If set to False while a connection is active, the control is disconnected from the server and reset. The default is False.

DatabaseName
The DatabaseName property is a read-write property that specifies the name of the database to connect to. The database must exist on the database server specified by the ServerName property.
Syntax
aaHistClientActiveDataGrid.DatabaseName = message; Result = aaHistClientActiveDataGrid.DatabaseName;

Remarks

When working with an IndustrialSQL Server historian database, the value for the DatabaseName property must be Runtime. However, aaHistClientActiveDataGrid can connect to any database in the Microsoft SQL Server, such as the master database. The default is Runtime.
ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

525

DefaultColumnWidth
The DefaultColumnWidth property is a read-write property that gets or sets the default column width, in pixels, of the columns shown in the data grid.
Syntax
aaHistClientActiveDataGrid.DefaultColumnWidth = integer; Result = aaHistClientActiveDataGrid.DefaultColumnWidth;

Remarks

The default is 100.

Domain
The Domain property is a read-write property that gets or sets the domain string for the connection to the server.
Syntax
aaHistClientActiveDataGrid.Domain = message; Result = aaHistClientActiveDataGrid.Domain;

Remarks

This property is used in cases where the Windows integrated security requires the domain name to be specified. The default is an empty message value ( "" ).

Enabled
The Enabled property is a read-write property that enables or disables the user interface functionality of the control.
Syntax
aaHistClientActiveDataGrid.Enabled = discrete; Result = aaHistClientActiveDataGrid.Enabled;

Remarks

True = User interface functionality enabled; False = User interface functionality disabled. The default is True.

EnableShortcutMenu
The EnableShortcutMenu property is a read-write property that enables or disables the right-click shortcut menu of the control.
Syntax
aaHistClientActiveDataGrid.EnableShortcutMenu = discrete; Result = aaHistClientActiveDataGrid.EnableShortcutMenu;

ActiveFactory Software Users Guide

526

Chapter 12 aaHistClientActiveDataGrid Control

Remarks

True = Shortcut menu enabled; False = Shortcut menu disabled. The default is True.

EOF
The EOF property is a read-only property that returns whether the aaHistClientActiveDataGrid user has attempted to navigate beyond the last row in the data grid.
Syntax
Result= aaHistClientActiveDataGrid.EOF;

Return Value

The result is a discrete. True is returned if an attempt was made to move past the last row in the data grid with a call to the MoveNext method; otherwise False is returned.

Handle
The Handle property is a read-only property that returns the Window handle for the control.
Syntax
Result = aaHistClientActiveDataGrid.Handle;

Return Value

528

Chapter 12 aaHistClientActiveDataGrid Control

ShowErrorDlgs
The ShowErrorDlgs property is a read-write property that determines whether error messages appear during runtime in an error dialog box.
Syntax
aaHistClientActiveDataGrid.ShowErrorDlgs = discrete; Result = aaHistClientActiveDataGrid.ShowErrorDlgs;

Remarks

True = Error messages displayed; False = Error messages suppressed. If the error message display is disabled, you do not see any errors, even if they are critical. Use this option with extreme caution. The default is True.

ShowNavigatorBar
The ShowNavigatorBar property is a read-write property that shows or hides the Navigator toolbar that is located above the data grid.
Syntax
aaHistClientActiveDataGrid.ShowNavigatorBar = discrete; Result = aaHistClientActiveDataGrid.ShowNavigatorBar;

Remarks

True = Shows the Navigator toolbar; False = Hides the Navigator toolbar. The default is True.

SQLString
The SQLString property is a read-write property that specifies the SQL statement to be executed by the Execute method.
Syntax
aaHistClientActiveDataGrid.SQLString = message; Result = aaHistClientActiveDataGrid.SQLString;

Remarks

The aaHistClientActiveDataGrid uses the InSQL OLE DB provider to access IndustrialSQL Server historian historical data. If you are querying data from the analog or discrete history tables, the SQL statement must follow the syntax rules for OLE DB provider queries. Otherwise, you can use any valid Transact-SQL that returns rows.
Remarks

The default is an empty message value ( "" ).

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

529

UserName
The UserName property is a read-write property that specifies the username used to logon to the IndustrialSQL Server historian specified in the ServerName property.
Syntax
aaHistClientActiveDataGrid.UserName = message; Result = aaHistClientActiveDataGrid.UserName;

Remarks

See the IndustrialSQL Server historian documentation for information on the default IndustrialSQL Server historian users.
Remarks

The default is wwUser.

VirtualDirectoryName
The VirtualDirectoryName property is a read-write property that gets or sets the virtual directory name.
Syntax
aaHistClientActiveDataGrid.VirtualDirectoryName = message; Result = aaHistClientActiveDataGrid.VirtualDirectoryName;

Remarks

The default is an empty message value ( "" ).

aaHistClientActiveDataGrid Methods
The aaHistClientActiveDataGrid methods are:

ClearGrid ColumnName ColumnValue ColumnValueByName Execute MoveFirst MoveLast MoveNext MovePrevious RowColumnValue RowColumnValueByName

ActiveFactory Software Users Guide

530

Chapter 12 aaHistClientActiveDataGrid Control

ShowPropertiesDialog SQLAppend

ClearGrid
The ClearGrid method clears the contents of the data grid and sets the Connected property to False.
Syntax
[Result=] aaHistClientActiveDataGrid.ClearGrid();

ColumnName
The ColumnName method returns the column name that corresponds to the specified column index.
Syntax
Result = aaHistClientActiveDataGrid.ColumnName(integer columnIndex);

Parameters

columnIndex Number of the column name for which the string representation is returned. Column names start at 1.
Return Value

The name of the column as a message value.

ColumnValue
The ColumnValue method returns the string representation of the data for the specified column of the currently selected row.
Syntax
Result = aaHistClientActiveDataGrid.ColumnValue(integer Column);

Parameters

Column Number of the column for which the string representation is returned. Column numbers start at 1.
Return Value

A message representation of the data.

ColumnValueByName
The ColumnValueByName method gets the string representation of the data for the specified column name, for the currently selected row.
Syntax
Result = aaHistClientActiveDataGrid.ColumnValueByName(message columnName);

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

531

Parameters

columnName The name of the column.

Return Value

The data in the column as a message value.

Execute
The Execute method executes the SQL query defined in the SQLString property.
Syntax
[Result=] aaHistClientActiveDataGrid.Execute();

Return Value

True = Execution is successful; False = Execution unsuccessful.

Remarks

If the Execute method fails, the data grid is cleared and an error is raised. The most typical conditions that causes Execute to fail are:
1 2 3 4

The specified server is not running or connection to it is not available. The server assigned to the ServerName property is invalid or not found. The username assigned to the UserName property is invalid or not found. The password assigned to the Password property is invalid or not associated with the specified UserName on the specified ServerName. There is a syntax error in the SQLString property. The DatabaseName property was not assigned or the wrong database was specified. The BusinessObjectServer property is set to an HTTP server that does not exist, or the HTTP server specified is not running

5 6 7

MoveFirst
The MoveFirst method selects the first row in the data grid.
Syntax
aaHistClientActiveDataGrid.MoveFirst();

ActiveFactory Software Users Guide

532

Chapter 12 aaHistClientActiveDataGrid Control

MoveLast
The MoveLast method selects the last row in the data grid.
Syntax
aaHistClientActiveDataGrid.MoveLast();

MoveNext
The MoveNext method selects the next row in the data grid.
Syntax
aaHistClientActiveDataGrid.MoveNext();

Remarks

If an attempt is made to move past the last row the EOF property is set to True.

MovePrevious
The MovePrevious method selects the previous row in the data grid.
Syntax
aaHistClientActiveDataGrid.MovePrevious();

Remarks

If an attempt is made to move past the last row the BOF property is set to True.

RowColumnValue
The RowColumnValue method returns the string representation of the data in the specified row and column in the data grid.
Syntax
[Result=] aaHistClientActiveDataGrid.RowColumnValue(integer row, integer column);

Parameters

row Number of the row for which the string representation is returned. Row numbers start at 1. column Number of the column for which the string representation is returned. Column numbers start at 1.
Return Value

A message representation of the data.

Remarks

This property does not move the selected row, nor does it require the selected row to be changed.

ActiveFactory Software Users Guide

535

aaHistClientActiveDataGrid Events
The aaHistClientActiveDataGrid control has the following events:

OnClick OnDblClick OnError

For information on ambient events, see Common Events on page 631.

OnClick
The OnClick event is triggered every time the user clicks on a data row in the control.
Syntax
aaHistClientActiveDataGrid.OnClick;

OnDblClick
The OnDblClick event is triggered every time the user double-clicks on a data row in the control.
Syntax
aaHistClientActiveDataGrid.OnDblClick;

OnError
The OnError event executes each time an error message is to be displayed.
Syntax
aaHistClientActiveDataGrid.OnError(integer ErrorNo, ref message ErrStr, ref discrete ShowErrorDlg);

Parameters

ErrorNo A unique number that corresponds to the error message, which is specified by the ErrStr parameter. ErrStr Message to be displayed in the error dialog box. ShowErrorDlg Determines whether the error dialog box appears. True = Error dialog box displayed; False = Err dialog box not displayed. The ShowErrorDlg parameter defaults to the value of the ShowErrorDlg property.
Remarks

The OnError event provides a means to intercept an error message and either disable it from showing or change the error message text shown.

ActiveFactory Software Users Guide

536

Chapter 12 aaHistClientActiveDataGrid Control

For information on error numbers and error text pertaining to each control, see the "Error Messages" section in the chapter for that control. The OnError event executes just prior to the display of any error messages. In your script, you can then capture the error, check the ErrStr parameter, and set the parameter to a new value. You can also translate the same string into a different language. If you want to implement your own error handling, you can suppress the default error dialog by setting the ShowErrorDlg parameter to False.
Example

The following example shows how the event parameter can be set in the InTouch HMI software:
TRErrorNo = #ThisEvent.OnErrorerrorNo; {Assign error number from the event to a tag called TRErrorNo} IF TRShowErrorDlg == 0 THEN {Checking user preference on showing Error Dialog}

#ThisEvent.OnErrorshowErrorDlg = TRShowErrorDlg; {Dont show any error dialog. A value has been assigned value to the ShowErrorDlg parameter}
ELSE

#ThisEvent.OnErrorshowErrorDlg = TRShowErrorDlg; {Show the Error dialog} IF UserPreferredDialog == 1 THEN {Check whether user wants his/her own dialog}
IF TRErrorNo == 0 THEN {If the error number from the event is 0} #ThisEvent.OnErrorerrorString = "General Error"; {Assigning a value to ErrStr parameter of the event.} ELSE IF TRErrorNo == 1 THEN #ThisEvent.OnErrorerrorString = "Not able to connect to the specified server."; ELSE IF TRErrorNo == 2 THEN #ThisEvent.OnErrorerrorString = "Set the server name first."; ENDIF; ENDIF; ENDIF;

ENDIF;
ENDIF;

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

537

Script Examples for aaHistClientActiveDataGrid

The following sections provide scripting examples for aaHistClientActiveDataGrid.

InTouch Example: History Data Over a LAN

The following example demonstrates how to connect to the IndustrialSQL Server historian named "maggie" on a LAN. The example retrieves the last 45 minutes of history data for the 'SysPulse' tag.
#aaHistClientActiveDataGrid.ServerName ="maggie"; #aaHistClientActiveDataGrid.UserName = "wwUser"; #aaHistClientActiveDataGrid.Password = "wwuser"; #aaHistClientActiveDataGrid.DatabaseName = "Runtime"; #aaHistClientActiveDataGrid.SQLString = ""; #aaHistClientActiveDataGrid.SQLAppend("DECLARE @StartDate Datetime"); #aaHistClientActiveDataGrid.SQLAppend("DECLARE @EndDate DateTime"); #aaHistClientActiveDataGrid.SQLAppend( "SELECT @StartDate = DateAdd(mi, -45, GetDate())"); #aaHistClientActiveDataGrid.SQLAppend("SELECT @EndDate = GetDate()"); #aaHistClientActiveDataGrid.SQLAppend("SELECT Tagname, DateTime, Value"); #aaHistClientActiveDataGrid.SQLAppend("FROM v_DiscreteHistory"); #aaHistClientActiveDataGrid.SQLAppend("WHERE TagName IN (SysPulse)"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime >= @StartDate"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime <= @EndDate"); #aaHistClientActiveDataGrid.SQLAppend("AND wwRetrievalMode = Delta"); #aaHistClientActiveDataGrid.Connected = 1;

InTouch Example: Retrieving Data from the Grid

The following example script demonstrates how to extract data from the grid using the ColumnValue method.
#aaHistClientActiveDataGrid.ServerName = "maggie"; #aaHistClientActiveDataGrid.UserName = "wwUser"; #aaHistClientActiveDataGrid.Password = "wwuser"; #aaHistClientActiveDataGrid.DatabaseName = "Runtime"; #aaHistClientActiveDataGrid.SQLString = "";

ActiveFactory Software Users Guide

538

Chapter 12 aaHistClientActiveDataGrid Control

#aaHistClientActiveDataGrid.SQLAppend("DECLARE @StartDate Datetime"); #aaHistClientActiveDataGrid.SQLAppend("DECLARE @EndDate Datetime"); #aaHistClientActiveDataGrid.SQLAppend("SELECT @StartDate = DateAdd(mi, -30, GetDate())"); #aaHistClientActiveDataGrid.SQLAppend("SELECT @EndDate = GetDate()"); #aaHistClientActiveDataGrid.SQLAppend("SELECT TagName, DateTime, Value"); #aaHistClientActiveDataGrid.SQLAppend("FROM v_AnalogHistory"); #aaHistClientActiveDataGrid.SQLAppend("WHERE TagName IN ('SysTimeSec')"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime >= @StartDate"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime <= @EndDate"); #aaHistClientActiveDataGrid.SQLAppend("AND wwRetrievalMode = 'Cyclic'"); #aaHistClientActiveDataGrid.SQLAppend("AND wwCycleCount = 100"); #aaHistClientActiveDataGrid.Connected = 1; #aaHistClientActiveDataGrid.MoveFirst(); FOR Row = 1 TO #aaHistClientActiveDataGrid.RowCount

TagName = #aaHistClientActiveDataGrid.ColumnValue(0); DateTime = #aaHistClientActiveDataGrid.ColumnValue(1); TagValueText = #aaHistClientActiveDataGrid.ColumnValue(2); TagValue = StringToReal( TagValueText ); EndOfFile = #aaHistClientActiveDataGrid.EOF; IF EndOfFile THEN
EXIT FOR;

ELSE
#aaHistClientActiveDataGrid.MoveNext();

ENDIF;
NEXT;

Another slightly different approach is to go through the returned data without actually moving the row selector using the RowColumnValue method. This approach is much more efficient because there is no UI updating.
#aaHistClientActiveDataGrid.ServerName = "maggie"; #aaHistClientActiveDataGrid.UserName = "wwUser"; #aaHistClientActiveDataGrid.Password = "wwuser"; #aaHistClientActiveDataGrid.DatabaseName = "Runtime";

ActiveFactory Software Users Guide

Using aaHistClientActiveDataGrid in an Application

539

#aaHistClientActiveDataGrid.SQLString = ""; #aaHistClientActiveDataGrid.SQLAppend("DECLARE @StartDate Datetime"); #aaHistClientActiveDataGrid.SQLAppend("DECLARE @EndDate Datetime"); #aaHistClientActiveDataGrid.SQLAppend("SELECT @StartDate = DateAdd(mi, -30, GetDate())"); #aaHistClientActiveDataGrid.SQLAppend("SELECT @EndDate = GetDate()"); #aaHistClientActiveDataGrid.SQLAppend("SELECT TagName, DateTime, Value"); #aaHistClientActiveDataGrid.SQLAppend("FROM v_AnalogHistory"); #aaHistClientActiveDataGrid.SQLAppend("WHERE TagName IN ('SysTimeSec')"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime >= @StartDate"); #aaHistClientActiveDataGrid.SQLAppend("AND DateTime <= @EndDate"); #aaHistClientActiveDataGrid.SQLAppend("AND wwRetrievalMode = 'Cyclic'"); #aaHistClientActiveDataGrid.SQLAppend("AND wwCycleCount = 100"); #aaHistClientActiveDataGrid.Connected = 1; FOR Row = 1 TO #aaHistClientActiveDataGrid.RowCount - 1

TagName = #aaHistClientActiveDataGrid.RowColumnValue(Row , 0); DateTime = #aaHistClientActiveDataGrid.RowColumnValue(Row , 1); TagValueText = #aaHistClientActiveDataGrid.RowColumnValue(Row , 2); TagValue = StringToReal ( TagValueText );
NEXT;

ActiveFactory Software Users Guide

540

Chapter 12 aaHistClientActiveDataGrid Control

aaHistClientActiveDataGrid Error Messages

The aaHistClientActiveDataGrid error messages are:
Error Number

Error Message

0 1 2 3 4 5 6 7

General error. A general error is usually due to a data connectivity error. Failed to connect to server: <ServerName> The ServerName property must be set to a valid InSQL server. The UserName property cannot be blank. Unable to get the Generic SQL view for server name: <ServerName> You must first execute the SQL query before performing this operation. You must enter the SQL you wish to execute before a connection attempt is performed. The 'ActiveDataGrid' ActiveX is not licensed for your use on this workstation. Please contact your Administrator. Row (<Row Index>) does not exist in the current query results.' Column (<Column index>) does not exist in the current query. The column name, <Column Name>, was not found. The RefreshFrequency property must be assigned a positive number.

8 9 10 11

ActiveFactory Software Users Guide

541

Chapter 13
aaHistClientSingleValueEntry Control

Use the aaHistClientSingleValueEntry control to manually add a tag value to the IndustrialSQL Server historian database.

Using the aaHistClientSingleValueEntry Control at Runtime

Use the aaHistClientSingleValueEntry control to manually add a single data value for a tag in the IndustrialSQL Server historian database. To add a data value for a tag:

You must log in to the historian with administrative privileges. The tag must currently exist in the database.

Values are inserted into the IndustrialSQL Server historians history blocks. Therefore, you can retrieve them using the same views and tables as data that is stored automatically by the IndustrialSQL Server historian.

Adding a Tag Value

The available functionality depends on how the application developer configured the aaHistClientSingleValueEntry control.

ActiveFactory Software Users Guide

542

Chapter 13 aaHistClientSingleValueEntry Control

To add a tag value 1

Log on to the historian using the means provided by the application. If the log on is successful, a green indicator appears in the server status icon in the status bar for the control. The name of the logged on user also appears in the status bar.

In the Tagname list, type the name of the tag for which you want to insert a value. To browse for a tag, click the ellipsis button. The Tag Picker appears, in which you can browse for a tag. For more information on using the Tag Picker, see Tag Picker on page 51. In the Date and time box, enter the timestamp used for the inserted value. To use the current time, select the check box to the right of the Date and time box. In the Value box, enter the data value to insert for the tag.

5 Click the arrow button. The status of the insertion appears in the status bar.

Using the aaHistClientSingleValueEntry Control in an Application

You can use the aaHistClientSingleValueEntry control's properties, methods, and events in runtime scripts in your application to control the functionality available to the runtime user.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

543

Adding the aaHistClientSingleValueEntry Control to an InTouch Window

To add the aaHistClientSingleValueEntry control 1

In WindowMaker, click the Wizards button. The Wizard Selection dialog box appears.

2 3

Select the aaHistClientSingleValueEntry control. Click OK. The control appears in the window.

ActiveFactory Software Users Guide

544

Chapter 13 aaHistClientSingleValueEntry Control

aaHistClientSingleValueEntry Control Properties

The aaHistClientSingleValueEntry control properties include:

AnalogValue ContextMenuEnabled CurrentServerName DateTime DateTimeFieldDisable DateTimeFieldVisible DateTimeString DisableTagEntry DisplayErrorMessages FieldLabelPosition FieldLayoutHorizontal HideDateTimeModeTabs HideFieldLabels HideStatusBar InsertButtonDisable InsertButtonVisible InTouchDateTime LastErrorDetails LastErrorMessage LastOperationResult LastOperationSuccessful Pwd Quality QualityDetail QualityDetailFieldDisable QualityDetailFieldVisible QualityFieldDisable QualityFieldVisible

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

545

RememberEnteredTags Servers StringValue TagName TagNameFieldDisable TagNameFieldVisible TagPickerButtonDisable TagPickerButtonVisible Tags TagType TagValid Transparent User UseTimezone Value ValueEx ValueFieldDisable

AnalogValue
The AnalogValue property is a read-write property that gets or sets the analog value to be inserted.
Syntax
aaHistClientSingleValueEntry.AnalogValue = real; Result = aaHistClientSingleValueEntry.AnalogValue;

Remarks

The default is 0.

CurrentServerName
The CurrentServerName property is a read-write property that gets or sets the name of the IndustrialSQL Server historian.
Syntax
aaHistClientSingleValueEntry.CurrentServerName = message; Result = aaHistClientSingleValueEntry.CurrentServerName;

ActiveFactory Software Users Guide

546

Chapter 13 aaHistClientSingleValueEntry Control

Remarks

If the server has already been added, the User property is automatically set to the current username. This property has no default.

DateTime
The DateTime property is a read-write property that gets or sets the timestamp to be used for the value insert.
Syntax
aaHistClientSingleValueEntry.DateTime = DateTime; Result = aaHistClientSingleValueEntry.DateTime;

Remarks

To use the current time, set this property to 0. Setting this property also updates the DateTimeString and InTouchDateTime properties, and vice-versa. For more information on the DateTime data type, see DateTime on page 638.
Remarks

The default is 12:00:00 AM.

DateTimeFieldDisable
The DateTimeFieldDisable property is a read-write property that gets or sets whether the Date and time box is available in the control at runtime.
Syntax
aaHistClientSingleValueEntry.DateTimeFieldDisable = discrete; Result = aaHistClientSingleValueEntry.DateTimeFieldDisable;

Remarks

The default is False.

DateTimeFieldVisible
The DateTimeFieldVisible property is a read-write property that gets or sets whether the Date and time box is visible in the control at runtime.
Syntax
aaHistClientSingleValueEntry.DateTimeFieldVisible = discrete; Result = aaHistClientSingleValueEntry.DateTimeFieldVisible;

Remarks

The default is True.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

547

550

Chapter 13 aaHistClientSingleValueEntry Control

InsertButtonDisable
The InsertButtonDisable property is a read-write property that gets or sets whether the Insert button is available in the control at runtime.
Syntax
aaHistClientSingleValueEntry.InsertButtonDisable = discrete; Result = aaHistClientSingleValueEntry.InsertButtonDisable;

Remarks

If set to True, the button is not available. The default is False.

InsertButtonVisible
The InsertButtonVisible property is a read-write property that gets or sets whether the Insert button is visible in the control at runtime.
Syntax
aaHistClientSingleValueEntry.InsertButtonVisible = discrete; Result = aaHistClientSingleValueEntry.InsertButtonVisible;

Remarks

The default is True.

InTouchDateTime
The InTouchDateTime property is a read-write property that gets or sets the timestamp for the data insert using the InTouch HMI software Date format.
Syntax
aaHistClientSingleValueEntry.InTouchDateTime = real; Result = aaHistClientSingleValueEntry.InTouchDateTime;

Remarks

The InTouchDateTime property reflects the value of the DateTime property, but it is expressed in the InTouch HMI software $DateTime format. The DateTime property is expressed in the Date format. For more information on the $DateTime format, see the InTouch HMI software documentation. If this property is set -1, the current date and time are used for the insert. If the DateTime property is set to 0, the current date and time are returned for the InTouchDateTime property.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

551

Setting this property also updates the DateTime and DateTimeString properties, and vice-versa. The DateTime property supports dates starting from 12/30/1899. The InTouch HMI software supports dates starting from 1/1/1970. Therefore, if the DateTime property is set to a date prior to 1/1/1970, the InTouchDateTime property are set to -1. To support dates prior to 1/1/1970, use the DateTimeString property. The default is -1.
Example

The following example sets the timestamp for the insert to the current time (reflected by the $DateTime system tag in the InTouch HMI software).
aaHistClientSingleValueEntry1.InTouchDateTime = $DateTime;

LastErrorDetails
The LastErrorDetails property is a read-only property that gets the error code for the error message from SQL Server.
Syntax
Result = aaHistClientSingleValueEntry.LastErrorDetails;

Remarks

If a SQL error occurred during the last insert, the error is returned to this property. This property contains the long version of the error. No details are available if the LastOperationResult property contains a value between 0 and -6. To clear the contents of this property, use the Reset method. This property has no default.

LastErrorMessage
The LastErrorMessage property is a read-only property that gets the status of the last data insert.
Syntax
Result = aaHistClientSingleValueEntry.LastErrorMessage;

Remarks

The status returned is the short version. Use the LastErrorDetails property to return the details. To clear the contents of this property, use the Reset method. This property has no default.

ActiveFactory Software Users Guide

552

Chapter 13 aaHistClientSingleValueEntry Control

LastOperationResult
The LastOperationResult property is a read-only property that gets the error code for the last insert.
Syntax
Result = aaHistClientSingleValueEntry.LastOperationResult;

Return Values

Returns one of the following values: 0 = The value was successfully inserted. -1 = The insert failed. -2 = The specified server is not in the collection of servers. Be sure that you call the AddServer method first. -3 = No server name provided. The CurrentServerName property is blank or the serverName parameter was not provided for the InsertValue method. -4 = No tagname provided. -5 = The date/time is invalid (the date/time string was unable to be converted). -6 = The tag does not exist on the server. <other negative values> = Error code from Microsoft SQL Server. For more information, check the LastErrorDetails property. The default is 0.
Remarks

Before calling this method, call the AddServer method to ensure that the server name is in the server collection for this object.

LastOperationSuccessful
The LastOperationSuccessful property is a read-only property that gets the status of the last data value insert.
Syntax
Result = aaHistClientSingleValueEntry.LastOperationSuccessful;

Remarks

If set to True, the last insert was successful. To reset this property, use the Reset method. The default is False.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

553

Pwd
Use this write-only property to specify the password that should be used to log on the current user to the current server.
Syntax
aaHistClientSingleValueEntry.Pwd = message;

Remarks

This property has no default.

Quality
The Quality property is a read-write property that gets or sets the data quality to be used for the inserted value.
Syntax
aaHistClientSingleValueEntry.Quality = integer; Result = aaHistClientSingleValueEntry.Quality;

Remarks

This property is only considered if you set it to a value of 1 (Bad). In this case, a NULL value is stored on the historian with a QualityDetail value of 24. In all other cases, the quality of the inserted value is determined by the QualityDetail property. Valid values are: -1 = None. 0 = Good 1 = Bad 16 = Doubtful The default is -1.

Using the aaHistClientSingleValueEntry Control in an Application

555

Syntax
aaHistClientSingleValueEntry.QualityFieldVisible = discrete; Result = aaHistClientSingleValueEntry.QualityFieldVisible;

Remarks

The default is False. Any value the user specifies in the Quality box is ignored. The quality of the inserted value is determined by the value specified in the Quality Detail box.

RememberEnteredTags
The RememberEnteredTags property is a read-write property that gets or sets whether the control keeps track of previously entered tags and makes them available in the Tag Name box at runtime.
Syntax
aaHistClientSingleValueEntry.RememberEnteredTags = discrete; Result = aaHistClientSingleValueEntry.RememberEnteredTags;

Remarks

The default is True.

Servers
The Servers property is a read-write property that sets or gets the list of servers used by the control.
Syntax
aaHistClientSingleValueEntry.Servers = aaServers; Result = aaHistClientSingleValueEntry.Servers;

Remarks

This property references the aaServers object. For more information, see aaServer Object on page 567. This property has no default.

StringValue
The StringValue property is a read-write property that sets or gets the value to be inserted for a tag.
Syntax
aaHistClientSingleValueEntry.StringValue = message; Result = aaHistClientSingleValueEntry.StringValue;

ActiveFactory Software Users Guide

556

Chapter 13 aaHistClientSingleValueEntry Control

Remarks

This property is provided for use within the InTouch HMI software, as the InTouch HMI software does not handle variant data types. The Value property is a variant datatype. Setting this property automatically updates the Value and AnalogValue properties. This property has no default.

TagName
The TagName property is a read-write property that gets or sets the name of the current tag assigned to the control.
Syntax
aaHistClientSingleValueEntry.TagName = message; Result = aaHistClientSingleValueEntry.TagName;

Remarks

Use this property to change an existing tag or to add a new tag. This property has no default.

TagNameFieldDisable
The TagNameFieldDisable property is a read-write property that gets or sets whether the Tag Name box is available in the control at runtime.
Syntax
aaHistClientSingleValueEntry.TagNameFieldDisable = discrete; Result = aaHistClientSingleValueEntry.TagNameFieldDisable;

Remarks

The default is False.

TagNameFieldVisible
The TagNameFieldVisible property is a read-write property that gets or sets whether the Tag Name box is visible in the control at runtime.
Syntax
aaHistClientSingleValueEntry.TagNameFieldVisible = discrete; Result = aaHistClientSingleValueEntry.TagNameFieldVisible;

558

Chapter 13 aaHistClientSingleValueEntry Control

Remarks

Valid values are: -1 The tag type cant be determined. This can occur if the tag is invalid or if there was a failure to connect to the server. Analog Discrete String Complex (not supported) Event

1 2 3 4 5

The default is -1.

TagValid
The TagValid property is a read-only property that gets whether the current tag is valid.
Syntax
Result = aaHistClientSingleValueEntry.TagValid;

Remarks

This value is set to False if the tag is invalid. The tag is invalid if there was a failure to connect to the server. The default is False.

User
The User property is a read-write property that gets or sets the current user for an IndustrialSQL Server historian.
Syntax
aaHistClientSingleValueEntry.User = message; Result = aaHistClientSingleValueEntry.User;

Remarks Important To insert data for a tag, a user must have wwAdministrator privileges for the IndustrialSQL Server historian.

If the value of the CurrentServerName property is changed, this property reflects the current user for the server. The default is wwUser.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

559

UseTimezone
The UseTimezone property is a read-write property that gets or sets the time zone to use.
Note Not implemented in this release. Syntax
aaHistClientSingleValueEntry.UseTimezone = aaUseTimeZoneEnumeration; Result = aaHistClientSingleValueEntry.UseTimezone;

Remarks

For more information on the aaUseTimeZoneEnumeration enumeration, see aaUseTimeZoneEnumeration Enumeration on page 566. The default is 0.

Value
This read-write property gets or sets the data value to be inserted for a tag.
Syntax
aaHistClientSingleValueEntry.Value = object; Result = aaHistClientSingleValueEntry.Value;

Remarks

This property has no default. It is not available in the .NET version of the control.

ActiveFactory Software Users Guide

560

Chapter 13 aaHistClientSingleValueEntry Control

ValueFieldDisable
The ValueFieldDisable property is a read-write property that gets or sets whether the Value box is available in the control at runtime.
Syntax
aaHistClientSingleValueEntry.ValueFieldDisable = discrete; Result = aaHistClientSingleValueEntry.ValueFieldDisable;

Remarks

The default is False.

aaHistClientSingleValueEntry Control Methods

The aaHistClientSingleValueEntry control properties include:

AddServer AddTag Connect CreateManualTag Disconnect Insert InsertValue Refresh Reset

AddServer
The AddServer method establishes a connection to a server.
Syntax
[Result=] aaHistClientSingleValueEntry.AddServer(message serverName, message loginName, message password, [discrete bPersistPassword]);

Parameters

serverName The name of the server to which to connect. loginName A valid user name for the server. password A valid password for the server.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

561

bPersistPassword If set to True, the password is remembered for the next time a connection is attempted. The password is only remembered for a single application; the persisted password is not available to all applications.
Return Value

Returns True if the server can be established; otherwise returns False.

Return Value

Returns True if the disconnect was successful; otherwise returns False.

Insert
The Insert method inserts a value for a manual tag.
Syntax
[Result=] aaHistClientSingleValueEntry.Insert();

Return Value

Returns True if the value was inserted; otherwise returns False.

Remarks

This method has the same effect as a runtime user clicking the Insert button on the control interface.

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

563

If this method returns False, use the LastOperationResult, LastErrorMessage, and LastErrorDetails properties to determine the cause of the failure.

InsertValue
The InsertValue method inserts a value for a manual tag.
Note Currently not implemented. Syntax
[Result=] aaHistClientSingleValueEntry.InsertValue(message tagName, object tagValue, [object dTime], [integer quality], [integer qualityDetail]);

Parameters

tagName The tag for which the value is inserted. tagValue The value to insert. dTime The timestamp for the data value. If this parameter is not specified, the current date and time is used. You can use a message value for this parameter, provided that it is in an acceptable date/time format. quality The quality value to use. qualityDetail The quality detail to use.
Return Value

For a description of return values, see the LastOperationResult property.

Remarks

This method attempts to insert the specified value for the specified tag on the current server, regardless of the user interface settings. Likewise, the current settings for the user interface have no effect on the calling of this method. If this method returns False, use the LastErrorMessage and LastErrorDetails properties to determine the cause of the failure.

Refresh
The Refresh method forces a repaint of the control.
Syntax
[Result=] aaHistClientSingleValueEntry.Refresh();

ActiveFactory Software Users Guide

564

Chapter 13 aaHistClientSingleValueEntry Control

Reset
The Reset method clears the error information and values for the control.
Syntax
[Result=] aaHistClientSingleValueEntry.Reset();

Remarks

Calling this method clears all of the text boxes in the user interface for the control. Also, any errors or success indicators from a previous operation are cleared.

aaHistClientSingleValueEntry Control Events

The aaHistClientSingleValueEntry control properties include:

Change InsertComplete InsertFail TagNameChanged ValueChanged

Change
The Change event is triggered when the significant properties for the control are changed.
Syntax
aaHistClientSingleValueEntry.Change();

Remarks

This event is triggered if any of the following properties change:

Tags Servers CurrentServerName User Pwd TagName DateTime (DateTimeString and InTouchDateTime) Value (AnalogValue and StringValue) Quality QualityDetail

ActiveFactory Software Users Guide

Using the aaHistClientSingleValueEntry Control in an Application

0 1

fldlblTop fldlblLeft

The label appears above the boxes. The label appears to the left of the boxes.

aaUseTimeZoneEnumeration Enumeration
Specifies the time zone.
Note Not implemented in this release. Value Enumeration Description

0 1

tzConvertLocalToServe r tzDoNotConvert

Convert to the server time zone. Do not convert to the server time zone.

ActiveFactory Software Users Guide

567

Chapter 14
Server Objects

Use the server-related objects to manage individual servers and the servers in the server list.

aaServer Object
The aaServer object encapsulates a SQL connection to a server. It provides properties for configuring the connection and methods for logging on and logging off the connection. It also includes read-only properties for obtaining information about the server and methods for working with the connection. This object is referenced with parameters from other ActiveFactory objects and controls.

aaServer Properties
The aaServer properties are:

BaseURLAddress Build Domain LoggedOn LoginID LoginTimeout MachineName Name Password

ActiveFactory Software Users Guide

568

Chapter 14 Server Objects

PatchLevel QueryTimeout RetainPassword RevisionNumber SchemaVersion ServerName ServerType State TrustedConnection UseHttp VirtualDirectoryName

BaseURLAddress
The BaseURLAddress property is a read-write property that gets or sets the base URL address for the HTTP connection to the server.
Syntax
aaServer.BaseURLAddress = message; Result = aaServer.BaseURLAddress;

Remarks

The default is http://localhost/.

Build
The Build property is a read-only property that returns the build number of the IndustrialSQL Server historian as a message.
Syntax
Result = aaServer.Build;

Return Value

Returns the build number as a message.

Remarks

An exception is thrown if no one is currently logged on to the server. Use the LoggedOn property to find out if the server is logged on. This property has no default.

ActiveFactory Software Users Guide

aaServer Object

569

Domain
The Domain property is a read-write property that gets or sets the domain string for the connection to the server.
Syntax
aaServer.Domain = message; Result = aaServer.Domain;

Remarks

This property is useful in cases where the Windows integrated security requires the domain name to be specified. The default is an empty message value ( "" ).

LoginID
The LoginID property is a read-write property that gets and sets the login ID for the SQL Server.
Syntax
aaServer.LoginID = message; Result = aaServer.LoginID;

Remarks

This login ID is used if Windows integrated security is not used. After a log on has occurred, changing the value of this property has no effect until a log off and subsequent log on occurs. The default is wwUser.

LoggedOn
The LoggedOn property is a read-only property that returns True if the server has been logged on.
Syntax
Result = aaServer.LoggedOn;

Return Value

Returns True if the server has been logged on; otherwise, returns False.
Remarks

The default is False.

This property has no default.

Password
The Password property is a read-write property that gets and sets the password for the connection to the server.
Syntax
aaServer.Password = message; Result = aaServer.Password;

Remarks

This property is used if Windows integrated security is not used. After a logon has occurred, changing the value of this property has no effect until a logoff and subsequent logon occurs. The default is wwUser.

ActiveFactory Software Users Guide

aaServer Object

571

PatchLevel
The PatchLevel property is a read-only property that returns the patch level of the IndustrialSQL Server historian.
Syntax
Result = aaServer.PatchLevel;

Return Value

Returns the patch level as a message value.

Remarks

An exception is thrown if no one is currently logged on to the server. Use the LoggedOn property to find out if the server is logged on. This property has no default.

QueryTimeout
The QueryTimeout property is a read-write property that specifies the number of seconds to wait for a query to finish executing before the operation is aborted with a timeout error.
Syntax
aaServer.QueryTimeout = integer; Result = aaServer.QueryTimeout;

Remarks

Changing the value of this property after log on has no effect until log off and subsequent log on. The default is 120. A value of 0 means no timeout. If you dont use a timeout, the application waits indefinitely when trying to query a server, which may cause it to hang if the server is unavailable.

RetainPassword
The RetainPassword property is a read-write property that indicates whether the password is stored in persistent storage.
Syntax
aaServer.RetainPassword = discrete; Result = aaServer.RetainPassword;

Remarks

The default is True.

Returns the name of the server as a message.

Remarks

You can use the Name property to return the server name. This property has no default.

ActiveFactory Software Users Guide

aaServer Object

573

ServerType
The ServerType property is a read-only property that gets the server type.
Note Provided for backward-compatibility only. Do not use for new applications. Syntax
Result = aaServer.ServerType;

Return Value

Returns the server type as an enumeration. For more information, see aaServerType Enumeration on page 583.
Remarks

This property always returns a value of 1.

State
The State property is a read-only property that gets the state of the server.
Syntax
Result = aaServer.State;

Return Value

Returns the server state as an enumeration. For more information, see aaServerState Enumeration on page 583. The default is 2.

TrustedConnection
The TrustedConnection property is a read-write property that gets or sets the indication of whether Windows integrated security is used when logging on to the IndustrialSQL Server historian.
Syntax
aaServer.TrustedConnection = discrete; Result = aaServer.TrustedConnection;

Remarks

True = Windows integrated security is used; False = A SQL Server login ID and password is used. Changing the value of this property after logon has no effect until logoff and subsequent logon. The default is False.

ActiveFactory Software Users Guide

574

Chapter 14 Server Objects

UseHttp
The UseHttp property is a read-write property that controls whether to use HTTP to access the SQL Server.
Syntax
aaServer.UseHttp = discrete; Result = aaServer.UseHttp;

Remarks

If set to True, HTTP is used. This property also creates the connection object, if necessary. The default is False.

VirtualDirectoryName
The VirtualDirectoryName property is a read-write property that gets or sets the virtual directory name.
Syntax
aaServer.VirtualDirectoryName = message; Result = aaServer.VirtualDirectoryName;

Remarks

The default is ActiveFactory.

aaServer Methods
The aaServer methods are:

LogOff LogOn

LogOff
The LogOff method terminates the connection to the server.
Syntax
[Result=] aaServer.LogOff();

Remarks

Repeated calls to this method are harmless and do not result in further state change events. For more information on state change events, see OnServerStateChange on page 580.

LogOn
The LogOn method creates a connection (logs on) to the server.
Syntax
[Result=] aaServer.LogOn(out message statusMessage);

ActiveFactory Software Users Guide

aaServers Object

575

Parameters

statusMessage Information about the result of the log on attempt.

Return Value

Returns True if the log on was successful; otherwise, returns False.

Remarks

The server must be configured before calling the LogOn method. Changes made to the server configuration after a logon do not take effect until after a logoff and subsequent logon. This method produces state change events. For more information, see OnServerStateChange on page 580.

aaServers Object
The aaServer object is collection of aaServer instances. This object provides methods and properties for maintaining a sorted list of servers. Use the properties to get information regarding the number of servers in the collection. Use the methods to perform basic functions for the collection, such as adding or removing servers. Events for this object indicate when servers are added to the list, removed from the list, updated within the list, or when a server's state changes. This object is referenced with parameters from other ActiveFactory objects and controls.

aaServers Properties
The aaServers properties are:

ApplicationName Count Items

ApplicationName
The ApplicationName property gets or sets the application name to be used in profile logs when making a request to the IndustrialSQL Server historian.
Syntax
aaServers.ApplicationName = message; [Result=] aaServers.ApplicationName;

Remarks

The name must be set prior to a server in the list initiating a log on.

ActiveFactory Software Users Guide

576

Chapter 14 Server Objects

Count
The Count property is a read-only property that gets the number of servers in the server list.
Syntax
Result = aaServers.Count;

Return Value

Returns the number as an integer.

Remarks

The default is 0.

Items
The Items property is a read-only property that returns the list of servers in an array.
Syntax
Result = aaServers.Items;

Return Value

Returns the aaServer object. The same aaServer object instances that are in the server list are in the array. For more information on the aaServer object, see aaServer Object on page 567.
Remarks

This property is not supported in the InTouch HMI software. This property has no default.

aaServers Methods
The aaServers methods are:

Add GetServer Remove Update

Update
The Update method updates the specified server in the server list.
Syntax
[Result=] aaServers.Update(aaServer server);

ActiveFactory Software Users Guide

578

Chapter 14 Server Objects

Parameters

server The name of the server to update.

Return Value

Returns True if the given aaServer instance is currently in the server list; otherwise, False is returned.
Remarks

The Update method serves two purposes:

It causes the list of servers (which is the list that appears in the Server Configuration dialog box) to be persisted, if persistence is in effect. For example, the ActiveFactory Trend and ActiveFactory Query applications run with persistence in effect; when you start up these applications, you see previously-configured servers in the list. Controls, however, do not necessarily run with persistence in effect. When changes are made to properties in an instance of the aaServer object, they are not persisted until the Update method is called. It causes an OnServerUpdated event to fire. This allows other parts of the application to respond to changes in any of the servers in the servers list. When changes are made to properties in an instance of aaServer, no event is fired to report the change until the Update method is called.

The aaServer instance must be the exact same instance, not just an instance with the same name. If the instance is not in the list, then the list is not updated. The aaServer instance passed as an argument to the OnServerUpdated event is the exact same instance that is in the list.

aaServers Events
The aaServers events are:

OnServerAdded OnServerUpdated OnServerRemoved OnServerStateChange

These events are not accessible from the InTouch HMI software.

ActiveFactory Software Users Guide

aaServers Object

579

OnServerAdded
The OnServerAdded event is triggered when a new server is added to the server list.
Syntax
aaServers.OnServerAdded(object source, aaServerListChangeArgs args);

Parameters

source This parameter is not used. args The server state change arguments. For more information on the aaServerListChangeArgs object, see aaServerListChangeArgs Object on page 581.
Remarks

This event is not accessible from the InTouch HMI software.

OnServerUpdated
The OnServerUpdated event is triggered when a server that is currently in the server list is updated.
Syntax
aaServers.OnServerUpdated(object source, aaServerListChangeArgs args);

Parameters

source The object. For more information on specifying an object, see Object on page 639. args The server state change arguments. For more information on the aaServerListChangeArgs object, see aaServerListChangeArgs Object on page 581.
Remarks

This event is not accessible from the InTouch HMI software.

OnServerRemoved
The OnServerRemoved event is triggered when a server is removed from the server list.
Syntax
aaServers.OnServerRemoved(object source, aaServerListChangeArgs args);

Parameters

source The object. For more information on specifying an object, see Object on page 639.

ActiveFactory Software Users Guide

580

Chapter 14 Server Objects

args The server state change arguments. For more information on the aaServerListChangeArgs object, see aaServerListChangeArgs Object on page 581.
Remarks

This event is not accessible from the InTouch HMI software.

OnServerStateChange
The OnServerStateChange event is triggered when the state of a server is changed.
Syntax
aaServers.OnServerStateChange(object source, aaServerStateChangeArgs args);

Parameters

source The object. For more information on specifying an object, see Object on page 639. args The server state change arguments. For more information on the aaServerStateChangeArgs object, see aaServerStateChangeArgs Object on page 581.
Remarks

This event is not accessible from the InTouch HMI software.

Instantiating an aaServers Object

The aaServers object is a cocreatable object. That is, it can be instantiated on its own, instead of only being created when used by a method of another object. In the InTouch HMI software, you can use the OLE_CreateObject() function to instantiate the aaServers object. The ProgID for the aaServers object is ArchestrA.HistClient.Database.aaServers. For example:
OLE_CreateObject (%Man, "ArchestrA.HistClient.Database.aaServers");

ActiveFactory Software Users Guide

aaServerListChangeArgs Object

581

aaServerListChangeArgs Object
The aaServerListChangeArgs object is used to return name of the aaServer instance that changed.

Properties
The aaServerListChangeArgs object property is:

Server

Server
The Server property is a read-only property that gets the aaServer instance that was either added, updated, or removed during the operation that produced the event.
Syntax
Result = aaServerListChangeArgs.Server;

Return Value

The aaServer instance. For more information on the aaServer object, see aaServer Object on page 567.
Remarks

This property has no default.

aaServerStateChangeArgs Object
The aaServerListChangeArgs object is used to return state changes for the server.

Properties
The aaServerStateChangeArgs object properties are:

Server State When Message

Server
The Server property is a read-only property that gets the server that changed state.
Syntax
Result = aaServerStateChangeArgs.Server;

Return Value

The aaServer instance. For more information on the aaServer object, see aaServer Object on page 567.

ActiveFactory Software Users Guide

582

Chapter 14 Server Objects

Remarks

This property has no default.

State
The State property is a read-only property that gets the state to which the server changed.
Syntax
Result = aaServerStateChangeArgs.State;

Return Value

The aaServerState enumeration. For more information on the aaServerState enumeration, see aaServerState Enumeration on page 583.
Remarks

This property has no default.

When
The When property is a read-only property that gets the date and time of the state change.
Syntax
Result = aaServerStateChangeArgs.When;

Return Value

The date/time stamp. For more information on the DateTime data type, see DateTime on page 638.
Remarks

This property has no default.

Message
The Message property is a read-only property that gets any message available for the state change, such as a detailed error message.
Syntax
Result = aaServerStateChangeArgs.Message;

Return Value

Returns the message as a message value.

Remarks

This property has no default.

ActiveFactory Software Users Guide

aaServerState Enumeration

583

aaServerState Enumeration
Specifies the allowed states of a server.
Value Enumeration Description

0 1 2

LoggedOn Error LoggedOff

There is a connection to the server. The connection can not be made to the server. No connection has been attempted to the server or the LogOff method has been called. An attempt to connect to the server has begun and has not yet succeeded, nor has the attempt yet timed out.

LoggingOn

aaServerType Enumeration
Specifies the types of a server.
Note Provided for backward-compatibility only. Do not use for new applications. Value Enumeration Description

0 1 2

isSvrPdssrv isSvrSQLServe r isSvrNotInSQ L

For backward-compatibility only. For backward-compatibility only. For backward-compatibility only.

ActiveFactory Software Users Guide

584

Chapter 14 Server Objects

ActiveFactory Software Users Guide

585

Chapter 15
aaTag Object

When tags are read from the IndustrialSQL Server historian database, they are each stored in an instance of the aaTag object. This object provides read-only properties for accessing the information about the tag that was obtained from the IndustrialSQL Server historian.

Using aaTag in an Application

You can use the aaTag object's properties in runtime scripts in your application to get configuration information for a tag. Also, this object is referenced with parameters from other ActiveFactory objects and controls.

aaTag Properties
The aaTag properties are: DateCreated Description IOAddress MaxRaw MinRaw MinEU MaxEU Message0 Message1

ActiveFactory Software Users Guide

586

Remarks

The default is NULL.

Remarks

The default is the name that was specified when the tag was created.

ActiveFactory Software Users Guide

Using aaTag in an Application

589

RawType
This read-only property returns the numeric type for the raw value. 1 = Euro Float (4 bytes); 2 = MS Float (4 bytes); 3 = Integer (2 or 4 bytes); 4 = MS Double (reserved for future use) (8 bytes).
Syntax
Result = aaTag.RawType;

Return Value

The return value is an integer.

Remarks

The default is 0.

Server
This read-only property returns the server associated with the tag.
Syntax
Result = aaTag.Server;

Return Value

The return value is an aaServer object. For more information, see aaServer Object on page 567. The server cannot be changed after construction.
Remarks

ActiveFactory Software Users Guide

591

Chapter 16
aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

The aaHistClientWorkbookRunner and aaHistClientReportRunner objects are used when reports are published to the ActiveFactory Reporting Website.

aaHistClientWorkbookRunner Object
The aaHistClientWorkbookRunner object is a control that is used to run reports created with ActiveFactory Workbook. There is no user interface for this control. You can use the aaHistClientWorkbookRunner control's properties and methods in runtime scripts in your application to run existing Workbook files (.xls) and output the results (.htm).

aaHistClientWorkbookRunner Object Properties

The aaHistClientWorkbookRunner object properties include: ErrDescription ErrNumber OutputFile SourceFile ExcelVisible

ActiveFactory Software Users Guide

592

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

ErrDescription
The ErrDescription property is a read-only property that returns an error message if the Run method fails.
Syntax
Result = aaHistClientWorkbookRunner.ErrDescription;

Return Value

The return value is a message. The error message describes the reason for the failure.
Remarks

The default is an empty message value ( "" ).

ErrNumber
The ErrNumber property is a read-only property that returns an error code number if the Run method fails.
Syntax
Result = aaHistClientWorkbookRunner.ErrNumber;

Return Value

The return value is an integer.

Remarks

The default is 0.

OutputFile
The OutputFile property is a read-write property that is used to specify the file to be created as a result of running the report.
Syntax
aaHistClientWorkbookRunner.OutputFile = message; Result = aaHistClientWorkbookRunner.OutputFile;

Remarks

You must specify the entire path and include the .htm extension. The default is an empty message value ( "" ).

SourceFile
The SourceFile property is a read-write property that specifies the name of the Excel file (.xls) to use to generate the report.
Syntax
aaHistClientWorkbookRunner.SourceFile = message; Result = aaHistClientWorkbookRunner.SourceFile;

Remarks

You must specify the entire path and include the .xls extension. The default is an empty message value ( "" ).
ActiveFactory Software Users Guide

aaHistClientWorkbookRunner Object

593

ExcelVisible
The ExcelVisible property is a read-write property that specifies whether or not the Excel application user interface is visible when the report is run.
Syntax
aaHistClientWorkbookRunner.ExcelVisible = discrete; Result = aaHistClientWorkbookRunner.ExcelVisible;

Remarks

If set to True, Excel is visible. If set to False, Excel is not visible. The default is False. Setting this property to True is useful when you are testing the report generation. The default is False.

aaHistClientWorkbookRunner Methods
The aaHistClientWorkbookRunner control methods include: Run RunReport RunReport2

Run
The Run method processes the Workbook report.
Syntax
[Result=] aaHistClientWorkbookRunner.Run();

Return Value

Returns True if the report generation was successful; otherwise returns False.
Remarks

When this method is called, the following occurs:

1 2 3

Excel starts. Excel is visible only if the ExcelVisible property was set to True. The workbook file (.xls) specified by the SourceFile property opens. The report runs and saved as the .htm file specified by the OutputFile property.

4 Excel closes. If you want to use binding options for the report, use the RunReport method.

ActiveFactory Software Users Guide

594

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

RunReport
The RunReport method processes the Workbook report. This method uses the date/time binding feature of Workbook.
Syntax
[Result=] aaHistClientWorkbookRunner.RunReport(

message message message integer message integer message integer message message integer Parameters

inputFile, outputFile, outputPrefix, outputFormat, tagString, NSFolderKey, nameSpace, dateMode, startDate, endDate, duration);

inputFile The name of the source file for the report generation, including the full path. Valid file types are .htm, .xls, and .xlt. outputFile The name of the output file that is generated, including the full path. If this parameter is set to an empty string ( " "), then a file name is generated automatically according to the following formula:
OutputFile = OutputPrefix + InputFile + year + month + day + _ + hour + minute + second

outputPrefix The value that is prepended to the output file name. If you specify an empty string ( " " ), no prefix is prepended. The outputPrefix parameter is only used if the outputFile parameter is an empty string. outputFormat The file type for the output file. Valid values are: 0 = Native. That is, if the source file is an .htm file, the output file is an .htm file. If the source file is an .xls or .xlt file, the output file is an .xls file. 1 = .htm 2 = .xls 3 = .xlt

ActiveFactory Software Users Guide

aaHistClientWorkbookRunner Object

595

tagString A comma separated list of strings to be used for the AFTagBinding named range. Valid formats are: "<tagname1>,<tagname2>" "'<tagname1>','<tagname2>'" For example: "ReactLevel,ReactTemp" "'ReactLevel','ReactTemp'" NSFolderKey Reserved for future use. This parameter cannot be blank. Specify a value (for example, 0) for this parameter, even though it has no effect. nameSpace Reserved for future use. This parameter cannot be blank. Specify an empty string ( "" ) for this parameter, even though it has no effect. dateMode Determines the values used for the AFStartBinding and AFEndBinding named ranges. Valid values are: 0 = Use specific start and end times. 1 = Use a duration relative to the current time. 2 = Use a duration relative to the specified start time. 3 = Use a duration relative to the specified end time. Use the startDate, endDate, and Duration parameters to specify the dates. startDate A date string that can be converted to a date by the Visual Basic CDate() function. A good format to use is one that reflects the standard short date and short time format on the local system. If the dateMode parameter is set to 1 or 3, this parameter is ignored. If the dateMode parameter is set to 0, this value indicates the specific date/time to be used for the AFStartBinding range. If the dateMode parameter is set to 2, then "rel" is used for the AFStartBinding range and '+Duration(StartDate)' is used for the AFEndBinding range.

ActiveFactory Software Users Guide

596

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

endDate A date string that can be converted to a date by the Visual Basic CDate() function. A good format to use is one that reflects the standard short date and short time format on the local system. If the dateMode parameter is set to 1 or 2, this parameter is ignored. If the dateMode parameter is set to 0, this value indicates the specific date/time to be used for the AFEndBinding range. If the dateMode parameter is set to 3, then "rel" is used for the AFStartBinding range and '+Duration(EndDate)' is used for the AFEndBinding range. Duration The time span, in seconds, used for date/time calculations. This value cannot be a negative number. If the dateMode parameter is set to 0, this value is ignored. If the dateMode parameter is set to 1, "rel" is used for the AFStartBinding range and '-Duration()' is used for the AFEndBinding range. If the dateMode parameter is set to 2, "rel" is used for the AFStartBinding range and '+Duration(StartDate)' is used for the AFEndBinding range. If the dateMode parameter is set to 3, "rel" is used for the AFStartBinding range and '-Duration(EndDate)' is used for the AFEndBinding range.
Return Value

Returns the output file name if the report generation was successful; otherwise, an empty string is returned.
Remarks

When this method is called, the following occurs:

1 2 3 4

Excel starts. Excel is visible only if the ExcelVisible property was set to True. The workbook file (.xls) specified by the SourceFile property opens. The binding information in the workbook file is updated. The report runs and is saved as the .htm file specified by the OutputFile property.

5 Excel closes. To run a report without using the binding options, use the Run method. To run a report that only uses additional binding options for custom filters, use the RunReport2 method.

ActiveFactory Software Users Guide

aaHistClientWorkbookRunner Object

597

RunReport2
The RunReport2 method processes the Workbook report. This method uses the date/time binding feature of Workbook, plus custom binding filters.
Syntax
[Result=] aaHistClientWorkbookRunner.RunReport(

message message message integer message integer message integer message message integer message Parameters

inputFile, outputFile, outputPrefix, outputFormat, tagString, NSFolderKey, nameSpace, dateMode, startDate, endDate, duration customFilters);

inputFile The name of the source file for the report generation, including the full path. Valid file types are .htm, .xls, and .xlt. outputFile The name of the output file generated, including the full path. If this parameter is set to an empty string ( " " ), then a file name is generated automatically according to the following formula:
OutputFile = OutputPrefix + InputFile + year + month+ day + _ + hour + minute + second

ActiveFactory Software Users Guide

598

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

ActiveFactory Software Users Guide

aaHistClientWorkbookRunner Object

599

ActiveFactory Software Users Guide

600

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

customFilters A string of name-value pairs used to pass information from the ActiveFactory Reporting Website to the workbook file before the report is run. The format for the string is as follows: <name>=<value> To pass more than one name-value pair, join them with ampersands. For example: <name>=<value>&<name>=<value> The parameter name that you use must correspond to an existing named range in the workbook that starts with "AFBinding." The value you specify in the name-value pair is used for the corresponding named range in the workbook. You can specify multiple values if you separate them with commas. For example, you workbook contains the AFBindingReportValue and AFBindingReportText named ranges. You want to pass a value of 5 for the report value and Line1 and Line2 for the ReportText. The customFilters parameter is: ReportValue=5&ReportText=Line2,Line2
Return Value

Returns the output file name if the report generation was successful; otherwise, an empty string is returned.
Remarks

When this method is called, the following occurs:

1 2 3 4 5

Excel closes. To run a report without using the binding options, use the Run method. To run a report that only uses the date/time binding options, use the RunReport method.

ActiveFactory Software Users Guide

aaHistClientReportRunner Object

601

aaHistClientReportRunner Object
The aaHistClientReportRunner object is a control that is used to run reports created with ActiveFactory Report. There is no user interface for this control. You can use the aaHistClientReportRunner object's properties and methods in runtime scripts in your application to run existing Report files and output the results (.htm).

aaHistClientReportRunner Object Properties

The aaHistClientReportRunner object properties include: ErrDescription ErrNumber OutputFile SourceFile WordVisible

ErrDescription
The ErrDescription property is a read-only property that returns an error message if the Run method fails.
Syntax
Result = aaHistClientReportRunner.ErrDescription;

Return Value

The return value is a message. The error message describes the reason for the failure.
Remarks

The default is an empty message value ( "" ).

ErrNumber
The ErrNumber property is a read-only property that returns an error code number if the Run method fails.
Syntax
Result = aaHistClientReportRunner.ErrNumber;

Return Value

The return value is an integer.

Remarks

The default is 0.

ActiveFactory Software Users Guide

602

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

OutputFile
The OutputFile property is a read-write property that is used to specify the file to be created as a result of running the report.
Syntax
aaHistClientReportRunner.OutputFile = message; Result = aaHistClientReportRunner.OutputFile;

Remarks

You must specify the entire path and include the .htm extension. The default is an empty message value ( "" ).

SourceFile
The SourceFile property is a read-write property that specifies the name of the Word template file (.htm) to use to generate the report.
Syntax
aaHistClientReportRunner.SourceFile = message; Result = aaHistClientReportRunner.SourceFile;

Remarks

You must specify the entire path and include the .htm extension. The default is an empty message value ( "" ).

WordVisible
The WordVisible property is a read-write property that specifies whether or not the Word application user interface is visible when the report is run.
Syntax
aaHistClientReportRunner.WordVisible = discrete; Result = aaHistClientReportRunner.WordVisible;

Remarks

If set to True, Word is visible. If set to False, Word is not visible. The default is False. Setting this property to True is useful when you are testing the report generation. The default is False.

ActiveFactory Software Users Guide

aaHistClientReportRunner Object

603

aaHistClientReportRunner Object Methods

The aaHistClientReportRunner object has a single method: Run

Run
The Run method processes the Word report.
Syntax
[Result=] aaHistClientReportRunner.Run();

Return Value

Returns True if the report generation was successful; otherwise returns False.
Remarks

When this method is called, the following occurs:

1 2 3 4

Word starts. Word is visible only if the WordVisible property was set to True. The report file (.htm) specified by the SourceFile property opens. The report runs and is saved as the .htm file specified by the OutputFile property. Word closes.

ActiveFactory Software Users Guide

604

Chapter 16 aaHistClientWorkbookRunner and aaHistClientReportRunner Objects

ActiveFactory Software Users Guide

605

Chapter 17
Workbook and Report Automation Objects

The ActiveFactoryWorkbook and ActiveFactoryReport automation objects allow you to automate ActiveFactory Workbook and Report from a scripting environment, such as Visual Basic for Applications.

ActiveFactoryWorkbook Object
To automate the generation of reports from ActiveFactory Workbook, use the ActiveFactoryWorkbook object within the scripting environment.

ActiveFactoryWorkbook Object Methods

The ActiveFactoryWorkbook object methods are:

AddServer Auto_Close Auto_Open GetLastError RunReport ActiveFactory Workbook Menu Methods ActiveFactory Workbook Functions

ActiveFactory Software Users Guide

606

Chapter 17 Workbook and Report Automation Objects

AddServer
The AddServer method adds a server to the list of servers for the current workbook.
Syntax
ActiveFactoryWorkbook.AddServer(message serverName, message loginName, message password)

Parameters

serverName The name of the server to which to connect. loginName A valid user name for the server. password A valid password for the server.

Auto_Close
The Auto_Close method removes the ActiveFactory toolbar and resets the main menu for Excel.
Syntax
ActiveFactoryWorkbook.AutoClose()

Auto_Open
The Auto_Open method adds the ActiveFactory toolbar and adds the ActiveFactory menu to the main menu for Excel.
Syntax
ActiveFactoryWorkbook.Auto_Open()

GetLastError
The GetLastError method returns a message for any error that occurs when the report is run using the RunReport method.
Syntax
[Result=] ActiveFactoryWorkbook.GetLastError()

Return Value

Returns a message value containing the error for the RunReport method. If an empty string is returned, then an error has occurred. If the output file name is returned, a warning may have occurred.
Remarks

Possible errors are:

Only available when a server is present, click OK to add a server. The input file specified does not exist.

ActiveFactory Software Users Guide

ActiveFactoryWorkbook Object

607

The output format specified is invalid. The DateMode argument must be 0, 1, 2, or 3. The specified start date is invalid. The specified end date is invalid. The specified duration is invalid. TagString is not empty and AFTagBinding does not exist. Invalid TagString format. Warning: The AFTagBinding range in the report contains no tags and no tags have been passed in. The <filename> range must be defined. An error occurred while attempting to save the file. <filename> is unknown. No values for <filename>. Wizard Error:

RunReport
The RunReport method processes the Workbook report. This method uses the date/time binding feature of Workbook, plus custom binding filters.
Syntax
[Result=] ActiveFactoryWorkbook.RunReport(

message message message integer message integer message integer message message integer message Parameters

inputFile, outputFile, outputPrefix, outputFormat, tagString, NSFolderKey, nameSpace, dateMode, startDate, endDate, duration customFilters)

inputFile The name of the source file for the report generation, including the full path. Valid file types are .htm, .xls, and .xlt.

ActiveFactory Software Users Guide

608

Chapter 17 Workbook and Report Automation Objects

outputFile The name of the output file generated, including the full path. If this parameter is set to an empty string ( "" ), then a file name is generated automatically according to the following formula:
OutputFile = OutputPrefix + InputFile + _ + year + month + day + hour + minute + second

outputPrefix The value prepended to the output file name. If you specify an empty string ( "" ), no prefix is prepended. The outputPrefix parameter is only used if the outputFile parameter is an empty string. outputFormat The file type for the output file. Valid values are: 0 = Native. That is, if the source file is an .htm file, the output file is an .htm file. If the source file is an .xls or .xlt file, the output file is an .xls file. 1 = .htm 2 = .xls 3 = .xlt tagString A comma separated list of strings to be used for the AFTagBinding named range. If the AFTagBinding range does not exist, and this parameter is set to any value other than an empty string ( "" ), an error is raised. Valid formats are: "<tagname1>,<tagname2>" "'<tagname1>','<tagname2>'" For example: "ReactLevel,ReactTemp" "'ReactLevel','ReactTemp'" NSFolderKey Reserved for future use. This parameter cannot be blank. Specify a value (for example, 0) for this parameter, even though it has no effect. nameSpace Reserved for future use. This parameter cannot be blank. Specify an empty string ( "" ) for this parameter, even though it has no effect.

ActiveFactory Software Users Guide

ActiveFactoryWorkbook Object

609

dateMode Determines the values used for the AFStartBinding and AFEndBinding named ranges. An error is raised if the binding ranges do not exist or if this parameter is blank. Valid values are: 0 = Use specific start and end times. 1 = Use a duration relative to the current time. 2 = Use a duration relative to the specified start time. 3 = Use a duration relative to the specified end time. Use the startDate, endDate, and Duration parameters to specify the dates. startDate A date string that can be converted to a date by the Visual Basic CDate() function. A good format to use is one that reflects the standard short date and short time format on the local system. If the dateMode parameter is set to 1 or 3, this parameter is ignored. If the dateMode parameter is set to 0, this value indicates the specific date/time to be used for the AFStartBinding range. If the dateMode parameter is set to 2, then "rel" is used for the AFStartBinding range and '+Duration(StartDate)' is used for the AFEndBinding range. endDate A date string that can be converted to a date by the Visual Basic CDate() function. A good format to use is one that reflects the standard short date and short time format on the local system. If the dateMode parameter is set to 1 or 2, this parameter is ignored. If the dateMode parameter is set to 0, this value indicates the specific date/time to be used for the AFEndBinding range. If the dateMode parameter is set to 3, then "rel" is used for the AFStartBinding range and '+Duration(EndDate)' is used for the AFEndBinding range.

ActiveFactory Software Users Guide

610

Chapter 17 Workbook and Report Automation Objects

Duration The time span, in seconds, used for date/time calculations. This value cannot be a negative number. If the dateMode parameter is set to 0, this value is ignored. If the dateMode parameter is set to 1, "rel" is used for the AFStartBinding range and '-Duration()' is used for the AFEndBinding range. If the dateMode parameter is set to 2, "rel" is used for the AFStartBinding range and '+Duration(StartDate)' is used for the AFEndBinding range. If the dateMode parameter is set to 3, "rel" is used for the AFStartBinding range and '-Duration(EndDate)' is used for the AFEndBinding range. customFilters A string of name-value pairs used to pass information from the ActiveFactory Reporting Website to the workbook file before the report is run. The format for the string is as follows: <name>=<value> To pass more than one name-value pair, join them with ampersands. For example: <name>=<value>&<name>=<value> The parameter name that you use must correspond to an existing named range in the workbook that starts with "AFBinding." The value you specify in the name-value pair is used for the corresponding named range in the workbook. You can specify multiple values if you separate them with commas. For example, you workbook contains the AFBindingReportValue and AFBindingReportText named ranges. You want to pass a value of 5 for the report value and Line1 and Line2 for the ReportText. The customFilters parameter is: ReportValue=5&ReportText=Line2,Line2
Return Value

Returns the output file name if the report generation was successful; otherwise, an empty string is returned.

ActiveFactory Software Users Guide

ActiveFactoryWorkbook Object

611

ActiveFactory Workbook Menu Methods

The following methods execute Workbook menu commands
Method Used to

mnuAbout mnuAddDSN mnuAggregates mnuAlarm mnuAnalysis mnuBaseDate mnuConvert mnuConvertSheet mnuEditFunction mnuHelp mnuHistory mnuInSQL mnuLive mnuOptions mnuQuery mnuRefreshSelection mnuRefreshSheet mnuSnapSearch mnuSnapShot mnuSumTagSearch mnuSumTagValues mnuTagDesc mnuTagSearch

Open the About dialog box. Open the Server List Configuration dialog box. Open the Aggregate Values wizard. Open the Alarm Values wizard. Open the Tag Analysis wizard. Open the Set Base Date/Time dialog box. Convert the function in the selected cell to values. Convert the functions in the active sheet to values. Open the appropriate wizard for the selected function. Open the Help file. Open the History Values wizard. Open the Server Details dialog box. Open the Live Values wizard. Open the Options dialog box. Open the Direct Query dialog box. Refresh the selected function. Refresh the active worksheet. Open the Event Snapshot Tag Selection dialog box. Open the Event Snapshot Values wizard. Open the Summary Tag Selection dialog box. Open the Summary Values wizard. Open the Tag Details wizard. Open the Tag Selection dialog box.

ActiveFactory Software Users Guide

612

Chapter 17 Workbook and Report Automation Objects

ActiveFactory Workbook Functions

For more information on the ActiveFactory Workbook Functions, see ActiveFactory Workbook Function Reference on page 302.

ActiveFactory Workbook Automation Example

The following example illustrates how to automate ActiveFactory Workbook within Visual Basic for Applications (VBA). In this example, a button is added to the workbook that can be used to convert the all of the functions in the sheet to values. This example uses the ActiveFactoryWorkbook.mnuConvertSheet method.
To automate ActiveFactory Workbook 1

Start Excel and create an ActiveFactory Workbook spreadsheet.

ActiveFactory Software Users Guide

ActiveFactoryWorkbook Object

613

On the Tools menu, point to Macro and then click Visual Basic Editor. The Microsoft Visual Basic editor appears.

On the Tools menu, click References. The References VBAProject dialog box appears.

4 5 6

Select the ActiveFactoryWorkbook check box. Click OK. On the Insert menu, click Module to add a new module to the project.

ActiveFactory Software Users Guide

614

Chapter 17 Workbook and Report Automation Objects

Add a subroutine that executes the mnuConvertSheet method.

8 9

Switch back to Excel. On the View menu, point to Toolbars and then click Forms to open the Forms toolbar.

ActiveFactory Software Users Guide

ActiveFactoryWorkbook Object

615

10 Insert a button into the worksheet. The Assign Macro

dialog box appears.

11 In the Macro name list, select ConvertToValues, which is

the subroutine that you created in Step 7.

12 Click OK. 13 Change the display name for the button and adjust the

size, appropriately.

ActiveFactory Software Users Guide

616

Chapter 17 Workbook and Report Automation Objects

14 Click the Convert To Values button to execute the

command. All of the functions in the sheet are converted to values.

ActiveFactoryReport Object
To automate the generation of reports from ActiveFactory Report, use the ActiveFactoryReport object within the scripting environment.

Report Object Properties

The Report object properties are:

ReportDate ReportTime

ReportDate
The ReportDate property is a read-write property that gets or sets the date that the report was run.
Syntax
ActiveFactoryReport.ReportDate = message; Result = ActiveFactoryReport.ReportDate;

Remarks

The value of this property is used for any #Date wildcards used within the report. For more information on the #Date wildcard, see #date Wildcard on page 342. The default is the current date of when Microsoft Word was launched.

ActiveFactory Software Users Guide

ActiveFactoryReport Object

617

ReportTime
The ReportTime property is a read-write property that gets or sets the time that the report was run.
Syntax
ActiveFactoryReport.ReportTime = message; Result = ActiveFactoryReport.ReportTime;

Remarks

The value of this property is used for any #ReportTime wildcards used within the report. For more information on the #ReportTime wildcard, see #ReportTime Wildcard on page 343. The default is the current date of when Microsoft Word was launched.

Report Object Methods

The Report object methods are:

AutoExec AutoExit RunReport

AutoExec
The AutoExec method initializes values.
Syntax
ActiveFactoryReport.AutoExec()

AutoExit
The AutoExit method removes the ActiveFactory toolbar and resets the main menu for Word.
Syntax
ActiveFactoryReport.AutoExit()

RunReport
The RunReport method processes the Word report.
Syntax
ActiveFactoryReport.RunReport()

Return Value

Returns False if the report generation was successful; otherwise returns True.
Remarks

Any message dialog boxes are suppressed.

ActiveFactory Software Users Guide

618

Chapter 17 Workbook and Report Automation Objects

ActiveFactory Software Users Guide

619

Chapter 18
aaHistClientGlobalFunctions Object

This object provides methods for accessing the information about ActiveFactory software installation.

Using aaHistClientGlobalFunctions Object in an Application

You can use the aaHistClientGlobalFunctions object's methods in runtime scripts in your application to get installation information for the ActiveFactory software. The ProgID for the GlobalFunctions object is: ArchestrA.HistClient.Util.aaHistClientGlobalFunctions

aaHistClientGlobalFunctions Methods
The aaHistClientGlobalFunctions methods are: GetDictionaryPath GetInstallPath MDACOk

GetDictionaryPath
The GetDictionaryPath method returns the path to the dictionary file.
Syntax
[Result=] aaHistClientGlobalFunctions.GetDictionaryPath();

ActiveFactory Software Users Guide

620

Chapter 18 aaHistClientGlobalFunctions Object

Return Value

Returns an empty string.

Remarks

This method is provided for backward compatibility only.

GetInstallPath
The GetInstallPath method returns the path where the ActiveFactory software is installed.
Syntax
[Result=] aaHistClientGlobalFunctions.GetInstallPath();

Return Value

Returns a fully-qualified path to the installation folder as a string.

MDACOk
The MDACOk method returns whether the Microsoft Data Access Components (MDAC) are installed.
Syntax
[Result=] aaHistClientGlobalFunctions.MDACOk();

Return Value

Returns True if the components are installed; otherwise, returns False.

Remarks

Since MDAC is a prerequisite for the ActiveFactory software, this method always returns True.

ActiveFactory Software Users Guide

621

Chapter 19
Common Properties, Methods, Events, Enums, and Data Types

This section describes the generic properties, methods, and events that are common to one or more controls. Also, descriptions for common data types and enumerations are provided. Some of the common properties, methods, and events are ambient. Ambient properties, methods, and events are defined by the control container to assist the control in adapting to the particular environment in which it is used.
Note Not all of the common properties, methods, events, enums, and data types are used by all of the controls.

Common Properties
All of the following properties are ambient properties.

BackColor BorderStyle Container DataBindings DragMode Font Height Index Name Parent

BackStyle CausesValidation ContextMenuEnabled DragIcon Enabled ForeColor HelpContextID Left Object TabIndex

ActiveFactory Software Users Guide

622

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

TabStop ToolTipText Transparent WhatsThisHelpID

Tag Top Visible Width

BackColor
The BackColor property is a read-write property that specifies the background color for the control.
Syntax
<objectname>.BackColor = integer; Result = <objectname>.BackColor;

Remarks

The default value of 1 indicates to use the window color.

Related Topics
ForeColor Font BackStyle Transparent

BackStyle
The BackStyle property is a read-write property that specifies whether the background for a label or a shape is opaque or transparent.
Syntax
<objectname>.BackStyle = integer; Result = <objectname>.BackStyle;

Remarks

0 = Transparent; 1 = Opaque. Setting this property to 0 has the same effect as setting the Transparent property to True.

Related Topics
ForeColor BackColor Font BorderStyle Transparent

ActiveFactory Software Users Guide

Common Properties

623

ActiveFactory Software Users Guide

Common Properties

625

Enabled
The Enabled property is a read-write property that determines whether the control can be acted upon by the runtime user.
Syntax
<objectname>.Enabled = discrete; Result = <objectname>.Enabled;

Font
The Font property is a read-write property that gets or sets the font object.
Syntax
<objectname>.Font = Font; Result = <objectname>.Font;

Remarks

This property controls the font appearance for all text in the user interface.

Related Topics
ForeColor BackColor BackStyle BorderStyle Transparent

ForeColor
The Fore property is a read-write property that gets or sets the color to be used for the foreground color in the control.
Syntax
<objectname>.ForeColor = Long; Result = <objectname>.ForeColor;

Remarks

The default is 1 (the window color).

Related Topics
Font BackColor BackStyle BorderStyle Transparent

ActiveFactory Software Users Guide

626

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

Height
The Height property is a read-write property that gets or sets the height of the control.
Syntax
<objectname>.Height = Single; Result = <objectname>.Height;

Remarks

This property is not available in the InTouch HMI software.

HelpContextID
The HelpContextID property is a read-write property that gets or sets the Help context ID for the object.
Syntax
<objectname>.HelpContextID = Long; Result = <objectname>.HelpContextID;

Remarks

This property is not available in the InTouch HMI software.

Index
The Index property is a read-only property that returns the number identifier for a control in an array.
Syntax
<objectname>.Index = integer; Result = <objectname>.Index;

Remarks

The starting value for the identifier is typically 1. This property is not available in the InTouch HMI software.

Left
The Left property is a read-write property that gets or sets the distance between the left edge of the container application and the internal left edge of the control.
Syntax
<objectname>.Left = Single; Result = <objectname>.Left;

Remarks

This property is not available in the InTouch HMI software.

ActiveFactory Software Users Guide

Common Properties

627

Name
The Name property is a read-only property that gets the name used to identify an object.
Syntax
<objectname>.Name = message; Result = <objectname>.Name;

Remarks

This property is not available in the InTouch HMI software.

Object
The Object property is a read-only property that gets the object in a control.
Syntax
<objectname>.Object = Object; Result = <objectname>.Object;

Remarks

This property is not available in the InTouch HMI software.

Parent
The Parent property is a read-only property that gets the object on which this object is located.
Syntax
<objectname>.Parent = Object; Result = <objectname>.Parent;

Remarks

This property is not available in the InTouch HMI software.

TabIndex
The TabIndex property is a read-write property that gets or sets the tab order of the object within its parent form.
Syntax
<objectname>.TabIndex = integer; Result = <objectname>.TabIndex;

Transparent
The Transparent property is a read-write property that gets or sets the background of the object to be transparent.
Syntax
<objectname>.Transparent = discrete; Result = <objectname>.Transparent;

Remarks

If set to True, the the underlying form appears through the background of the object. The field (text box) label is not transparent. However, you can hide the field label to achieve total transparency. The default is False.

Related Topics
ForeColor BackColor BackStyle BorderStyle Font

Visible
The Visible property is a read-write property that determines whether an object is visible or hidden.
Syntax
<objectname>.Visible = discrete; Result = <objectname>.Visible;

Remarks

This property is not available in the InTouch HMI software. To hide the control, change the object coordinates so that the object appears out of the bounds of the window.

WhatsThisHelpID
The WhatsThisHelpID property is a read-write property that gets or sets the associated context-sensitive Help ID number for an object.
Syntax
<objectname>.WhatsThisHelpID = Long; Result = <objectname>.WhatsThisHelpID;

Remarks

This property is not available in the InTouch HMI software.

ActiveFactory Software Users Guide

630

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

This property is not available in the InTouch HMI software.

Common Methods
All of the following methods are ambient methods.

Drag Move SetFocus SetToolbarButtonEnabled ShowWhatsThis ZOrder

Drag
The Drag method begins, ends, or cancels the drag operation for any object except for Menu, Line, Time, and Shape.
Syntax
[Result=] <objectname>.Drag();

Return Value

Returns True if successful; otherwise returns False.

Move
The Move method moves an object.
Syntax
[Result=] <objectname>.Move(single Left, [Top], [Width], [Height]);

ActiveFactory Software Users Guide

Common Events

631

SetFocus
The SetFocus method sets the focus to the specified object.
Syntax
[Result=] <objectname>.SetFocus();

ShowWhatsThis
The ShowWhatsThis method displays a particular topic in a Help file.
Syntax
[Result=] <objectname>.ShowWhatsThis();

Remarks

The What' This? popup control provided by Windows Help is used.

ActiveFactory Software Users Guide

632

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

MouseUp Validate

Click
The Click event is triggered when the runtime user clicks on the object at runtime with the mouse.
Syntax
<objectname>.Click();

ActiveFactory Software Users Guide

Common Events

633

GotFocus
The GotFocus event is triggered when an object receives focus.
Syntax
<objectname>.GotFocus();

ActiveFactory Software Users Guide

634

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

LostFocus
The LostFocus event is triggered when an object loses focus.
Syntax
<objectname>.LostFocus();

ActiveFactory Software Users Guide

Common Enumerations

635

Validate
The Validate event is triggered when a control loses focus to a control that causes validation.
Syntax
<objectname>.Validate(discrete Cancel);

Common Enumerations
Common enumerations are:

aaRetrievalSource Enumeration aaTagType Enumeration

aaRetrievalSource Enumeration
Specifies the source of process data to retrieve.
Value Enumeration Description

ExtensionTablesOnl y ManualHistoryOnly

Retrieve data only from a history extension tables (for example, History). Retrieve dataonly from a manual history tables (for example, ManualAnalogHistory). Retrieve data from both the extension table and the manual history table and combine the data from both.

Both

aaTagType Enumeration
Specifies the set of tag types allowed for tags.
Value Enumeration Description

UnknownTag

Not a valid type. This value indicates a tag that cannot be found on the server. Analog tag type. Discrete tag type. String tag type.

1 2 3

Analog Discrete String

ActiveFactory Software Users Guide

636

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

Value

Enumeration

Description

4 5

Complex Event

Complex tag type. Event tag type.

aaTimeRangeEnumeration Enumeration
Specifies which time range is selected.
Enum Value Description

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

Custom LastMinute Last5Minutes Last10Minutes Last15Minutes Last30Minutes LastHour Last2Hours Last4Hours Last8Hours Last12Hours Last24Hours Last2Days LastWeek Last2Weeks LastMonth Last3Months OneMinute FiveMinutes TenMinutes FifteenMinutes ThirtyMinutes OneHour

The time duration is custom. The last minute. The last five minutes. The last ten minutes. The last fifteen minutes. The last 30 minutes. The last hour. The last two hours. The last four hours. The last eight hours. The last twelve hours. The last twenty-four hours. The last two days. The last week. The last two weeks. The last month. The last three months. One minute. Five minutes. Ten minutes. Fifteen minutes. 30 minutes. One hour.

ActiveFactory Software Users Guide

Common Enumerations

637

Enum

Value

Description

23 24 25 26 27 28 29 30 31 32 33

TwoHours FourHours EightHours TwelveHours TwentyFourHours TwoDays OneWeek TwoWeeks OneMonth ThreeMonths Yesterday

Two hours. Four hours. Eight hours. Twelve hours. Twenty-four hours. Two days. One week. Two weeks. One month. Three months. 0:00:00 of the previous day to 0:00:00 of the current day. 0:00:00 of the current day to the current time. The start of the previous hour to the start of the current hour. The start of the current hour to the current time. Only applicable in relative mode. Sets the offsets and duration so that the trend shows the same time period as it did before it was switched into relative mode.

34 35

CurrentDay PreviousHour

36 37

CurrentHour FullPeriod

ActiveFactory Software Users Guide

638

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

Common Data Types

Common data types are:

DateTime Color DataSet Font Object

DateTime
For the InTouch HMI software, use a message value in a valid date/time format. For C# and .NET applications, a DateTime parameter or result can reference a DateTime structure. For more information, see the documentation on the DateTime structure in the .NET Framework Class Library.

Color
To specify a color for a control, you must specify the color as an integer value. The color is an ABGR color, where: A = Transparency B = Blue G = Green R = Red A BGR color value is made up of 24 bits, with the upper 8 bits always being 0. For example, 0xFF0000 is 0B00 in the BGR convention, which equates to Blue. An ABGR color value is made up of 32 bits, with upper 8 bits being 0 by default, but can be set to any opacity:

00 (in HEX) in the upper 8 bits means no transparency or full opacity. FF (in HEX) in the upper 8 bits means full transparency or no opacity. B0 (in HEX) in the upper 8 bits means more transparent than opaque. 0A (in HEX) in the upper 8 bits means more opaque than transparent.

In decimal notation, the value for full transparency is 255.

ActiveFactory Software Users Guide

Common Data Types

639

For a color of Blue, the ABGR values are as follows: A = 0 (full opacity) B = 255 G=0 R=0 The hexidecimal value for this color is 0x00FF0000. The decimal value is 16711680. 0xA0FF0000 is half-transparent, half-opaque blue. The decimal value is 2701066240. 0xFFFF0000 is fully transparent blue, so you dont see it at all. The decimal value is 4294901760. 0xA0000000 is a transparent shade of black (half-transparent). The decimal value is 2684354560.

DataSet
For C# and .NET applications, a DataSet parameter or result can reference a DataSet object. For more information, see the documentation on the ADO.NET DataSet object in the .NET Framework Developer's Guide.

Font
For C# and .NET applications, a Font parameter or result can reference a Font class. For more information, see the documentation on the Font class in the .NET Framework Class Library.

Object
For C# and .NET applications, an object parameter or result can reference an Object class. For more information, see the documentation on the Object class in the .NET Framework Class Library.

ActiveFactory Software Users Guide

640

Chapter 19 Common Properties, Methods, Events, Enums, and Data Types

ActiveFactory Software Users Guide

641

Appendix A
Configuring an IIS Virtual Directory for SQL Server

To enable access to SQL Server via HTTP, you must install the SQLXML software and set up a virtual directory for ActiveFactory. The following instructions show how to set up a virtual directory on the Windows 2003 Server operating system. To define and register a new virtual directory, use the IIS Virtual Directory Management for SQL Server utility on the computer running the Microsoft Internet Information Services (IIS) software. Use this utility to associate a new virtual directory and an instance of Microsoft SQL Server.
To configure an IIS virtual directory 1

Create or determine a physical directory to use for the virtual directory. For example: c:\Inetpub\wwwroot\ActiveFactory.

ActiveFactory Software Users Guide

642

Appendix A Configuring an IIS Virtual Directory for SQL Server

On the Windows Start menu, point to Programs, point to Microsoft SQL Server, and then click Configure SQL XML Support in IIS. The IIS Virtual Directory Management for SQL Server console appears.

2 3

Expand the server name. Right-click on Default Web Site, point to New, and then click Virtual Directory. The New Virtual Directory Properties dialog box appears.

ActiveFactory Software Users Guide

643

Click the General tab.

In the Virtual Directory Name box, type the name through which ActiveFactory users access the IndustrialSQL Server historian. This name can be any name you choose, but keep in mind that it is used in the client-side configuration for the server. In the Local Path box, type the path to the physical directory that you want to use as the virtual directory. Or, click the Browse button to select an existing path.

ActiveFactory Software Users Guide

644

Appendix A Configuring an IIS Virtual Directory for SQL Server

Click the Security tab.

Select the appropriate authentication mode. For more information, see Authentication for HTTP Access on page 44. For the Always log on as option, no password is required for the client, which means security has to be managed differently. For the Use Windows Integrated Authentication option, integrated security is used, which means that the client must supply the user name, password and domain (if necessary). For the Use Basic Authentication option, a SQL Server login is used (user name and password). The IIS Server must receive these from the client and sends them to the SQL Server.

ActiveFactory Software Users Guide

645

Click the Data Source tab.

10 In the SQL Server box, type the name of the SQL Server to

use. You may be prompted to provide login information to connect to the SQL Server.
11 In the Database list, select the Runtime database.

ActiveFactory Software Users Guide

646

Appendix A Configuring an IIS Virtual Directory for SQL Server

12 Click the Settings tab.

13 Select all of the check boxes except for Allow posted updategrams (which is unavailable). 14 In the Maximum size of POST queries box, leave the default

value of 1000. If publishing is to be done through the HTTP server, then this value must be at least as high as the largest size document published. Typically, an Excel file is between 30 and 80 kilobytes.

ActiveFactory Software Users Guide

647

15 Click OK.

The new virtual directory is listed in the console window.

ActiveFactory Software Users Guide

648

Appendix A Configuring an IIS Virtual Directory for SQL Server

ActiveFactory Software Users Guide

Understanding Retrieval Modes

649

Appendix B
Understanding Data Retrieval

The ActiveFactory software supports a variety of retrieval modes and options to suit different reporting needs and applications. Additionally, the Trend application allows you to use retrieval styles that automatically switch retrieval modes based on the trend duration and tag type. This chapter explains all available retrieval modes and options and describes how to set up retrieval styles.

Understanding Retrieval Modes

Different retrieval modes allow you to access the data stored on an IndustrialSQL Server historian in different ways. For example, if you retrieve data for a long time period, you might want to retrieve only a few hundred evenly spaced data points to minimize response time. For a shorter time period, you might want to retrieve all values that are stored on the server to get more accurate results. IndustrialSQL Server historians with a version earlier than 9.0 support two retrieval modes:

Cyclic Retrieval Delta Retrieval

IndustrialSQL Server historians with a version of 9.0 or higher support various additional modes:

Full Retrieval Interpolated Retrieval Best Fit Retrieval

ActiveFactory Software Users Guide

650

Appendix B Understanding Data Retrieval

Average Retrieval Minimum Retrieval Maximum Retrieval Integral Retrieval Slope Retrieval Counter Retrieval ValueState Retrieval

The following sections explain how each of these modes works.

Cyclic Retrieval
Cyclic retrieval is the retrieval of stored data for the given time period based on a specified cyclic retrieval resolution, regardless of whether or not the value of the tag(s) has changed. It works with all types of tags. Cyclic retrieval produces a virtual rowset, which may or may not correspond to the actual data rows stored on the IndustrialSQL Server historian. In cyclic retrieval, one row is returned for each cycle boundary. You specify the number of cycles either directly or by means of a time resolution, that is, the spacing of cycle boundaries in time. If you specify a number of cycles, the IndustrialSQL Server historian returns that number of rows, evenly spaced in time over the requested period. The cyclic resolution is calculated by dividing the requested time period by the number of cycle boundaries. If you specify a resolution, the number of cycles is calculated by dividing the time period by the resolution. If no data row is actually stored at a cycle boundary, the last value before the boundary is returned.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

651

The following illustration shows how values are returned for cyclic retrieval:

Data is retrieved in cyclic mode with a start time of TC0 and an end time of TC2. The resolution has been set in such a way that the historian returns data for three cycle boundaries at TC0, TC1, and TC2. Each dot in the graphic represents an actual data point stored on the historian. From these points, the following are returned:

At TC0: P2, because it falls right on the cycle boundary At TC1: P7, because it is the last point before the cycle boundary At TC2: P11, for the same reason

Cyclic retrieval is fast and therefore consumes little server resources. However, it may not correctly reflect the stored data because important process values (gaps, spikes, etc.) might fall between cycle boundaries. For an alternative, see Best Fit Retrieval on page 655. You can use various parameters to adjust which values are returned in cyclic retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Timestamp Rule on page 680 (only on IndustrialSQL Server 9.0 and above) Row Limit on page 682

ActiveFactory Software Users Guide

652

Appendix B Understanding Data Retrieval

Delta Retrieval
Delta retrieval, or retrieval based on exception, is the retrieval of only the changed values for a tag(s) for the given time interval. That is, duplicate values are not returned. It works with all types of tags. Delta retrieval always produces a rowset comprised of only rows that are actually stored on the historian; that is, a delta query returns all of the physical rows in history for the specified tags, over the specified period, minus any duplicate values. If there is no actual data point at the start time, the last data point before the start time is returned. The following illustration shows how values are returned for delta retrieval:

Data is retrieved in delta mode with a start time of T1 and an end time of T2. Each dot in the graphic represents an actual data point stored on the historian. From these points, the following are returned:

P2, because there is no actual data point at T1 P5, P8, P9, P10, and P11, because they represent changed values during the time period

You can use various parameters to adjust which values are returned in delta retrieval mode. For more information, see the following sections:

Time Deadband on page 676 Value Deadband on page 677 History Version on page 678 Row Limit on page 682

ActiveFactory Software Users Guide

Understanding Retrieval Modes

653

Full Retrieval
In full retrieval mode, all stored data points are returned, regardless of whether a value or quality has changed since the last value. This mode allows the same value and quality pair (or NULL value) to be returned consecutively with their actual timestamps. It works with all types of tags. By using full retrieval in conjunction with storage without filtering (that is, no delta or cyclic storage mode is applied at the historian), you can retrieve all values that originated from the plant floor data source or from another application. Full retrieval best represents the process measurements recorded by the IndustrialSQL Server historian. However, it creates a higher load for the server, the network and the client system because a very large number of records may be returned for longer time periods. The following illustration shows how values are returned for full retrieval:

Data is retrieved in full mode with a start time of T1 and an end time of T2. Each dot in the graphic represents an actual data point stored on the historian. From these points, the following are returned:

P2, because there is no actual data point at T1 P3 through P12, because they represent stored data points during the time period

You can use various parameters to adjust which values are returned in full retrieval mode. For more information, see the following sections:

History Version on page 678 Row Limit on page 682

ActiveFactory Software Users Guide

654

Appendix B Understanding Data Retrieval

Interpolated Retrieval
Interpolated retrieval works like cyclic retrieval, except that interpolated values are returned if there is no actual data point stored at the cycle boundary. This retrieval mode is useful if you want to retrieve cyclic data for slow-changing tags. For a trend, interpolated retrieval results in a smoother curve instead of a "stair-stepped" curve. This mode is also useful if you have a slow-changing tag and a fast-changing tag and want to retrieve data for both. Finally, some advanced applications require more evenly spaced values than would be returned if interpolation was not applied. By default, interpolated retrieval uses the interpolation setting specified for the tag in the IndustrialSQL Server historian. This means that if a tag is set to use stair-step interpolation, interpolated retrieval gives the same results as cyclic retrieval. Interpolation is only applied to analog tags. If you retrieve data for other types of tags, stair-step interpolation is used, and the results are the same as for cyclic retrieval. Interpolated retrieval is a bit slower than cyclic retrieval. It shares the limitations of cyclic retrieval in that it may not accurately represent the stored process data. The following illustration shows how the values for an analog tag that is configured for linear interpolation are returned when using interpolated retrieval.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

655

Data is retrieved in interpolated mode with a start time of TC0 and an end time of TC2. The resolution has been set in such a way that the historian returns data for three cycle boundaries at TC0, TC1, and TC2. P1 to P12 represent actual data points stored on the historian. Of these points, eleven represent normal analog values, and one, P7, represents a NULL value due to an I/O Server disconnect, which causes a gap in the data between P7 and P8. The green points (P2, PC1, PC2) are returned. The yellow points (P7, P11, P12) are used to interpolate the returned value for each cycle. The red points are considered, but not used in calculating the points to return. Because P2 is located exactly at the query start time, it is returned at that time without the need for any interpolation. At the following cycle boundary, point PC1 is returned, which is the NULL value represented by P7 shifted forward to time TC1. At the last cycle boundary, point PC2 is returned, which has been interpolated using points P11 and P12. You can use various parameters to adjust which values are returned in interpolated retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Interpolation Type on page 678 Timestamp Rule on page 680 Quality Rule on page 682 Row Limit on page 682

Best Fit Retrieval

For the best fit retrieval mode, the total time for the query is divided into even sub-periods, and then up to five values are returned for each sub-period:

First value in the period Last value in the period Minimum value in the period, with its actual time Maximum value in the period, with its actual time The first exception in the period (non-Good quality)

ActiveFactory Software Users Guide

656

Appendix B Understanding Data Retrieval

Best fit retrieval allows for a compromise between delta retrieval and cyclic retrieval. For example, delta retrieval can accurately represent a process over a long period of time, as shown in the following trend. However, to achieve this representation, a large number of data values must be returned.

If cyclic retrieval is used to retrieve the data, the retrieval is much more efficient, because fewer values are returned. However, the representation is not as accurate, as the following trend shows.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

657

Best fit retrieval allows for faster retrieval, as typically achieved by using cyclic retrieval, plus the better representation typically achieved by using delta retrieval. This is shown in the following trend.

For example, for one week of five-second data, 120,960 values would be returned for delta retrieval, versus around 300 values for best-fit retrieval. Best-fit retrieval uses retrieval cycles, but it is not a true cyclic mode. Apart from the initial value, it only returns actual delta points. For example, if one point is both the first value and the minimum value in a cycle, it is returned only once. In a cycle where a tag has no points, nothing is returned. As in cyclic retrieval, the number of cycles is based on the specified resolution or cycle count. However, the number of values returned is likely to be more than one per cycle. The best-fit algorithm is only applied to analog tags. For all other tags, delta results are returned.

ActiveFactory Software Users Guide

658

Appendix B Understanding Data Retrieval

The following illustration shows how the best-fit algorithm selects points for an analog tag.

Data is retrieved in best-fit mode with a start time of TC0 and an end time of TC2. The resolution has been set in such a way that the historian returns data for two complete cycles starting at TC0 and TC1 and an incomplete cycle starting at TC2. P1 to P12 represent actual data points stored on the historian. Of these points, eleven represent normal analog values, and one, P7, represents a NULL value due to an I/O Server disconnect, which causes a gap in the data between P7 and P8. Because P2 is located exactly at the start time, no initial value needs to be interpolated at the start time. Therefore, point P1 is not considered at all. All other points are considered, but only the points indicated by green markers on the graph are returned. From the first cycle, four points are returned:

P2 as the initial value of the query, as well as the first value in the cycle P4 as the minimum value in the cycle P6 as both the maximum value and the last value in the cycle P7 as the first (and only) occurring exception in the cycle

From the second cycle, three points are returned:

P8 as the first value in the cycle P9 as the maximum value in the cycle P11 as both the minimum value and the last value in the cycle

ActiveFactory Software Users Guide

Understanding Retrieval Modes

659

As no exception occurs in the second cycle, none is returned.

Because the tag does not have a point exactly at the query end time, where an incomplete third cycle starts, the end value PC2 is interpolated between P11 and P12, assuming that linear interpolation is used. You can use various parameters to adjust which values are returned in best-fit retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Interpolation Type on page 678 Quality Rule on page 682 Row Limit on page 682

Average Retrieval
For the time-weighted average (in short: average) retrieval mode, a time-weighted average algorithm is used to calculate the value to be returned for each retrieval cycle. For a statistical average, the actual data values are used to calculate the average. The average is the sum of the data values divided by the number of data values. For the following data values, the statistical average is computed as: (P1 + P2 + P3 + P4) / 4) = Average

ActiveFactory Software Users Guide

660

Appendix B Understanding Data Retrieval

For a time-weighted average, values are multiplied by the time difference between the points to determine the time-weighted value. Therefore, the longer a tag had a particular value, the more weight that value holds in the overall average. The overall average is determined by adding all of the time-weighted values and then dividing that number by the total amount of time. Which values are weighted depends on the interpolation setting of the tag. For a tag that uses linear interpolation, the midpoints between values are weighted. For a tag that uses stair-step interpolation, the earlier of two values is weighted. For the following data values of a tag that uses linear interpolation, the time-weighted average is computed as: (((P1 + P2) / 2) x (T2 - T1)) + (((P2 + P3) / 2) x (T3 - T2)) + (((P3 + P4) / 2) x (T4 - T3)) / (T4 - T1) = Average

If the same tag uses stair-step interpolation, the time-weighted average is: ((P1 x (T2 - T1)) + (P2 x (T3 - T2)) + (P3 x (T4 - T3))) / (T4 - T1) = Average The SQL Server AVG aggregate is a simple statistical average. Using the average retrieval mode with a cycle count of 1 returns data much faster than the AVG aggregate, and usually more accurately due to the time weighting. Average retrieval returns one row for each tag in the query for each cycle. The number of cycles is based on the specified resolution or cycle count. The time-weighted average algorithm is only applied to analog tags. If you use average retrieval with other tags, the results are the same as when using regular cyclic retrieval.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

661

The following illustration shows how the time-weighted average is calculated for an analog tag that uses linear interpolation.

Data is retrieved in average mode with a start time of TC0 and an end time of TC2. The resolution has been set in such a way that the historian returns data for two complete cycles starting at TC0 and TC1 and an incomplete cycle starting at TC2. P1 to P9 represent actual data points stored on the historian. Of these points, eight represent normal analog values, and one, P5, represents a NULL due to an I/O Server disconnect, which causes a gap in the data between P5 and P6. Results are calculated as follows:

The initial value returned at the query start time (TC0) is the time-weighted average of the points in the last cycle preceding TC0. The value returned at TC1 is the time-weighted average of the points in the cycle starting at TC0. The value returned at the query end time (TC2) is the time-weighted average of the points in the cycle starting at TC1.

To understand how the time-weighted average is calculated, observe the last cycle as an example. First, the area under the curve must be calculated. This curve is indicated by the red line through P6, P7, P8 and PC2, where PC2 represents the interpolated value at time TC2 using points P8 and P9. The data gap caused by the I/O Server disconnect does not contribute anything to this area.

ActiveFactory Software Users Guide

662

Appendix B Understanding Data Retrieval

To understand how the area is calculated, consider points P6 and P7. The area contribution between these two points is calculated by multiplying the arithmetic average of value P6 and value P7 by the time difference between the two points. The formula is: ((P6 + P7) / 2) x (T7 - T6) When the area for the whole cycle has been calculated, the time-weighted average is calculated by dividing that area by the cycle time, less any periods within the cycle that did not contribute anything to the area calculation. The result is returned at the cycle end time. If you take a closer look at points P4 and P5 in the example, you can see that the red line through point P4 is parallel to the x-axis. This is because P5 represents a NULL, which cannot be used to calculate an arithmetic average. Instead, the value P4 is used for the whole time period between points P4 and P5. The area calculation is signed. If the arithmetic average between two points is negative, then the contribution to the area is negative. You can use various parameters to adjust which values are returned in average retrieval mode. For more information, see the following sections:

ActiveFactory Software Users Guide

Understanding Retrieval Modes

663

Minimum Retrieval
The minimum value retrieval mode returns the minimum value from the actual data values within a retrieval cycle. If there are no actual data points stored on the historian for a given cycle, nothing is returned. NULL is returned if the cycle contains one or more NULL values. As in cyclic retrieval, the number of cycles is based on the specified resolution or cycle count. However, minimum retrieval is not a true cyclic mode. Apart from the initial value, all points returned are delta points. Minimum retrieval only works with analog tags. For all other tags, normal delta results are returned. All returned values are in chronological order. If multiple points are to be returned for a particular timestamp, they are returned in the order in which the tags were specified in the query. The following illustration shows how the minimum value is selected for an analog tag.

This example has a start time of TC0 and an end time of TC2. The resolution has been set in such a way that the historian returns data for two complete cycles starting at TC0 and TC1, a phantom cycle starting at TCP, and an incomplete cycle starting at TC2. The phantom cycle has the same duration as the first cycle in the query period, extending back in time from the query start time. For the queried tag, a total of 18 points are found throughout the cycles, represented by the markers P1 through P18. Of these points, 17 represent normal analog values. The point P13 represents a NULL due to an I/O Server disconnect, which causes a gap in the data between P13 and P14.

ActiveFactory Software Users Guide

664

Appendix B Understanding Data Retrieval

The minimum value for the phantom cycle starting at TCP is returned as the initial value at TC0. Point P18 is not considered at all because it is outside of the query time frame. All other points are considered, but only the points indicated by green markers on the graph are returned (P10, P13, and P17). In total, four points are returned:

P4 as the minimum value of the phantom cycle and the initial point P10 as the minimum value in the first cycle P13 as the first and only exception occurring in the first cycle P17 as the minimum value in the second cycle

No points are returned for the incomplete third cycle starting at the query end time, because the tag does not have a point exactly at that time. If the minimum value of the first cycle is located exactly at the query start time, both this value and the minimum value of the phantom cycle are returned. You can use various parameters to adjust which values are returned in minimum retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Quality Rule on page 682 Row Limit on page 682

ActiveFactory Software Users Guide

Understanding Retrieval Modes

665

Maximum Retrieval
The maximum value retrieval mode returns the maximum value from the actual data values within a retrieval cycle. If there are no actual data points stored on the historian for a given cycle, nothing is returned. NULL is returned if the cycle contains one or more NULL values. As in cyclic retrieval, the number of cycles is based on the specified resolution or cycle count. However, maximum retrieval is not a true cyclic mode. Apart from the initial value, all points returned are delta points. Maximum retrieval only works with analog tags. For all other tags, normal delta results are returned. All returned values are in chronological order. If multiple points are to be returned for a particular timestamp, they are returned in the order in which the tags were specified in the query. The following illustration shows how the maximum value is selected for an analog tag.

ActiveFactory Software Users Guide

666

Appendix B Understanding Data Retrieval

The maximum value for the phantom cycle starting at TCP is returned as the initial value at TC0. Point P18 is not considered at all because it is outside of the query time frame. All other points are considered, but only the points indicated by green markers on the graph are returned (P12, P13, and P15). In total, four points are returned:

P6 as the maximum value of the phantom cycle and the initial point P12 as the maximum value in the first cycle P13 as the first and only exception occurring in the first cycle P15 as the maximum value in the second cycle

No points are returned for the incomplete third cycle starting at the query end time, because the tag does not have a point exactly at that time. If the maximum value of the first cycle is located exactly at the query start time, this value and the maximum value of the phantom cycle are returned. You can use various parameters to adjust which values are returned in maximum retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Quality Rule on page 682 Row Limit on page 682

Integral Retrieval
Integral retrieval calculates the values at retrieval cycle boundaries by integrating the graph described by the points stored for the tag. Therefore, it works much like average retrieval, but it additionally applies a scaling factor. For example, if one of your tags represents product flow in gallons per second, integral retrieval allows you to retrieve the total product flow in gallons during a certain time period. Integral retrieval is a true cyclic mode. It returns one row for each tag in the query for each cycle. The number of cycles is based on the specified resolution or cycle count.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

667

Integral retrieval only works with analog tags. For all other tags, normal cyclic results are returned. Calculating values for a cycle in integral retrieval is a two-step process:

First, the historian calculates the area under the graph created by the data points. This works the same as in average retrieval. For more information, see Average Retrieval on page 659. Then, the area is scaled using the Time Base of the tags Engineering Unit. The time base represents the conversion factor from the actual rate to one of units per second.

For example, if the time-weighted average for a tag during a 1-minute cycle is 3.5 liters per second, integral retrieval returns a value of 210 for that cycle (3.5 liters per second multiplied by 60 seconds). You can use various parameters to adjust which values are returned in integral retrieval mode. For more information, see the following sections:

Slope Retrieval
Slope retrieval returns the slope of a line drawn through a given point and the point immediately before it, thus expressing the rate at which values change. This retrieval mode is useful for detecting if a tag is changing at too great a rate. For example, you might have a temperature that should steadily rise and fall by a small amount, and a sharp increase or decrease could point to a potential problem. The slope retrieval mode can be considered a delta mode. Apart from the initial value and a value at the query end time, all returned points are calculated delta points returned with the timestamp of an actual delta point.

ActiveFactory Software Users Guide

668

Appendix B Understanding Data Retrieval

Slope retrieval only works with analog tags. For all other tags, normal delta results are returned. All returned values are in chronological order. If multiple points are to be returned for a particular timestamp, they are returned in the order in which the tags were specified in the query. The following illustration shows how the slope is calculated for an analog tag.

This example has a start time of TS and an end time of TE. For the queried tag, a total of nine points are found, represented by the markers P1 through P9. Of these points, eight represent normal analog values. The point P5 represents a NULL due to an I/O Server disconnect, which causes a gap in the data between P5 and P6. For every point in the time period, slope retrieval returns the slope of the line going through that point and the point immediately before it. For two points P1 and P2 occurring at times T1 and T2, the slope formula is as follows: (P2 - P1) / (T2 - T1) The difference between T1 and T2 is measured in seconds. Therefore, the return value represents the change in Engineering Units per second. In this example, point P2 is located at the query start time, and because there is a prior value (P1), the slope of the line through both points is calculated and returned at time TS. Similarly, slopes are calculated to be returned at times T3, T4, T7, and T8. The slope is also calculated for the line through P8 and P9, but that value is returned as point PTE at the query end time.

ActiveFactory Software Users Guide

Understanding Retrieval Modes

669

For point P6, there is no prior point with which to perform a slope calculation. Instead, the slope of the flat line going through the point (that is, the value 0) is calculated. At the time of P5, NULL is returned. You can use various parameters to adjust which values are returned in slope retrieval mode. For more information, see the following sections:

History Version on page 678 Quality Rule on page 682 Row Limit on page 682

Counter Retrieval
Counter retrieval allows you to accurately retrieve the delta change of a tags value over a period of time even for tags that are reset upon reaching a rollover value. This retrieval mode is useful for determining how much of an item was produced during a particular time period. For example, you might have a counter that keeps track of how many cartons were produced. The counter has an indicator like this:

The next value after the highest value that can be physically shown by the counter is called the rollover value. In this example, the rollover value is 10,000. When the counter reaches the 9,999th value, the counter rolls back to 0. Therefore, a counter value of 9,900 at one time and a value of 100 at a later time means that you have produced 200 units during that period, even though the counter value has dropped by 9,800. Counter retrieval allows you to handle this situation and receive the correct value. Counter retrieval is a true cyclic mode. It returns one row for each tag in the query for each cycle. The number of cycles is based on the specified resolution or cycle count. Counter retrieval only works with non-real analog tags and discrete tags. For all other tags, no rows are returned. For analog tags, counter retrieval uses the Rollover Value configured for the tag on the IndustrialSQL Server historian. For discrete tags, the rollover value is always assumed to be 2.

ActiveFactory Software Users Guide

670

Appendix B Understanding Data Retrieval

The following illustration shows how the counter algorithm determines the count for an analog tag.

This example has a start time of TC0 and an end time of TC3. The resolution has been set in such a way that the historian returns data for three complete cycles starting at TC0, TC1, and TC2, and an incomplete cycle starting at TC3. For the queried tag, a total of twelve points are found throughout the cycles represented by the markers P1 through P12. Of these points, eleven represent normal analog values. The point P9 represents a NULL due to an I/O Server disconnect, which causes a gap in the data between P9 and P10. Point P12 is not considered because it is outside of the query time frame. All points are considered in the counter calculation, but only the yellow ones are actually used to determine which values to return to the client. The returned points are PC0, PC1, PC2 and PC3, shown in green at the top to indicate that there is no simple relationship between them and any of the actual points. All cycle values are calculated as the delta change between the cycle time in question and the previous cycle time, taking into account the number of rollovers between the two points in time. The counter algorithm assumes that a rollover occurred if the current value is lower than the previous value. The initial value at the query start time (PC1) is calculated the same way, only based on a phantom cycle before the query start time. For example, the formula to calculate PC1 is as follows: PC1 = n * VR + P6 - P1

ActiveFactory Software Users Guide

Understanding Retrieval Modes

671

where: n = the number of rollovers that have occurred during the cycle VR = the rollover value for the tag If either n or VR are equal to zero, PC1 is simply the difference between the values P1 and P6. In the case of cycle C2, there is no value at the cycle time, so the NULL value represented by point P9 is returned. In the case of cycle C3, a NULL is again returned, because there is no counter value at the previous cycle boundary to use in the calculation. There must be a full cycle of values in order for the counter to be calculated. If a gap is fully contained inside a cycle, and if points occur within the cycle on both sides of the gap, then a counter value is returned, even though it may occasionally be erroneous. Zero or one rollovers are assumed, even though the counter might have rolled over multiple times. If you have a counter that you typically reset manually before it rolls over, you must set the rollover value for the tag to 0 so that the count is simply how much change occurred since the manual reset. For example, assume that you have the following data values for five consecutive cycle boundaries, and that the value 0 occurs as the first value within the last cycle: 100, 110, 117, 123, 3 If you set the rollover value to 0, the counter retrieval mode assumes that the 0 following the value 123 represents a manual reset, and returns a value of 3 for the last cycle, which is assumed to be the count after the manual reset. The value 0 itself does not contribute 1 to the counter value in this case. If the rollover value is instead set to 200, then the counter retrieval mode assumes that the value 0 represents a normal rollover, and a count of 80 is calculated and returned (200 123 + 3). In this case, the value 0 contributes 1 to the counter value, and that is the change from the value 199 to the value 200. You can use various parameters to adjust which values are returned in integral retrieval mode. For more information, see the following sections:

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675

ActiveFactory Software Users Guide

672

Appendix B Understanding Data Retrieval

History Version on page 678 Timestamp Rule on page 680 Quality Rule on page 682 Row Limit on page 682

ValueState Retrieval
ValueState retrieval returns information on how long a tag has been in a particular value state during each retrieval cycle. That is, a time-in-state calculation is applied to the tag value. This retrieval mode is useful for determining how long a machine has been running or stopped, how much time a process spent in a particular state, how long a valve has been open or closed, and so on. For example, you might have a steam valve that releases steam into a reactor, and you want to know the average amount of time the valve was in the open position during the last hour. ValueState retrieval can return the shortest, longest, average, or total time a tag spent in a state, or the time spent in a state as a percentage of the total cycle length. When you use ValueState retrieval for a tag in the Trend application, you must specify a single value state for which to retrieve information. ValueState retrieval then returns one value for each cyclefor example, the total amount of time that the valve was in the open state during each 1-hour cycle. This information is suitable for trend display. If you dont specify a state, ValueState retrieval returns one row of information for each value that the tag was in during each cycle. For example, this would return not only the time a valve was in the open state, but also the time it was in the closed state. This information is not suitable for meaningful display in a regular trend. You can, however, retrieve this type of information in the Query application and view it as a table. ValueState retrieval only works with integer, discrete, and string tags. For other types of tags, no rows are returned. NULL values are treated like any other distinct state. The values returned at the query start time are the result of applying the algorithm to a phantom cycle preceding the query range. It is assumed that the tag value at the start of the cycle is located at that point in time. You can use various parameters to adjust which values are returned in ValueState retrieval mode. For more information, see the following sections:

ActiveFactory Software Users Guide

Understanding Retrieval Options

673

Cycle Count (X Values over Equal Time Intervals) on page 674 Resolution (Values Spaced Every X ms) on page 675 History Version on page 678 Timestamp Rule on page 680 Quality Rule on page 682 Row Limit on page 682 State Calculation on page 683 State on page 684

Understanding Retrieval Options

In all retrieval modes, you can adjust which values the historian returns by specifying retrieval options. This section explains each of these options. For an overview of which options apply to which retrieval modes, see Which Options Apply to Which Retrieval Modes?.

Which Options Apply to Which Retrieval Modes?

The following table shows which retrieval options apply to which modes. If you specify an option in a mode where it isnt applicable, the option is ignored.
Cycle Count (X Values over Equal Time Intervals) Resolution (Values Spaced Every X ms)

Interpolation Type

State Calculation

Timestamp Rule

Value Deadband

Time Deadband

History Version

Quality Rule

Row Limit

Cyclic Retrieval Delta Retrieval Full Retrieval Interpolated Retrieval Best Fit Retrieval

ActiveFactory Software Users Guide

State

674

Appendix B Understanding Data Retrieval

Cycle Count (X Values over Equal Time Intervals)

Resolution (Values Spaced Every X ms)

Interpolation Type

State Calculation

Timestamp Rule

Value Deadband

Time Deadband

History Version

Quality Rule

Row Limit

Average Retrieval Minimum Retrieval Maximum Retrieval Integral Retrieval Slope Retrieval Counter Retrieval ValueState Retrieval

* (only on IndustrialSQL Server 9.0 and above)

Cycle Count (X Values over Equal Time Intervals)

In retrieval modes that use cycles, the cycle count determines the number of cycles for which data is retrieved. The number of actual return values is not always identical with this cycle count. In truly cyclic modes (Cyclic, Interpolated, Average, and Integral), a single data point is returned for every cycle boundary. However, in other cycle-based modes (Best Fit, Minimum, Maximum, Counter, and ValueState), multiple or no data points may be returned for a cycle, depending on the nature of the data. The length of each cycle (the resolution of the returned values) is calculated as follows: DC = DQ / (n 1) Where DC is the length of the cycle, DQ is the duration of the query, and n is the cycle count. Instead of specifying a cycle count, you can specify the resolution. In that case, the cycle count is calculated based on the resolution and the query duration. For more information, see Resolution (Values Spaced Every X ms).

ActiveFactory Software Users Guide

State

Understanding Retrieval Options

675

In the Trend application, you can choose to have the cycle count determined automatically based on the chart width. In this case, the cycle count is:

One cycle for every 15 pixels when using Best Fit, Minimum, Maximum, Counter, or ValueState retrieval One cycle for every pixel when using other cyclic modes

This option is relevant in the following retrieval modes:

Cyclic Retrieval Interpolated Retrieval Best Fit Retrieval Average Retrieval Minimum Retrieval Maximum Retrieval Integral Retrieval Counter Retrieval ValueState Retrieval

Resolution (Values Spaced Every X ms)

In retrieval modes that use cycles, the resolution is the sampling interval for retrieving data, that is, the length of each cycle. The number of cycles, therefore, depends on the time period and the resolution: number of cycles = time period / resolution The number of actual return values is not always identical with this cycle count. In truly cyclic modes (Cyclic, Interpolated, Average, and Integral), a single data point is returned for every cycle boundary. However, in other cycle-based modes (Best Fit, Minimum, Maximum, Counter, and ValueState), multiple or no data points may be returned for a cycle, depending on the nature of the data. Instead of specifying a resolution, you can specify the cycle count directly. In that case, the resolution is calculated based on the cycle count and the query duration. For more information, see Cycle Count (X Values over Equal Time Intervals) on page 674. This option is relevant in the following retrieval modes:

Cyclic Retrieval

ActiveFactory Software Users Guide

676

Appendix B Understanding Data Retrieval

Interpolated Retrieval Best Fit Retrieval Average Retrieval Minimum Retrieval Maximum Retrieval Integral Retrieval Counter Retrieval ValueState Retrieval

For delta retrieval, you can achieve similar results by using a time deadband. For more information, see Time Deadband.

Time Deadband
A time deadband for retrieval controls the time resolution of data returned in delta mode. Any value changes that occur within the time deadband are not returned. Time deadbands can be applied to analog, discrete, and string tags. The deadband base value is reset each time that a value is returned, so that the last value returned acts as the basis for the deadband. The following illustration shows an example of applying a time deadband:

ActiveFactory Software Users Guide

Understanding Retrieval Options

677

Data is retrieved for the time period starting with TS and ending with TE. All points in the graphic represent data values stored on the historian. The grey areas represent the time deadband, which starts anew with every returned value. Only the green points (P2, P4, P7, P8, P9, P11) are returned. The other points are not returned because they fall within a deadband.

Value Deadband
A value deadband for retrieval controls the value resolution of data returned in delta mode. Any data values that change less than the specified deadband are not returned. The deadband is a percentage of a tags full scale in engineering units. The deadband base value is reset each time that a value is returned, so that the last value returned acts as the basis for the deadband. The following illustration shows an example of applying a value deadband:

Data is retrieved for the time period starting with TS and ending with TE. All points in the graphic represent data values stored on the historian. The grey areas represent the value deadband, which starts anew with every returned value. Only the green points (P2, P5, P6, P7, P9, P10, P11) are returned. The other points are not returned because they fall within a deadband.

ActiveFactory Software Users Guide

678

Appendix B Understanding Data Retrieval

History Version
The IndustrialSQL Server historian allows you to overwrite a stored tag value with later versions of the value. The original version of the value is still maintained, so that effectively, multiple versions of the tag value exist at the same point in time. When retrieving data, you can specify whether to retrieve the originally stored version or the latest version that is available. To do this, set the History Version option to Original for the original version or Latest for the latest available version. To distinguish between a latest value and an original value, the historian returns a special QualityDetail value of 202 for a latest point with good quality. This option is relevant in all retrieval modes.

Interpolation Type
For various retrieval modes, you can set the Interpolation Type option to control how analog tag values at cycle boundaries are calculated if there is no actual value stored at that point in time. The options are as follows:
Stairstep: No interpolation occurs. The value at the cycle

boundary is assumed to be the same value as the last stored value before the cycle boundary.

ActiveFactory Software Users Guide

Understanding Retrieval Options

679

Linear: The historian calculates a new value at the cycle boundary by interpolating between the last stored value before the boundary and the first stored value after the boundary. If either of these values is NULL, it returns the last stored value before the boundary.

Expressed as a formula, Vc is calculated as: Vc = V1 + ((V2 - V1) * ((Tc - T1) / (T2 - T1)))

Tag setting: For each tag in the query, the historian uses

the interpolation type configured in the tags properties. The type of data that you want to retrieve usually determines the interpolation type to use. For example, if you have a thermocouple, the temperature change is linear, so its best to use linear interpolation. If you have a tag that contains discrete measurements, such as a set point, then you probably want to use stair-stepped values. In general, it is recommended that you use linear interpolation as the general setting, and use stair-stepped values for the exceptions. This option is relevant in the following retrieval modes:

Interpolated Retrieval Best Fit Retrieval Average Retrieval Integral Retrieval

ActiveFactory Software Users Guide

680

Appendix B Understanding Data Retrieval

Timestamp Rule
For various cycle-based retrieval modes, you can set the Time stamp option to control whether the returned values are timestamped at the beginning or at the end of each cycle. The options are as follows:
Start: The value for a given cycle is stamped with the cycle start time. For example, in the following illustration of a cyclic query, the following values are returned at the cycle boundaries:

At TC0: P7, because it falls on the cycle boundary. In cyclic mode, if there is a value right on the cycle boundary, it is considered to belong to the cycle before the boundary. In this case, this is the cycle starting at TC0 and ending at TC1, and because the Start timestamp rule is used, the value is timestamped at TC0. At TC1: P11, because it is the last value in the cycle starting at TC1 and ending at TC2 At TC2: The last value in the phantom cycle starting at TC2

End: The value for a given cycle is stamped with the cycle

end time. For example, in the following illustration of a cyclic query, the following values are returned at the cycle boundaries:

At TC0: P1, because it is the last value in the phantom cycle ending at TC0. Because the End timestamp rule is used, the value is timestamped at TC0.

ActiveFactory Software Users Guide

Understanding Retrieval Options

681

At TC1: P7, because it falls on the cycle boundary. In cyclic mode, if there is a value right on the cycle boundary, it is considered to belong to the cycle before the boundary. In this case, this is the cycle starting at TC0 and ending at TC1, and because the End timestamp rule is used, the value is timestamped at TC1. At TC2: P11, because it is the last value in the cycle ending at TC2

Server default: Either Start or End is used, depending on the system parameter setting on the IndustrialSQL Server historian.

This option is relevant in the following retrieval modes:

Cyclic Retrieval (only on IndustrialSQL Server 9.0 and above) Interpolated Retrieval Average Retrieval Integral Retrieval Counter Retrieval ValueState Retrieval

ActiveFactory Software Users Guide

682

Appendix B Understanding Data Retrieval

Quality Rule
For various retrieval modes, you can set the Quality option to explicitly exclude values with doubtful quality from data retrieval in modes that calculate return values. The options are as follows:
Good: Data values with doubtful OPC quality are

excluded from retrieval calculations.

Extended: Data values with doubtful OPC quality are

included in the retrieval calculations.

Server default: Either Good or Extended is used,

depending on the default setting on the IndustrialSQL Server historian. This option is relevant in the following retrieval modes:

Interpolated Retrieval Best Fit Retrieval Average Retrieval Minimum Retrieval Maximum Retrieval Integral Retrieval Slope Retrieval Counter Retrieval ValueState Retrieval

Row Limit
You can specify a row limit for data retrieval to avoid excessively large result sets. For example, if you set a row limit of 200, the historian only returns the first 200 rows of a querys results. The row limit applies to each query. In the Trend application, multiple queries may be used for the tags in a trend depending on the tags configuration. Therefore, the total number of rows retrieved may be higher than the row limit you configured in the application options. For example, assume the following scenario:

The row limit in the application options is set to 200. There are five tags in the trend. Four of them use the application options, but one of them is separately configured for a row limit of 100.

ActiveFactory Software Users Guide

Understanding Retrieval Options

683

In this case, the four tags that use the application options are combined in a single query, but a separate query is created for the tag with the custom row limit. Therefore, you may receive up to 300 rows for all tags combined. This option is relevant in all retrieval modes.

State Calculation
In ValueState retrieval, you can choose which type of time-in-state information to return for a tag by setting the State calculation option:
Minimum: The shortest amount of time that the tag has been in each unique state. Maximum: The longest amount of time that the tag has

been in each unique state.

Average: The average amount of time that the tag has

been in each unique state.

Total: The total amount of time that the tag has been in

each unique state.

Percent: The total percentage of time that the tag has been in each unique state.

All results except Percent are in milliseconds. Percent is a percentage between 0.0 and 100.0. The calculations apply to each unique value state that the tag was in during each retrieval cycle for the query. The total and percent calculations are always exact, but the minimum, maximum, and average calculations are subject to arbitrary cycle boundaries that do not coincide with the value changes. Therefore, non-intuitive results may be returned. This is most apparent for slowly-changing tags queried over long cycles. For example, a string tag that assumes only two distinct values changing every 10 minutes is queried with a cycle time of two hours. Going into a cycle, the value (state) at the cycle boundary is recorded. If the value then changes a short while into the cycle, the state found at the cycle start time will most likely end up being the minimum value. Likewise, the state at the cycle end time is cut short at the cycle end time. The two cut-off occurrences in turn skew the average calculation.

ActiveFactory Software Users Guide

684

Appendix B Understanding Data Retrieval

State
In ValueState retrieval, you can select a specific value state of a tag for which to return time-in-state information. For example, you can retrieve time-in-state information only for the On state of a tag instead of for all possible states. To specify the state, enter it in the State box.

Working with Retrieval Styles

The Trend application allows you to use retrieval styles that automatically switch retrieval modes for trend tags based on the trend duration and/or tag type. For example, you could configure a style that uses delta retrieval for short time periods and best-fit retrieval for longer periods. This helps you to balance response speed and accuracy. Also, retrieval styles allow you to calculate moving averages and retrieve data from the IndustrialSQL Server historians summary tables. Retrieval styles cover the following retrieval options:

Retrieval mode Resolution for cycle-based modes (as time duration or number of pixels per cycle) Data retrieval source (history or summary tables) Moving average calculation State calculation for ValueState retrieval

If you want to use additional retrieval options, such as deadbands, row limits or a quality rule, you must specify them in the Trend application at the application and/or tag level. For more information, see Configuring Retrieval Options on page 120 and Configuring Retrieval Options for a Tag on page 75. You can use retrieval styles at the application and/or tag level. When you specify a retrieval style at the application level, that style is used for all tags that dont have a different style specified. The Trend application comes with various predefined styles that you can use. For a description of each style, see Using the Standard Retrieval Styles on page 692. Alternatively, you can define your own retrieval styles to suit your needs. For more information, see Location and Structure of Retrieval Styles on page 685 and Creating and Editing Retrieval Styles on page 687.

ActiveFactory Software Users Guide

Working with Retrieval Styles

685

Location and Structure of Retrieval Styles

Retrieval styles are stored at the application level in the following XML file: C:\<Documents and Settings>\All Users\Application Data\ArchestrA\ActiveFactory\Trend\RetrievalStyles.xml Once you add or edit a style in this file, it is available to all users of the Trend application on the system. You can edit the file in any text or XML editor. Note the following requirements:

You must save the file in UTF-8 encoding. Names and values are case-sensitive. If any name or value is misspelt, the Trend application may hang on startup.

Structure of the Retrieval Styles File

The retrieval styles file has the following structure:
XML header Style collection

Retrieval style 1
Style names for different locales Duration range 1 Retrieval type 1 ... Retrieval type n Duration range 2 ... Duration range n

Retrieval style 2 ... Retrieval style n

End of style collection

That is:

The file contains exactly one style collection, represented by the styleCollection XML element. For more information, see styleCollection XML Element on page 687. The style collection contains one or more retrieval styles, represented by the retrievalStyle XML element. Each of these represents a style that is available for use in the Trend application. For more information, see retrievalStyle XML Element on page 688.

ActiveFactory Software Users Guide

686

Appendix B Understanding Data Retrieval

Each retrieval style contains one or more duration ranges, represented by the duration XML element. A duration range defines the retrieval types that are to be used for trend queries whose duration is within a specified range. Duration ranges should be arranged in descending length. For more information, see duration XML Element on page 689. Each duration range contains one or more retrieval types, represented by the retrieval XML element. The retrieval type defines the retrieval options that are to be used for tags of a certain type. For more information, see retrieval XML Element on page 690.

The retrieval type that gets used for a given tag is determined as follows:
1 2

You select a retrieval style in the Trend application. The Trend application searches that retrieval style for a duration range that covers the duration of your trend. This would be the first duration range with a time period that is shorter than the trend duration.

When it has found a suitable duration range, it searches that duration range for a retrieval type that suits the type of the tag. A simple example file might look like this:
3
<?xml version="1.0" encoding="utf-8" ?> <styleCollection version="9.2" xmlns="urn:retrievalstyle-schema"> <retrievalStyle server="InSQL" minVersion="8.0" maxVersion="9.0" enabled="true"> <styleName locale="en">My style</styleName> <styleName locale="ja">My style in Japanese</styleName> <styleName locale="zh-CN">My style in Chinese</styleName> <styleName locale="de">My style in German</styleName> <styleName locale="fr">My style in French</styleName> <duration minSpan="P0Y0M1DT0H0M0S"> <retrieval tagType="Discrete" source="History" retrievalMode="Delta" stateCalc="*" resolution="0" pixels="0" movingAverageValues="0" /> <retrieval tagType="All" source="History" retrievalMode="Cyclic" stateCalc="*" resolution="0" pixels="5" movingAverageValues="0" /> </duration> <duration minSpan="P0Y0M0DT0H0M0S"> <retrieval tagType="All" source="History" retrievalMode="Delta" stateCalc="*" resolution="0" pixels="0" movingAverageValues="0" /> </duration> </retrievalStyle> </styleCollection>

ActiveFactory Software Users Guide

Working with Retrieval Styles

687

In this case, the file only defines one style named My style. When querying two days of data for a discrete tag using this style, delta retrieval is used (the first retrieval element in the first duration element). For an analog tag, cyclic retrieval with one cycle for every five pixels of the trend width is used instead (the second retrieval element in the first duration element). For queries that are shorter than one day, delta retrieval is used regardless of the tag type (the only retrieval element in the second duration element).

Creating and Editing Retrieval Styles

To create or edit retrieval styles, you edit the retrieval styles file in a text or XML editor. Read Location and Structure of Retrieval Styles on page 685 first to get an overview of how this file is structured. The following procedure gives you the basic steps to add a new style. For details on each XML element, refer to the corresponding subsection.
To create a new style 1 2

Under the styleCollection element, add a retrievalStyle element. Under the retrievalStyle element, add a styleName elements for each locale in which you want to use the style. For more information, see retrievalStyle XML Element on page 688. Decide at which trend durations you want to switch retrieval options. Under your retrievalStyle element, add duration elements for each of these switching points. For more information, see duration XML Element on page 689. For each duration element, add retrieval elements as needed to define retrieval types. For more information, see retrieval XML Element on page 690.

Retrieval Style XML Elements

The following sections describe each of the XML elements in the retrieval styles file. For information on how they fit together, see Location and Structure of Retrieval Styles on page 685.

styleCollection XML Element

The styleCollection element represents a collection of retrieval styles. It is the container for multiple retrieval styles represented by retrievalStyle elements. It has two required attributes:

ActiveFactory Software Users Guide

688

Appendix B Understanding Data Retrieval

version: Specifies the format version of the style collection. The only valid value is 9.2. xmlns: Specifies the XML namespace to be used. Set this attribute to urn:retrievalstyle-schema.

The retrieval styles file can only contain a single styleCollection element.

retrievalStyle XML Element

The retrievalStyle element represents a single retrieval style. It is the container for two other elements:
styleName: Specifies the name of the style for the locale specified by the locale attribute. This is the name by which you can access the style when the Trend application runs under the specified locale.

You can specify the locale as just a two-character ISO language code or a four-character combination of language code and country code. If you specify a name for a two-character locale, it is used for all sub-locales that dont have a separate name defined. For example, if you specify a name for the de locale, it is used for the de-DE, de-AT and de-CH locales unless you specify separate names for those locales. You must specify a styleName element for all styles that you want to use in a given locale. If a style doesnt have a name defined for a locale, the Trend application doesnt show it when running under that locale. The only exception is when you run the Trend application under a locale for which no style names are defined at all. In that case, the styles are shown with their names for the en locale.
duration: Specifies a duration range. For more

information, see duration XML Element.

It has three required attributes:

server: Specifies the server type for which the style can be used. Always set this attribute to InSQL. minVersion: The minimum IndustrialSQL Server version that the retrieval style can work with, either 8.0 or 9.0. If the Trend application is connected to an IndustrialSQL Server historian whose version is lower than the version specified here, the style is not used.

Specify 9.0 if your style uses functionality that is not supported in IndustrialSQL Server 8.0.
enabled: Specifies whether the style is active. To

temporarily disable the style, set this attribute to false.

ActiveFactory Software Users Guide

Working with Retrieval Styles

689

It has one optional attribute:

maxVersion: The maximum IndustrialSQL Server version against which the retrieval style can be used. This attribute is not currently used.

duration XML Element

The duration element represents a duration range. It contains the retrieval types that are used when the trend period is longer than the time period it specifies. A retrieval style can contain any number of duration elements. However, you should arrange these elements in descending length. This is because the Trend application uses the first suitable duration range that it finds, that is, the first duration range with a time period shorter than the current trend period. For example, assume you have three duration ranges defined in the following order:

1 day 4 hours 0 seconds

For a query with a duration of 2 days, the Trend application uses the retrieval types defined for the 1 day duration range because it is the first range whose time period is shorter than 2 days. Now assume the same duration ranges are ordered like this:

4 hours 1 day 0 seconds

In this case, the Trend application uses the retrieval types defined for the 4 hours duration range because again, it is the first range whose time period is shorter than 2 days. The more suitable 1 day duration range is ignored.
Note You should always define a duration range with a time period of 0 seconds. This serves as a catch-all for trend periods that arent covered by any other duration range.

The duration element has one required attribute:

ActiveFactory Software Users Guide

690

Appendix B Understanding Data Retrieval

minSpan: Specifies the time period as a standard XML duration value, for example, P0Y0M1DT0H0M0S. The number to the left of Y represents the number of years, the number to the left of M represents the number of months, and so on (D = days, H = hours, M = minutes, S = seconds). P and T are separator characters.

It is the container for one other element:

retrieval: Specifies a retrieval type. For more information, see retrieval XML Element.

retrieval XML Element

The retrieval element represents a retrieval type, that is, a set of retrieval options for a certain type of tag. You can have multiple retrieval elements in a duration range. However, you should order them from the most specific to the least specific one. This is because the Trend application uses the first suitable retrieval type that it finds, that is, the first retrieval type with a matching tag type and available history source. For example, assume that you have three retrieval types defined in the following order:

Analog tags, Summary data Analog tags, History data All tags, History data

For an analog tag, the Trend application first tries to retrieve summary data according to the first retrieval type. If no summary data is available, it retrieves history data according to the second retrieval type. Now assume the retrieval types are ordered like this:

Analog tags, History data Analog tags, Summary data All tags, History data

In this case, the Trend application never tries to retrieve summary data for an analog tag; it never considers the second retrieval type because it has already found a suitable retrieval type in the first one.
Note You should always define a retrieval type with a tag type of All and a history source of History. This serves as a catch-all for tags that arent covered by any other retrieval style.

The retrieval element has seven required attributes:

ActiveFactory Software Users Guide

Working with Retrieval Styles

691

tagType: Specifies the tag type for which the retrieval type should be used. Valid values are All, Analog, Discrete and String. source: Specifies the history source from which to retrieve data. Valid values are History to retrieve data from history tables and Summary to retrieve data from summary tables. When using Summary, you must specify the summary frequency in the resolution attribute. retrievalMode: Specifies which retrieval mode to use. Valid values are Cyclic, Delta, Full, Interpolated, BestFit, Average, Min, Max, Integral, Slope, Counter and ValueState. Make sure that you specify a retrieval mode that is supported for the specified tag type. For example, Counter retrieval doesnt work with string tags. Therefore, if you try to retrieve data for a string tag in Counter mode, the IndustrialSQL Server historian doesnt return any data.

For information on each mode, see Understanding Retrieval Modes on page 649.
stateCalc: Specifies which state calculation to use in ValueState retrieval. Valid values are Min, Max, Average, Total, and Percent. For more information, see State Calculation on page 683. If you are not using ValueState retrieval, specify an asterisk (*). resolution: Specifies the retrieval resolution in milliseconds when retrieving history data in cycle-based retrieval modes, or the summary frequency in seconds when retrieving summary data. For more information, see Resolution (Values Spaced Every X ms) on page 675.

Alternatively, you can set this attribute to 0 and specify a retrieval resolution using the pixels attribute.

retrieval modes as the number of pixels per cycle. The number of cycles is the width of the trend chart divided by the value of this attribute. For example, if the chart is 500 pixels wide and the pixels attribute is set to 5, then 100 cycles are used. Alternatively, you can set this attribute to 0 and specify a retrieval resolution using the resolution attribute. If you specify non-zero values for both the pixels and the resolution attributes, resolution takes precedence.

pixels: Specifies the retrieval resolution for cycle-based

ActiveFactory Software Users Guide

692

Appendix B Understanding Data Retrieval

movingAverageValues: Specifies whether to calculate

moving averages when retrieving history data. If set to 0, no moving averages are calculated. Otherwise, moving averages are calculated using the number of values specified in this attribute.

Using the Standard Retrieval Styles

The following table describes the standard retrieval styles available in the ActiveFactory Trend application.
Style name Description

BestFit-5 BestFit-10 BestFit-15 Cyclic (ActiveFactory 9.1) Integral (ad hoc)

Best Fit retrieval with one cycle per five pixels. Best Fit retrieval with one cycle per ten pixels. Best Fit retrieval with one cycle per 15 pixels. Cyclic retrieval with one cycle per two pixels. Integral retrieval for queries longer than 15 minutes. Resolution depends on query duration. Best-fit retrieval with one cycle per ten pixels for queries shorter than 15 minutes. Tries to retrieve analog averages from summary tables. If no summary data is available, uses Average retrieval for analog tags and ValueState retrieval for discrete tags. Resolution depends on query duration. Average retrieval for analog tags and ValueState retrieval for discrete tags. Resolution depends on query duration. Tries to retrieve analog averages from summary tables for queries longer than 15 minutes. If no summary data is available, uses Cyclic retrieval with one cycle per pixel for queries longer than 8 hours and Delta retrieval for shorter queries. Counter retrieval with one cycle per 20 pixels. Counter retrieval with cycles at even time periods (one minute, one hour, etc. depending on the resolution). ValueState retrieval with percent calculation for queries longer than one minute. Resolution depends on query duration. Full retrieval for shorter queries.

Averages (From Summaries or Ad Hoc)

Averages (ad hoc)

Summary (InSQL 8.0)

Counter-20 Counter on round periods

Time In State (percent)

ActiveFactory Software Users Guide

Understanding Relations between Retrieval Styles, Application Settings and Tag Settings

Style name

Description

Time In State (Avg)

ValueState retrieval with average calculation for queries longer than one minute. Resolution depends on query duration. Full retrieval for shorter queries. Moving averages for analog tags with 12 values and a resolution of five seconds. Delta retrieval for all other tags. Moving averages for analog tags with 30 values and a resolution of one second. Delta retrieval for all other tags. Moving averages for analog tags with 10 values and a resolution of one cycle per pixel. Delta retrieval for all other tags.

MovingAverage (12-5 sec)

MovingAverage (30-1 sec)

MovingAverage (10-1 pixel)

Understanding Relations between Retrieval Styles, Application Settings and Tag Settings
There are various ways to set retrieval options in the Trend application: using a retrieval style vs. using custom retrieval options, using the application-wide options vs. using tag-level options. Also, there are some differences depending on which IndustrialSQL Server version you are using. The following guidelines help you understand which retrieval settings are actually used in a given situation.
1

Settings at the tag level override settings at the application level. For the aaHistClientTrend control, this means that the properties starting with CurrentTag... override the properties starting with
RetrievalOptions...

Because a retrieval style definition can contain multiple sets of retrieval settings with different retrieval modes, some of the settings available for editing at the application or tag level may turn out to be irrelevant for the retrieval mode that actually gets used for a given query. However, because there is no way to know in advance which retrieval mode will be used, the settings are still available for editing. The same applies to properties in the aaHistClientTrend control.

ActiveFactory Software Users Guide

694

Appendix B Understanding Data Retrieval

At the application level, you can specify additional options for retrieving data from IndustrialSQL Server historians with a version earlier than 9.0. For more information, see Configuring Other Options on page 126. These settings override any style that you may have selected at the application level. For example, if you have set these options to enable delta retrieval for periods below 15 minutes, but you have selected a style at the application level that specifies cyclic retrieval for all time periods, the Trend application enforces delta retrieval for all time periods below 15 minutes regardless of the settings in the style. However, if you select the style at the tag level, then the style settings override the application options. In the above example, cyclic retrieval would be used for all time periods regardless of the application settings specifying delta retrieval.

If there is a conflict between a setting specified in a style and a setting specified using one of the aaHistClientTrend controls properties (for example, retrieval resolution), the style setting overrides the property setting.

ActiveFactory Software Users Guide

695

Appendix C
Control and Object Migration Reference

This appendix provides acomparison between the main controls and objects used in different versions of the ActiveFactory software. Migration notes are also included.

ActiveFactory Version Comparison: Overview

The following table provides a comparison between the main controls and objects used in different versions of the ActiveFactory software.
ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Changes for 9.2

iTrend

aaHistClientTrend

All of the previous properties, methods and events are included. New properties, methods, and events are included that either provide additional functionality or provide a more efficient means for the same functionality. For more information, see iTrend and aaHistClientTrend Comparison on page 699.

ActiveFactory Software Users Guide

696

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Changes for 9.2

iQuery

aaHistClientQuery

All of the previous properties, methods and events are included. New properties, methods, and events are included that either provide additional functionality or provide a more efficient means for the same functionality. For more information, see iQuery and aaHistClientQuery Control Comparison on page 703.

TimeBar

aaHistClientTimeRange Picker

Slight changes. For more information, see TimeBar and aaHistClientTimeRangePicker Comparison on page 704. Slight changes. For more information, see TagPicker and aaHistClientTagPicker Comparison on page 705.

TagPicker

aaHistClientTagPicker

ActiveDataGrid

aaHistClientActiveData Grid

All previous properties, methods, and events are exactly the same. Some new properties have been added. For more information, see ActiveDataGrid and aaHistClientActiveDataGrid Comparison on page 709.

SingleValueEntry

aaHistClientSingleValue Entry

Slight changes. For more information, see SingleValueEntry and aaHistClientSingleValueEntry Comparison on page 708. Slight changes. For more information, see Server and aaServer Object Comparison on page 709.

Server

aaServer

ActiveFactory Software Users Guide

Migrating an ActiveFactory 8.5 Application

697

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Changes for 9.2

Servers

aaServers

Slight changes. For more information, see Server and aaServer Object Comparison on page 709.

Tag

aaTag

Slight changes. For more information, see Tag and aaTag Object Comparison on page 711.

Tags TimeSelector ServerTester GlobalFunctions WorkbookRunner ReportRunner ManualDataEntry dbAlias ActiveTagBrowser ActiveTimeSelector

(no equivalent) (no equivalent) (no equivalent) aaHistClientGlobalFunc tions aaHistClientWorkbookR unner aaHistClientReportRun ner (no equivalent) (no equivalent) (no equivalent) (no equivalent)

Functionality is provided by the aaTag object. N/A The server configuration is tested when a log on is initiated. N/A No changes. Properties, methods, and events are exactly the same. No changes. Properties, methods, and events are exactly the same. N/A N/A N/A N/A

Migrating an ActiveFactory 8.5 Application

To migrate an ActiveFactory 8.5 application in the InTouch HMI software for use with the ActiveFactory 9.2 controls, you must do the following:

The controls do not show up immediately in WindowMaker. If you repaint the window, the controls appear. Open and save all of the InTouch windows containing ActiveFactory controls one time in WindowMaker before running the windows in WindowViewer, so that the controls display properly at runtime.

ActiveFactory Software Users Guide

698

Appendix C Control and Object Migration Reference

If you assigned any properties to tagnames for a control using the control Properties dialog box, you must recreate the assignments. For the ActiveDataGrid control, if you configured connection settings or SQL statements using the ActiveDataGrid Properties dialog box in ActiveFactory 8.5 software, you must instead configure this information using scripts or tagname assignments. The ActiveFactory 9.x software does not provide custom tabs in the ActiveDataGrid Properties dialog box for this information. The aaHistClientTimeRangePicker and aaHistClientTagPicker controls do not have the same signatures in their properties, methods, and events as in the ActiveFactory 8.5 software. You must modify your application accordingly. When an ActiveFactory 9.x client application or control connects to an IndustrialSQL Server historian, it validates the presence of required ActiveFactory support in the Runtime database (for example, stored procedures and tables). If the supporting entities are not found, a login dialog box appears so that you can provide an administrative login in order that the required support can be automatically configured. After this initial setup is complete, no further action is required. If your existing InTouch application uses an ActiveFactory control that only uses a user login (for example, through a script), and the ActiveFactory 9.x server-side support has not yet been configured for the historian database, it is possible that no administrative logon prompt appears after you migrate the application to the ActiveFactory 9.x version. Therefore, make sure that you have logged into the IndustrialSQL Server historian at least one time as administrator using one of the ActiveFactory applications, such as ActiveFactory Trend.

Existing .CRV files cannot be opened with the aaHistClientTrend control. You must import any .CRV files into the ActiveFactory Trend application and then save them as .aaTrend files. For more information, see Importing .CRV Data on page 160. Then, change the references for the .CRV files in the application to the appropriate aaTrend files. You must change references to
uisupport.globalfunctions to ArchestrA.HistClient.Util.aaHistClientGlobalFu nctions.

ActiveFactory Software Users Guide

iTrend and aaHistClientTrend Comparison

699

iTrend and aaHistClientTrend Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 iTrend control and the aaHistClientTrend control. The tables only list differences related to functionality present in version 8.5. Unless otherwise noted, properties, methods and events work the same way as before. You must reconfigure the servers for the aaHistClientTrend control; the aaHistClientTrend control does not automatically use the servers as specified by the iTrend control.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

ApplyRubberBandToAll Tags BackGradient BackGradientEndColor BackImage BorderStyle BorderWidth CyclicRows

This is the same as the RubberBandAll property in version 8.5.

-----CyclicRows

When retrieving data from an IndustrialSQL Server 8.0 historian, a fixed algorithm controls how many rows are returned. Typically, it is the width of the plot area of the chart. For an IndustrialSQL Server 9.0 historian, use retrieval styles instead.

DatePickerFormatStrin g

DatePickerFormatString

Can also be configured using a method in the aaHistClientTimeRangePick er control.

ActiveFactory Software Users Guide

700

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

EnableDeltaRetrieval

Only relevant when retrieving data from an IndustrialSQL Server 8.0 historian. For an IndustrialSQL Server 9.0 historian, use retrieval styles instead. Present, but ignored. Use retrieval styles instead.

EnableSummaryData ---

EnableSummaryData HistorySource LiveModeRate

Provides the same functionality as RealTimeRate, except this property is in milliseconds. You can also use the Server object, or Servers object. Only relevant when retrieving data from an IndustrialSQL Server 8.0 historian. For an IndustrialSQL Server 9.0 historian, use retrieval styles instead. Only relevant when retrieving data from an IndustrialSQL Server 8.0 historian. For an IndustrialSQL Server 9.0 historian, use retrieval styles instead. Only relevant when retrieving data from an IndustrialSQL Server 8.0 historian. For an IndustrialSQL Server 9.0 historian, use retrieval styles instead.

LoginTimeout MaxDeltaSamples

MaxMinutesForDeltaAn alog

MaxMinutesForDeltaDi screte

MaxMinutesForDeltaDis crete

-MovingAverageMode

MaxSamplesPerTag MovingAverageMode Present, but ignored. Use retrieval styles instead.

ActiveFactory Software Users Guide

iTrend and aaHistClientTrend Comparison

701

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

MovingAverageSamples ----PrintShowMarkers QueryTimeout RetrieveExtensionData RetrieveManualData RTRate RubberBand RubberBandAll

MovingAverageSamples PlotColor PlotGradient PlotGradientEndColor PlotImage PrintShowMarkers QueryTimeout RetrieveExtensionData RetrieveManualData RTRate RubberBand RubberBandAll

Present, but ignored. Use retrieval styles instead.

Not applicable to version 9.x. You can also use the Server object or Servers object. You can also use HistorySource. You can also use HistorySource. Use RealTimeRate instead. You can use RubberBandScaling instead. You can use ApplyRubberBandToAllTags instead. Same as RubberBand.

--SummaryDataMode TagGridOrientation TimeBarVisible2 TimeSelector -ToolBarVisible2 UseIniFile Width

RubberBandScaling Servers SummaryDataMode TagGridOrientation TimeBarVisible2 TimeSelector ToolBarVisible ToolBarVisible2 UseIniFile --

Present, but ignored. Use retrieval styles instead. Not applicable in 9.x. Not applicable in 9.x. Not applicable in 9.x. Same as ToolbarVisible2. You can also use ToolbarVisible. Not applicable in 9.x.

ActiveFactory Software Users Guide

702

Appendix C Control and Object Migration Reference

Methods ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

AddServer GetMenuItemEnabled

You can also add a server using the Servers object. Not applicable in 9.x. The menu is automated for enabling/disabling. Since data formats are encrypted, this is no longer applicable. You can also use the Servers object. Not applicable in 9.x. The TagList user interface provides this functionality. Not applicable in 9.x. The TagList user interface provides this functionality. Present, but not applicable in 9.x. The menu is automated for enabling/disabling.

LoadCRVString

RemoveServer ScaleAllTagsDlg

ScaleTagDlg

SetMenuItemEnabled

Events ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

DatesChanged

This functionality is also available through the TimeRangePicker object.

ActiveFactory Software Users Guide

iQuery and aaHistClientQuery Control Comparison

703

iQuery and aaHistClientQuery Control Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 iQuery control and the aaHistClientQuery control. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before. You must reconfigure the servers for the aaHistClientQuery control; the aaHistClientQuery control does not automatically use the servers as specified by the iQuery control.
Properties ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

-FontBold FontCharset FontItalic FontName FontSize --UsePersistedServers

CurrentServer FontBold FontCharset FontItalic FontName FontSize QueryFont Servers UsePersistedServers

CurrentServer returns an aaServer object. You can use QueryFont instead. You can use QueryFont instead. You can use QueryFont instead. You can use QueryFont instead. You can use QueryFont instead.

You can also use the Servers object to change the server set.

Methods ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

SetDates2 SetDuration2

---

ActiveFactory Software Users Guide

704

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

SetQueryType

Cannot be used in the InTouch HMI software. Use the SetQueryType2 method instead. Cannot be used in the InTouch HMI software. Use the SetDates and SetDuration methods instead. Not applicable in version 9.x.

SetTimeSpan

ShowLicenseManager

-Events

No changes.

TimeBar and aaHistClientTimeRangePicker Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 TimeBar control and the aaHistClientTimeRangePicker control. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

AllowModeChange BackColor BackStyle BorderStyle DTFormat -Enabled --ForeColor

-----DurationMS -EndDate Format --

Use the time range picker to set a duration or a custom set of times. Ambient. Ambient. Ambient. Use Format.

Ambient.

ActiveFactory Software Users Guide

TagPicker and aaHistClientTagPicker Comparison

705

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

Servers --TimeSelector

-StartDate TimeDuration -Methods

Not needed.

Use the time range picker to set a duration or a custom set of times.

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

-Refresh

GetStartAndEndTimes -RefreshTimes Use RefreshTimes.

SetDates SetDuration --

--SetStartAndEndTimes
Events

Use SetStartAndEndTimes. Use SetStartAndEndTimes.

No changes.

TagPicker and aaHistClientTagPicker Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 TagPicker control and the aaHistClientTagPicker control. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

AllowAddToTarget AllowUserPaneCon trol BackColor

----

Drag-and-drop, cut and paste, and so on are suitable alternatives. No control allowed. Ambient.

ActiveFactory Software Users Guide

706

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

BackStyle BorderStyle Enabled Font ForeColor ---SelectedTags SelectionMode

-----HideCaption SelectedTagCount SelectedPath ---

Ambient. Ambient. Ambient.

Ambient.

Use the SelectedTag method. The determination of whether a tag is selected or picked is now managed through the OnPicked and OnSelected events. Not provided. You can now add as many servers as you choose, as well has control how many servers appear for the control. Not needed. The user interface displays all tag types and includes an all-inclusive All tab. Not needed. The user interface displays all tag types and includes an all-inclusive All tab. Drag-and-drop, cut and paste, and so on are suitable alternatives.
Methods

SingleServerMode

TagTypeFilter

TagTypeFilterEnab led TargetName

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

AddAllTagsToTarge t AddTagsToTarget -Refresh ReloadTree

--RefreshTags ---

Drag-and-drop, cut and paste, and so on are suitable alternatives. Drag-and-drop, cut and paste, and so on are suitable alternatives.

Use RefreshTags. Not needed.

ActiveFactory Software Users Guide

TagPicker and aaHistClientTagPicker Comparison

707

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

-ValidNode

SelectedTag -Events

Not implemented.

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

Click DblClick KeyDown KeyPress KeyUp MouseDown MouseMove MouseUp ------NodeClick

--------OnFilterChanged OnGroupChanged OnSelectedTabChange d OnServerChanged OnTagsPicked OnTagsSelected

Ambient. Ambient. Ambient. Ambient. Ambient. Ambient. Ambient. Ambient.

Not designed. There is no need for this behavior.

ActiveFactory Software Users Guide

708

Appendix C Control and Object Migration Reference

SingleValueEntry and aaHistClientSingleValueEntry Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 SingleValueEntry object and the ActiveFactory 9.2 aaHistClientSingleValueEntry object. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

BackColor BackStyle BorderStyle Enabled Font ForeColor

------Methods

Ambient. Ambient. Ambient. Ambient.

Ambient.

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

InsertValue

-Events

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

Click DblClick KeyDown KeyPress KeyUp MouseDown MouseMove

--------

Ambient. Ambient. Ambient. Ambient. Ambient. Ambient. Ambient.

ActiveFactory Software Users Guide

ActiveDataGrid and aaHistClientActiveDataGrid Comparison

709

ActiveDataGrid and aaHistClientActiveDataGrid Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 ActiveDataGrid control and the ActiveFactory 9.2 aaHistClientActiveDataGrid Control.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

----

Domain VirtualDirectoryName Visible

Methods

Used for HTTP access. Used for HTTP access. Ambient.

No changes.
Events

No changes.

Server and aaServer Object Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 Server object and the ActiveFactory 9.2 aaServer object. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

---------

BaseURLAddress Build Domain LoginID LoginTimeout MachineName Name Password

ActiveFactory Software Users Guide

710

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

---------

PatchLevel QueryTimeout RetainPassword SchemaVersion State TrustedConnection UseHttp VirtualDirectoryName

Methods

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

---

LogOff LogOn
Events

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

ServerSatusChanged

Servers and aaServers Object Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 Servers object and the ActiveFactory 9.2 aaServers object. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

LoginTimeOut QueryTimeOut

---

Applied on a per-server basis. Applied on a per-server basis.

ActiveFactory Software Users Guide

Tag and aaTag Object Comparison

711

Methods ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

--GetStatus LogOn LogOff UnderlyingServerName -UpdateSchemaVersion

ApplicationName GetServer ----Update -Events

Applied on a per-server basis. Applied on a per-server basis.

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

LicenseFailure ----ServerSatusChanged OnServerAdded OnServerUpdated OnServerRemoved OnServerStateChanged --

Tag and aaTag Object Comparison

This section provides a comparison for the properties, methods, and events between the ActiveFactory 8.5 Tag object and the ActiveFactory 9.2 aaTag object. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Properties ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

----

DateCreated Description IOAddress

ActiveFactory Software Users Guide

712

Appendix C Control and Object Migration Reference

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

----------ServerName TagName TagType ----

MaxRaw MinRaw MinEU MaxEU Message0 Message1 Mode Name RawType Server ---Type TypeAsTagType Units
Methods

The Server property can be used to get the name. Use the Name property instead. Us the TypeAsTagType property instead.

ActiveFactory 8.5 Software

ActiveFactory 9.2 Software

Comments

GetBasicInfo

Use the version 9.x properties.

ActiveFactory Software Users Guide

Tags Object

713

Tags Object
The ActiveFactory 8.5 Tags object does not have an equivalent in ActiveFactory 9.x. In most cases, an array of tags can be used instead. The functionality provided by this object is provided in ActiveFactory 9.x software through the SelectedTagCount and SelectedTags properties of the aaHistClientTagPicker control.

GlobalFunctions Object and aaHistClientGlobalFunctions Object Comparison

This section provides a comparison for the methods between the ActiveFactory 8.5 GlobalFunctions object and the ActiveFactory 9.2 aaHistClientGlobalFunctions object. The tables only list differences between the two versions. Unless otherwise noted, properties, methods and events work the same way as before.
Methods ActiveFactory 8.5 Software ActiveFactory 9.2 Software

Comments

GetDictionaryPath GetInstallPath

For 9.x, returns an empty string. The installation folder for version 9.x does not have the same structure as 8.5.

ActiveFactory Software Users Guide

aaHistClientQuery control 703 configuration details, retrieving for a tag 218 configuration, server connections 39 configuring scatter plots 139 target region 72 trend 64 configuring , formatting options 283 configuring axes, scatter plots 141 configuring for scatter plot, target region 143 configuring options reports 345 scatter plots 146 configuring properties annotations 135 target region 136 configuring the , database connection 517 Connect 561 Connected 524 Container 623 ContextMenuEnabled 623 controls about 347 getting started 349 using in different environments 349 using within InTouch HMI software 350 Controls 34 converting to values functions 207 sheet 208 copying to the clipboard, trend chart 154 copying, functions 212 CopyQuery 487 copyright information 59 Count 576 counter retrieval mode 669 counter, retrieval modes 669 CreateManualTag 562 creating groups 53 query 166, 176 reports 205 server connections 40 SQL statements 518 trend set 150

Index

719

Criteria tab 169, 175, 183, 249 .crv data, importing 160 CurrentServer 480, 497 CurrentServerName 367, 545 CurrentTagChanged 466 CurrentTagColor 367 CurrentTagCycleCount 367 CurrentTagEffectiveRetrievalMode 368 CurrentTagFormat 368 CurrentTagGetStyle 430 CurrentTagHistoryVersion 369 CurrentTagIndex 369 CurrentTagInterpolationType 370 CurrentTagName 370 CurrentTagNumStyles 371 CurrentTagOffsetMS 371 CurrentTagPenStyle 372 CurrentTagPenWidth 373 CurrentTagPrecision 373 CurrentTagQualityRule 373 CurrentTagResolution 374 CurrentTagRetrievalMode 375 CurrentTagRetrievalStyle 375 CurrentTagRowLimit 376 CurrentTagStartDate 376 CurrentTagState 377 CurrentTagStateCalculation 377 CurrentTagTargetRegionVisible 378 CurrentTagTimeDeadband 378 CurrentTagTimeStampRule 378 CurrentTagTrendType 379 CurrentTagUseAutoCycles 379 CurrentTagUseResolution 380 CurrentTagValAtX1 381 CurrentTagValAtX2 381 CurrentTagValueDeadband 381 CurrentValOfX1 382 CurrentValOfX2 382 CurrentValOfY1 383 CurrentValOfY2 383 CurrentXAxisTagIndex 383 CurrentXAxisTagName 384 CurrentXAxisTagServerName 384 cursor difference, showing/hiding 95 CutQuery 487 cycle count 674 cyclic retrieval about 197

cyclic retrieval, about 650 cyclic, retrieval modes 650 CyclicRows 384

D
data grid 516 about 516 clearing 530 refreshing 519 data log viewing in a narrow format 98 viewing in a wide format 100 data quality 98, 172, 179, 181, 186, 190, 228, 248 data source options, configuring 290 data types 638 database connection aaHistClientActiveDataGrid 517 aaHistClientActiveDataGrid control 517 configuring the 517 database options, configuring 120, 126 database user 105, 175 DatabaseName 524 DataBindings 624 DataPointLabelType 385 DataSet 639 date and time options 340 wildcards 341 date/time format, verifying 213 DateCreated 586 DateMode 385 DatePickerFormatString 386 DatesChanged 467 DateTime 546, 638 DateTimeFieldDisable 546 DateTimeFieldVisible 546 DateTimeString 547 DblClick 632 deadband 197, 198, 240, 318, 676, 677 deadband, for events 221 DefaultColumnWidth 525 DefaultTagFormat 386 DefaultTagPrecision 387 defining target region, scatter plots 143 defining, retrieval styles 685 DeleteCurrentTag 430

ActiveFactory Software Users Guide

720

Index

deleting annotations 106 groups 53 deleting an annotation, trend 106 deleting files from, trend set 151 deleting from a trend, tags 67 deleting in a trend, annotations 106 delta retrieval about 197 delta retrieval, about 652 delta, retrieval modes 652 Description 586 description, annotations 103 DescriptionFilter 497 desktop applications 34 detection time 177, 179, 228, 248 detector scripts 192 direct query, creating 280 DisableTagEntry 547 Disconnect 562 discrete tag analysis 268 DisplayErrorMessages 547 displaying in the trend, tags 78 displaying live data, trend 79 displaying, live values 79 documentation conventions 31 Domain 525, 569 Drag 630 DragDrop 632 DragIcon 624 DragMode 624 DragOver 632 duration 58 duration XML element 689 DurationMS 509

E
editing annotations 106 functions 207 groups 53 query 339 server connections 42 trend set 151 e-mail 153 EnableAllQueriestab 480 Enabled 525, 625

EnableDeltaRetrieval 387 EnableShortcutMenu 525 EnableSummaryData 388 EnableTimeOffsets 388 end time 58 EndDate 388, 509 engineering units 192, 198, 221, 240, 318, 587, 677 enumerations, aaHistClientTrend control 468 enumerations, common 635 EOF 526 EOF property 526 ErrDescription 592, 601 ErrNumber 592, 601 error messages aaHistClientActiveDataGrid 540 aaHistClientActiveDataGrid control 540 functions 319 error reporting 46 event actions snapshot actions about 214 event history values, querying 176 event snapshot querying 177 retrieving values for tags 244 selecting tags 217 event tag 109 events aaHistClientActiveDataGrid control 535 aaHistClientQuery control 492 aaHistClientSingleValueEntry control 564 aaHistClientTagPicker control 503 aaHistClientTimeRangePicker control 513 aaHistClientTrend control 466 aaServers object 578 common 631 trending 109 ExactMatchFilter 498 ExcelVisible 593 Execute 531 Execute method 531 exporting, trend 152

ActiveFactory Software Users Guide

Index

721

F
FALSE 192, 588 FavoriteQueriesFolder 480 favorites, query 180 field codes 328 inserting into a report 341 showing/hiding 329 FieldLabelPosition 548 FieldLayoutHorizontal 548 file structure, retrieval styles 685 FileName 389 FileNew 431 FileOpen 431, 487 FileSave 431 filter pane, using 55 FilterVisible 498 Font 625, 639 FontBold 481 FontCharset 481 FontItalic 482 FontName 482 FontSize 482 for a trend, annotations 103 for controls and objects, migration 697 ForeColor 625 Format 509 formats, time offsets 114 formatting options 288 configuring 283 referencing in a query 285 formulas 206 full, retrieval modes 653 functions 206 arguments 308 converting to values 207 copying 212 editing 207 error messages 319 manually editing 211 manually inserting 208 refreshing 207

GetLastError 606 GetMenuItemEnabled 432 GetServer 577 GetStartAndEndTimes 511 GetTagColor 432 GetTagFormat 433 GetTagOffsetMS 433 GetTagPenStyle 434 GetTagPenWidth 435 GetTagPrecision 436 GetTagValAtX1 436 GetTagValAtX2 437 GetTagVisible 438 getting started ActiveFactory Query 161 ActiveFactory Trend 61 controls 349 GetToolbarButtonEnabled 439 GotFocus 633 GraphStack 439 grid, showing/hiding 96 GridColor 389 GridHorizontal 389 GridVertical 390 GridVisible 390 groups 52 adding 53 adding a tag 53 creating 53 deleting 53 editing 53 renaming 54

H
Handle 526 Height 626 HelpContextID 626 HideCaption 498 HideCurrentTag 390 HideDateTimeModeTabs 549 HideFieldLabels 549 HideStatusBar 549 hiding/showing in a trend, tags 78 hiding/showing tags, trend 78 HighlightCurrentTag 390 highlighting, tags 77 historical data, displaying in "replay" mode 80

G
general options, configuring 291 general properties, configuring 129 GetDictionaryPath 619 GetInstallPath 620

ActiveFactory Software Users Guide

722

Index

history data over a LAN, aaHistClientActiveDataGrid control 537 history data retrieval functions, migration 319 history values querying 180 retrieving 229 history version 678 HistorySource 391 HTTP access 43, 44, 48 HTTP access, using 43

K
KeyDown 633 KeyPress 633 KeyUp 633

L
LastErrorDetails 551 LastErrorMessage 551 LastOperationResult 552 LastOperationSuccessful 552 Left 626 legacy retrieval settings 128, 694 licensing 59 limit names 173, 174 limit properties, configuring 133 limit type 173 limits for a storage location 188 linear interpolation 679 live data 79 live values displaying 79 querying 186 retrieving 225 LiveModeRate 391 LoadCRVString 439 LoadTargetRegionFromFile 439 LockDown 391 LoggedOn 569 LoginID 569 LoginTimeout 392, 569 LogOff 574 LogOn 501, 574 LostFocus 634

I
I/O Server, querying 185 in applications, SQL statements 46 Index 626 IndustrialSQL Server historian about 35 viewing details 321 Insert 562 InsertButtonDisable 550 InsertButtonVisible 550 InsertComplete 565 InsertFail 565 inserting into a report field codes 341 query 336 InsertValue 563 instantiating, aaServers object 580 integral retrieval mode 666 integral, retrieval modes 666 interpolated, retrieval modes 654 interpolation 654 interpolation of values, scatter plots 142 interpolation type 678 InTouch window aaHistClientTimeRangePicker control, adding to an 508 aaHistClientTrend control, adding to an 354 InTouch windows, aaHistClientQuery control, adding to 478 InTouchDateTime 550 IOAddress 586 IOAddressFilter 498 Items 576

M
MachineName 570 managing, server connections 202, 328 ManualConnect 440, 488 manually editing, functions 211 manually inserting, functions 208 manually loading 203, 327 matching of value pairs, scatter plots 142 MaxDeltaSamples 392 MaxEU 587 maximum retrieval mode 665 maximum, retrieval modes 665

ActiveFactory Software Users Guide

Index

723

MaxMinutesForDeltaAnalog 393 MaxMinutesForDeltaDiscrete 393 MaxRaw 587 MaxSamplesPerTag 394 MDACOk 620 Message 582 Message0 588 Message1 588 methods aaHistClientActiveDataGrid 529 aaHistClientActiveDataGrid control 529 aaHistClientGlobalFunctions object 619 aaHistClientQuery control 485 aaHistClientReportRunner object 603 aaHistClientSingleValueEntry control 560 aaHistClientTagPicker control 501 aaHistClientTimeRangePicker control 511 aaHistClientTrend control 425 aaHistClientWorkbookRunner object 593 aaServer object 574 aaServers object 576 common 630 Report object 617 Microsoft office, add-ins 34 migration aaHistClientSingleValueEntry control 708 aaHistClientTagPicker control 705 aaHistClientTimeRangePicker control 704 aaHistClientTrend control 699 for controls and objects 697 history data retrieval functions 319 MinEU 587 minimum, retrieval modes 663 MinRaw 587 miscellaneous options, configuring 125 Mode 588 ModeChanged 492 MouseDown 634 MouseMove 634 MouseUp 634 Move 630 MoveFirst 531

MoveLast 532 MoveNext 532 MoveNextTag 440 MovePrevious 532 MovePrevTag 440 Moving a Cursor 95 moving tags up or down, trend 90 MovingAverageMode 394 MovingAverageSamples 394 multiple scales 84 multiple, scale 84

N
Name 570, 588, 627 named range 288 named range, formatting options 287 navigator bar 516, 528 NumDataPointLabels 395 numerical data types 351 NumTimeAxisGridPerValue 395 NumTimeAxisValues 395 NumXValueAxisGridLinesPerLabel 396 NumXValueAxisLabels 396 NumYAxisGridPerValue 396 NumYAxisValues 397

O
Object 627, 639 objects 52 objects, about 347 OnChange 513 OnClick 535 OnError 535 OnFilterChanged 503 OnGroupChanged 503 OnSelectedTabChanged 504 OnServerAdded 579 OnServerChanged 504 OnServerRemoved 579 OnServerStateChange 580 OnServerUpdated 579 OnTagsPicked 503 OnTagsSelected 504 OPC 172, 182, 187, 228, 248 OPC quality 682 opening report documents 330 trend 63, 166

ActiveFactory Software Users Guide

724

Index

OpenQuery 488 options, date and time 340 original data 678 OutputFile 592, 602 outputting, trend data 149 over HTTP 44 overview retrieval styles 684 scatter plots 138 target region 70

P
PanLeft 441 panning 93 panning in, trend 93 panning, in a scatter plot 143 panning, scatter plots 143 PanPercentage 397 PanRight 441 Parent 627 Password 526, 570 PasteQuery 488 PatchLevel 571 performance 47 PlaybackSpeed 397 PlotColor 398 PlotGradient 398 PlotGradientEndColor 399 PlotImage 399 PrintGraph 441 PrintGraphDlg 442 printing annotations 107 trend 149 trend data 149 trend set 149, 152 printing, trends 149 PrintShowActiveTag 399 PrintShowMarkers 400 PrintShowTitle 400 PrintTitle 401 private groups 52 process data 37 program information 59 program information, viewing 59 properties 533, 581 aaHistClientActiveDataGrid 521

aaHistClientActiveDataGrid control 521 aaHistClientQuery control 479 aaHistClientReportRunner object 601 aaHistClientSingleValueEntry control 544 aaHistClientTagPicker control 497 aaHistClientTimeRangePicker control 508 aaHistClientTrend control 355 aaServer object 567 aaServers object 575 aaTag object 585 common 621 methods events 348 Report object 616 PropertiesDlg 442 public groups 52 PublicAnnotations 401 publishing trend reports 154 workbook reports 298 Pwd 553

Q
Quality 553 quality 98, 172, 179, 181, 186, 190, 228, 248 quality calculation, scatter plots 143 quality rule 682 quality rule, retrieval 682 quality, retrieval rule 682 QualityDetail 553 QualityDetailFieldDisable 554 QualityDetailFieldVisible 554 QualityFieldDisable 554 QualityFieldVisible 554 query creating 166, 176 editing 339 favorites 180 file opening 166 saving 166 inserting into a report 336 time options for 297 types 168 common tabs for 195

ActiveFactory Software Users Guide

Index

725

query files 165 QueryChanged 493 QueryFont 483 querying aggregate values 168 alarm limits 174 annotations 174 event snapshot 177 history values 180 live values 186 queryingnumber of , tags 187 QueryString 483 QueryTimeout 401, 571

R
raw value 192, 220, 587 RawType 589 RealTimeMode 402 RealTimeRate 402 Recordset 483 referencing in a query, formatting options 285 Refresh 488, 563 refresh, aaHistClientActiveDataGrid 522, 526 RefreshData 442 RefreshFrequency 526 RefreshFrequency property 527 refreshing data grid 519 functions 207 sheet 207 trend chart 67 refreshing the graph, trend 67 RefreshTags 502 RefreshTimes 512 relative time 110, 112, 113 relative time, time offsets 112 relative, time 112 reliability 47 RememberEnteredTags 555 Remove 577 RemoveServer 442 RemoveTag 443, 489 removing, server connections 42 renaming, groups 54 report documents opening 330

running 331 saving 332 saving as a report template 332 saving as an HTML file 334 Report object methods 617 properties 616 ReportDate 616 reports configuring options 345 creating 205 selecting tags for 214 ReportTime 617 Reset 564 resolution 190, 197, 239, 255, 262, 266, 270, 275, 279, 675 Results pane 163 RetainPassword 571 retrieval 197 quality rule 682 time deadband 676 value deadband 677 version of data 678 retrieval modes average (time-weighted) 659 best fit 655 counter 669 cyclic 650 delta 652 full 653 integral 666 interpolated 654 maximum 665 minimum 663 slope 667 time-in-state 672 ValueState 672 retrieval options, configuring for a tag 75 retrieval styles defining 685 file structure 685 overview 684 Retrieval tab 184 retrieval XML element 690 RetrievalOptionsCycleCount 402 RetrievalOptionsGetStyle 443 RetrievalOptionsHistoryVersion 403 RetrievalOptionsInterpolationType 403

ActiveFactory Software Users Guide

726

Index

RetrievalOptionsNumStyles 404 RetrievalOptionsQualityRule 404 RetrievalOptionsResolution 405 RetrievalOptionsRetrievalMode 406 RetrievalOptionsRetrievalStyle 406 RetrievalOptionsRowLimit 407 RetrievalOptionsState 407 RetrievalOptionsStateCalculation 408 RetrievalOptionsTimeDeadband 408 RetrievalOptionsTimeStampRule 409 RetrievalOptionsUseAutoCycles 409 RetrievalOptionsUseResolution 410 RetrievalOptionsValueDeadband 411 retrievalStyle XML element 688 RetrieveAnnotations 411 RetrieveExtensionData 411 RetrieveManualData 412 retrieving aggregate values 235 alarm limits 223 history values 229 live values 225 tag values 225 retrieving configuration information, tags 218 retrieving data from the grid, aaHistClientActiveDataGrid control 537 retrieving values for tags, event snapshot 244 returning to original scale, tags 90 RevisionNumber 572 rollover value 669 roperties, aaHistClientWorkbookRunner object 591 Row 527 row count 197, 239, 278 Row property 527 RowColumnValue 532 RowColumnValue method 532 RowColumnValueByName 533 RowCount 527 RowCount property 527 RTRate 412 rubber band scaling 91 Rubberband 412 RubberbandAll 413 RubberBandScaling 413 Run 593, 603

running, report documents 331 RunReport 594, 607, 617 RunReport2 597

S
sampling interval 675 SaveData 444 SaveImage 445 SaveQuery 489 SaveResults 489 SaveSettings 445 saving report documents 332 trend 63 saving as a .csv file, annotations 107 saving as a report template, report documents 332 saving as an HTML file, report documents 334 saving to a .csv file, trend data 152 scale multiple 84 single 82 ScaleAllTags 445 ScaleAllTagsDlg 446 ScaleAutoAllTags 446 ScaleAutoTag 447 ScaleDownAllTags 447 ScaleDownTag 448 ScaleMoveAllTagsDown 448 ScaleMoveAllTagsUp 449 ScaleMoveTagDown 450 ScaleMoveTagUp 450 ScaleTag 451 ScaleTagDlg 451 ScaleUpAllTags 452 ScaleUpTag 452 scaling 89 scaling tags 81, 87 scaling tags, scatter plots 141 scaling, tags in a scatter plot 141 scan rate for event tags 193, 222, 315 scatter analysis 264 scatter plots configuring 139 configuring axes 141 configuring options 146

730

Index

Units 590 UnsetCurrentTagXAxisTag 465 Update 577 UpdateToCurrentTimeState 421 UseHttp 574 UseIniFile 422 UsePersistedServers 485 User 558 UserName 529 users 105, 175 UseTimezone 559 using annotations 103 axis cursors 94 Servers pane 52 using at runtime aaHistClientActiveDataGrid control 516 aaHistClientQuery control 477 aaHistClientSingleValueEntry control 541 using in an application aaHistClientActiveDataGrid control 520 aaHistClientGlobalFunctions object 619 aaHistClientSingleValueEntry control 542 aaTag object 585 using in different environments, controls 349 using within InTouch HMI software, controls 350

version of data, retrieval 678 versioned data 678 viewing , statistics 101 viewing data trend 97 trend chart 66 viewing details, IndustrialSQL Server historian 321 viewing in a narrow format, data log 98 viewing in a table format, trend data 97 viewing in a trend, statistics 101 viewing in a wide format, data log 100 viewing list, annotations 105 viewing statistics, trend 101 views, Tag Picker 57 VirtualDirectoryName 529, 574 Visible 629 VPN access 49

W
WhatsThisHelpID 629 When 582 Width 630 wildcards, date and time 341 wildcards, inserting into a report 344 WordVisible 602 workbook file, opening 203 workbook options, configuring 283 workbook report, publishing 299, 300 workbook reports, publishing 298 wwHistory function, updating to wwHistory2 319 wwWideHistory function, updating to wwWideHistory2 319

V
Validate 635 Value 559 value adding 541 value deadband 677 value deadband, retrieval 677 ValueAxisLabel 422 ValueChanged 565 ValueFieldDisable 560 ValueState retrieval mode 672 ValueState, retrieval modes 672 version information 59

X
x-axis, tag cursors 94 XCursor1Color 422 XCursor1Pos 423 XCursor2Color 423 XCursor2Pos 424

Y
y-axis, tag cursor 94 YCursor1Color 424 YCursor2Color 425

ActiveFactory Software Users Guide

Index

731

Z
zoom factor 133 ZoomIn 465 zooming 95 scatter plots 143

trend 95 zooming, in a scatter plot 143 ZoomOut 465 ZoomOutPercentage 425 ZOrder 631

ActiveFactory Software Users Guide

732

Index

ActiveFactory Software Users Guide

Fox On The Moonlight Papercraft by Bumagid
70% (10)
Fox On The Moonlight Papercraft by Bumagid
26 pages
Using-Bapi Outb Delivery Confirm Dec-Cross-Hu
No ratings yet
Using-Bapi Outb Delivery Confirm Dec-Cross-Hu
23 pages
Hans Loewald The Psychoanalyst As Mystic
No ratings yet
Hans Loewald The Psychoanalyst As Mystic
13 pages
Ivi-Tec Admon
No ratings yet
Ivi-Tec Admon
2 pages
WONDERWARE 2013 Historian Concepts PDF
No ratings yet
WONDERWARE 2013 Historian Concepts PDF
374 pages
HistClient PDF
No ratings yet
HistClient PDF
872 pages
Wonderware Application Server Scripting Guide
No ratings yet
Wonderware Application Server Scripting Guide
148 pages
Wonderware: Factorysuite Gateway User'S Guide
No ratings yet
Wonderware: Factorysuite Gateway User'S Guide
110 pages
Wonderware Historian Installation Guide
No ratings yet
Wonderware Historian Installation Guide
80 pages
ArchestrA Alarm Control Guide
100% (1)
ArchestrA Alarm Control Guide
196 pages
HistorianRetrieval PDF
No ratings yet
HistorianRetrieval PDF
233 pages
Aveva Intouch Hmi: Formerly Wonderware
No ratings yet
Aveva Intouch Hmi: Formerly Wonderware
132 pages
E Learning Rockwell Automation
No ratings yet
E Learning Rockwell Automation
2 pages
Access and OPC PDF
No ratings yet
Access and OPC PDF
12 pages
IFIX Drivers
No ratings yet
IFIX Drivers
17 pages
MBTCP DAServer User's Guide PDF
No ratings yet
MBTCP DAServer User's Guide PDF
112 pages
A330-16 OMS V61 E No Scripting RVR 2
100% (1)
A330-16 OMS V61 E No Scripting RVR 2
431 pages
Historian Concepts
No ratings yet
Historian Concepts
29 pages
Available Protocols in PcVue
No ratings yet
Available Protocols in PcVue
5 pages
Basics of PI SQL
No ratings yet
Basics of PI SQL
11 pages
Historian Database
100% (1)
Historian Database
320 pages
DNP3 Interface Reference
No ratings yet
DNP3 Interface Reference
52 pages
Training Document For InTouch
50% (2)
Training Document For InTouch
27 pages
Historian Retrieval
100% (1)
Historian Retrieval
213 pages
With Wonderware
No ratings yet
With Wonderware
3 pages
Da Server Manager
No ratings yet
Da Server Manager
32 pages
SFC ST Presentation1
No ratings yet
SFC ST Presentation1
51 pages
Logix5000 Controllers Major and Minor Faults Programming Manual
No ratings yet
Logix5000 Controllers Major and Minor Faults Programming Manual
32 pages
Meaning of Network Topology
No ratings yet
Meaning of Network Topology
10 pages
ATQMS-MKTG-DOC-Adroit Ignite HMI Technical Description
No ratings yet
ATQMS-MKTG-DOC-Adroit Ignite HMI Technical Description
97 pages
Resources For The Certified Automation Professional
No ratings yet
Resources For The Certified Automation Professional
3 pages
Historian Scenarios
No ratings yet
Historian Scenarios
30 pages
IFIX Operator Tools
No ratings yet
IFIX Operator Tools
16 pages
2016 Wonderware Training Catalog RevB 08 2016
No ratings yet
2016 Wonderware Training Catalog RevB 08 2016
78 pages
Foxboro SCADA Master Stations PDF
100% (1)
Foxboro SCADA Master Stations PDF
39 pages
Historian Admin
No ratings yet
Historian Admin
259 pages
Ois 40 Series Hardware Iioic43
No ratings yet
Ois 40 Series Hardware Iioic43
79 pages
Beginners Guide To OPC V2
No ratings yet
Beginners Guide To OPC V2
16 pages
TelePACE User and Reference Manual PDF
No ratings yet
TelePACE User and Reference Manual PDF
728 pages
Variador PS200 - PDF
No ratings yet
Variador PS200 - PDF
122 pages
FOUNDATION™ Fieldbus Book A Tutorial
No ratings yet
FOUNDATION™ Fieldbus Book A Tutorial
70 pages
SQL Data Grid Users Guide
No ratings yet
SQL Data Grid Users Guide
36 pages
Data Acquisition & SCADA Systems
No ratings yet
Data Acquisition & SCADA Systems
4 pages
FactoryTalk Batch View HMI Controls - Quick Start
No ratings yet
FactoryTalk Batch View HMI Controls - Quick Start
28 pages
Micrologix Lab 2
No ratings yet
Micrologix Lab 2
26 pages
NUMA
No ratings yet
NUMA
4 pages
Safety Considerations Guide For Tricon v9-v10 Systems
No ratings yet
Safety Considerations Guide For Tricon v9-v10 Systems
122 pages
Connected Components Workbench™ Software Guide For Studio 5000 Logix Designer® Software Users
No ratings yet
Connected Components Workbench™ Software Guide For Studio 5000 Logix Designer® Software Users
46 pages
Unity Programming Software Telemecanique Modicon M340 Programming
No ratings yet
Unity Programming Software Telemecanique Modicon M340 Programming
17 pages
Kepserverex V5 Help: © 2011 Kepware Technologies
No ratings yet
Kepserverex V5 Help: © 2011 Kepware Technologies
191 pages
FTView Alias Topic Switching
100% (1)
FTView Alias Topic Switching
3 pages
FactoryTalk View SE IIS Handbook Rev 1-1
No ratings yet
FactoryTalk View SE IIS Handbook Rev 1-1
30 pages
Mkted2140504en Esx Control Expert
No ratings yet
Mkted2140504en Esx Control Expert
50 pages
BulkConfigurator V11
No ratings yet
BulkConfigurator V11
96 pages
FactoryTalk View SE Network Station Architecture Considerations
No ratings yet
FactoryTalk View SE Network Station Architecture Considerations
6 pages
Micrologix Lab 4
No ratings yet
Micrologix Lab 4
14 pages
GS 85a7c01-16en007
No ratings yet
GS 85a7c01-16en007
10 pages
Electronic test equipment Third Edition
From Everand
Electronic test equipment Third Edition
Gerardus Blokdyk
No ratings yet
The Alarm Management Handbook - Second Edition: A Comprehensive Guide
From Everand
The Alarm Management Handbook - Second Edition: A Comprehensive Guide
Bill Hollifield
No ratings yet
DeviceNet The Ultimate Step-By-Step Guide
From Everand
DeviceNet The Ultimate Step-By-Step Guide
Gerardus Blokdyk
No ratings yet
PLC: Programmable Logic Controller – Arktika.: EXPERIMENTAL PRODUCT BASED ON CPLD.
From Everand
PLC: Programmable Logic Controller – Arktika.: EXPERIMENTAL PRODUCT BASED ON CPLD.
MARIO FRANCO
No ratings yet
WW HistClient 92 PDF
No ratings yet
WW HistClient 92 PDF
732 pages
In SQLAdmin
No ratings yet
In SQLAdmin
332 pages
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
No ratings yet
WALK
0% (1)
WALK
4 pages
Form 1 Science Chapter 1 2 1 3
0% (1)
Form 1 Science Chapter 1 2 1 3
50 pages
Dokumen - Tips Crimpro Finals Reviewer 2docx
No ratings yet
Dokumen - Tips Crimpro Finals Reviewer 2docx
129 pages
PWC (2011), Executive Summary, Chapter 2 & 4 Chapter 2: Risk Management and The System of Internal Control 1. Risk Management Process
100% (1)
PWC (2011), Executive Summary, Chapter 2 & 4 Chapter 2: Risk Management and The System of Internal Control 1. Risk Management Process
4 pages
Business Economics Meaning, Definitions Etc
No ratings yet
Business Economics Meaning, Definitions Etc
15 pages
Arc Welding Electrodes (Product Catalogue)
No ratings yet
Arc Welding Electrodes (Product Catalogue)
28 pages
Mba Mco101 Unit 5
No ratings yet
Mba Mco101 Unit 5
15 pages
13-3 Permutations and Combinations
No ratings yet
13-3 Permutations and Combinations
44 pages
Batiment International, Building Research and Practice
No ratings yet
Batiment International, Building Research and Practice
2 pages
Lesson Plan TTL (AutoRecovered)
No ratings yet
Lesson Plan TTL (AutoRecovered)
9 pages
Final Team Charter and Schedule
No ratings yet
Final Team Charter and Schedule
3 pages
ELS 100 Lesson 1 - Nature of Language
100% (1)
ELS 100 Lesson 1 - Nature of Language
3 pages
An Overview of Facilitated Stretching - Robert E. McAtee - A-9
No ratings yet
An Overview of Facilitated Stretching - Robert E. McAtee - A-9
9 pages
English IVNALDI SUGIAMOTO PERTEMUAN 10
No ratings yet
English IVNALDI SUGIAMOTO PERTEMUAN 10
14 pages
Noelle Lor
No ratings yet
Noelle Lor
1 page
LSE 100 Summary Notes
No ratings yet
LSE 100 Summary Notes
16 pages
Session 7 Veritas Final
No ratings yet
Session 7 Veritas Final
6 pages
Checklist For Selecting A CMMS Solution PDF
No ratings yet
Checklist For Selecting A CMMS Solution PDF
4 pages
101 - Managerial Economics - Class Assignmnet
No ratings yet
101 - Managerial Economics - Class Assignmnet
2 pages
(2003) Clair - The Changing Story of Ethnography (Expressions of Ethnography)
No ratings yet
(2003) Clair - The Changing Story of Ethnography (Expressions of Ethnography)
24 pages
Engineering Assignment Coversheet
No ratings yet
Engineering Assignment Coversheet
1 page
Overview of CRM
0% (1)
Overview of CRM
43 pages
Questionnaire 3
No ratings yet
Questionnaire 3
2 pages
Note 3 Neo Diagrama
No ratings yet
Note 3 Neo Diagrama
10 pages
Star Grain in Propulsion
No ratings yet
Star Grain in Propulsion
8 pages
GB560 AssignmentTemplate
No ratings yet
GB560 AssignmentTemplate
4 pages