Intouch(R) Reference Guide - wccandm.services · Wonderware® FactorySuite™ InTouch® Reference Guide Revision A Last Revision: September 2002 Invensys Systems, Inc

Wonderware® FactorySuite™InTouch® Reference Guide

Revision A

Last Revision: September 2002

Invensys Systems, Inc.

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 the 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.

© 2002 Invensys Systems, Inc. All Rights Reserved.

Invensys Systems, Inc.33 Commercial StreetFoxboro, MA 02035(949) 727-3200http://www.wonderware.com

Trademarks

All terms mentioned in this book 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 book should not be regarded as affecting the validity of any trademark or service mark.

Alarm Logger, ActiveFactory, ArchestrA, Avantis, DBDump, DBLoad, DTAnalyst, FactoryFocus, FactoryOffice, FactorySuite, hotlinks, 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 3

Contents
Introduction ......................................................15
Document Conventions .................................................................... 15About this Manual ................................................................................ 16Technical Support................................................................................. 17Your FactorySuite License ................................................................... 17

CHAPTER 1: System Tagnames .....................19$AccessLevel ....................................................................................... 19$AlarmPrinterError .............................................................................. 20$AlarmPrinterNoPaper......................................................................... 20$AlarmPrinterOffline ........................................................................... 21$AlarmPrinterOverflow ....................................................................... 21$ApplicationChanged........................................................................... 22$ApplicationVersion............................................................................. 22$ChangePassword ................................................................................ 23$ConfigureUsers................................................................................... 23$Date .................................................................................................... 24$DateString........................................................................................... 24$DateTime ............................................................................................ 24$Day ..................................................................................................... 25$HistoricalLogging............................................................................... 25$Hour.................................................................................................... 26$InactivityTimeout ............................................................................... 26$InactivityWarning............................................................................... 27$LogicRunning..................................................................................... 27

$Minute............................................................................................. 28$Month ................................................................................................. 28$Msec ................................................................................................... 28$NewAlarm .......................................................................................... 29$ObjHor................................................................................................ 29$ObjVer ................................................................................................ 29$Operator.............................................................................................. 30$OperatorDomain................................................................................. 30$OperatorDomainEntered .................................................................... 31$OperatorEntered ................................................................................. 31$OperatorName .................................................................................... 31$PasswordEntered ................................................................................ 32$Second ................................................................................................ 32$StartDdeConversations....................................................................... 32

InTouch Reference Guide

4 Contents

$System.................................................................................................33$Time ....................................................................................................33$TimeString...........................................................................................33$VerifiedUserName...............................................................................34$Year .....................................................................................................34

CHAPTER 2: Dotfields .....................................35Tagname Types......................................................................................35Memory Type Tagnames.......................................................................36

I/O Type Tagnames............................................................................36Indirect Discrete, Indirect Analog, Indirect Message........................37Miscellaneous Type Tagnames..........................................................37

Tagname Type vs. Dotfield Usage Matrix ............................................38.Ack .......................................................................................................44.AckDev ................................................................................................44.AckDsc ................................................................................................46.AckROC...............................................................................................46.AckValue..............................................................................................48.Alarm ...................................................................................................48.AlarmAccess ........................................................................................50.AlarmAckModel ..................................................................................50.AlarmClass...........................................................................................52.AlarmComment....................................................................................52.AlarmDate............................................................................................54.AlarmDev.............................................................................................54.AlarmDevCount ...................................................................................56.AlarmDevDeadband.............................................................................56.AlarmDevUnAckCount .......................................................................57.AlarmDisabled .....................................................................................57.AlarmDsc .............................................................................................58.AlarmDscCount ...................................................................................58.AlarmDscDisabled ...............................................................................60.AlarmDscEnabled ................................................................................60.AlarmDscInhibitor ...............................................................................61.AlarmDscUnAckCount........................................................................61.AlarmEnabled ......................................................................................63.AlarmGroup .........................................................................................63.AlarmGroupSel ....................................................................................64.AlarmHiDisabled .................................................................................64.AlarmHiEnabled ..................................................................................65.AlarmHiHiDisabled .............................................................................65.AlarmHiHiEnabled .............................................................................66.AlarmHiHiInhibitor .............................................................................66


Contents 5

.AlarmHiInhibitor................................................................................. 68

.AlarmLimit.......................................................................................... 68

.AlarmLoDisabled ................................................................................ 70

.AlarmLoEnabled ................................................................................. 70

.AlarmLoInhibitor ................................................................................ 70

.AlarmLoLoDisabled............................................................................ 72

.AlarmLoLoEnabled............................................................................. 72

.AlarmLoLoInhibitor............................................................................ 72

.AlarmMajDevDisabled ....................................................................... 74

.AlarmMajDevEnabled ........................................................................ 74

.AlarmMajDevInhibitor........................................................................ 75

.AlarmMinDevDisabled ....................................................................... 75

.AlarmMinDevEnabled ........................................................................ 77

.AlarmMinDevInhibitor ....................................................................... 77

.AlarmName ......................................................................................... 79

.AlarmOprName................................................................................... 79

.AlarmOprNode.................................................................................... 81

.AlarmPri .............................................................................................. 81

.AlarmProv ........................................................................................... 83

.AlarmROC .......................................................................................... 83

.AlarmROCCount................................................................................. 85

.AlarmROCDisabled ............................................................................ 85

.AlarmROCEnabled ............................................................................. 86

.AlarmROCInhibitor ............................................................................ 86

.AlarmROCUnAckCount ..................................................................... 88

.AlarmState........................................................................................... 88

.AlarmTime .......................................................................................... 89

.AlarmTotalCount................................................................................. 89

.AlarmType........................................................................................... 90

.AlarmUnAckCount ............................................................................. 90

.AlarmUserDefNum1 ........................................................................... 91

.AlarmUserDefNum2 ........................................................................... 92

.AlarmUserDefStr ................................................................................ 93

.AlarmValDeadband ............................................................................. 94

.AlarmValue.......................................................................................... 94

.AlarmValueCount................................................................................ 95

.AlarmValueUnAckCount .................................................................... 95

.Caption ................................................................................................ 96

.ChartLength......................................................................................... 96

.ChartStart ............................................................................................ 98

.Comment ............................................................................................. 98

.DevTarget ............................................................................................ 99

.DisplayMode ....................................................................................... 99


6 Contents

.Enabled.................................................................................................99

.EngUnits.............................................................................................101

.Freeze .................................................................................................101

.HiHiLimit...........................................................................................102

.HiHiSet...............................................................................................102

.HiHiStatus ..........................................................................................103

.HiLimit...............................................................................................103

.HiSet...................................................................................................104

.HiStatus ..............................................................................................104

.ListChanged .......................................................................................105

.ListCount............................................................................................105

.ListIndex ............................................................................................106

.LoLimit ..............................................................................................106

.LoLoLimit ..........................................................................................108

.LoSet ..................................................................................................108

.LoLoSet..............................................................................................109

.LoLoStatus .........................................................................................109

.LoStatus..............................................................................................111

.MajorDevPct ......................................................................................111

.MajorDevSet ......................................................................................112

.MajorDevStatus..................................................................................112

.MaxEU ...............................................................................................114

.MaxRange ..........................................................................................114

.MaxRaw.............................................................................................116

.MinEU................................................................................................116

.MinorDevPct ......................................................................................118

.MinorDevSet ......................................................................................118

.MinorDevStatus .................................................................................119

.MinRange...........................................................................................119

.MinRaw..............................................................................................121

.Name ..................................................................................................121

.NewIndex ...........................................................................................123

.NextPage ............................................................................................123

.Normal ...............................................................................................124

.NumAlarms........................................................................................124

.OffMsg ...............................................................................................126

.OnMsg................................................................................................126

.PageNum............................................................................................126

.Pen1-.Pen8 .........................................................................................128

.PendingUpdates .................................................................................131

.PrevPage.............................................................................................131

.PriFrom ..............................................................................................133

.PriTo...................................................................................................133


Contents 7

.ProviderReq....................................................................................... 133

.ProviderRet........................................................................................ 135

.Quality............................................................................................... 135

.QualityLimit ...................................................................................... 139

.QualityLimitString ............................................................................ 139

.QualityStatus ..................................................................................... 139

.QualityStatusString ........................................................................... 141

.QualitySubstatus................................................................................ 141

.QualitySubstatusString...................................................................... 143

.QueryState ......................................................................................... 143

.QueryType ......................................................................................... 143

.RawValue .......................................................................................... 145

.ReadOnly........................................................................................... 145

.Reference........................................................................................... 147

.ReferenceComplete ........................................................................... 147

.ROCPct.............................................................................................. 148

.ROCSet.............................................................................................. 148

.ROCStatus ......................................................................................... 149

.ScooterLockLeft................................................................................ 149

.ScooterLockRight.............................................................................. 151

.ScooterPosLeft .................................................................................. 151

.ScooterPosRight ................................................................................ 153

.Successful.......................................................................................... 153

.SuppressRetain .................................................................................. 155

.TagID................................................................................................. 155

.TimeDate ........................................................................................... 155

.TimeDateString ................................................................................. 157

.TimeDateTime................................................................................... 157

.TimeDay............................................................................................ 157

.TimeHour .......................................................................................... 158

.TimeMinute ....................................................................................... 158

.TimeMonth........................................................................................ 158

.TimeMsec.......................................................................................... 159

.TimeSecond....................................................................................... 159

.TimeTime .......................................................................................... 159

.TimeTimeString................................................................................. 161

.TimeYear ........................................................................................... 161

.TopIndex............................................................................................ 161

.TotalPages ......................................................................................... 163

.UnAck ............................................................................................... 163

.UpdateCount...................................................................................... 165

.UpdateInProgress .............................................................................. 165

.UpdateTrend...................................................................................... 167


8 Contents

.Value...................................................................................................167

.Value...................................................................................................169

.Visible ................................................................................................170

CHAPTER 3: InTouch QuickScript Functions....171

Abs()....................................................................................................172Ack() ...................................................................................................172ActivateApp()......................................................................................173AddPermission() .................................................................................173almAckAll() ........................................................................................174almAckDisplay() .................................................................................174almAckGroup() ...................................................................................174almAckPriority() .................................................................................176almAckRecent() ..................................................................................176almAckSelect()....................................................................................177almAckSelectedGroup()......................................................................177almAckSelectedPriority()....................................................................178almAckSelectedTag()..........................................................................178almAckTag() .......................................................................................179almDefQuery() ....................................................................................180almMoveWindow() .............................................................................180almQuery() ..........................................................................................181almSelectAll() .....................................................................................182almSelectGroup() ................................................................................182almSelectionCount() ...........................................................................183almSelectItem() ...................................................................................183almSelectPriority() ..............................................................................184almSelectTag() ....................................................................................185almSetQueryByName().......................................................................185almShowStats() ...................................................................................186almSuppressAll() ................................................................................186almSuppressGroup() ...........................................................................187almSuppressDisplay() .........................................................................188almSuppressPriority() .........................................................................188almSuppressRetain() ...........................................................................189almSuppressSelected() ........................................................................189almSuppressTag()................................................................................190almSuppressSelectedGroup()..............................................................191almSuppressSelectedPriority()............................................................192almSuppressSelectedTag() ..................................................................192almUnSelectAll() ................................................................................193


Contents 9

almUnSuppressAll()........................................................................... 193ArcCos() ............................................................................................. 194ArcSin().............................................................................................. 194ArcTan() ............................................................................................. 195AttemptInvisibleLogon().................................................................... 195ChangePassword().............................................................................. 196Cos() ................................................................................................... 197DialogStringEntry()............................................................................ 197DialogValueEntry() ............................................................................ 199DText() ............................................................................................... 201EnableDisableKeys().......................................................................... 201Exp()................................................................................................... 201FileCopy() .......................................................................................... 203FileDelete()......................................................................................... 204FileMove().......................................................................................... 205FileReadFields() ................................................................................. 207FileReadMessage()............................................................................. 208FileWriteFields() ................................................................................ 209FileWriteMessage() ............................................................................ 210GetNodeName() ..................................................................................211GetPropertyD()....................................................................................211GetPropertyI() .................................................................................... 212GetPropertyM() .................................................................................. 212Hide .................................................................................................... 213HideSelf.............................................................................................. 213HTGetLastError()............................................................................... 214HTGetPenName()............................................................................... 215HTGetTimeAtScooter()...................................................................... 215HTGetTimeStringAtScooter()............................................................ 216HTGetValue() ..................................................................................... 217HTGetValueAtScooter()..................................................................... 218HTGetValueAtZone()......................................................................... 219HTScrollLeft().................................................................................... 220HTScrollRight() ................................................................................. 220HTSelectTag() .................................................................................... 221HTSetPenName() ............................................................................... 221HTUpdateToCurrentTime()................................................................ 222HTZoomIn() ....................................................................................... 222HTZoomOut() .................................................................................... 223InfoAppActive() ................................................................................. 224InfoAppTitle() .................................................................................... 224InfoDisk() ........................................................................................... 225InfoFile() ............................................................................................ 226


10 Contents

InfoInTouchAppDir()..........................................................................227InfoResources() ...................................................................................227Int()......................................................................................................227InvisibleVerifyCredentials()................................................................228IOGetApplication() .............................................................................228IOGetNode() .......................................................................................229IOGetTopic() .......................................................................................229IOReinitialize() ...................................................................................229IOSetAccessName()............................................................................230IOSetItem() .........................................................................................231IOStartUninitConversations() .............................................................232IsAnyAsynchFunctionBusy()..............................................................232IsAssignedRole().................................................................................233Log()....................................................................................................233LogMessage()......................................................................................234LogN().................................................................................................234Logoff() ...............................................................................................234Pi().......................................................................................................235PlaySound().........................................................................................235PostLogonDialog()..............................................................................236PrintHT().............................................................................................236PrintScreen() .......................................................................................237PrintWindow().....................................................................................239QueryGroupMembership()..................................................................241RecipeDelete() ....................................................................................241RecipeGetMessage() ...........................................................................241RecipeLoad().......................................................................................243RecipeSave() .......................................................................................244RecipeSelectNextRecipe() ..................................................................245RecipeSelectPreviousRecipe() ............................................................246RecipeSelectRecipe() ..........................................................................247RecipeSelectUnit() ..............................................................................248ReloadWindowViewer()......................................................................249RestartWindowViewer()......................................................................249Round() ...............................................................................................250SendKeys ............................................................................................251SetPropertyD() ....................................................................................252SetPropertyI()......................................................................................253SetPropertyM()....................................................................................253Sgn()....................................................................................................254Show....................................................................................................254ShowAt().............................................................................................255ShowHome..........................................................................................256


Contents 11

ShowTopLeftAt() ............................................................................... 256Sin().................................................................................................... 257SPCConnect()..................................................................................... 257SPCDatasetDlg() ................................................................................ 258SPCDisconnect() ................................................................................ 258SPCDisplayData() .............................................................................. 259SPCLocateScooter() ........................................................................... 259SPCMoveScooter()............................................................................. 260SPCSaveSample() .............................................................................. 260SPCSelectDataset() ............................................................................ 261SPCSelectProduct() ............................................................................ 261SPCSetControlLimits() ...................................................................... 262SPCSetMeasurement() ....................................................................... 262SPCSetProductCollected() ................................................................. 263SPCSetProductDisplayed() ................................................................ 263SPCSetRangeLimits() ........................................................................ 264SPCSetSpecLimits()........................................................................... 264SQLAppendStatement() ..................................................................... 265SQLClearParam()............................................................................... 265SQLClearStatement() ......................................................................... 265SQLClearTable() ................................................................................ 266SQLCommit()..................................................................................... 266SQLConnect() .................................................................................... 268SQLCreateTable() .............................................................................. 270SQLDelete() ....................................................................................... 270SQLDisconnect()................................................................................ 272SQLDropTable()................................................................................. 272SQLEnd() ........................................................................................... 272SQLErrorMsg() .................................................................................. 273SQLExecute()..................................................................................... 273SQLFirst() .......................................................................................... 274SQLGetRecord() ................................................................................ 274SQLInsert()......................................................................................... 274SQLInsertEnd() .................................................................................. 275SQLInsertExecute()............................................................................ 276SQLInsertPrepare() ............................................................................ 276SQLLast()........................................................................................... 277SQLLoadStatement() ......................................................................... 277SQLManageDSN()............................................................................. 278SQLNext().......................................................................................... 278SQLNumRows()................................................................................. 278SQLPrepareStatement() ..................................................................... 279SQLPrev() .......................................................................................... 280


12 Contents

SQLRollback() ....................................................................................280SQLSelect().........................................................................................281SQLSetParamChar() ...........................................................................284SQLSetParamDate()............................................................................284SQLSetParamDateTime() ...................................................................284SQLSetParamDecimal()......................................................................286SQLSetParamFloat() ...........................................................................286SQLSetParamInt()...............................................................................286SQLSetParamLong()...........................................................................288SQLSetParamNull() ............................................................................288SQLSetParamTime()...........................................................................290SQLSetStatement() .............................................................................290SQLTransact() .....................................................................................292SQLUpdate() .......................................................................................292SQLUpdateCurrent()...........................................................................294Sqrt() ...................................................................................................294StartApp ..............................................................................................295StringASCII()......................................................................................296StringChar().........................................................................................297StringFromIntg() .................................................................................298StringFromReal() ................................................................................299StringFromTime() ...............................................................................300StringFromTimeLocal() ......................................................................301StringInString() ...................................................................................302StringLeft()..........................................................................................303StringLen() ..........................................................................................304StringLower()......................................................................................304StringMid()..........................................................................................305StringReplace() ...................................................................................306StringRight() .......................................................................................307StringSpace().......................................................................................308StringTest()..........................................................................................309StringToIntg()......................................................................................310StringToReal().....................................................................................311StringTrim() ........................................................................................312StringUpper() ......................................................................................313Tan() ....................................................................................................313Text() ...................................................................................................314Trunc().................................................................................................314TseGetClientId()..................................................................................315TseQueryRunningOnConsole()...........................................................315TseQueryRunningOnClient() ..............................................................316wcAddItem() .......................................................................................316


Contents 13

wcClear()............................................................................................ 317wcDeleteItem()................................................................................... 317wcDeleteSelection() ........................................................................... 318wcErrorMessage() .............................................................................. 319wcFindItem()...................................................................................... 320wcGetItem() ....................................................................................... 321wcGetItemData()................................................................................ 322wcInsertItem() .................................................................................... 323wcLoadList() ...................................................................................... 324wcLoadText() ..................................................................................... 325wcSaveList()....................................................................................... 326wcSaveText()...................................................................................... 327wcSetItemData()................................................................................. 328WWControl() ..................................................................................... 329WWExecute()..................................................................................... 330WWPoke().......................................................................................... 331WWRequest()..................................................................................... 332

CHAPTER 4: OLE Automation and InTouch 333Elements of OLE Automation............................................................ 333InTouch OLE Automation Client Extensions .................................... 333

InTouch Automation Expressions................................................... 334Creating an Object: OLE_CreateObject ......................................... 337Managing an Object: OLE_ReleaseObject..................................... 337Testing for a Valid Object: OLE_IsObjectValid ............................. 338Getting a Property Value................................................................. 338Setting a Property ........................................................................... 340Calling a Method ............................................................................ 341InTouch Error Handling.................................................................. 343Frequent Automation Object Errors ............................................... 346

APPENDIX A: Troubleshooting QuickScript Functions .........................................................347

Error Messages for Windows Controls and Distributed Alarms .... 347Troubleshooting Recipe Script Functions ...................................... 348

SPC DDE Item Names ....................................................................... 350SPC Control and Display DDE Items............................................. 350SPC Current Sample DDE Items.................................................... 352SPC Manual Input DDE Items ....................................................... 356SPC Selection DDE Items .............................................................. 357Troubleshooting SQL Script Functions .......................................... 360

Specific Database Error Messages ..................................................... 362........................................................................................................ 362


14 Contents

Index................................................................365


Introduction 15

Introduction

This reference guide provides you with an alphabetic detailed reference for each tagname dot field (.field), windows controls property, alarm object property, system tagname and QuickScript function included in the InTouch product suite. Including the InTouch add-on products; Recipe Manager, SPC Pro and SQL Access Manager. This reference guide consists of:

• Chapter 1, "System Tagnames" details all InTouch pre-defined system tagnames.

Note All system tagnames begin with a dollar sign ($).

• Chapter 2, "Dot Fields" details the tagname .fields for tagnames, alarms, distributed alarms, windows controls, system, historical trending and other miscellaneous

• Chapter 3, "InTouch QuickScript Functions" details the built-in InTouch QuickScript functions (string, math, system, historical, windows controls, distributed alarms and miscellaneous functions).

• Chapter 4, “OLE Automation and InTouch” provides a brief outline of the OLE Automation architecture.

Document Conventions

To the right of each system tagname, property, dot field and script function table field, the usage category (security, alarm, application, etc.) is listed to provide easier referencing. For example:

$AccessLevelsecurity

Examples of Convention Description.ChartStart In general, bold text indicates a .field,

system tagname or function.Tagname In syntax, italic letters indicates

placeholders for information you supply.{ .HiLimit | .HiHiLimit } In syntax, braces and a vertical bar

indicate a choice between two or more items.

[ErrorMessage=] Items in square brackets are optional.


16 Before You Begin

About this ManualIf you are viewing this manual online, when you see text that is green, click the text to "jump" to the referenced section or chapter. When you jump to another section or chapter and you want to come back to the original section, a "back" option is provided.

Tip These are "tips" that tell you an easier or quicker way to accomplish a function or task.

The InTouch User's Guide will help you familiarize yourself with the WindowMaker development environment and its tools (read Chapter 1, "WindowMaker Program Elements.") To learn about working with windows, graphic objects, wizards, ActiveX controls and so on, read Chapter 2, "Using WindowMaker." To learn more about writing InTouch QuickScripts, read Chapter 06, "Creating QuickScripts in InTouch."

For details on the runtime environment (WindowViewer), see your InTouch Runtime User's Guide.

For details on the add-on program, SPC Pro, see your SPC Pro User's Guide.

For details on the add-on program, Recipe Manager, see your Recipe Manager User's Guide.

For details on the add-on program, SQL Access Manager, see your SQL Access Manager User's Guide.

The FactorySuite Systems Administrator's Guide also provides you with complete information on the common components in the FactorySuite, system requirements, networking considerations, product integration, technical support, and so on.

Online manuals are also included in your FactorySuite software package for all FactorySuite components.

Note You must install the Adobe Acrobat Reader (version 4.0 or later) to view or print the online manuals.

AssumptionsThis manual assumes you are:

• Familiar with the Windows 2000 and/or Windows NT operating system working environment.

• Knowledgeable of how to use of a mouse, Windows menus, select options, and accessing online Help.

• Experienced with a programming or macro language. For best results, you should have an understanding of programming concepts such as variables, statements, functions and methods.


Introduction 17

Technical SupportWonderware Technical Support offers a variety of support options to answer any questions on Wonderware products and their implementation.

Prior to contacting technical support, please refer to the relevant chapter(s) in your InTouch User's Guide for a possible solution to any problem you may have with your InTouch system. If you find it necessary to contact technical support for assistance, please have the following information available:

1. Your software serial number.

2. The version of InTouch you are running.

3. The type and version of the operating system you are using. For example, Microsoft Windows NT Version 4.0 SP4 workstation.

4. The exact wording of system error messages encountered.

5. Any relevant output listing from the Wonderware Logger, the Microsoft Diagnostic utility (MSD), or any other diagnostic applications.

6. Details of the attempts you made to solve the problem(s) and your results.

7. Details of how to recreate the problem.

8. If known, the Wonderware Technical Support case number assigned to your problem (if this is an on-going problem).

For more information on Technical Support, see your online FactorySuite System Administrator's Guide.

Your FactorySuite LicenseYour FactorySuite system license information can be viewed through the license viewing utility that is launched from the WindowMaker Help About dialog box.

To open license utility program

1. On the WindowMaker Help menu, select the About command.

2. Click View License. The License Utility - LicView dialog box appears.

For more information on the licensing viewing utility, see your online FactorySuite System Administrator's Guide.


18 Before You Begin


System Tagnames 19

C H A P T E R 1

System Tagnames

InTouch provides several pre-defined system tagnames. These tagnames are built into InTouch and can be identified by a preceding dollar sign ($). During runtime, InTouch acts upon the values of these tagnames in response to system events. System tagnames can be used anywhere an InTouch tagname can be used, such as in animation links or QuickScripts.

$AccessLevelDefines the access level of the currently logged-in user.

Category securityUsage $AccessLevel

Remarks This is a read-only tagname for which the value is determined by the Access Level assigned to the currently logged-in user's security profile within InTouch. This profile can be accessed through the Configure Users menu in WindowViewer.

The actual numeric value of $AccessLevel has no meaning to WindowViewer. Any "security" desired must be created by the application developer. By utilizing $AccessLevel, many things can be set to enable security within the system.

Data Type Integer (read only)Valid Values 0 through 9999Example(s) The following statement is used for the Visibility link to make an object, such

as a button, visible based on the logged on user's access level:

$AccessLevel >= 2000;{Objects can have a "disable" link associated with them,with the expression based on $AccessLevel.}$AccessLevel < 5411;

IF $AccessLevel <=500 THENShow "Access Denied"; {popup window denying access}

ELSEShow "Access Granted"; {popup window granting access}

ENDIF;

See Also $Operator, $OperatorEntered, $PasswordEntered; $ConfigureUsers


20 Chapter 1

$AlarmPrinterError

$AlarmPrinterNoPaper

Alarm printer error.Category alarmsUsage $AlarmPrinterError

Remarks Contains a value of 1 if there is a printer error on the alarm printer.Data Type Discrete (read only)Valid Values 0 = No error on alarm printer

1 = Error on alarm printerExample(s) The following statement, if used as the expression in an Analog Display Link,

displays a value of 1 if there is an error on the Alarm Printer; otherwise, it displays 0.

IF $AlarmPrinterError == 1 THENDisplayMessageTag = "Error on alarm printer";

ELSEDisplayMessageTag = "No error on alarm printer";

ENDIF;

See Also $AlarmPrinterNoPaper, $AlarmPrinterOffline, $AlarmPrinterOverflow

Alarm printer is out of paper.Category alarmsUsage $AlarmPrinterNoPaper

Remarks Contains a value of 1 if the alarm printer is out of paper.Data Type Discrete (read only)Valid Values 0 = Alarm printer has paper

1 = Alarm printer is out of paperExample(s) This statement, if used as the expression in an Analog Display Link, will

display a value of 1 if the alarm printer is out of paper; otherwise, it will display 0.

$AlarmPrinterNoPaper

Use in an On True condition action script:

Condition:$AlarmPrinterOffline == 1

Script:show"window";

playsound("c:\winnt\system32\alarm.wav",1);

See Also $AlarmPrinterOffline, $AlarmPrinterError, $AlarmPrinterOverflow


System Tagnames 21

$AlarmPrinterOffline

$AlarmPrinterOverflow

Alarm printer is offline.Category alarmsUsage $AlarmPrinterOffline

Remarks Contains a value of 1 if the printer is offline.Data Type Discrete (read only)Valid Values 0 = Alarm printer is online

1 = Alarm printer is offlineExample(s) This statement, if used as the expression in an Analog Display Link, will

display a value of 1 if the alarm printer is offline; otherwise, it will display 0.

$AlarmPrinterOffline

IF $AlarmPrinterOffline == 1 THENCall PLCHorn( );

{A Quick function which turns on an audible alarm on theplant floor}

ENDIF;

See Also $AlarmPrinterNoPaper, $AlarmPrinterError, $AlarmPrinterOverflow

Alarm printer buffer overflow.Category alarmsUsage $AlarmPrinterOverflow

Remarks Contains a value of 1 if there is an alarm printer error (too many characters sent to printer).

Data Type Discrete (read only)Valid Values 0 = Alarm printer buffer is not full

1 = Alarm printer buffer is full and being overflowedExample(s) The following statement, if used as the expression in an Analog Display Link,

displays a value of 1 if the alarm printer buffer is full; otherwise, it displays 0.

$AlarmPrinterOverflow

See Also $AlarmPrinterNoPaper, $AlarmPrinterOffline, $AlarmPrinterError


22 Chapter 1

$ApplicationChanged

$ApplicationVersion

Signals that the master application has changed in a Network Application Development (NAD) architecture.

Category applicationUsage $ApplicationChanged

Remarks This tagname changes to 1 every time the update signal is generated by selecting Notify Clients on the Special menu in WindowViewer. It is reset to 0 when the application is updated. Used for distributed application maintenance.

Data Type Discrete (read only)Example(s) The following statement, if used in a Data Change QuickScript's tagname

field, causes the body of the QuickScript to execute. The QuickScript's body could show a window informing the user to restart WindowViewer for the change to take effect.

$ApplicationChanged

See Also $ApplicationVersion

Contains the current version number of the application. This number changes each time a tagname or QuickScript is changed, added or deleted.

Category applicationUsage $ApplicationVersion

Remarks NoneData Type Real (read only)Example(s) Used in an Analog Display Link, this system tagname displays the current

version of the application that is running within WindowViewer.

$ApplicationVersion

See Also $ApplicationChanged


System Tagnames 23

$ChangePassword

$ConfigureUsers

Displays the Change Password dialog box. Equal to selecting Security then Change Password on the Special menu in WindowViewer.

Category securityUsage $ChangePassword

Remarks Setting the value to 1 causes the Change Password dialog box to appear. Once the dialog box is closed, InTouch automatically resets the value to 0. Setting this system tagname to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (write only)Valid Values 1Example(s) A discrete pushbutton can be created to allow the operator to open the

Change Password dialog box. The pushbutton should have a single Discrete Pushbutton link attached to it, with the Set option selected. When the button is pressed $ChangePassword, is set to 1 causing the Change Password dialog box to appear.

See Also $AccessLevel, $OperatorEntered, $PasswordEntered, $Operator, $ConfigureUsers

Displays the generic Configure Users dialog box. Equal to selecting Security then Change Password on the Special menu in WindowViewer.

Category securityUsage $ConfigureUsers

Remarks Setting the value to 1 causes the Configure Users dialog box to appear. Once the dialog box is closed, InTouch automatically resets the value to 0. The user must have an $AccessLevel of >9000 to display this dialog box. Setting this system tagname to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (write only)Valid Values 1Example(s) A discrete pushbutton can be created to allow the operator to open the

Change Password dialog box. The pushbutton should have a single Discrete Pushbutton link attached to it, with the Set option selected. When the button is pressed $ConfigureUsers, is set to 1 causing the Configure Users dialog box to appear.

See Also $Operator, $OperatorEntered, $ChangePassword, $PasswordEntered, $AccessLevel


24 Chapter 1

$Date

$DateString

$DateTime

Contains the whole number of days which have passed since 1/1/70.Category systemUsage $Date

Remarks NoneData Type Integer (read only)Example(s) StringFromTime(($Date*86400)+($Time/1000),3);

{Returns current time}

See Also $DateTime, $DateString, $Day, $Month, $Year

Contains the date in the same format set in the WIN.INI file.Category systemUsage $DateString

Remarks The date format is set through the Windows Control Panel or by double-clicking the Clock on the Windows Taskbar.

Data Type Memory message (read only)Example(s) If StringRight($DateString,2)== "00" THEN

LogMessage("The Year 2000!");

ENDIF;

See Also $Date, $DateTime, $Day, $Month, $Year, $Time, $TimeString

Contains the fractional number of days that have passed since 1/1/70.Category systemUsage $DateTime

Remarks NoneData Type Real (read only)Example(s) dayvalue = 86400 * $DateTime;

If StringFromTime(Dayvalue,4) == "Fri" THENDisplayMessageTag = "It's Friday!";

ENDIF;

See Also $Date, $DateString, $Day, $Month, $Year, $Time, $TimeString


System Tagnames 25

$Day

$HistoricalLogging

Contains the current day of the month.Category systemUsage $Day

Remarks Contains a value between 1 and 31.Data Type Integer (read only)Example(s) If $Day == 15 THEN

Show "Mid-Month Washdown Window";

ENDIF;

See Also $DateTime, $DateString, $Date, $Month, $Year

Monitors and/or controls starting and stopping of historical logging. Equal to selecting Restart Historical Logging on the Special menu in WindowViewer or, selecting Stop Historical Logging on the Special menu in WindowViewer.

Category historicalUsage $HistoricalLogging

Remarks Setting this system tagname equal to 0 stops historical logging. Setting the value to 1 restarts historical logging. You cannot "start" historical logging via $HistoricalLogging unless the Enable Historical Logging option is selected in the Historical Logging Properties dialog box.

Data Type Discrete (read / write)Example(s) IF (InfoDisk("C",4,$Second)/1024)<50 THEN

{Shutdown Historical logging if free space is less than50MB}$HistoricalLogging = 0;

ENDIF;


26 Chapter 1

$Hour

$InactivityTimeout

Contains the current hour of the day.Category systemUsage $Hour

Remarks Contains a value between 0 and 23.Data Type Integer (read only)Example(s) On True Condition QuickScript:

$Hour == 20 AND $Second == 30

PrintWindow("Day Batch Summary",1,1,0,0,0);

See Also $DateTime, $Minute, $Msec, $Second, $Time, $TimeString

Indicates that the time configured for the automatic log-off of the user has elapsed.

Category securityUsage $InactivityTimeout

Remarks Contains the value of 1 when automatic log-off has elapsed. To configure the tagname time, on the Special menu, point to Configure and then, click WindowViewer or, in the Application Explorer, under Configure, double-click WindowViewer. The WindowViewer Properties dialog box appears with the General properties sheet active. Enter the time value in seconds under the Inactivity group.

Note The inactivity timer does not reset for Active-X controls, OLE Automation controls and SPC wizards.

Data Type Discrete (read only)See Also $InactivityWarningExample(s) On True Condition QuickScript:

Condition:$InactivityTimeout == 1

Script:Show "You have been logged off window";

See Also $InactivityWarning


System Tagnames 27

$InactivityWarning

$LogicRunning

Indicates that the time configured for warning the user that log-off is about to occur has elapsed.

Category securityUsage $InactivityWarning

Remarks Contains the value of 1 when log-off is about to occur. The inactivity timer is reset by mouse clicks or keyboard activity only. To configure the tagname time, on the Special menu, point to Configure and then, click WindowViewer or, in the Application Explorer, under Configure, double-click WindowViewer. The WindowViewer Properties dialog box appears with the General properties sheet active. In the Inactivity group, type the time value in seconds.

Note The inactivity timer does not reset for Active-X controls, OLE Automation controls and SPC wizards.

Data Type Discrete (read only)Example(s) On True Condition QuickScript:

If $InactivityWarning == 1 THENShow "You are about to be logged off-window";

ENDIF;

See Also $InactivityTimeOut

Monitors and/or controls the running of scripts. Equal to selecting Start Logic on the Logic menu in WindowViewer or selecting Halt Logic on the Logic menu in WindowViewer. Note Asynchronous QuickFunctions that are currently executing cannot be stopped. However, you can prevent new QuickFunctions from executing.

Category systemUsage $LogicRunning

Remarks Setting the value to 1 starts the QuickScript logic. Setting the value to 0 stops the QuickScript logic.

Data Type Discrete (read / write)


28 Chapter 1

$Minute

$Month

$Msec

Contains the current minute of the hour.Category systemUsage $Minute

Remarks Contains a value between 0 and 59.Data Type Integer (read only)Example(s) In an animation link value output string expression:

IF InfoFile("C:\InTouch.32\WIZ.INI",1,$Minute)==1 THENLogMessage("The File Exists!");

ENDIF;

See Also $DateTime, $Hour, $Msec, $Second, $Time, $TimeString

Contains the current month of the year.Category systemUsage $Month

Remarks Contains a value between 1 and 12.Data Type Integer (read only)Example(s) IF $Month==10 THEN

CurrentMonthName = "October";

ENDIF;

See Also $Date, $Day, $Year

Contains the current milliseconds. The rate of update for this system tagname is increased by changing the settings for Tick Interval and Update Time Variables. On the Special menu, point to Configure and then, click WindowViewer or, in the Application Explorer under Configure, double-click WindowViewer. The WindowViewer Properties dialog box appears with the General properties sheet active.

Category systemUsage $Msec

Remarks Contains a value between 0 and 999.Data Type Integer (read only)See Also $DateTime, $Minute, $Second, $Hour, $Time, $TimeString


System Tagnames 29

$NewAlarm

$ObjHor

$ObjVer

Indicates that a new alarm has occurred.Category alarmsUsage $NewAlarm

Remarks Contains a value of 1 when a new alarm occurs. This is only set when a new local alarm occurs. It is not set for remote alarms.

Data Type Discrete (read / write)Example(s) This tagname can be linked to the PlaySound logic function, causing an

audible alarm to sound. An acknowledgment pushbutton can be created to allow the operator to reset this value to 0 and acknowledge the alarm.

Contains the horizontal pixel location of the center of a selected object.Category systemUsage $ObjHor

Remarks NoneData Type Integer (read only)See Also $ObjVer

Contains the vertical pixel location of the center of a selected object.Category systemUsage $ObjVer

Remarks NoneData Type Integer (read only)See Also $ObjHor


30 Chapter 1

$Operator

$OperatorDomain

Controls the user's ability to perform specific functions. Category securityUsage $Operator

Remarks Contains the name of the user currently logged on.Data Type Message (read only)Example(s) Access a specific window could be controlled by entering the following

script:

IF $Operator == "DayShift" THENShow "Control Panel Window";

ELSEShow "Wrong Operator";

ENDIF;

See Also $OperatorEntered, $AccessLevel, $PasswordEntered, $ChangePassword, $ConfigureUsers

Category SecurityUsage If operating system-based security is selected and an operator has

successfully logged on, the $OperatorDomain tag will contain the domain or machine name that was specified at log on. If ArchestrA security is selected a user is logged on, the $OperatorDomain will contain "ArchestrA." If InTouch securty is selected, the $OperatorDomain tag contains the string "InTouch." If "None" is selected, it is an empty string "".

Remarks N/AData Type StringExample(s) $Operator = "john";

$OperatorDomain="CORPORATE_HQ";

See Also $Operator


System Tagnames 31

$OperatorDomainEntered

$OperatorEntered

$OperatorName

Category SecurityUsage Whenever the $PasswordEntered tag changes, a log on is attempted

internally without any GUI being displayed. The log on attempt uses the $*Entered tags as input user name and the string value of $OperatorDomainEntered as the domain name ( used only if the current mode is operating system-based security ). If the security mode is not operating system-based, this tag is ignored.

Remarks N/AData Type StringExample(s) $OperatorEntered="john";

$OperatorDomainEntered="Corporate_hq";$PasswordEntered="password";

See Also $Operaror

Used to enter a valid user name. Category securityUsage $OperatorEntered

Remarks Creates a custom log-on window. Touch-sensitive input objects and/or QuickScripts can be linked to this tagname to set the "User Name" for the user.

Note When $OperatorEntered is valid, $AccessLevel and $Operator will be set to their pre-defined values.

Data Type Message (read / write)See Also $AccessLevel, $Operator, $PasswordEntered, $ChangePassword,

$ConfigureUsers

Category SecurityUsage The $OperatorName tag will contain the full legal name of the operator if

operating system-based or ArchestrA authentication is used and someone has logged on and has not logged off . Otherwise, the tag will contain the name of the user logged on (same contents as the $Operator tag).

Remarks N/AData Type StringExample(s) $Operator = "john";

$OperatorName = "John Smith";

See Also $Operator


32 Chapter 1

$PasswordEntered

$Second

$StartDdeConversations

Used to enter a valid password.Category securityUsage $PasswordEntered

Remarks This system tagname will always read back as an empty string. Display links tied to $PasswordEntered will always be blank. Since the tagname always returns an empty string, Data Change QuickScripts will never trigger off of $PasswordEntered. Can be used to create a custom log-on window. Touch-sensitive input objects and/or QuickScripts can be linked to this tagname to set the "Password" for the user.

Note When $PasswordEntered is valid, $AccessLevel and $Operator will be set to their pre-defined values.

Data Type Message (write only)See Also $AccessLevel, $Operator, $OperatorEntered, $ChangePassword,

$ConfigureUsers

Contains the current second.Category systemUsage $Second

Remarks Contains a value between 0 and 59.Data Type Integer (read only)Example(s) Wave=100*Sin(6*$Second);

See Also $DateTime, $Minute, $Msec, $Hour, $Time

Starts uninitiated conversations during runtime when the Special menu has been disabled. Equal to selecting Start Uninitiated Conversations on the Special menu in WindowViewer.

Category systemUsage $StartDdeConversations

Remarks Setting the value to 1 starts uninitiated DDE conversations.Data Type Discrete (read / write)


System Tagnames 33

$System

$Time

$TimeString

The default alarm group. Category alarmsUsage $System

Remarks If a tagname is not assigned to a specific Alarm Group name, it is automatically assigned to this root group by default. All defined Alarm Groups are descendants of $System.

Data Type System Alarm Group (read only)Example(s) $System.Ack = 1;{Acknowledges All Alarms}

Contains the time in milliseconds since midnight.Category systemUsage $Time

Remarks NoneData Type Integer (read only)Example(s) Sec_Midnight = $Time/1000;{Number of Seconds since

Midnight}

See Also $DateTime, $Minute, $Msec, $Second, $Hour, $TimeString

Contains the time in the same format set in the WIN.INI file.Category systemUsage $TimeString

Remarks The time format is set through the Windows Control Panel or by double-clicking the clock on the Windows Taskbar.

Data Type String (read only)Example(s) BatchStartString = $TimeString;

See Also $DateTime, $Minute, $Msec, $Second, $Hour, $Time


34 Chapter 1

$VerifiedUserName

$Year

Contains the verified user's full name if the call to InvisibleVerifyCredentials() is successful and if the security mode is set to operating system-based or ArchestrA AppServer-based security. If the call fails, then the above system tag will be set to null.

Category securityUsage $VerifiedUserName

Remarks Whenever the above system tag changes (meaning whenever InvisibleVerifiCredentials is called), an event will be generated and the column "Value" will contain the verified user's full name if the call was successful. The column "Value" will contain null if the call failed. The column Name will contain the value "$VerifiedUserFullName."

Data Type StringValid Values A User's full Name

Example(s) Tag = InvisibleVerifyCrdentials( "john","password","Plant_Floor"). If the call is successful, the$VerifiedUserName is set to "John Smith" and an OperatorEvent is generated. The name column indicates in the event$VerifiedUserName and the value column is set to "JohnSmith." If the above call is not successful,$VerifiedUserName and the value column in the event areset to "". Everytime the above script function is called,the $VerifiedUserName is set to the corresponding user'sfull name or to null.

See Also InvisibleVerifyCredentials(); $OperatorName, $Operator

Contains the current year in four digits.Category systemUsage $Year

Remarks Contains the year in the following format:2002

Data Type Integer (read only)Example(s) CurrentYear = $Year;

NoYrsTill2010 = 2002 - CurrentYear;

See Also $Day, $Month


Dotfields 35

C H A P T E R 2

Dotfields

InTouch uses dotfields to expose properties of objects such as tagnames, historical trends, and windows controls. You can use these dotfields to monitor and modify those properties. Depending on the object, these properties may be accessed in one of two ways: directly via a Tagname.field syntax, or indirectly via a script function.

All objects, except windows controls and the distributed alarm object, use the Tagname.field syntax. To access these properties, you simply type the object name followed by the property you want to access in an InTouch QuickScript or Animation link. For example, to allow runtime changes to the HiHi alarm limit on tagname Analog_Tag, you could create an Analog - User Input Touch link and then apply it to a pushbutton using Analog_Tag.HiHiLimit for its expression. Then, during runtime, the operator could click the button and type in a new value for the HiHi alarm limit being used for Analog_Tag.

Windows controls and the distributed alarm object use the GetPropertyX and SetPropertyX script functions (where X is the data type of the property (D = Discrete, I = Integer and M = Message.) You can also use these functions in InTouch QuickScripts or Animation links to access properties.

For more information on the GetProperty and SetProperty QuickScript functions, refer to Chapter 3, "InTouch QuickScript Functions."

Tagname TypesWhen you are defining tagnames in the InTouch Tagname Dictionary, you must assign a specific type to each tagname according to its usage. For example, if the tagname is to read or write values coming from or going to another Windows application such as an I/O server, it must be an I/O type tagname. The following describes each InTouch tagname type and its usage.


36 Chapter 2

Memory Type TagnamesMemory tagname types exist internally within your InTouch application. You use them to create system constants and simulations. You can also use them to create calculated variables that are accessed by other Windows programs. For example, you can define a memory tagname with the initial value of 3.1416 or, you could store recipes in groups of memory tagnames. In simulations, you can use memory tagnames to control the actions of a background script. For example, you could define a memory tagname "COUNT" that is changed in an action script to cause various animation effects to occur for the current STEP of a process. There are four Memory types:

Memory DiscreteInternal Discrete tagname with a value of either 0 (False, Off) or 1 (True, On).

Memory IntegerA 32-bit signed Integer value between -2,147,483,648 and 2,147,483,647.

Memory RealFloating (decimal) point Memory tagname. The floating point value may be between +3.4e38. All floating point calculations are performed with 64-bit resolution, but the result is stored in 32-bit.

Memory MessageText string tagname that can be up to 131 characters long.

I/O Type TagnamesAll tagnames that read or write their values from or to another Windows program are I/O type tagnames. This includes all inputs and outputs from programmable controllers, process computers and data from network nodes. I/O tagnames are accessed either through the Microsoft Dynamic Data Exchange (DDE) protocol or through the SuiteLink transport protocol.

When the value of a read/write I/O type tagname changes, it is immediately written to the remote application. The tagname may also be updated from the remote application whenever the item to which the tagname is linked changes in the remote application. By default, all I/O tagnames are set to read/write. However, you can restrict them to read only by selecting the Read Only option in the Tagname Dictionary dialog box. There are four I/O types:

I/O DiscreteDiscrete input/output tagname with a value of either 0 (False, Off) or 1 (True, On).


Dotfields 37

I/O IntegerA 32-bit signed integer value between -2,147,483,648 and 2,147,483,647.

I/O RealFloating (decimal) point tagname. The floating point value may be between +3.4e38. All floating point calculations are performed with 64-bit resolution, but the result is stored in 32-bit.

I/O MessageText string input/output tagname that can be up to 131 characters long.

Indirect Discrete, Indirect Analog, Indirect Message

Indirect type tagnames allow you to create one window and reassign the tagnames in that window to multiple sources. For example, you could create a Data Change script that would modify the source for all tagnames in a window based on a value that has changed.

Miscellaneous Type TagnamesThere are several special tagname types that you can assign to tagnames to perform complex functions such as creating dynamic alarm displays, historical trends, monitoring or controlling the tagname each historical trend pen is plotting. There are also indirect tagname types that you can use to reassign a tagname to multiple sources. These special tagname types are described below.

Hist TrendInTouch requires a Hist Trend type tagname when you create a historical trend. All of the dotfields associated with historical trends can be applied to Hist Trend tagnames.

Tag IDThis special type is used with historical trend objects. You use Tag ID type tagnames to retrieve information about tagnames being plotted in a historical trend. In most cases, you would use Tag ID tagnames to display the name of the tagname assigned to a specific pen or, to change the tagname assigned to the pen.

For more information on Historical Trending, see your online InTouch User's Guide.


38 Chapter 2

SuperTagsInTouch SuperTags allow you to define composite tagname types. You can define SuperTags with up to 64 members and 2 nesting levels. Members behave exactly like normal tagnames. They support trending, alarming and all tagname dotfields.

For more information on SuperTags see your InTouch User's Guide.

Tagname Type vs. Dotfield Usage MatrixThe matrix below illustrates a quick reference between the Tagname Type and the Dotfield. The footnotes below apply to the matrix on the next page.

If these Memory type tagnames are requested as I/O points from a client, View (server) provides its local time stamp the moment the value is sent to the client. However, from a local standpoint Memory tagnames always have GOOD quality, and NO Timestamp. This means that the timestamp is NOT updated based on the memory values changing in scripts or links.

*Supported in InTouch 7.0 or greater.

** Supported in InTouch 7.1 or greater.

*** Supported in InTouch 7.11 or greater

Tagname Types: Memory I/O Indirect Miscellaneous

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

DField Names.Ack X X X X X X X X X.AckDev*** X X X X X X.AckDsc X X X X.AckROC*** X X X X X X.AckValue*** X X X X X X.Alarm X X X X X X X X X.AlarmAccess ** X.AlarmAckModel*** X X X X X X X X X.AlarmClass ** X.AlarmComment ** Usage 1 X X X X X X X X X X.AlarmComment ** Usage 2 X.AlarmDate** X.AlarmDev X X X X X X.AlarmDevCount X X X X X X


Dotfields 39

.AlarmDevDeadband X X X X X

.AlarmDevUnAckCount X X X X X X

.AlarmDisabled*** X X X X X X X X X

.AlarmDsc X X X X

.AlarmDscCount X X X X

.AlarmDscDisabled X X X X

.AlarmDscEnabled X X X X

.AlarmDscInhibitor X X X X

.AlarmDscUnAckCount X X X X

.AlarmEnabled X X X X X X X X X

.AlarmGroup** X

.AlarmGroupSel ** X

.AlarmHiDisabled*** X X X X X X

.AlarmHiEnabled*** X X X X X X

.AlarmHiHiDisabled*** X X X X X X

.AlarmHiHiEnabled*** X X X X X X

.AlarmHiHiInhibitor*** X X X X X X

.AlarmHiInhibitor*** X X X X X X

.AlarmLimit ** X

.AlarmLoDisabled*** X X X X X X

.AlarmLoEnabled*** X X X X X X

.AlarmLoInhibitor*** X X X X X X

.AlarmLoLoDisabled*** X X X X X X

.AlarmLoLoEnabled*** X X X X X X

.AlarmLoLoInhibitor*** X X X X X X

.AlarmMajDevDisabled*** X X X X X X

.AlarmMajDevEnabled*** X X X X X X

.AlarmMajDevInhibitor*** X X X X X X

.AlarmMinDevDisabled*** X X X X X X

.AlarmMinDevEnabled*** X X X X X X

.AlarmMinDevInhibitor*** X X X X X X

.AlarmName ** X

.AlarmOprName ** X


Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

D


40 Chapter 2

.AlarmOprNode ** X

.AlarmPri ** X

.AlarmProv ** X

.AlarmROC X X X X X X

.AlarmROCCount X X X X X X

.AlarmROCDisabled*** X X X X X X

.AlarmROCEnabled*** X X X X X X

.AlarmROCInhibitor*** X X X X X X

.AlarmROCUnAckCount X X X X X X

.AlarmState ** X

.AlarmTime ** X

.AlarmTotalCount X X X X X X X X X

.AlarmType ** X

.AlarmUnAckCount X X X X X X X X X

.AlarmUserDefNum1*** X X X X X X X X X

.AlarmUserDefNum2*** X X X X X X X X X

.AlarmUserDefStr*** X X X X X X X X X

.AlarmValDeadband X X X X X

.AlarmValue ** X

.AlarmValueCount X X X X X X

.AlarmValueUnAckCount X X X X X X

.Caption X

.ChartLength X

.ChartStart X

.Comment X X X X X X X X X

.DevTarget X X X X X

.DisplayMode X

.Enabled X X X X X X X X

.EngUnits * X X X X X

.Freeze X

.HiHiLimit X X X X X

.HiHiSet ** X X X X X

.HiHiStatus X X X X X


Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

D


Dotfields 41

.HiLimit X X X X X

.HiSet ** X X X X X

.HiStatus X X X X X

.ListChanged X

.ListCount X

.ListIndex X

.LoLimit X X X X X

.LoLoLimit ** X X X X X

.LoLoSet X X X X X

.LoLoStatus X X X X X

.LoSet ** X X X X X

.LoStatus X X X X X

.MajorDevPct X X X X X

.MajorDevSet ** X X X X X

.MajorDevStatus X X X X X

.MaxEU X X X X X

.MaxRange X

.MaxRaw * X X X

.MinEU X X X X X

.MinorDevPct X X X X X

.MinorDevSet ** X X X X X

.MinorDevStatus X X X X X

.MinRange X

.MinRaw * X X X

.Name X X X X X X X X X X X X

.NewIndex X X

.NextPage X

.Normal X X X X X X X X X

.NumAlarms X

.OffMsg * X X X

.OnMsg * X X X

.PageNum X

.Pen1 through .Pen8 X


Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

D


42 Chapter 2

.PendingUpdates X

.PrevPage X

.PriFrom X

.PriTo X

.ProviderReq X

.ProviderRet X

.Quality X X X X X X X X

.QualityLimit * X X X X X X X X

.QualityLimitstring * X X X X X X X X

.QualityStatus * X X X X X X X X

.QualityStatusString * X X X X X X X X

.QualitySubstatus * X X X X X X X X

.QualitySubstatusString * X X X X X X X X

.QueryState X

.QueryType X

.RawValue * X X X

.ReadOnly X

.Reference X X X X X

.ReferenceComplete X X X X X

.ROCPct X X X X X

.ROCSet ** X X X X X

.ROCStatus X X X X X

.ScooterLockLeft X

.ScooterLockRight X

.ScooterPosLeft X

.ScooterPosRight X

.Successful X

.SuppressRetain X

.TagID X

.TimeDate * X X X X X X X X

.TimeDateString X X X X X X X X

.TimeDateTime X X X X X X X X

.TimeDay * X X X X X X X X


Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

D


Dotfields 43

.TimeHour * X X X X X X X X

.TimeMinute * X X X X X X X X

.TimeMonth * X X X X X X X X

.TimeMsec * X X X X X X X X

.TimeSecond * X X X X X X X X

.TimeTime * X X X X X X X X

.TimeTimeString X X X X X X X X

.TimeYear * X X X X X X X X

.TopIndex X

.TotalPages X

.UnAck X X X X X X X X X

.UpdateCount X

.UpdateinProgress X

.UpdateTrend X

.Value(Tagname) X X X X X X X X X X

.Value(Windows Control) X

.Visible X


Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Inte

ger

Rea

l

Dis

cret

e

Ana

log

Ala

rm G

roup

His

t Tre

nd

Dis

trib

uted

Ala

rmO

bjec

t / C

ontr

ols

TagI

D


44 Chapter 2

.Ack

.AckDev

Monitors and/or controls the alarm acknowledgment status of all types of local alarm(s).

Category alarmsUsage Tagname.Ack=1

Parameter DescriptionTagname Any Discrete, Integer or Real tagname, Indirect

Analog tagname or Alarm Group.Remarks Set this dotfield to a value of 1 to acknowledge any outstanding alarm(s) the

specified tagname/group may have associated with it. When the specified tagname is an Alarm Group, all unacknowledged alarms associated with the tagnames within the specified group are acknowledged. When the specified tagname is of any type other than Alarm Group, only the unacknowledged alarm associated with that tagname is acknowledged. Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (read/write)Valid Values 1Example(s) The following statement acknowledges an alarm associated with a tagname

named Tag1.

Tag1.Ack=1;

This next example would be used to acknowledge all unacknowledged alarms within the alarm group named PumpStation:

PumpStation.Ack=1;

Note .Ack has an inverse .field called .UnAck. When an unacknowledged alarm occurs, .UnAck will be set to 0. .UnAck can then be used in animation links or condition scripts to trigger enunciators for any unacknowledged alarms.

See Also .Alarm, .UnAck, .AckDev, AckROC, .AckDSC, .AckValue, .AlarmAckModel

Monitors and/or controls the alarm acknowledgment status of local deviation alarm(s).

Category alarmsUsage Tagname.AckDev=1

Parameter DescriptionTagname Any Integer or Real tagname, Indirect Analog

tagname or Alarm Group.


Dotfields 45

Remarks Set this dotfield to a value of 1 to acknowledge any outstanding deviation alarm(s) the specified tagname/group may have associated with it. When the specified tagname is an Alarm Group, all unacknowledged deviation alarms associated with the tagnames within the specified group are acknowledged. Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (read/write)Valid Values 1Example(s) The following statement acknowledges a deviation alarm associated with a

tagname named Tag1.

Tag1.AckDev=1;

This next example would be used to acknowledge all unacknowledged deviation alarms within the Alarm Group named PumpStation:

PumpStation.AckDev=1;

See Also .Alarm, .AlarmDev, .Ack, .UnAck, .AckDSC, .AckROC, .AckValue, .AlarmAckModel


46 Chapter 2

.AckDsc

.AckROC

Monitors and/or controls the alarm acknowledgment status of local Discrete alarm(s).

Category alarmsUsage Tagname.AckDsc=1

Parameter DescriptionTagname Any Indirect Discrete tagname or Alarm Group.

Remarks Set this dotfield to a value of 1 to acknowledge any outstanding discrete alarm(s) the specified tagname/group may have associated with it. When the specified tagname is an Alarm Group, all unacknowledged discrete alarms associated with the tagnames within the specified group are acknowledged. When the specified tagname is of any type other than Alarm Group, only the unacknowledged discrete alarm associated with that tagname is acknowledged. Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (read/write)Valid Values 1Example(s) The following statement acknowledges a Discrete alarm associated with a

tagname named Tag1.

Tag1.AckDsc=1;

This next example would be used to acknowledge all unacknowledged Discrete alarms within the Alarm Group named PumpStation:

PumpStation.AckDsc=1;

See Also .Alarm, .AlarmDSC, .Ack, .UnAck, .AckDev, .AckDSC, .AckROC, .AckValue, .AlarmAckModel

Monitors and/or controls the alarm acknowledgment status of local rate-of-change alarm(s).

Category alarmsUsage Tagname.AckROC=1


tagname or Alarm Group.Remarks Set this dotfield to a value of 1 to acknowledge any outstanding rate-of-

change alarm(s) the specified tagname/group may have associated with it. When the specified tagname is an Alarm Group, all unacknowledged rate-of-change alarms associated with the tagnames within the specified group are acknowledged. When the specified tagname is of any type other than Alarm Group, only the unacknowledged rate-of-change alarm associated with that tagname is acknowledged. Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.


Dotfields 47

Data Type Discrete (read/write)Valid Values 1Example(s) The following statement acknowledges a rate-of-change alarm associated

with a tagname named Tag1.

Tag1.AckROC=1;

This next example would be used to acknowledge all unacknowledged rate-of-change alarms within the Alarm Group named PumpStation:

PumpStation.AckROC=1;

See Also .Alarm, .AlarmROC, .Ack, .UnAck, .AckDev, .AckDSC, .AckValue, .AlarmAckModel


48 Chapter 2

.AckValue

.Alarm

Monitors and/or controls the alarm acknowledgment status of local value alarm(s).

Category alarmsUsage Tagname.AckValue=1


tagname or Alarm Group.Remarks Set this dotfield to a value of 1 to acknowledge any outstanding value

alarm(s) the specified tagname/group may have associated with it. When the specified tagname is an Alarm Group, all unacknowledged value alarms associated with the tagnames within the specified group are acknowledged. When the specified tagname is of any type, only the unacknowledged value alarm associated with that tagname is acknowledged. Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (read/write)Valid Values 1Example(s) The following statement acknowledges a value alarm associated with a

tagname named Tag1:

Tag1.AckValue=1;

This next example would be used to acknowledge all unacknowledged value alarms within the Alarm Group named PumpStation:

PumpStation.AckValue=1;

An Indirect AlarmGroup (using GroupVar) can be used to acknowledge value alarms. For example, using an assignment such as:

StationAlarms.Name = "PumpStation";

Where StationAlarms is defined as an Alarm Group type tagname and is then associated with PumpStation. Thus, the statement below is similar to the above examples, except it is used to acknowledge any unacknowledged value alarms within the alarm group PumpStation, which is currently associated with the Alarm Group tagname StationAlarms.

StationAlarms.AckValue=1

See Also .Alarm, .AlarmValue .Ack, .UnAck, .AckDev, .AckDSC, .AckROC, .AlarmAckModel

Equal to 1 when an alarm condition exists for the specified tagname or Alarm Group.

Category alarmsUsage Tagname.Alarm


Dotfields 49


Analog tagname or Alarm Group.Remarks This read-only dotfield is normally equal to 0. When an alarm condition

exists for the specified tagname, it is set to a value of 1 by the system. It will remain equal to 1 until the alarm condition no longer exists. If the specified tagname is the name of an Alarm Group, the .Alarm field will be set equal to 1 if any of the tagnames within that group are in alarm. .Alarm has an inverse dotfield called .Normal.

Data Type Discrete (read-only)Valid Values 0 or 1 (discrete)Example(s) The following statement verifies if Tag1 has an active alarm associated with

it:

IF (Tag1.Alarm == 1) THEN

The body of this IF-THEN statement would be processed if there were active alarms within the alarm group named PumpStation.

IF (PumpStation.Alarm == 1) THENMyAlarmMessage="The pumping station currently has anALARM!";

ENDIF;

This dotfield is not linked to the .Ack or .UnAck dotfield. Therefore, even when an active alarm has been acknowledged, this dotfield remains equal to 1.

See Also .Ack, .Normal, Ack()


50 Chapter 2

.AlarmAccess

.AlarmAckModel

Returns the access name of the tagname associated with a selected alarm. The alarm has to be selected by clicking on the Summary Distributed Alarm Display.

Category alarmsUsage GetPropertyM("Objectname.AlarmAccess",Tagname);

Parameter DescriptionObjectname Name of the Distributed Alarm Object.Tagname Any Memory Message tagname.

Data Type Memory Message (read-only)Example(s) The following statement returns the name of the tagname for a selected alarm:

GetPropertyM("AlmObj_1.AlarmAccess",almAccess);

Where AlmObj_1 is the name of the distributed alarm object and almAccess is a Memory Message tagname that will contain the access name of the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almAccess when the operator presses the button which can then be used for further processing or display. almAccess would then contain the access name of the tagname associated with the selected alarm.

See Also GetPropertyM(), .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType,

Monitors the acknowledgment model associated with the tagname as follows:

0 = condition (default)1 = event oriented2 = expanded summary

Category alarmsUsage Tagname.AlarmAckModel


Analog tagname or Alarm Group.Remarks This dotfield defaults to 0 (condition acknowledgment model). Data Type Analog (read-only)Valid Values 0, 1 or 2


Dotfields 51

Example(s) The body of this IF-THEN statement would be processed if PumpStation is an event alarm:

IF (PumpStation.AlarmAckModel == 1) THENMyAlarmMessage="PumpStation is an Event alarm";

ENDIF;

See Also .Alarm, .Ack, .UnAck, .AckDev, .AckDSC, .AckROC


52 Chapter 2

.AlarmClass

.AlarmComment

Returns the class of the tagname associated with a selected alarm. The alarm has to be selected by clicking on the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmClass",

Tagname);

Parameter DescriptionObjectName Name of the distributed alarm object. For example,

AlmObj_1.Tagname Any Memory Message tagname.

Data Type Memory Message (read-only)Example(s) The following statement returns the alarm class associated with the selected

alarm.

GetPropertyM("AlmObj_1.AlarmClass",almClass);

Where AlmObj_1 is the name of the distributed alarm object and almClass is a Memory Message tagname that will contain the class for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almClass when the operator presses the button which can then be used for further processing or display. almClass would then contain the alarm class associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue

Read/write text string that describes what the alarm is about, not the tagname. By default, it is empty in a new application.

However, when the old InTouch application is converted to 7.11, the tagname comment is copied to the .AlarmComment dotfield for backward compatibility.

Category alarmsUsage 1 Tagname.AlarmComment

Parameter DescriptionTagname Any InTouch tagname or Alarm Group.

Data Type Message (read/write)Usage 2 [ErrorNumber=]GetPropertyM("ObjectName.AlarmComment",Tagn

ame);

Parameter DescriptionTagname Memory Message tagname.


Dotfields 53

ObjectName Name of the distributed alarm object. For example, AlmObj_1.

Data Type Message (read-only)Example(s) Usage 1: The following example will return the alarm comment for Tag1 and

place it in mTag1. mTag1 is a Memory Message tagname:

mTag1=Tag1.AlarmComment;

Usage 2: The following example would return the alarm comment for a tagname selected in an distributed alarm object AlmObj_1 and place it in the Memory Message tagname almComment:

GetPropertyM(AlmObj_1.AlarmComment”, almComment);

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue


54 Chapter 2

.AlarmDate

.AlarmDev

Returns the date for the tagname associated with a selected alarm. The alarm has to be selected by clicking on the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmDate",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmDate",almDate);

Where AlmObj_1 is the name of the distributed alarm object and almDate is a Memory Message tagname that will contain the date for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almDate when the operator presses the button which can then be used for further processing or display. almDate would then contain the alarm date associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue, .AlarmValue

Equal to 1 when a deviation alarm condition exists for the specified tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmDev


tagname or Alarm Group.Remarks This read-only dotfield is normally equal to 0. When a deviation alarm

condition exists for the specified tagname, it is set to a value of 1 by the system. It will remain equal to 1 until the deviation alarm condition no longer exists. If the specified tagname is the name of an Alarm Group, the .AlarmDev will be set equal to 1 if any of the tagnames within that group are in deviation alarm.

Data Type Discrete (read-only)Valid Values 0 or 1 (discrete)


Dotfields 55

Example(s) The following statement verifies if Tag1 has an active deviation alarm associated with it:

IF (Tag1.AlarmDev == 1) THEN

The body of this IF-THEN statement would be processed if there were active deviation alarms within the alarm group named PumpStation.

IF (PumpStation.AlarmDev == 1) THENMyAlarmMessage="The pumping station currently has anALARM!";

ENDIF;

This dotfield is not linked to the .Ack or .UnAck dotfields. Therefore, even when an active alarm has been acknowledged, this dotfield remains equal to 1.

See Also .Ack, .UnAck, .Alarm, .AckDev


56 Chapter 2

.AlarmDevCount

.AlarmDevDeadband

Tracks the total number of deviation alarms active on a given tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmDevCount

Parameter DescriptionTagname Any Integer or Real tagname, or Alarm Group.

Remarks This includes the count of minor and major deviation alarms. It includes both acknowledged and unacknowledged alarms. For non-expanded summary alarm tagnames, this count will always be 1. However, the count may vary with alarm groups.

Data Type Analog (read-only)Valid Values 0 or any positive IntegerExample(s) ADC=Tag1.AlarmDevCount

Where Tag1 is an Analog tagname configured for Deviation alarms. ADC is also an Analog tagname, which gets the total number of active deviation (both UnAck and Ack) alarms present in Tag1.

See Also .AlarmDSCCount, .AlarmValueCount, .AlarmROCUnAckCount, .AlarmTotalCount, .AlarmDSCUnAckCount, .AlarmValueUnAckCount, .AlarmDevUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount

Monitors and/or controls the deviation percentage deadband for both minor and major deviation alarms.

Category alarmsUsage Tagname.AlarmDevDeadband

Parameter DescriptionTagname Any Integer or Real tagname, or Indirect Analog

tagname.Remarks Selecting the Retentive Parameters option in the Tagname Dictionary will

automatically save any changes made to this field through animation or scripting in WindowViewer.

Data Type Integer (read/write) Valid Values 0 through 100 (Integer)Example(s) The following statement changes the deviation deadband percentage to 25%:

Tagname.AlarmDevDeadband=25;

See Also .AlarmValDeadband, .AlarmDev


Dotfields 57

.AlarmDevUnAckCount

.AlarmDisabled

Tracks the total number of unacknowledged deviation alarms active on a given tagname or Alarm Group. This includes the count of minor and major deviation alarms.

Category alarmsUsage Tagname.AlarmDevUnAckCount

Parameter DescriptionTagname Any Integer, Real tagname, or Alarm Group.

Data Type Analog (read-only)Valid Values 0 or any positive IntegerExample(s) ADUC = Tag1.AlarmDevUnAckCount;

Where Tag1 is an Analog tagname configured for Deviation alarms. ADUC is also an Analog tagname, which gets the total number of unacknowledged deviation alarms present in Tag1.

See Also .AlarmDevCount, .AlarmDSCCount, .AlarmValueCount, .AlarmROCUnAckCount, .AlarmTotalCount, .AlarmDSCUnAckCount, .AlarmValueUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount

Disables and/or enables alarms for a tagname or an Alarm group.Category alarmsUsage Tagname.AlarmDisabled

Parameter DescriptionTagname Any Discrete, Integer, or Real tagname, Indirect

Discrete or Indirect Analog tagname, or Alarm Group.

Remarks When .AlarmDisabled is set equal to 1, all events and alarms are ignored. They are not stored in a buffer, nor are they written to disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

When the specified tagname is an Alarm Group, all alarms associated with the tagnames within the specified Alarm Group are disabled.The same as .AlarmEnabled, but of opposite polarity.

Data Type Discrete (read/write)Valid Values 0 = Enable alarms (default)

1 = Disable alarmsExample(s) The following example enables the alarms of the tagname Tag1.

Tag1.AlarmDisabled=0;

See Also .AlarmEnabled


58 Chapter 2

.AlarmDsc

.AlarmDscCount

Equal to 1 when a Discrete alarm condition exists for the specified tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmDsc

Parameter DescriptionTagname Any Discrete, Indirect, or Discrete tagname, or

Alarm Group.Remarks This read-only dotfield is normally equal to 0. When a Discrete alarm

condition exists for the specified tagname, it is set to a value of 1 by the system. It will remain equal to 1 until the Discrete alarm condition no longer exists. If the specified tagname is the name of an Alarm Group, the .AlarmDSC field will be set equal to 1 if any of the tagnames within that group are in discrete alarm.

Data Type Discrete (read/write)Valid Values 0 or 1Example(s) The following statement verifies if Tag1 has an active discrete alarm

associated with it:

IF (Tag1.AlarmDsc == 1) THENMyAlarmMessage="The pumping station currently has anALARM!";

ENDIF;

This dotfield is not linked to the .Ack or .UnAck dotfield. Therefore, even when an active alarm has been acknowledged, this dotfield remains equal to 1.

See Also .Ack, .UnAck, .Alarm, .AlarmDsc, .AckDsc

Tracks the total number of discrete alarms active on a given tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmDscCount

Parameter DescriptionTagname Any Discrete tagname or Alarm Group.

Remarks It includes both acknowledged and unacknowledged alarms. For non-expanded summary alarm tagnames, this count will always be 1. However, the count may vary with alarm groups.

Data Type Analog (read-only)Valid Values 0 or any positive Integer.


Dotfields 59

Example(s) ADC = Tag1.AlarmDSCCount

Where Tag1 is an Analog tagname configured for Discrete alarms. ADC is also an Analog tagname, which gets the total number of active discrete alarms (both UnAck and Ack) present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmValueCount, .AlarmROCUnAckCount, .AlarmTotalCount, .AlarmDscUnAckCount, .AlarmValueUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount


60 Chapter 2

.AlarmDscDisabled

.AlarmDscEnabled

Indicates whether or not the tagname can generate discrete alarms.Category alarmsUsage Tagname.AlarmDscDisabled


Remarks When .AlarmDscDisabled is set to 1, all discrete condition alarms and events are ignored. They are not stored in a buffer, nor are they written to a disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

The same as .AlarmDscEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Enable alarms (default)

1 = Disable alarmsExample(s) The following example enables the discrete alarms from Tag1:

Tag1.AlarmDscDisabled=0;

See Also .AlarmDscEnabled

Indicates whether or not the tagname can generate discrete alarms.Category alarmsUsage Tagname.AlarmDscEnabled


Remarks When .AlarmDscEnabled is set to 0, all events and alarms are ignored. They are not stored in a buffer, nor are they written to a disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

The same as .AlarmDscDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) The following example disables the discrete alarms from Tag1:

Tag1.AlarmDscEnabled=0;

See Also .AlarmDscDisabled


Dotfields 61

.AlarmDscInhibitor

.AlarmDscUnAckCount

Returns the name of the inhibitor tagname assigned to the discrete alarm(if any) for this tagname.

Category alarmsUsage Tagname.AlarmDscInhibitor


Remarks Configured in WindowMaker and cannot be changed at runtime.Data Type Message (read-only)Example(s) The .AlarmDSCInhibitor dotfield is used by setting .Name to an Indirect

tagname that is equal to the value of the .AlarmDscInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a discrete alarm (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmDscInhibitor;

The inhibition state of the alarmed tagname can be controlled by setting the value of the indirect tag as follows:

SomeIndirectTag = 1;

Turns on inhibitionDiscrete alarms are disabled for AlarmedTag


Turns off inhibitionDiscrete alarms can be generated for AlarmedTag

Tracks the total number of unacknowledged discrete alarms active on a given tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmDscUnAckCount


Data Type Analog (read-only)Valid Values All Integers and 0


62 Chapter 2

Example(s) ADUC = Tag1.AlarmDscUnACKCount;

Where Tag1 is an Analog tagname configured for Discrete alarms. ADUC is also an Analog tagname, which gets the total number of unacknowledged discrete alarms present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmValueCount, .AlarmROCCount, .AlarmTotalCount, .AlarmValueUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount


Dotfields 63

.AlarmEnabled

.AlarmGroup

Enables and/or disables alarms for a tagname or an Alarm Group.Category alarmsUsage Tagname.AlarmEnabled



Remarks When .AlarmEnabled is set equal to 0, all events and alarms are ignored. They are not stored in a buffer, nor are they written to disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

When the specified tagname is an Alarm Group, all alarms associated with the tagnames within the specified Alarm Group are enabled.The same as .AlarmDisabled, but of opposite polarity.

Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) The following example disables the alarms of the tagname Tag1:

Tag1.AlarmEnabled=0;

See Also .AlarmDisabled

Contains the current query used to populate a distributed alarm display object.Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmGroup",

Tagname);


AlmObj_1.Tagname A Message tagname that holds the property value

when the function is processed.Remarks This read-only dotfield contains the current alarm query used by the named

distributed alarm display object. This query may be a list of alarm groups or direct alarm provider references.

Data Type Message (read-only)Example(s) This statement returns the current alarm query used by the distributed alarm

object "AlmObj_1" to the Message tagname CurrentQuery:

GetPropertyM("AlmObj_1.AlarmGroup",CurrentQuery);

See Also GetPropertyM(), .AlarmGroupSel, .AlarmName


64 Chapter 2

.AlarmGroupSel

.AlarmHiDisabled

Returns the alarm group for the tagname associated with a selected alarm. The alarm has to be selected by clicking on the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmGroupSel",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmGroupSel",almGroup);

Where AlmObj_1 is the name of the distributed alarm object and almGroup is a Memory Message tagname that will contain the alarm group for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almGroup when the operator presses the button which can then be used for further processing or display. almGroup would then contain the alarm group associated with the selected alarm.

See Also GetPropertyM(), .AlarmGroup, .AlarmName

Disables and/or enables High condition events and alarms.Category alarmsUsage Tagname.AlarmHiDisabled


tagname, or Alarm Group. Remarks When .AlarmHiDisabled is set equal to 1, all High condition events and

alarms are ignored. They are not stored in a buffer, nor are they written to disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

The same as .AlarmHiEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) To enable Hi alarm:

Tag1.AlarmHiDisabled=0;

See Also .AlarmHiEnabled, .AlarmDisabled


Dotfields 65

.AlarmHiEnabled

.AlarmHiHiDisabled

Enables and/or disables High condition events and alarms.Category alarmsUsage Tagname.AlarmHiEnabled


tagname, or Alarm Group.Remarks When .AlarmHiEnabled is set equal to 0, all High condition events and


The same as .AlarmHiDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) To disable Hi alarm:

Tag1.AlarmHiEnabled=0;

See Also .AlarmHiDisabled, .AlarmEnabled

Disables and/or enables HiHi condition events and alarms.Category alarmsUsage Tagname.AlarmHiHiDisabled


tagname, or Alarm Group.Remarks When .AlarmHiHiDisabled is set equal to 1, all HiHi condition events and


The same as .AlarmHiHiEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) To enable HiHi alarm:

Tag1.AlarmHiHiDisabled=0;

See Also .AlarmHiHiEnabled, .AlarmDisabled


66 Chapter 2

.AlarmHiHiEnabled

.AlarmHiHiInhibitor

Enables and/or disables HiHi condition events and alarms.Category alarmsUsage Tagname.AlarmHiHiEnabled


tagname, or Alarm Group.Remarks When .AlarmHiHiEnabled is set equal to 0, all HiHi condition events and


The same as .AlarmHiHiDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) To disable HiHi alarm:

Tag1.AlarmHiHiEnabled=0;

See Also .AlarmHiHiDisabled, .AlarmEnabled

Returns a string containing the alarm inhibitor tagname associated with the HiHi alarm condition.

Category alarmsUsage Tagname.AlarmHiHiInhibitor

Parameter DescriptionTagname Analog tagnames with alarms or Alarm Group

Remarks Configured in WindowMaker. Cannot be changed during runtime.Data Type Message (read-only)


Dotfields 67

Example(s) The .AlarmHiHiInhibitor dotfield is used by setting .Name to an Indirect tagname that is equal to the value of the .AlarmHiHiInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a HiHi alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):SomeIndirectTag.Name = AlarmedTag.AlarmHiHiInhibitor;The inhibition state of the alarmed tagname can be controlled by setting the value of the indirect tagname as follows:


Turns on inhibitionHiHi alarms are disabled for AlarmedTag


Turns off inhibitionHiHi alarms can be generated for AlarmedTag

See Also .AlarmHiInhibitor, .AlarmLoInhibitor, .AlarmLoLoInhibitor


68 Chapter 2

.AlarmHiInhibitor

.AlarmLimit

Returns the alarm inhibitor tagname associated with the High alarm condition.

Category alarmsUsage Tagname.AlarmHiInhibitor


Remarks Configured in WindowMaker. Cannot be changed during runtime.Data Type Message (read-only)Example(s) The .AlarmHiInhibitor dotfield is used by setting .Name to an Indirect

tagname that is equal to the value of the .AlarmHiInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a High alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmHiInhibitor;

The inhibition state of the alarmed tagname can be controlled by setting the value of the Indirect tagname as follows:


Turns on inhibitionHi alarms are disabled for AlarmedTag


Turns off inhibitionHi alarms can be generated for AlarmedTag

See Also .AlarmHiHiInhibitor, .AlarmLoInhibitor, .AlarmLoLoInhibitor

Returns the limit for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.AlarmLimit",

Tagname);


AlmObj_1.Tagname Any Message tagname.

Data Type Message (read-only)


Dotfields 69

Example(s) GetPropertyI("AlmObj_1.AlarmLimit", almLimit);

Where AlmObj_1 is the name of the distributed alarm object and almLimit is a Memory Message tagname that will contain the alarm limit for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almLimit when the operator presses the button which can then be used for further processing or display. almLimit would then contain the alarm limit associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue


70 Chapter 2

.AlarmLoDisabled

.AlarmLoEnabled

.AlarmLoInhibitor

Disables and/or enables Low condition events and alarms.Category alarmsUsage Tagname.AlarmLoDisabled


tagname, or Alarm Group.Remarks When .AlarmLoDisabled is set equal to 1, all Low condition events and


The same as .AlarmLoEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) Tag1.AlarmLoDisabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmLoEnabled

Enables and/or disables Low condition events and alarms.Category alarmsUsage Tagname.AlarmLoEnabled


tagname, or Alarm Group. Remarks When .AlarmLoEnabled is set equal to 0, all Low condition events and


The same as .AlarmLoDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) Tag1.AlarmLoEnabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmLoDisabled

Returns the alarm inhibitor tagname associated with a Low alarm condition. Category alarms


Dotfields 71

Usage Tagname.AlarmLoInhibitor

Parameter DescriptionTagname Analog tagnames with alarms or Alarm Group.

Remarks Configured in WindowMaker. Cannot be changed during runtime.Data Type Message (read-only)Example(s) The .AlarmLoInhibitor dotfield is used by setting .Name to an Indirect

tagname that is equal to the value of the .AlarmLoInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a Low alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmLoInhibitor;



Turns on inhibitionLo alarms are disabled for AlarmedTag


Turns off inhibitionLo alarms can be generated for AlarmedTag

See Also .AlarmHiInhibitor, .AlarmHiHiInhibitor, .AlarmLoLoInhibitor


72 Chapter 2

.AlarmLoLoDisabled

.AlarmLoLoEnabled

.AlarmLoLoInhibitor

Disables and/or enables LoLo condition events and alarms.Category alarmsUsage Tagname.AlarmLoLoDisabled


tagname, or Alarm Group.Remarks When .AlarmLoLoDisabled is set equal to 1, all LoLo condition events and


The same as .AlarmLoLoEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) Tag1.AlarmLoLoDisabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmLoLoEnabled

Enables and/or disables LoLo condition events and alarms.Category alarmsUsage Tagname.AlarmLoLoEnabled


tagname, or Alarm Group. Remarks When .AlarmLoLoEnabled is set equal to 0, all LoLo condition events and


The same as .AlarmLoLoDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) Tag1.AlarmLoLoEnabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmLoLoDisabled

Returns the alarm inhibitor tagname associated with a LoLo alarm condition. Category alarms


Dotfields 73

Usage Tagname.AlarmLoLoInhibitor


Remarks Configured in WindowMaker. Cannot be changed during runtime.Data Type Message (read-only)Example(s) The .AlarmLoLoInhibitor dotfield is used by setting .Name to an Indirect

tagname that is equal to the value of the .AlarmLoLoInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a LoLo alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmLoLoInhibitor;The inhibition state of the alarmed tagname can be controlled by setting the value of the Indirect tagname as follows:


Turns on inhibitionLoLo alarms are disabled for AlarmedTag


Turns off inhibitionLoLo alarms can be generated for AlarmedTag

See Also .AlarmHiInhibitor, .AlarmHiHiInhibitor, .AlarmLoInhibitor


74 Chapter 2

.AlarmMajDevDisabled

.AlarmMajDevEnabled

Disables and/or enables major deviation events and alarms.Category alarmsUsage Tagname.AlarmMajDevDisabled


tagname, or Alarm Group. Remarks When .AlarmMajDevDisabled is set equal to 1, all major deviation events

and alarms are ignored. They are not stored in a buffer, nor are they written to disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

The same as .AlarmMajDevEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) Tag1.AlarmMajDevDisabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmMajDevEnabled

Enables and/or disables major deviation events and alarms.Category alarmsUsage Tagname.AlarmMajDevEnabled


tagname, or Alarm Group. Remarks When .AlarmMajDevEnabled is set equal to 0, all major deviation events


The same as .AlarmMajDevDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) Tag1.AlarmMajDevEnabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmMajDevDisabled


Dotfields 75

.AlarmMajDevInhibitor

.AlarmMinDevDisabled

Returns the alarm inhibitor tagname associated with the major deviation alarm condition.

Category alarmsUsage Tagname.AlarmMajDevInhibitor


Remarks Configured in WindowMaker. Cannot be changed during runtime.Data Type Message (read-only)Example(s) The .AlarmMajDevInhibitor dotfield is used by setting .Name to an

Indirect tagname that is equal to the value of the .AlarmMajDevInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a major deviation alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmMajDevInhibitor;



Turns on inhibitionMajor deviation alarms are disabled for AlarmedTag


Turns off inhibitionMajor deviation alarms can be generated for AlarmedTag

See Also .AlarmMinDevInhibitor

Disables and/or enables minor deviation events and alarms.Category alarmsUsage Tagname.AlarmMinDevDisabled


tagname or Alarm Group. Remarks When .AlarmMinDevDisabled is set equal to 1, all minor deviation events


The same as .AlarmMinDevEnabled, but of opposite polarity.Data Type Discrete (read/write)


76 Chapter 2

Valid Values 1 = Disable alarms0= Enable alarms (default)

Example(s) Tag1.AlarmMinDevDisabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmMinDevEnabled


Dotfields 77

.AlarmMinDevEnabled

.AlarmMinDevInhibitor

Enables and/or disables minor deviation events and alarms.Category alarmsUsage Tagname.AlarmMinDevEnabled


tagname or Alarm Group. Remarks When .AlarmMinDevEnabled is set equal to 0, all minor deviation events


The same as .AlarmMinDevDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) Tag1.AlarmMinDevEnabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmMinDevDisabled

Returns the alarm inhibitor tagname associated with a minor deviation alarm condition.

Category alarmsUsage Tagname.AlarmMinDevInhibitor




78 Chapter 2

Example(s) The .AlarmMinDevInhibitor dotfield is used by setting .Name to an Indirect tagname that is equal to the value of the .AlarmMinDevInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a minor deviation alarm limit (assuming SomeIndirectTag is an Analog Indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmMinDevInhibitor;



Turns on inhibitionMinor deviation alarms are disabled for AlarmedTag


Turns off inhibitionMinor deviation alarms can be generated for AlarmedTag

See Also .AlarmMajDevInhibitor


Dotfields 79

.AlarmName

.AlarmOprName

Returns the name of the alarm for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmName",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmName", almName);

Where AlmObj_1 is the name of the distributed alarm object and almName is a Memory Message tagname that will contain the name of the alarm limit for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almName when the operator presses the button which can then be used for further processing or display. almName would then contain the alarm name associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue

Returns the operator name for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmOprName",

Tagname);



Data Type Memory Message (read-only)


80 Chapter 2

Example(s) GetPropertyM("AlmObj_1.AlarmOprName", almOprName);

Where AlmObj_1 is the name of the distributed alarm object and almOprName is a Memory Message tagname that will contain the name of the operator for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almOprName when the operator presses the button which can then be used for further processing or display. almOprName would then contain the alarm operator name associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue


Dotfields 81

.AlarmOprNode

.AlarmPri

Returns the operator node for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmOprNode",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmOprNode", almOprNode);

Where AlmObj_1 is the name of the distributed alarm object and almOprNode is a Memory Message tagname that will contain the name of the operator's node for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almOprNode when the operator presses the button which can then be used for further processing or display. almOprNode would then contain the alarm operator node associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue

Returns the priority (1-999) for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmPri",

Tagname);


AlmObj_1.Tagname Any Analog tagname.

Data Type Memory Message (read-only)Valid Values Integer (1-999) (read-only)


82 Chapter 2

Example(s) GetPropertyI("AlmObj_1.AlarmPri", almPri);

Where AlmObj_1 is the name of the distributed alarm object and almPri is an Integer tagname that will contain the priority level for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almPri when the operator presses the button which can then be used for further processing or display. almPri would then contain the priority associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue


Dotfields 83

.AlarmProv

.AlarmROC

Returns the provider for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmProv",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmProv", almProv);

Where AlmObj_1 is the name of the distributed alarm object and almProv is a Memory Message tagname that will contain the name of the provider for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almProv when the operator presses the button which can then be used for further processing or display. almProv would then contain the alarm provider associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmState, .AlarmTime, .AlarmType, .AlarmValue

Equal to 1 when a rate-of-change alarm condition exists for the specified tagname.

Category alarmsUsage Tagname.AlarmROC


tagname or Alarm Group.Remarks This read-only dotfield is normally equal to 0. When a rate-of-change alarm

condition exists for the specified tagname, it is set to a value of 1 by the system. It will remain equal to 1 until the rate-of-change alarm condition no longer exists. If the specified tagname is the name of an Alarm Group, the .Alarm will be set equal to 1 if any of the tagnames within that group are in rate-of-change alarm.

Data Type Discrete (read-only)Valid Values 0 or 1 (discrete)


84 Chapter 2

Example(s) The following statement verifies if Tag1 has an active rate-of-change alarm associated with it:

IF (Tag1.AlarmROC == 1) THEN

The body of this IF-THEN statement would be processed if there were active rate-of-change alarms within the alarm group named PumpStation.

IF (PumpStation.AlarmROC == 1) THENMyAlarmMessage="The pumping station currently has anALARM!";

ENDIF;

This dotfield is not linked to the .Ack or .UnAck dotfield. Therefore, even when an active rate-of-change alarm has been acknowledged, this dotfield remains equal to 1.

See Also .Ack, .AckROC, .Alarm, .AlarmROCEnabled, .AlarmROCDisabled


Dotfields 85

.AlarmROCCount

.AlarmROCDisabled

Tracks the total number of rate-of-change alarms active on a given tagname or alarm group. It includes both acknowledged and unacknowledged alarms. For non-expanded summary alarm tagnames, this count will always be 1. However, the count may vary with alarm groups. This dotfield is read-only.

Category alarmsUsage Tagname.AlarmROCCount


RemarksData Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) ARC = Tag1.AlarmROCCount

Where Tag1 is an Analog tag name configured for rate-of-change alarms. ARC is also an Analog tagname, which gets the total number of active rate-of-change alarms (both UnAck and Ack) present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmDscUnAckCount, .AlarmValueCount, .AlarmTotalCount, .AlarmValueUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount

Disables and/or enables rate-of-change events and alarms.Category alarmsUsage Tagname.AlarmROCDisabled


tagname or Alarm Group. Remarks When .AlarmROCDisabled is set equal to 1, all rate-of-change events and


The same as .AlarmROCEnabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 1 = Disable alarms

0 = Enable alarms (default)Example(s) Tag1.AlarmROCDisabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmROCEnabled


86 Chapter 2

.AlarmROCEnabled

.AlarmROCInhibitor

Enables and/or disables rate-of-change events and alarms.Category alarmsUsage Tagname.AlarmROCEnabled


tagname or Alarm Group. Remarks When .AlarmROCEnabled is set equal to 0, all rate-of-change condition

events and alarms are ignored. They are not stored in a buffer, nor are they written to disk. It is very important to re-enable events/alarms, whenever possible, to avoid data loss.

The same as .AlarmROCDisabled, but of opposite polarity.Data Type Discrete (read/write)Valid Values 0 = Disable alarms

1 = Enable alarms (default)Example(s) Tag1.AlarmROCEnabled=0;

See Also .AlarmDisabled, .AlarmEnabled, .AlarmROCDisabled

Returns the alarm inhibitor tagname associated with a rate-of-change alarm condition.

Category alarmsUsage Tagname.AlarmROCInhibitor




Dotfields 87

Example(s) The .AlarmROCInhibitor dotfield is used by setting .Name to an Indirect tagname that is equal to the value of the .AlarmROCInhibitor tagname then manipulating the value of the Indirect tagname. The following statement returns the name of the alarm inhibitor tagname for a rate-of-change alarm limit (assuming SomeIndirectTag is an Analog indirect tagname):

SomeIndirectTag.Name = AlarmedTag.AlarmROCInhibitor;



Turns on inhibitionRate-of-change alarms are disabled for AlarmedTag


Turns off inhibitionRate-of-change alarms can be generated for AlarmedTag


88 Chapter 2

.AlarmROCUnAckCount

.AlarmState

Tracks the total number of unacknowledged rate-of-change alarms active on a given tagname or Alarm Group.

Category AlarmsUsage Tagname.AlarmROCUnAckCount


Data Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) ARUC = Tag1.AlarmROCUnACKCount;

Where Tag1 is an Analog tagname configured for rate-of-change alarms. ARUC is also an Analog tagname, which gets the total number of unacknowledged rate-of-change alarms present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmDscUnAckCount, .AlarmValueCount, .AlarmTotalCount, .AlarmValueUnAckCount, .AlarmROCCount, .AlarmUnAckCount

Returns the state for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmState",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmState", almState);

Where AlmObj_1 is the name of the distributed alarm object and almState is a Memory Message tagname that will contain the alarm state for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almState when the operator presses the button which can then be used for further processing or display. almState would then contain the alarm state associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmTime, .AlarmType, .AlarmValue


Dotfields 89

.AlarmTime

.AlarmTotalCount

Returns the time for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmTime",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmTime", almTime);

Where AlmObj_1 is the name of the distributed alarm object and almTime is a Memory Message tagname that will contain the time for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almTime when the operator presses the button which can then be used for further processing or display. almTime would then contain the alarm time associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmType, .AlarmValue

Tracks the total number of alarms active on a given tagname or Alarm Group.Category alarmsUsage Tagname.AlarmTotalCount

Parameter DescriptionTagname All types of tagnames.

Remarks This includes the count of value, deviation, rate-of-change and discrete alarms. It includes both acknowledged and unacknowledged alarms.

Data Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) ATC = Tag1.AlarmTotalCount;

Where Tag1 is an Analog tagname configured for alarms. ATC is also an Analog tagname, which gets the total number of all active alarms (both UnAck and Ack) present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDSCCount, .AlarmDSCUnAckCount, .AlarmValueCount, .AlarmUnAckCount, .AlarmValueUnAckCount, .AlarmROCCount, .AlarmROCUnACkCount


90 Chapter 2

.AlarmType

.AlarmUnAckCount

Returns the type for the tagname associated with a selected alarm. The alarm has to be selected by clicking the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmType",

Tagname);



Data Type Memory Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmType", almType);

Where AlmObj_1 is the name of the distributed alarm object and almType is a Memory Message tagname that will contain the type for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almType when the operator presses the button which can then be used for further processing or display. almType would then contain the alarm type associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmValue

Tracks the total number of unacknowledged alarms active on a given tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmUnAckCount

Parameter DescriptionTagname All types of tagnames.

Remarks This includes the count of value, deviation, rate-of-change and discrete alarms.

Data Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) AUC = Tag1.AlarmUnAckCount;

Where Tag1 is an Analog or discrete tag name configured for alarms. AUC is also an Analog tagname, which gets the total number of unacknowledged alarms present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmDscUnAckCount, .AlarmValueCount, .AlarmTotalCount, .AlarmValueUnAckCount, .AlarmROCCount, .AlarmROCUnACkCount


Dotfields 91

.AlarmUserDefNum1If you set this dotfield, it is attached to the information recorded for each alarm by Alarm DB Logger in the alarm database. (.AlarmUserDefNum1 corresponds to database field User1.) You can use the "user-defined" columns in a SELECT statement to select particular collections of alarms for database operations. For example, if $System.AlarmUserDefNum1 is set to a Batch Number and is changed each time the Batch changes, a selection involving the database field User1 can be used to select alarms for particular batches.

Category alarmsUsage Tagname.AlarmUserDefNum1



Remarks This user-defined dotfield is enabled for a wide range of tagnames, particularly Discrete tagnames, Analog tagnames, and Alarm Groups (whether or not they have alarms defined). You can leave these items unset, set all of them, or set only some of them for any individual tagname, group, or parent group.

Data Type Analog (read/write)Valid Values 0.0 and not set (default)Example(s) The value of this dotfield is attached to the alarm, but ONLY if a value has

been set, for example, via a script or a POKE.

$System.AlarmUserDefNum1 = 4;GroupA.AlarmUserDefNum1 = 27649;

All of the above examples use constant values. However, you can use InTouch QuickScripting to copy the value of another tagname to any of these user-defined fields. You can also use PtAcc to set or inspect them, or use InTouch as an I/O server to get or set the values.

In concept, the lowest-level setting prevails, when an alarm notification is sent to the Distributed Alarm System. That is, if the tagname has .AlarmUserDefNum1 set to some value, the alarm record should be populated using that setting. However, if the tagname doesn't have one, WindowViewer will check if the tagname's alarm group has one, and so on up the line until the root group $System is reached. If no setting is found at any level, the entry in the alarm record will be left empty (zero for numbers, an empty string for strings).

Note This hierarchical search is handled independently for each item. Therefore, if a tagname has a setting for .AlarmUserDefNum2 but not for .AlarmUserDefNum1, but its parent group has a setting for .AlarmUserDefNum1, the tagname will inherit the setting for .AlarmUserDefNum1 from its parent group.

See Also .AlarmUserDefNum2, .AlarmUserDefStr


92 Chapter 2

.AlarmUserDefNum2If you set this dotfield, it is attached to the information recorded for each alarm by AlarmLogger in the alarm database. (.AlarmUserDefNum2 corresponds to database field User2.) You can use the "user-defined" columns in a SELECT statement to select particular collections of alarms for database operations. For example, if $System.AlarmUserDefNum2 is set to a Batch Number and is changed each time the Batch changes, a selection involving the database field User2 can be used to select alarms for particular batches.

Category alarmsUsage Tagname.AlarmUserDefNum2




Data Type Analog (read/write)Valid Values 0.0 and not set (default)Example(s) The value of this dotfield is attached to the alarm, but ONLY if a value has


$System.AlarmUserDefNum2 = 4;GroupA.AlarmUserDefNum2 = 27649;

All of the above examples use constant values. However, you can use InTouch QuickScripting to copy the value of another tagname to any of these user-defined fields. You can also use PtAcc to set or inspect them, or use InTouch as an I/O server to get or set the values.

In concept, the lowest-level setting prevails, when an alarm notification is sent to the Distributed Alarm System. That is, if the tagname has .AlarmUserDefNum2 set to some value, the alarm record should be populated using that setting. However, if the tagname doesn't have one, WindowViewer will check if the tagname's alarm group has one, and so on up the line until the root group $System is reached. If no setting is found at any level, the entry in the alarm record will be left empty (zero for numbers, an empty string for strings).

Note This hierarchical search is handled independently for each item. Therefore, if a tagname has a setting for .AlarmUserDefNum1 and not for .AlarmUserDefNum2, but its parent group has a setting for .AlarmUserDefNum2, the tagname will inherit the setting for .AlarmUserDefNum2 from its parent group.

See Also .AlarmUserDefNum1, .AlarmUserDefStr


Dotfields 93

.AlarmUserDefStrIf you set this dotfield, it is attached to the information recorded for each alarm by Alarm DB Logger in the alarm database. (.AlarmUserDefStr corresponds to database field User3.) You can use the "user-defined" columns in a SELECT statement to select particular collections of alarms for database operations. For example, if $System.AlarmUserDefStr is set to a Batch String and is changed each time the Batch changes, a selection involving the database field User3 can be used to select alarms for particular batches.

Category alarmsUsage Tagname.AlarmUserDefStr




Data Type Message (read/write)Valid Values NULL and any valid stringExample(s) The value of this dotfield is attached to the alarm, but ONLY if a value has


Tag04.AlarmUserDefStr = "Joe";

This example uses a constant value. However, you can use InTouch QuickScripting to copy the value of another tagname to any of these user-defined fields. You can also use PtAcc to set or inspect them, or use InTouch as an I/O server to get or set the values.

In concept, the lowest-level setting prevails, when an alarm notification is sent to the Distributed Alarm System. That is, if the tagname has .AlarmUserDefStr set to some value, the alarm record should be populated using that setting. However, if the tagname doesn't have one, WindowViewer will check if the tagname's alarm group has one, and so on up the line until the root group $System is reached. If no setting is found at any level, the entry in the alarm record will be left empty (zero for numbers, an empty string for strings).

Also note that this hierarchical search is handled independently for each item. Therefore, if a tagname has a setting for .AlarmUserDefNum1 but not for .AlarmUserDefStr, but its parent group has a setting for .AlarmUserDefStr, that setting will be used in the alarm record.

See Also .AlarmUserDefNum1, .AlarmUserDefNum2


94 Chapter 2

.AlarmValDeadband

.AlarmValue

Monitors and/or controls the value of an alarm's deadband.Category alarmsUsage Tagname.AlarmValDeadband



automatically save any changes made to this field through animation or scripting in WindowViewer.

Data Type Analog (read/write) Valid Values Must be in the value range configured for the specified tagname.Example(s) The following statement changes the deadband for tagname Tag1 to a value

of 25:

Tag1.AlarmValDeadband=25;

See Also .AlarmDevDeadband

Returns the value of the alarm for the tagname associated with a selected alarm. The alarm has to be selected by clicking on the Summary Distributed Alarm Display.

Category alarmsUsage [ErrorNumber=]GetPropertyM("ObjectName.AlarmValue",

Tagname);


AlmObj_1.Tagname Any Message tagname.

Data Type Message (read-only)Example(s) GetPropertyM("AlmObj_1.AlarmValue", almValue);

Where AlmObj_1 is the name of the distributed alarm object and almValue is a Memory Message tagname that will contain the alarm value for the tagname associated with the selected alarm.

If utilized in a Touch Pushbutton QuickScript, this statement returns the value to almValue when the operator presses the button which can then be used for further processing or display. almValue would then contain the alarm value associated with the selected alarm.

See Also GetPropertyM(), .AlarmAccess, .AlarmClass, .AlarmComment, .AlarmDate, .AlarmLimit, .AlarmName, .AlarmOprName, .AlarmOprNode, .AlarmPri, .AlarmProv, .AlarmState, .AlarmTime, .AlarmType


Dotfields 95

.AlarmValueCount

.AlarmValueUnAckCount

Tracks the total number of value alarms active on a given tagname or Alarm Group.

Category alarmsUsage Tagname.AlarmValueCount

Parameter DescriptionTagname Any Integer or Real tagname or Alarm Group.

Remarks This includes the count of HiHi, Hi, Lo, and LoLo alarms. It includes both acknowledged and unacknowledged alarms. For non-expanded summary alarm tagnames, this count will not exceed 1. However, the count may vary with alarm groups.

Data Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) AVC = Tag1.AlarmValueCount;

Where Tag1 is an Analog tagname configured for Integer alarms. AVC is also an Analog tagname, which gets the total number of all alarm values present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmDscUnAckCount, .AlarmROCCount, .AlarmTotalCount, .AlarmValueUnAckCount, .AlarmROCUnAckCount, .AlarmUnAckCount

Tracks the total number of unacknowledged value alarms active on a given tagname or Alarm Group. This includes the count of HiHi, Hi, Lo, and LoLo alarms.

Category alarmsUsage Tagname.AlarmValueUnAckCount

Parameter DescriptionTagname Any Integer or Real tagname or Alarm Group.

Data Type Integer (read-only)Valid Values 0 or any positive IntegerExample(s) AVUC = Tag1.AlarmValueUnAckCount;

Where Tag1 is an Analog tagname configured for Integer alarms. AVUC is also an Analog tagname, which gets the total number of all unacknowledged alarm values present in Tag1.

See Also .AlarmDevCount, .AlarmDevUnAckCount, .AlarmDscCount, .AlarmDscUnAckCount, .AlarmROCCount, .AlarmTotalCount, .AlarmValueCount, .AlarmROCUnAckCount, .AlarmUnAckCount


96 Chapter 2

.Caption

.ChartLength

Determines the message to be displayed with the check box.Category windows controlUsage [ErrorNumber=]GetPropertyM ("ControlName.Caption",

Tagname);

[ErrorNumber=]GetPropertyM ("ControlName.Caption","Message");

Parameter DescriptionControlName Name of the windows control. For example,

ChkBox_4.Tagname A Message tagname that holds the property

requested."Message" A message string surrounded in quotes.

Remarks This property is read/write during both development and runtime.Data Type Message (read/write)Applies To Check boxes.Example This statement sets the Caption of the Check box object "CheckBox_1" to

"Blue Paint Option."

SetPropertyM("CheckBox_1.Caption","Blue Paint Option");

See Also GetPropertyM(), SetPropertyM()

Controls the length (span in seconds) of time displayed in a Historical Trend Chart.

Category historicalUsage Tagname.ChartLength

Parameter DescriptionTagname Any Hist Trend tagname.


Dotfields 97

Remarks This read/write dotfield is used to set (or verify) the value of the Chart Length of a Historical Trend Chart. The Chart Length is expressed in seconds. The length is defined as the amount of time currently displayed on the Historical Trend Chart. More specifically, the calculation used to retrieve the Chart Length from a Historical Trend Chart is:

ChartLength=(Date/Time Stamp on Right-Hand Side of Chart)- (Date/Time Stamp on Left-Hand Side of Chart);

Since Date/Time Stamps are expressed in seconds since midnight on 1/1/70, the calculation results in "seconds of time displayed between the left and right hand sides of the chart."

Whenever adding or subtracting from .ChartLength, it is important to remember that you are dealing in seconds. Therefore, if you wish to subtract "2 hours" from the current .ChartLength, you need to convert "2 hours" to seconds before performing the calculation. For example:

(2 hours) * (60 minutes/hour) * (60 seconds/minute) = 7200 seconds.Data Type Integer (read/write)Valid Values Any positive IntegerExample(s) The following statement forces the chart span to be 1 hour:

HtTagname.ChartLength=3600 {60 minutes * 60seconds/minute};

The following statement scrolls the chart left by half:

HtTagname.ChartStart=HtTagname.ChartStart -HtTagname.ChartLength / 2;

The following statement scrolls the chart left by 10%:

HtTagname.ChartStart=HtTagname.ChartStart - (.10 *HtTagname.ChartLength);

See Also .ChartStart


98 Chapter 2

.ChartStart

.Comment

Controls the starting date/time stamp of a Historical Trend Chart.Category historicalUsage Tagname.ChartStart


Remarks This read/write dotfield is used to set (or verify) the value of the starting (left hand side) date/time stamp of a Historical Trend Chart. The .ChartStart field is expressed as the number of seconds since 12:00AM, 1/1/70. The "start" is defined as the first date/time stamp on the left hand side of the Historical Trend Chart.

Data Type Integer (read/write)Valid Values Any positive IntegerExample(s) The following statement scrolls the chart to the right by 1 minute:

HtTagname.ChartStart=HtTagname.ChartStart + 60;

See Also .ChartLength

Contains the value of the Comment field for a tagname in the Tagname Dictionary.

Category tagnameUsage Tagname.Comment

Parameter DescriptionTagname Any tagname.

Remarks While this field is read only in WindowMaker, the value can be changed in WindowViewer (memory only). Once WindowViewer is shut down and restarted again, the old value for the Comment field is used. This field is used by the Distributed Alarm System for alarm comments.

Data Type Message (read only)Valid Values Any string containing from 1 to 50 characters. See note below for character

string limitations.

Note The Comment field for a tagname can only be changed while in the Tagname Dictionary. Inputting a value into the .Comment field while in WindowViewer, will not write to the Tagname Dictionary.

Example(s) The following statement assembles a string (contents of a Message tagname) by containing the name of the tagname and the value of its Comment field:

OperatorMessage=MyTag.Name + " has a comment of: " +MyTag.Comment;

Note This field writes to the runtime database. It is not saved in the Tagname Dictionary.


Dotfields 99

.DevTarget

.DisplayMode

.Enabled

Monitors and/or controls the target for minor and major deviation alarms.Category alarmsUsage Tagname.DevTarget


tagname.Remarks Selecting the Retentive Parameters option in the Tagname Dictionary

automatically saves any changes made to this field through animation links or QuickScripts in WindowViewer.

Data Type Analog (read/write)Valid Values Must be in the value range configured for the specified tagname.Example(s) The following statement sets the Deviation Target for the tagname MyTag to

a value of 500;

MyTag.DevTarget=500;

See Also .AckDev, .AlarmDev, .AlarmMajDevDisabled, .AlarmMajDevEnabled, .AlarmMajDevInhibitor, .MajorDevSet, .MajorDevStatus

Determines the method to be used in displaying values on the trend.Category historicalUsage Tagname.DisplayMode


Data Type Analog (read/write)Valid Values 1 = Displays the min/max for each sample period (default).

2 = Displays the average for each sample period in a "scatter" diagram.3 = Displays the average for each sample period in a "bar chart" diagram.

Example(s) The following statement instructs the Historical Trend associated with MyHistTrendTag to display a bar chart type diagram:

MyHistTrendTag.DisplayMode=3;

See Also .ChartLength, .ChartStart

Determines whether the control object can respond to user-generated events.Category windows control


100 Chapter 2

Usage [ErrorNumber=] GetPropertyD("ControlName.Enabled",Tagname);

[ErrorNumber=] SetPropertyD("ControlName.Enabled",Discrete);


ChkBox_4.Tagname A Discrete tagname that holds the property

requested.Discrete A discrete value:

0 = Control is disabled1 = Control is enabled-Or-A Discrete tagname that holds the value to be written when the function is processed.

Remarks This property is read/write during both development and runtime.Data Type Discrete (read/write)Applies To Text boxes, List boxes, Combo boxes, Check boxes and Radio buttons.Example(s) The following statement disables the List box object named: "ListBox_1."

SetPropertyD("ListBox_1.Enabled",0);

See Also GetPropertyD(), SetPropertyD()


Dotfields 101

.EngUnits

.Freeze

The EngUnits field allows the user to access the engineering units of an Analog tagname as specified in the Tagname Dictionary.

Category tagnameUsage Tagname.EngUnits

Parameter DescriptionTagname Any Integer or Real tagname or Indirect Analog

tagname.Remarks This field is a text field and does not affect scale, conversions, or format of

the tagname value.Data Type Message (read/write)

Note Values written to this field are not retentive.Valid Values Any string containing from 0 to 31 characters.Example(s) IF Temperature.EngUnits == "Celsius" THEN

CALL TempConvert(Temperature);{A Quick Function whichmight be used to convert Celsius to Fahrenheit}

ENDIF;

See Also .MinEU, .MaxEU, .MaxRange, .MinRange, .MinRaw, .MaxRaw, .RawValue

Reads/writes the freeze status of the distributed alarm display object.Category alarmsUsage [ErrorNumber=]GetPropertyD(“ObjectName.Freeze”,Tagname”);

[ErrorNumber=]SetPropertyD(“ObjectName.Freeze”,Tagname”);


AlmObj_1.Tagname A Discrete tagname that holds the property value

when the function is processed.Remarks A read-write dotfield that contains or changes the freeze status of a

distributed alarm display object.Data Type Discrete (read-write)Valid Values 0 = Freeze OFF

1 = Freeze ONExample(s) The following statement sets the Freeze property for the “AlmObj_1” from

the Discrete tagname AlmFreeze.

SetPropertyD(“AlmObj_1.Freeze”,AlmFreeze);



102 Chapter 2

.HiHiLimit

.HiHiSet

Monitors and/or controls the HiHi limit for value alarm checks.Category alarmsUsage Tagname.HiHiLimit



automatically saves any changes made to this field through animation links or QuickScripts in WindowViewer.

Data Type Analog (read/write)Valid Values Must be in value range configured for the specified tagname.Example(s) The following statement increases the HiHi alarm limit for the tagname

MyTag by a value of 5:

MyTag.HiHiLimit=MyTag.HiHiLimit + 5;

See Also .Alarm, .AlarmValue, .Ack, .HiHiStatus, .HiHiSet, .AlarmDisabled, .AlarmEnabled, .AlarmHiHiDisabled, .AlarmHiHiEnabled, .AlarmHiHiInhibitor

Returns a value of 0 (false) or 1 (true) depending on whether or not a HiHi limit alarm condition has been set for an Analog tagname.

Category alarmsUsage Tagname.HiHiSet

Parameter DescriptionTagname Any Analog tagname.

Remarks This dotfield can only be used for Integer or Real type tagnames.Data Type DiscreteValid Values 1 (true) or 0 (false)Example(s) The following statement could be used on an Analog Output link to determine

whether the HiHi alarm limit is set for the tagname MyTag:

MyTag.HiHiSet 5;

{Where 0 is returned if not set; 1 is returned if set.}

See Also .Alarm, .AlarmValue, .Ack, .HiHiStatus, .HiHiLimit, .AlarmDisabled, .AlarmEnabled, .AlarmHiHiDisabled, .AlarmHiHiEnabled, .AlarmHiHiInhibitor


Dotfields 103

.HiHiStatus

.HiLimit

Determines whether a HiHi alarm exists.Category alarmsUsage Tagname.HiHiStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When a HiHi value alarm

condition exists for the specified tagname, this dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists. This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.

Data Type Discrete (read-only)Valid Values 0 = Specified alarm condition is not present

1 = Specified alarm condition is presentExample(s) The following IF-THEN statement executes when the .HiHiStatus (HiHi

alarm) for the tagname MyTag is equal to a value of 1.

IF (MyTag.HiHiStatus == 1) THENOperatorMessage="MyTag has gone into HiHi Alarm";

ENDIF;

See Also .Alarm, .AlarmValue, .Ack, .HiHiLimit, .HiHiSet, .AlarmDisabled, .AlarmEnabled, .AlarmHiHiDisabled, .AlarmHiHiEnabled, .AlarmHiHiInhibitor

Monitors and/or controls the High limit for value alarm checks.Category alarmsUsage Tagname.HiLimit


Remarks Selecting the Retentive Parameters option in the Tagname Dictionary automatically saves any changes made to this field through animation links or QuickScripts in WindowViewer.

Data Type Analog (read/write)Valid Values Must be in value range configured for the specified tagname.Example(s) Temperature.HiLimit = 212;

See Also .Alarm, .AlarmValue, .Ack, .HiStatus, .HiSet, .AlarmDisabled, .AlarmEnabled, .AlarmHiDisabled, .AlarmHiEnabled, .AlarmHiInhibitor


104 Chapter 2

.HiSet

.HiStatus

Returns a value of 0 (false) or 1 (true) depending on whether or not a High limit has been set for an Analog tagname.

Category alarmsUsage Tagname.HiSet


Remarks This field can only be used for Integer or Real tagname.Data Type DiscreteValid Values 1 (true) or 0 (false)Example(s) The following statement could be used on an Analog Output link to determine

whether the High alarm limit is set for the tagname MyTag:

MyTag.HiSet;


See Also .Alarm, .AlarmValue, .Ack, .HiStatus, .HiLimit, .AlarmDisabled, .AlarmEnabled, .AlarmHiDisabled, .AlarmHiEnabled, .AlarmHiInhibitor

Determines whether a High limit alarm exists.Category alarmsUsage Tagname.HiStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When a High alarm condition

exists for the specified tagname, this dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists. This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.


1 = Specified alarm condition is presentExample(s) IF (MotorAmps.HiStatus == 1) THEN

CALL PumpShutdown( );

ENDIF;

{QuickFunction which might be used to kill a pump motoroutput}

See Also .Alarm, .AlarmValue, .Ack, .HiLimit, .HiSet, .AlarmDisabled, .AlarmEnabled, .AlarmHiDisabled, .AlarmHiEnabled, .AlarmHiInhibitor


Dotfields 105

.ListChanged

.ListCount

Indicates whether there are any new alarms or updates for the Distributed Alarm Object.

Category alarmsUsage [ErrorNumber=]GetPropertyD(“ObjectName.ListChanged”,Tagna

me);

Parameter DescriptionObjectName Name of the Distributed alarm object. For example,

AlmObj_1.Tagname A Discrete type tagname that holds the property

value when the function is processed.Remarks This read-only dotfield contains the information about whether there is any

change that needs to be updated in the distributed alarm display object. This property is automatically reset on reading the property.

Data Type Discrete (read only)Valid Values 0 = No new alarms or updates for the display object

1 = New updates for the display objectExample(s) The following statement returns if there are any new alarms or updates for the

Distribute alarm object “AlmObj_1” to the Discrete tagname AlmDispStat:

GetPropertyD(“AlmObj_1.ListChanged”,AlmDispStat);

See Also Get PropertyD()

Determines the number of items in the List box or Combo box.Category Windows controlUsage [ErrorNumber=]GetPropertyI("ControlName.ListCount",

Tagname);


ListBox_4.Tagname A valid tagname that contains the integer count of

the items in the list.Remarks This property is available only in runtime.Data Type Integer (read-only) Applies To List boxes and Combo boxes.Example(s) The following statement retrieves the number of items in the List box named

"ListBox_1" and writes that value to the memory integer tagname MyListBoxCount.

GetPropertyI("ListBox_1.ListCount",MyListBoxCount);

See Also GetPropertyI(), .ListIndex


106 Chapter 2

.ListIndex

.LoLimit

Determines the corresponding index (Tagname or Number) of the currently selected item in the list. (Index is a number that defines a specific item in a list.) When using a List box, an index of -1 indicates that no item is currently selected. When using a Combo box, an index of -1 indicates that the user has entered new text into the text entry field of the control.

Category windows controlUsage [ErrorNumber=]GetPropertyI("ControlName.ListIndex",

Tagname);[ErrorNumber=]SetPropertyI("ControlName.ListIndex",Number);


ListBox_4.Tagname A valid tagname that contains the integer count of

the items in the list.Number The index number that defines a specific item in the

list.Remarks This property is available only in runtime.Data Type Integer (read/write)Applies To List boxes and Combo boxes.Example This statement retrieves the index of the currently selected item in the List

box named "ListBox_1" and writes that value to the Memory Integer tagname MyListBoxIndex.

GetPropertyI( "ListBox_1.ListIndex",MyListBoxIndex );

See Also GetPropertyI(), SetPropertyI(), .NewIndex, .TopIndex

Monitors and/or controls the Low limit for value alarm checks.Category alarmsUsage Tagname.LoLimit



automatically saves any changes made to this dotfield through Animation Links or QuickScripts in WindowViewer.

Data Type Analog (read/write)Valid Values Must be in value range configured for the specified tagname.


Dotfields 107

Example(s) This statement decreases the Low alarm limit for the tagname MyTag by a value of 10:

MyTag.LoLimit=MyTag.LoLimit - 10;

See Also .Alarm, .AlarmValue, .Ack, .LoStatus, .LoSet, .AlarmDisabled, .AlarmEnabled, .AlarmLoDisabled, .AlarmLoEnabled, .AlarmLoInhibitor


108 Chapter 2

.LoLoLimit

.LoSet

Monitors and/or controls the LoLo limit for value alarm checks.Category alarmsUsage Tagname.LoLoLimit



automatically saves any changes made to this dotfield through Animation Links or QuickScripts in WindowViewer.

Data Type Analog (read/write)Valid Values Must be in value range configured for the specified tagname.Example(s) This statement decreases the LoLo alarm limit for the tagname MyTag by a

value of 10:

MyTag.LoLoLimit=MyTag.LoLoLimit - 10;

See Also .Alarm, .AlarmValue, .Ack, .LoLoStatus, .LoLoSet, .AlarmDisabled, .AlarmEnabled, .AlarmLoLoDisabled, .AlarmLoLoEnabled, .AlarmLoLoInhibitor

Returns a value of 0 (false) or 1 (true) depending on whether or not a Low limit has been set for an Analog tagname.

Category alarmsUsage Tagname.LoSet


Remarks This dotfield can only be used for Integer or Real tagname.Data Type DiscreteValid Values 1 (true) or 0 (false)Example(s) The following statement could be used on an Analog Output link to determine

whether the Low alarm limit is set for the tagname MyTag:

MyTag.LoSet;


See Also .Alarm, .AlarmValue, .Ack, .LoStatus, .LoLimit, .AlarmDisabled, .AlarmEnabled, .AlarmLoDisabled, .AlarmLoEnabled, .AlarmLoInhibitor


Dotfields 109

.LoLoSet

.LoLoStatus

Returns a value of 0 (false) or 1 (true) depending on whether or not a LoLo limit has been set for an Analog tagname.

Category alarmsUsage Tagname.LoLoSet



whether the LoLo alarm limit is set for the tagname MyTag:

MyTag.LoLoSet;


See Also .Alarm, .AlarmValue, .Ack, .LoLoStatus, .LoLoLimit, .AlarmDisabled, .AlarmEnabled, .AlarmLoLoDisabled, .AlarmLoLoEnabled, .AlarmLoLoInhibitor

Determines whether a LoLo limit alarm exists.Category alarmsUsage Tagname.LoLoStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When a LoLo value alarm

condition exists for the specified tagname, this dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists. This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.


1 = Specified alarm condition is present


110 Chapter 2

Example(s) The following IF-THEN executes when the .LoLoStatus (LoLo alarm limit) for the tagname MyTag is equal to a value of 1.

IF (MyTag.LoLoStatus == 1) THENOperatorMessage="MyTag has gone into LoLo Alarm";

ENDIF;

See Also .Alarm, .AlarmValue, .Ack, .LoLoLimit, .LoLoSet, .AlarmDisabled, .AlarmEnabled, .AlarmLoLoDisabled, .AlarmLoLoEnabled, .AlarmLoLoInhibitor


Dotfields 111

.LoStatus

.MajorDevPct

Determines whether a Low limit alarm exists.Category alarmsUsage Tagname.LoStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When a Low alarm condition

exists for the specified tagname, this dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists. This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.


1 = Specified alarm condition is presentExample(s) IF (WaterLevelTank1.LoStatus == 1) THEN

PumpShutdown = 1;WaterFillValue = 1;

ENDIF;

See Also .Alarm, .AlarmValue, .Ack, .LoLimit, .LoSet, .AlarmDisabled, .AlarmEnabled, .AlarmLoDisabled, .AlarmLoEnabled, .AlarmLoInhibitor

Monitors and/or controls the major percentage of deviation for alarm checking.

Category alarmsUsage Tagname.MajorDevPct



automatically save any changes made to this dotfield through animation or scripting in WindowViewer.

Data Type Real (read/write)Valid Values 0 to 100%Example(s) The following statement sets the Major Deviation limit property for the

tagname MyTag to a value of 25%:

MyTag.MajorDevPct=25;

See Also .AckDev, .AlarmDev, .AlarmMajDevDisabled, .AlarmMajDevEnabled, .AlarmMajDevInhibitor, .MajorDevSet, .MajorDevStatus


112 Chapter 2

.MajorDevSet

.MajorDevStatus

Returns a value of 0 (false) or 1 (true) depending on whether or not a Major Deviation percentage has been set for an Analog tagname.

Category alarmsUsage Tagname.MajorDevSet



whether the major deviation percentage alarm limit is set for the tagname MyTag:

MyTag.MajorDevSet;


See Also .AckDev, .AlarmDev, .AlarmMajDevDisabled, .AlarmMajDevEnabled, .AlarmMajDevInhibitor, .MajorDevPct, .MajorDevStatus

Determines whether a major deviation alarm exists for the specified tagname.Category alarmsUsage Tagname.MajorDevStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When an alarm condition

exists for the specified tagname, the associated dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists.

This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.


1 = Specified alarm condition is present


Dotfields 113

Example(s) The following IF-THEN statement executes when the .MajorDevStatus (Major deviation alarm) for the tagname MyTag is equal to a value of 1.

IF (MyTag.MajorDevStatus == 1) THENOperatorMessage="MyTag has gone into a Major DeviationAlarm";

ENDIF;

See Also .AckDev, .AlarmDev, .AlarmMajDevDisabled, .AlarmMajDevEnabled, .AlarmMajDevInhibitor, .MajorDevPct, .MajorDevSet


114 Chapter 2

.MaxEU

.MaxRange

The maximum values (in engineering units) for the specified tagname.Category tagnameUsage Tagname.MaxEU


tagname.Remarks A value from a server is considered RAW when it first arrives in

WindowViewer. These raw values may require scaling. .MinEU and .MaxEU are used to scale RAW values. As a typical example, assume a level gauge is being read by a Programmable Logic Controller in the field. The level transmitter sends back a signal that ranges between 4 and 20mA. The PLC in the field converts this signal (through a digital to analog converter) to an integer value between 0 and 4096. This value is being read into the tagname TankTwoLevel.

Displaying this RAW value (between 0 and 4096) will present no useful data to the operator. It is therefore necessary to scale this value to an appropriate engineering range. To accomplish this, the Minimum Engineering Units and Maximum Engineering Units fields must be setup correctly. In our example, if the RAW value of 0 (4mA from the field) translated to "0 Gallons" and the value of 4096 (20mA from the field) translated to "100 Gallons", the following setup would be required to display the correct value on the screen:

Minimum Raw=0, Maximum Raw z= 4096Minimum Engineering Units=0, Maximum Engineering Units=100

With these settings, when the RAW value in the field is 4096, the value displayed on the screen will be 100.

Data Type Real for real tagnames and Integer for Integer tagnames (read-only)Valid Values Depends on the type of tagname specified.Example(s) Since this dotfield is read-only, assigning a value to it is not possible.

Displaying the .MinEU and .MaxEU or using them in calculations is very useful, and can enhance the understanding of the operator by providing basis for your calculations on the screen.

DialogValueEntry ("IO_Point_717", IO_Point_717.MinEU,IO_Point_717.MaxEU, "Please Enter a New Value:");

See Also .EngUnits, .MinEU, .MaxRange, .MinRange, .MinRaw, .MaxRaw, .RawValue

Represents the percentage of the tagname's Engineering Unit range that should be displayed for each tagname being trended.

Category historicalUsage Tagname.MaxRange


Dotfields 115


Remarks Since many different tagnames can be displayed on the Historical Trend at any one time, specifying the .MinRange and .MaxRange in engineering units would be impossible, since each of the tagnames could (and usually do) have completely different engineering ranges. Therefore, the min and max are expressed as a percentage of the engineering range of each tagname. This way, regardless of the tagname's true engineering range, the Historical Trend will simply display the indicated percentage of that tagname's particular engineering range.

Data Type Real (read/write)Valid Values The limits for .MaxRange and .MinRange are from 0 to 100. .MinRange

and .MaxRange are expressed in percent. .MinRange must be less than .MaxRange. If a value less than 0 or greater than 100 is assigned to either of these dotfields, the value will be clamped at 0 or 100. If .MinRange is greater than or equal to .MaxRange, the Trend will not display any data.

Example(s) The following statement sets the maximum range percentage of the Historical Trend associated with the Hist Trend tagname MyHistTrendTag to a value of 25%:

MyHistTrendTag.MaxRange=25;

See Also .ChartStart, .ChartLength, .DisplayMode, .EngUnits, .MinEU, .MaxEU, .MinRange, .MinRaw, .MaxRaw, .RawValue


116 Chapter 2

.MaxRaw

.MinEU

The high clamp setting for the actual raw value received from an I/O server by WindowViewer as a client. The value for .MaxRaw dotfield comes from the Max Raw value field in the Tagname Dictionary for the specified I/O tagname. Any raw value that exceeds this setting is clamped to this value.

Category tagnameUsage Tagname.MaxRaw

Parameter DescriptionTagname Any I/O Discrete, Indirect Discrete, I/O Integer,

Memory Real, Indirect Analog, I/O Message, or Indirect Message tagname.

Remarks This read-only dotfield is used to display the Max Raw high clamp setting.Data Type Real or Integer (read-only)Valid Values Any analog value.Example(s) The following could be used to determine if a tagname is out of normal

operating range and thus its value was clamped.

IF ((Temp01.RawValue > Temp01.MaxRaw) OR (Temp01.RawValueTemp01.MinRaw))THENShow "Instrument Failure Window";

ENDIF;

See Also .EngUnits, .MinEU, .MaxEU, .MaxRange, .MinRange, .MinRaw, .RawValue

The minimum values (in engineering units) for the specified tagname.Category tagnameUsage Tagname.MinEU

Parameter DescriptionTagname Any Integer and Real tagname, or Indirect Analog

tagname.


Dotfields 117

Remarks A value from a server is considered RAW when it first arrives in WindowViewer. These raw values may require scaling. .MinEU and .MaxEU are used to scale RAW values. As a typical example, assume a level gauge is being read by a Programmable Logic Controller in the field. The level transmitter sends back a signal that ranges between 4 and 20mA. The PLC in the field converts this signal (through a digital to analog converter) to an integer value between 0 and 4096. This value is being read into the tagname TankTwoLevel.

Displaying this RAW value (between 0 and 4096) will present no useful data to the operator. It is therefore necessary to scale this value to an appropriate engineering range. To accomplish this, the Minimum Engineering Units and Maximum Engineering Units fields must be setup correctly. In our example, if the RAW value of 0 (4mA from the field) translated to "0 Gallons" and the value of 4096 (20mA from the field) translated to "100 Gallons", the following setup would be required to display the correct value on the screen:

Minimum Raw=0, Maximum Raw = 4096Minimum Engineering Units=0, Maximum EngineeringUnits=100

With these settings, when the RAW value in the field is 4096, the value displayed on the screen will be 100.

Data Type Real for real tagnames and Integer for integer tagnames (read-only)Valid Values Depends on the type of tagname specified.Example(s) AbsoluteTagRange = (Tag.MaxEU - Tag.MinEU);

See Also .EngUnits, .MaxEU, .MaxRange, .MinRange, .MinRaw, .MaxRaw, .RawValue


118 Chapter 2

.MinorDevPct

.MinorDevSet

Monitors and/or controls the minor percent of deviation for alarm checking.Category alarmsUsage Tagname.MinorDevPct



automatically save any changes made to this dotfield through animation or scripting in WindowViewer.

Data Type Real (read/write)Valid Values 0 to 100%Example(s) The following statement sets the Minor Deviation limit property for the

tagname MyTag to a value of 25%:

MyTag.MinorDevPct=25;

See Also .AckDev, .AlarmDev, .AlarmMinDevDisabled, .AlarmMinDevEnabled, .AlarmMinDevInhibitor, .MinorDevSet, .MinorDevStatus

Returns a value of 0 (false) or 1 (true) depending on whether or not a minor deviation percentage has been set for an Analog tagname.

Category alarmsUsage Tagname.MinorDevSet


Remarks This dotfield can only be used for Integer or Real type tagname.Data Type DiscreteValid Values 1 (true) or 0 (false)Example(s) The following statement could be used on an Analog Output link to

determine whether the minor deviation percentage alarm limit is set for the tagname MyTag:

MyTag.MinorDevSet;


See Also .AckDev, .AlarmDev, .AlarmMinDevDisabled, .AlarmMinDevEnabled, .AlarmMinDevInhibitor, .MinorDevPct, .MinorDevStatus


Dotfields 119

.MinorDevStatus

.MinRange

Determines whether a minor deviation alarm exists for the specified tagname.Category alarmsUsage Tagname.MinorDevStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When an alarm condition exists

for the specified tagname, the associated dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists.


1 = Specified alarm condition is presentExample(s) The following IF-THEN statement executes when the .MinorDevStatus

(minor deviation alarm) for the tagname MyTag is equal to a value of 1.

IF (MyTag.MinorDevStatus == 1) THENOperatorMessage="MyTag has gone into a Minor DeviationAlarm";

ENDIF;

Remarks This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.

See Also .AckDev, .AlarmDev, .AlarmMinDevDisabled, .AlarmMinDevEnabled, .AlarmMinDevInhibitor, .MinorDevPct

Represents the percentage of a Historical Trend range that should be displayed for each tagname being trended.

Category historicalUsage Tagname.MinRange


Remarks Since many different tagnames can be displayed on the Historical Trend at any one time, specifying the .MinRange and .MaxRange in engineering units would be impossible, since each of the tagnames could (and usually do) have completely different engineering ranges. Therefore, the min and max are expressed as a percentage of the engineering range of each tagname. This way, regardless of the tagname's true engineering range, the Historical Trend will simply display the indicated percentage of that tagname's particular engineering range.

Data Type Real (read/write)


120 Chapter 2

Valid Values The limits for .MaxRange and .MinRange are from 0 to 100. .MinRange and .MaxRange are expressed in percent. .MinRange must be less than .MaxRange. If a value less than 0 or greater than 100 is assigned to either of these dotfields, the value will be clamped at 0 or 100. If .MinRange is greater than or equal to .MaxRange, the Trend will not display any data.

Example(s) TotalChartHeight=MyHistTrendTag.MaxRange -MyHistTrendTag.MinRange;

See Also .ChartStart, .ChartLength, .DisplayMode, .EngUnits, .MinEU, .MaxEU, .MaxRange, .MinRaw, .MaxRaw, .RawValue


Dotfields 121

.MinRaw

.Name

The low clamp setting for the actual raw value received from an I/O server by WindowViewer as a client. The value for .MinRaw dotfield comes from the Min Raw value field in Tagname Dictionary for the specified I/O tagname. Any raw value that falls below this setting is clamped to this value.

Category tagnameUsage Tagname.MinRaw



Remarks This read-only dotfield is used to display the Min Raw high clamp setting.Data Type Real or Integer (read-only)Valid Values Any analog value.Example(s) The following could be used to determine if a tagname is out of normal

operating range and thus its value was clamped.

IF ((Temp01.RawValue > Temp01.MaxRaw) OR (Temp01.RawValue<

Temp01.MinRaw)) THENShow "Instrument Failure Window";ENDIF;

See Also .EngUnits, .MinEU, .MaxEU, .MaxRange, .MinRange, .MaxRaw, .RawValue

Contains the name of the specified tagname in "String" form.Category tagnameUsage Tagname.Name

Parameter DescriptionTagname Any tagname type.

Data Type Message (read/write)Valid Values Assignments can only be made to the .Name field of Indirect type tagnames

that includes Alarm Group and Tag ID. When making assignments to this field, the format of the assignment string must follow tagname naming rules, such as what symbols are appropriate and the first character should always be alphabetical.


122 Chapter 2

Remarks This dotfield is read-only for the following tagnames: Hist Trend, any Memory, and any I/O types.

This field is read/write for the following tagnames: Tag ID and any Indirect types.

In the read-only implementation, this dotfield is useful for specifying the tagname without having to put the tagname in quotation marks, i.e., MyTag.Name is the same as MyTag. This is highly beneficial when you select the Update Use Counts command on the Special menu in WindowMaker or Cross Reference is used to scan for a tagname's usage. It cannot see the tagname being used if it is within quotation marks. Therefore, if a tagname's only usage is being specified between "quotes," and you perform an Update Use Counts followed by a Special > Delete Unused Tags, the tagname will be removed, since it is considered, unused. A "" can be used to de-reference an Indirect tagname, thus "nullifying" any previous assignment.

In the read/write implementation, this dotfield is even more useful. It allows you to modify the identity of the specified Indirect tagname. When the .Name dotfield of an Indirect tagname is assigned the name of another tagname, assuming both tagnames are of the same type, the Indirect tagname actually becomes the other tagname, and it can be used anywhere in InTouch that the original tagname can be used.

Example(s) The following read-only statement use of .Name concatenation is used to create a message for the operator:

MyMessageTag="The tagnamenamed "+ MyTag.Name+ "has acomment of "+ MyTag.Comment";

Scenario: You develop a graphic window to display three vital statistics about an oil well, but you have 100 oil wells. The following Data Change QuickScript can be used to update a single graphic window no matter which oil well the operator selects. The tagname for the Data Change QuickScript is OilWellNumber.

IndOilWellPump.Name = "OilWellPump" + Text(OilWellNumber,"#");

IndOilWellTEP.Name = "OilWellTemp" + Text(OilWellNumber,"#");

IndOilWellPressure.Name = "OilWellPressure" +Text(OilWellNumber, "#");

To force the QuickScript to execute, use a pushbutton with a Touch Input Analog link, using OilwellNumber for its tagname. Then, in Runtime, when the operator clicks the button and enters a well number the QuickScript will execute.


Dotfields 123

.NewIndex

.NextPage

Returns the corresponding integer index (Tagname) of the last item added to the List box or Combo box via the wcAddItem() or wcInsertItem().

Category windows controlUsage [ErrorNumber=]GetPropertyI("ControlName.NewIndex",Tagname

);


ListBox_4.Tagname A tagname containing the integer index of the last

item added to the List or Combo box. For empty lists, a value of -1 is returned.

Remarks This property is only available in runtime.Data Type Integer (read-only) Applies To List boxes and Combo boxes.Example The following statement retrieves the index of the most recently added item in

the List box named "ListBox_1" and writes that value to the memory integer tagname NewItemIndex.

GetPropertyI("ListBox_1.NewIndex",NewItemIndex);

See Also GetPropertyI(), wcAddItem(), wcInsertItem(), .ListIndex, .TopIndex

Scrolls the alarm display object one page (one screen full of alarms) down when this property transitions from 1 to 0.

Category alarmsUsage [ErrorNumber=]GetPropertyD("ObjectName.NextPage",Tagname)

;[ErrorNumber=]SetPropertyD("ObjectName.NextPage",Value);


AlmObj_1.Tagname The name of a Discrete tagname that holds the

property value when the function is processed used as "Tagname" or Tagname.Name.

Value A discrete value. Or, a Discrete tagname that holds the value to be written when the function is processed.

Remarks When this value transitions from 1 to 0, the alarm display object shows the next page. Once the next page is displayed, the variable is automatically set to 1, unless the top of the list has been reached. In this case, the value remains 0.

Data Type Discrete (read/write) See Also GetPropertyD(), SetPropertyD(), .PrevPage, .PageNum, .TotalPages


124 Chapter 2

.Normal

.NumAlarms

.Normal is equal to 1 when there are no alarms for the specified tagname.Category alarmsUsage Tagname.Normal

Parameter DescriptionTagname Any Discrete, Integer, or Real tagname, or Indirect

Analog tagname.Remarks This dotfield is used in QuickScripts or Display links to indicate that the

specified tagname is in a "normal" state (no alarms active). If one or more alarms become active for the specified tagname, this dotfield value is set to 0.

Data Type Discrete (read-only)Valid Values 0 = One or more alarms active for the specified tagname

1 = No alarms are active for the specified tagname (default)Example(s) The following IF-THEN statement executes when there are no alarms

associated with the tagname Tag1. When there is one or more alarms active for Tag1, the "ELSE" body executes:

IF (Tag1.Normal==1) THENMyOperatorMessage="Tag1 is OK - No alarms associatedwith it";

ELSEMyOperatorMessage="Tag1 has one or more alarms active!";

ENDIF;

See Also .Alarm, .AlarmDev, .AlarmROC, .AlarmValue

Contains the number of alarms within a Distributed Alarm Object.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.NumAlarms",Tagname

);


AlmObj_1.Tagname An Integer type tagname that holds the property

value when the function is processed.Remarks This read-only dotfield contains the current number of alarms registered in a

named distributed alarm display object. This includes not only those alarms displayed, but all alarms registered.

Data Type Integer (read-only)


Dotfields 125

Example(s) The following statement returns the current number of alarms used by the distributed alarm object "AlmObj_1" to the Integer tagname AlarmCount:

GetPropertyI("AlmObj_1.NumAlarms",AlarmCount);

See Also GetPropertyI()


126 Chapter 2

.OffMsg

.OnMsg

.PageNum

The .OffMsg dotfield allows you to access the off message of a Discrete tagname as specified in the Tagname Dictionary.

Category tagnameUsage Tagname.OffMsg

Parameter DescriptionTagname Any Discrete tagname.

Data Type Message (read/write). Values written to this dotfield are not retentive.Valid Values Any string containing from 0 to 15 characters.Example(s) If MyDiscrete has a value of 0, the following statement assigns the OffMsg

string contained in the Tagname Dictionary for MyDiscrete to the Discrete tagname StateMessage.

StateMessage=Dtext (MyDiscrete, MyDiscrete.OnMsg,MyDiscrete.OffMsg);

See Also .OnMsg

The .OnMsg dotfield allows you to access the on message of a Discrete tagname as specified in the Tagname Dictionary.

Category tagnameUsage Tagname.OnMsg

Parameter DescriptionTagname Any Discrete tagname.

Data Type Message (read/write). Values written to this dotfield are not retentive.Valid Values Any string containing from 0 to 15 characters.Example(s) IF IndAnalog.OnMsg == "Running" THEN

TypeOfTag = "IndAnalog was assigned a Motor Starter";

ENDIF

See Also .OffMsg

Contains the current page numbers displayed in the alarm object.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.PageNum",Tagname);



value when the function is processed.


Dotfields 127

Remarks This read-only dotfield contains the number of the currently displayed page in a named distributed alarm display object.

Data Type Integer (read-only) Example(s) The following statement returns the current page number of the distributed

alarm object "AlmObj_1" to the Integer tagname AlarmPage:

GetPropertyI("AlmObj_1.PageNum",AlarmPage);

See Also GetPropertyI(), .NextPage, .PrevPage, .TotalPages


128 Chapter 2

.Pen1-.Pen8Controls the tagname being historically trended by each pen.

Category historicalUsage Tagname{.Pen1 | .Pen2 | .Pen3 | .Pen4 | .Pen5 | .Pen6 |

.Pen7 | .Pen8};


Remarks Due to the complexity of using the .PenX dotfields, it is recommended that the HTSetPenName and HTGetPenName functions be used, if possible.

Note Only local tagnames can be assigned to a .PenX dotfield. The provider.tag notation cannot be used. The provider.tag can only be used with HTSetPenName.

A good reference to use when learning how these dotfields function is a Historical Trend Wizard placed on the screen and broken apart. This will show how the dotfields are intended to be used.

Data Type TagID (read/write)Valid Values This dotfield is type .TagID. This means that the "handle" of a tagname may

be assigned to this dotfield. You cannot assign the name of a tagname to this dotfield. You must assign the associated .TagID dotfield of a tagname to this dotfield. You may want to refer to the description of the .TagID dotfield for a clearer understanding of this explanation. In general, a TagID type tagname can only be equated to another TagID tagname. It cannot be mixed with any other tagname type unless the .TagID dotfield extension is added to the other tagname.

Although this dotfield is considered read/write, its value cannot be directly displayed on the screen.

Example(s) The following statement will be used to assign a new tagname to Pen1 of the Historical Trend associated with the Hist Trend type tagname named MyHistTrendTag. By processing the following statement within a script Pen1 of the Historical Trend associated with MyHistTrendTag will begin displaying the historically logged data for the tagname MyLoggedTag. We must append the .TagID dotfield to the name of the MyLoggedTag in order to assign it to Pen1. This is because .Pen1 of TagID type and since you must match types when performing assignments (that is, DiscreteTag = DiscreteTag, is acceptable, whereas DiscreteTag = MessageTag is illegal) we must assign a TagID type object to that dotfield.

MyHistTrendTag.Pen1=MyLoggedTag.TagID;


Dotfields 129

Working from the example above, what if we wanted to display the name of the tagname we just assigned to MyHistTrendTag.Pen1? This would be very useful information for the operator. Additionally it is nice to have the tagnames displayed in a legend near the Historical Trend for reference. To accomplish this, it would seem natural to display the value of MyHistTrendTag.Pen1 in a Message Output link, but as you can see if you try this for yourself, it doesn't work. Why not? The actual value of the .Pen1 dotfield is an Integer that represents a memory location within WindowViewer; not particularly useful for display purposes. To get around this, we need to exercise a little caveat. First, create a new tagname of TagID type; called Pen01. Place the following statement underneath the statement from the previous example:

Pen01=MyHistTrendTag.Pen1;

In the first example, we assigned the tagname MyLoggedTag to Pen1 of MyHistTrendTag. In this example we went one step further by assigning the value of Pen1 of MyHistTrendTag, which is now the TagID of MyLoggedTag, to the tagname Pen01. Why did we do this? The reason is that we needed a way to get to the .Name. We could not simply display MyHistTrendTag.Name on the screen because it would always display MyHistTrendTag. If we then tried to display MyHistTrendTag.Pen1 on the screen, the link editor wouldn't let us, because Pen1 is TagID type, which cannot be displayed. So we need a helper-tagname to bridge the gap between the display system and the historical system. By assigning the value of MyHistTrendTag.Pen1 to the TagID type tagname Pen01 we have essentially assigned MyLoggedTag to Pen01. In fact, we could have accomplished the same task as we did above with the following line of code. They are functionally identical:

Pen01=MyLoggedTag.TagID;


130 Chapter 2

So, why did we choose the first statement over the second? Because the first is more generic. In addition, you can simply place MyHistTrendTag.Pen1 as the tagname in a Data Change QuickScript and place: Pen01 = MyHistTrendTag.Pen1; in the body. This way, without ever knowing which tagname was just assigned to Pen1 you can assign that same tagname to Pen01. This allows you to constantly display the name of the tagname that is assigned to Pen1 of the historical trend on the screen, even when someone changes the tagname either through the regular user interface (click on the trend in WindowViewer) or through a QuickScript somewhere in the system.

Taking this example one step further, you may at some point, wish to display the minimum and maximum Engineering Units of a particular tagname that is being trended. The Historical Trend Wizard does a very nice job of this. We suggest you take a moment and place a Historical Trend Wizard on the screen, break it apart and see how it was constructed. This will give you a good idea of how these dotfields function.

Because TagID type tagnames, like Pen01, do not have engineering units or any of the other dotfields normally available to a tagname, we cannot use it to display the engineering units of a tagname assigned to it. For example, we cannot display Pen01.MaxEU since the link editor would complain that .MaxEU is not a valid dotfield for Pen01 which is TagID type.

To get around this, we merely need a helper tagname to handle the conversion between TagID type and the display system. First, create a tagname of type Indirect Analog for example, IndirectAnalogPen1. Within the same data change script as example #2, place the following statement:

IndirectAnalogPen1.Name=Pen01.Name;

Pen01's name (at this point in our example it should equal MyLoggedTag) is assigned to the Indirect tagname IndirectAnalogPen1. With this done, we can access all the dotfields normally available to us with respect to an Analog tagname in this case the Integer tagname called MyLoggedTag. So we can now place the following with an Analog Display link on the screen:

IndirectAnalogPen1.MaxEU

This will display the Maximum Engineering units of the tagname currently assigned to the tagname IndirectAnalogPen1. Since we assigned Pen01.Name to it in the Data Change QuickScript above, we can be certain that it will display the Maximum Engineering units of the tagname currently assigned to Pen1 of MyHistTrendTag.

See Also .TagID, HTGetPenName( ), HTSetPenName( )


Dotfields 131

.PendingUpdates

.PrevPage

Indicates if there are any updates pending for a Distributed Alarm Object. Category alarmsUsage [ErrorMessage=]GetPropertyI(“ObjectName.PendingUpdates”,

Tagname);



value when the function is processed.Remarks This read-only dotfield contains information about the pending updates for a

named distributed alarm display object. Any value greater than zero indicates that the distributed alarm object has new alarm data. This value is reset every time the object is redrawn.

Data Type Integer (read only)Example(s) The following statement returns if there are any pending updates for the

distributed alarm display object “AlmObj_1” to the Integer tagname AlarmPendingUpdates:

GetPropertyI(“AlmObj_1.PendingUpdates”,AlarmPendingUpdates);

See Also GetProperty

Scrolls the distributed alarm display object one page (one screen full of alarms) up when this property transitions from 1 to 0.

Category alarmsUsage [ErrorNumber=]GetPropertyD("ObjectName.PrevPage",Tagname)

;[ErrorNumber=]SetPropertyD("ObjectName.PrevPage",Value);


AlmObj_1.Tagname A tagname (of the same type to be returned) that

holds the property value when the function is processed.

Value A discrete value. Or, a Discrete tagname that holds the value to be written when the function is processed.

Remarks When this value transitions from 1 to 0, the distributed alarm display object shows the previous page. Once the previous page is displayed, the variable is automatically set to 1, unless the top of the list has been reached. In this case, the value remains 0.


132 Chapter 2

Data Type Discrete (read/write) See Also GetPropertyD(), SetPropertyD(), .NextPage, .PageNum, .TotalPages


Dotfields 133

.PriFrom

.PriTo

.ProviderReq

Contains the lower priority value used by the current query.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.PriFrom",Tagname);


AlmObj_1.Tagname An Integer tagname that holds the property value

when the function is processed.Remarks This read-only dotfield contains the minimum priority value used in a named

distributed alarm display object to query for alarms.Data Type Integer (read-only)Example(s) The following statement returns the minimum priority value of the query used

by distributed alarm object "AlmObj_1" to the Integer tagname MinPri:

GetPropertyI("AlmObj_1.PriFrom",MinPri);

See Also GetPropertyI(), .PriTo, .AlarmPri

Contains the upper priority value used by the current query.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.PriTo",Tagname);



when the function is processed.Remarks This read-only dotfield contains the maximum priority value used in a named

distributed alarm display object to query for alarms.Data Type Integer (read-only)Example(s) The following statement returns the maximum priority value of the query

used by distributed alarm object "AlmObj_1" to the Integer tagname MaxPri:

GetPropertyI("AlmObj_1.PriTo",MaxPri);

See Also GetPropertyI(), .PriFrom, .AlarmPri

Contains the number of alarm providers required by the current query.Category alarms


134 Chapter 2

Usage [ErrorNumber=]GetPropertyI("ObjectName.ProviderReq",Tagname);



when the function is processed.Remarks This read-only dotfield contains the number of alarm providers required by

the current query used by a named distributed alarm display object.Data Type Integer (read-only) Example(s) The following statement returns the number of alarm providers required by

the current query used by distributed alarm object "AlmObj_1". This value is written to the Integer tagname TotalProv:

GetPropertyI("AlmObj_1.ProviderReq",TotalProv);

See Also GetPropertyI(), .ProviderRet


Dotfields 135

.ProviderRet

.Quality

Contains the number of alarm providers that have successfully returned their query results.

Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.ProviderRet",

Tagname);



when the function is processed.Remarks This read-only dotfield contains the number of alarm providers returned by

the current query used by a named distributed alarm display object.Data Type Integer (read-only) Example(s) The following statement returns the number of alarm providers that have

successfully returned their alarms to distributed alarm object "AlmObj_1". This value is written to the Integer tagname RetProv:

GetPropertyI("AlmObj_1.ProviderRet",RetProv);

See Also GetPropertyI(), .ProviderReq

To completely understand the Quality dotfields used by Wonderware a brief definition of quality standard is stated. The Wonderware Data Quality standard is based on the OLE for Process Control (OPC) proposed quality, which in turn is based on Fieldbus Data Quality Specifications.

Quality flags represent the quality state for an item's data value. This design makes it fairly easy for both Servers and Client applications to determine how much functionality they want to implement.

The low 8 bits (Least Significant Byte) of the Quality flags are currently defined in the form of three bit fields; Quality, Substatus and Limit status arranged as follows:

QQSSSSLL

The Quality field allows the user to access the quality of an I/O tagname as provided by an I/O server.

Note If the I/O connection becomes invalid, the quality dotfields are automatically reset to the initial value of zero. The .ReferenceComplete flag is also set to zero at this time.

Category tagnameUsage Tagname.Quality

Parameter Description


136 Chapter 2

Tagname Any Discrete, Integer, or Real tagname, or Indirect Analog or Indirect Message tagname.

Data Type Integer (read only)Valid Values Value may be 0 to 255Example(s) IF I0Tag.Quality <> 192 THEN

LogMessage("This data is not Good!");

ENDIF;

Wonderware I/O servers can report six (6) mutually exclusive states of quality of data being sent back to their clients. They are as follows:

OPC QualityBytesOPC Quality Bits .QualityStatusMSByte LSByte .QualitySubStatus

States of Quality Hex Value xxxxxxxx QQSSSSLL .QualityLimit1. Good 0x00C0 00000000 00000000 Q=3 S=0 L=02. Clamped High 0x0056 00000000 00000000 Q=1 S=5 L=23. Clamped Low 0x0055 00000000 00000000 Q=1 S=5 L=14. Cannot Convert 0x0040 00000000 00000000 Q=1 S=0 L=05. Cannot Access Point

0x0004 00000000 00000000 Q=0 S=1 L=0

6. Communications Failed

0x0018 00000000 00000000 Q=0 S=6 L=0

When the client application is unable to communicate with the Server .QualityStatus is 0.0x0000 00000000 00000000 Q=0 S=0 L=0

The conditions under which each of these quality states will be reported are as follows:

1. Good The Communications link has been verified.

The PLC understood our Poll request and returned a valid response packet.

If a write occurred, there were no errors during the write process.

There were no conversion problems with the data contained in the response packet.

Example The value 0x0000A is returned due to a poll of a register containing 10 (decimal).


Dotfields 137

2. Clamped High The Communications link has been verified.


The register was read or written without error.

It was necessary to clamp its intended value to a limit because the value was larger than the maximum allowed.

In the case of a string, the string is truncated.

Example An unsigned 16 bit integer is clamped to 65535.3. Clamped Low The Communications link has been verified.


The register was read or written without error.

It was necessary to clamp its intended value to a limit because the value was smaller than the minimum allowed.

Example An unsigned 16 bit integer is clamped to 0.4. Cannot Convert

The Communications link has been verified.


The data from the PLC could not be converted into the desired format.

Possibilities for cannot convert include, but are not limited to:

The Server may return a constant in place of the data or return quality information alone.

The data is not usable.

It is not known whether the value is too large or too small.

The data returned from the PLC is of the incorrect data type.

A Floating Point number is returned, but is not value (for example: Not A Number).

Example The value of 0x000A is returned from a BCD register in a PLC.


138 Chapter 2

5. Cannot Access Point

The Communications link has been verified.


The PLC reported that it could not access the requested point.

Possibilities for lack of accessibility include, but are not limited to:

Item does not exist in PLC memory.

Item is not currently available (locked in some way due to resource contention).

Item is not of the correct format / data type.

A write attempt was made, but item is read-only.

In most cases, a group of items will be affected when one item is invalid. This is due to the block-polling scheme used by the Servers. For example, if one item in a block of 10 is invalid, then entire block is marked invalid by the PLC. The Server will report invalid quality for all items in the block.

The data is unusable.Example Attempting to read R40001 but R40001 is not defined in the PLC's memory

map.6. Communications Failed

Any combination of the following:

Data communications are down.

The Topic is in slow poll (or equivalent) mode.

There have been no link validating messages.

Lack of resources in the Server. For example, a TSR (or driver) cannot allocate memory.

Lack of resources in the communications link.

The communications link is off-line.

All communications channels are in use.

The network is unable to route the message to the PLC.Example Attempting to read data from a PLC which has been powered off.See Also .QualityLimit, .QualityStatus, .QualitySubstatus


Dotfields 139

.QualityLimit

.QualityLimitString

.QualityStatus

Integer used to display the quality limit of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualityLimit


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values (LL)

0 Not Limited1 Low Limited2 High Limited3 Constant

See Also .Quality

Used to display the quality limit string of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualityLimitString


Analog or Indirect Message tagname.Data Type Message (read-only)See Also .QualityLimit, .Quality

Integer used to display the quality status of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualityStatus

Parameter DescriptionTagname Any Discrete, Integer, Real tagname, or Indirect

Analog or Indirect Message tagname.Remarks The Substatus Bit-Field (QQ) is dependent on the value of the Quality Field

(QQSSSSLL). Data Type Integer (read-only)Valid Values (QQ)


140 Chapter 2

0 Bad1 Uncertain3 Good

See Also .QualitySubStatus, .Quality


Dotfields 141

.QualityStatusString

.QualitySubstatus

Used to display the quality status string of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualityStatusString


Analog or Indirect Message tagname.Data Type Message (read-only)See Also .QualityStatus, .QualitySubStatus, .Quality

Integer used to display the quality substatus of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualitySubstatus


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values (SSSS) and (QQ)

Substatus (SSSS) for BAD Quality (QQ=0):0 Non-specific1 Configuration Error2 Not Connected3 Device Failure4 Sensor Failure5 Last Known Value6 Com Failure7 Out of ServiceSubstatus (SSSS) for UNCERTAIN Quality (QQ=1):0 Non-specific1 Last Usable Value4 Sensor Not Accurate5 Engineering Units

Exceeded6 Sub-Normal


142 Chapter 2

Substatus (SSSS) for GOOD Quality (QQ=2):0 Non-specific6 Local Override

See Also .QualityStatus, .Quality


Dotfields 143

.QualitySubstatusString

.QueryState

.QueryType

Used to display the quality substatus string of an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.QualitySubstatusString


Analog or Indirect Message tagname.Data Type Message (read-only)See Also .QualityStatus, .QualitySubstatus, .Quality

Represents the current alarm state query filter.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.QueryState",

Tagname);



when the function is processed.Remarks This read-only dotfield contains the current query filter used by a named

distributed alarm display object.Data Type Integer (read-only)Valid Values 0 = All

1 = UnAck2 = Ack

Example(s) The following statement returns the current query filter of distributed alarm object "AlmObj_1" to the Integer tagname AlmQueryState:

GetPropertyI("AlmObj_1.QueryState",AlmQueryState);

See Also GetPropertyI(), .QueryType

Represents the current alarm query type.Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.QueryType",Tagname

);


144 Chapter 2



when the function is processed.Remarks This read-only dotfield contains the current query type used by a named

distributed alarm display object.Data Type Integer (read-only)Valid Values 1 = History

2 = SummaryExample(s) The following statement returns the current query type of distributed alarm

object "AlmObj_1" to the Integer tagname AlmQueryType:

GetPropertyI("AlmObj_1.QueryType",AlmQueryType);

See Also GetPropertyI(), .QueryState


Dotfields 145

.RawValue

.ReadOnly

The actual value received from an I/O server by WindowViewer as a client. The Raw Value field allows the user to access the value of an I/O tagname before InTouch applies scaling.

Category tagnameUsage Tagname.RawValue



Remarks This read-only dotfield is used to display the actual discrete or analog I/O value before InTouch applies scaling.

Data Type Any data type. For example, real for Real tagnames, discrete for Discrete tagnames, etc. (read-only)

Valid Values Where discrete or analog values can be specified.Example(s) The following could be used to determine if a tagname is out of normal

operating range.

IF ((IOtag.RawValue > IOtag.MaxRaw) OR (IOTag.RawValueIOTag.MinRaw))THENAlarmMessage = "Sensor is out of calibration or requiresreplacement.";

ENDIF;

See Also .EngUnits, .MinEU, .MaxEU, .MinRaw, .MaxRaw

Determines whether the contents of the Text box are read-only or read/write.Category windows controlUsage [ErrorNumber=]GetPropertyD("ControlName.ReadOnly",

Tagname);


Textbox_1.Tagname A Discrete tagname that holds the property value

when the function is processed.Remarks This property is available in both development and runtime.Data Type Discrete (read-only)Valid Values 0 = Contents of Text box is read/write

1 = Contents of Text box is read-onlyApplies To Text boxes.


146 Chapter 2

Example(s) The following statement retrieves the read-only status of the Text box named "TextBox_1":

GetPropertyD("TextBox_1.ReadOnly",A_Tagname);



Dotfields 147

.Reference

.ReferenceComplete

Allows the operator to dynamically change the Access Name and/or Item Name during runtime.

Category tagnameUsage Tagname.Reference

Parameter DescriptionTagname Any I/O tagname or an Indirect tagname assigned to

an I/O tagname.Remarks This dotfield provides an easy way to dynamically change the Access Name

and /or Item of a tagname. Data Type Message (read/write) Valid Values Any string that contains an Access Name and/or Item. Example(s) The following statement sets the Item field of a I/O Integer to an item name

generated by a text function, and is determined by the value of a Memory Integer. This would be used within a condition script, based on .ReferenceComplete to cycle through a sequence of tagnames:

MyIOTag.Reference="R" + Text( MyIndex, "#" );

{ If MyIndex=40001,the resulting ITEM would be: R40001 }

ExcelTag.Reference="R"+Text(RowNum,"#")+"C"+Text(ColNum, "#");

Returns a confirmation when the .Reference item tagname changed, receives the item requested and the updated is reflected in the .Value dotfield for that tagname.

Category tagnameUsage Tagname.ReferenceComplete;

Parameter DescriptionTagname Any I/O tagname or an Indirect tagname assigned to

an I/O tagname.Remarks This dotfield is very useful when using the .Reference dotfield.

.ReferenceComplete indicates that the item and/or access name has been changed, and more importantly, that a new value has been received from the new data source. Even if the new data source value is identical to the previous data source, when the first update occurs from the new data source, this dotfield will be set to 1 by the system.

During the actual update process, from the time .Reference is modified until the time the first update from the new data source arrives, this dotfield value will be set equal to 0 by the system.

Data Type Discrete (read-only)


148 Chapter 2

.ROCPct

.ROCSet

Monitors and/or controls the rate-of-change for alarm checking.Category AlarmsUsage Tagname.ROCPct


tagname.Remarks This dotfield is expressed in percentage. The dotfield corresponds directly to

the same field configured within the alarm section of the Tagname Dictionary. The user may display this dotfield or use it in a script. Additionally, the value can be changed during runtime to accommodate changes to the process being monitored.

Data Type Integer (read/write)Valid Values 0 to 100 %Example(s) The following statement sets the Rate-of-Change % property of the tagname

MyTag to a value of 25%:

MyTag.ROCPct=25;

See Also .ROCStatus, .ROCSet

Returns a value of 0 (false) or 1 (true) depending on whether or not a rate-of-change property in the Tagname Dictionary has been set for an Analog tagname.

Category alarmsUsage Tagname.ROCSet


Remarks This dotfield can only be used for Integer or Real tagname.Data Type DiscreteValid Values 1 (true) or 0 (false)Example The following statement could be used on an Analog Output link to determine

whether the Rate-of-Change alarm limit is set for the tagname MyTag:

MyTag.ROCSet;


See Also .Alarm, .Ack, .LoLimit, .LoLoLimit, .HiHiLimit, .HiLimit, .HiSet, .LoSet, .LoLoSet, .HiStatus, .HiHiStatus, .ROCPct, .ROCStatus


Dotfields 149

.ROCStatus

.ScooterLockLeft

Determines whether a rate-of-change alarm exists for the specified tagname.Category alarmsUsage Tagname.ROCStatus


tagname.Remarks This read-only dotfield is normally equal to 0. When a rate-of-change alarm

condition exists for the specified tagname, this dotfield is set to a value of 1 by the system. The dotfield will remain equal to 1 until the alarm condition no longer exists.


1 = Specified alarm condition is presentExample(s) The following IF-THEN statement executes when the .ROCStatus (rate-of-

change alarm) for the tagname MyTag is equal to a value of 1.

IF (MyTag.ROCStatus == 1) THENOperatorMessage="MyTag has gone into a Rate-Of-Change-Alarm";

ENDIF;

Remarks This dotfield is often used in conjunction with the .Alarm and .Ack dotfields to determine the exact nature of the alarm status of a particular tagname within the system.

See Also .ROCPct, .ROCSet

Setting this dotfield to a value equal to 1 (True) will not allow the Right Scooter from moving to the Left of (overtake) the Left Scooter's position.

Category historicalUsage Tagname.ScooterLockLeft


Remarks In general, it is beneficial to prevent the operator from moving the Right Scooter farther left than the Left Scooter's current position. When the left scooter is not locked, the right scooter will force the left scooter position to be equal to the right scooter position whenever the right scooter overtakes the left scooter.

Data Type Discrete (read/write)Valid Values 0 = False = Right Scooter can overtake the Left Scooter's position

1 = True = Right Scooter cannot overtake the Left Scooter's position


150 Chapter 2

Example(s) When the following statement executes, the Right Scooter associated with the Hist Trend tagname MyHistTrendTag, will not be able to move to the left of the Left Scooter's current position.

MyHistTrendTag.ScooterLockLeft=1;

See Also .ScooterPosRight, .ScooterPosLeft, .ScooterLockRight


Dotfields 151

.ScooterLockRight

.ScooterPosLeft

Setting this dotfield to a value equal to 1 (True) will not allow the Left Scooter from moving to the Right of (overtake) the Right Scooter's position.

Category historicalUsage Tagname.ScooterLockRight


Remarks In general, it is beneficial to prevent the operator from moving the Left Scooter farther right than the Right Scooter's current position. When the right scooter is not locked, the left scooter will force the right scooter position to be equal to the left scooter position whenever the left scooter overtakes the right scooter.

Data Type Discrete (read/write)Valid Values 0 = False = Left Scooter can overtake the Right Scooter's position

1 = True = Left Scooter cannot overtake the Right Scooter's positionExample(s) When the following statement executes, the Left Scooter, associated with the

Hist Trend tagname MyHistTrendTag, will not be able to move to the right of the Right Scooter's current position.

MyHistTrendTag.ScooterLockRight=1;

See Also .ScooterPosRight, .ScooterPosLeft, .ScooterLockLeft

Monitors and/or controls the position of the Left Scooter.Category historicalUsage Tagname.ScooterPosLeft


Remarks This read/write dotfield dynamically controls the position of the Left Scooter. You can use this dotfield in a QuickScript function to retrieve the current position of the Left Scooter, or you can assign a value to this dotfield to adjust the position of the Left Scooter to another location on the Trend.

This dotfield is most often used in conjunction with the HTGetValue() function collection. These functions must be told which Historical Trend is being queried, as well as the current position of the Trend's scooters.

Data Type Real (read/write)Valid Values 0.0 to 1.0; where 0 is the extreme left hand side of the Historical Trend chart,

and 1.0 is the extreme right hand side of the Historical Trend chart.


152 Chapter 2

Example(s) When the following statement executes a new location is set for the Left Scooter. The Left Scooter will be moved to a location 34% of the chart's total length away from the extreme left hand side of the Historical Trend chart currently associated with the Hist Trend tagname MyHistTrendTag.

MyHistTrendTag.ScooterPosLeft=.34;

In the following statement, the QuickScript function HTGetValueAtScooter() is used to retrieve the value of Pen1 at the Left Scooter's current position. Since a change to any variable within a function's parameter list causes the function to be re-evaluated, each time the position of the Left Scooter changes, this statement will be re-evaluated.

MyRealTag=HTGetValueAtScooter(MyHistTrendTag,MyHistTrendTag.UpdateCount,1,MyHistTrendTag.ScooterPosLeft,1,"PenValue");

See Also .ScooterPosRight, .ScooterLockLeft, .ScooterLockRight


Dotfields 153

.ScooterPosRight

.Successful

Monitors and/or controls the position of the Right Scooter.Category historicalUsage Tagname.ScooterPosRight


Remarks This read/write dotfield dynamically controls the position of the Right Scooter. You can use this dotfield in a QuickScript function to retrieve the current position of the Right Scooter, or you can assign a value to this dotfield to adjust the position of the Right Scooter to another location on the trend.

This dotfield is most often used in conjunction with the HTGetValue() function collection. These functions must be told which Historical Trend is being queried, as well as the current position of the Trend's scooters. See the following example.

Data Type Real (read/write)Valid Values 0.0 to 1.0; where 0 is the extreme right hand side of the Historical Trend chart,

and 1.0 is the extreme left hand side of the Historical Trend chart.Example(s) When the following statement executes a new location is set for the Right

Scooter. The Right Scooter will be moved to a location 34% of the chart's total length away from the extreme right hand side of the Historical Trend chart which is currently associated with the Historical Trend tagname MyHistTrendTag.

MyHistTrendTag.ScooterPosRight=.34;

This statement uses the QuickScript function HTGetValueAtScooter() to retrieve the value of Pen1 at the Right Scooter's current position. Since a change to any variable within a function's parameter list causes the function to be re-evaluated, each time the position of the Right Scooter changes, this statement is re-evaluated.

MyRealTag=HTGetValueAtScooter(MyHistTrendTag,MyHistTrendTag.UpdateCount,2,MyHistTrendTag.ScooterPosRight,1,"PenValue");

See Also .ScooterPosLeft, .ScooterLockLeft, .ScooterLockRight

Represents whether the current query was successful.Category alarmsUsage [ErrorNumber=]GetPropertyD("ObjectName.Successful",

Tagname);


154 Chapter 2


AlmObj_1.Tagname A Discrete tagname that holds the property value

when the function is processed.Remarks This read-only dotfield contains the state of the last query used by a named

distributed alarm display object.Data Type Discrete (read-only)Valid Values 0 = Error in query

1 = Successful queryExample(s) The following statement returns the state of the last query of distributed alarm

object "AlmObj_1" to the Discrete tagname AlmFlag:

GetPropertyD("AlmObj_1.Successful",AlmFlag);

See Also GetPropertyD()


Dotfields 155

.SuppressRetain

.TagID

.TimeDate

Reads/writes the status of the feature that retains the suppression for the Distributed Alarm Display Object.

Category alarmsUsage [ErrorNumber=]GetPropertyD(“ObjectName.SuppressRetain”,

Tagname”);

[ErrorNumber=]SetPropertyD(“ObjectName.SuppressRetain”,Tagname”);

Parameter DescriptionObjectName Name of the Distributed Alarm Object. For

example, AlmObj_1.Tagname A Discrete tagname that holds the property value

when the function is processed.Data Type Discrete (read-write)Valid Values 0 = Retain Off

1 = Retain OnExample(s) The following statement sets the status of suppression retainer for the

“AlmObj_1” from the Discrete tagname, SupRtn:

SetPropertyD(“AlmObj_1.SuppressRetain”, SupRtn);

See Also GetPropertyD(), SetProperty()

Used in conjunction with the Historical Trend .Pen1-.Pen8 TagID tagnames to monitor and/or control the tagname being trended by a pen.

Category tagnameUsage Tagname.TagID


Discrete or Indirect Analog tagname.Remarks .TagID provides the handle of a tagname and is used mainly in the context of

assigning tagnames to pens in a Historical Trend.Data Type TagID (read-only)Example(s) MyHistTrendTag.Pen6=SomeAnalogTag.TagID;

See Also .Pen1-.Pen8

Integer Tagname.field used to display the whole number of days that have passed since an I/O value provided by an I/O server when the I/O connection is valid.

Category tagname


156 Chapter 2

Usage Tagname.TimeDate

Parameter DescriptionTagname Any Discrete, Integer, or Real tagname, or, Indirect

Analog or Indirect Message tagname.Data Type Integer (read-only)See Also .TimeDateString, .TimeDay, .TimeDateTime, .TimeHour, .TimeMinute,

.TimeMsec, .TimeMonth, .TimeSecond, .TimeTime, .TimeTimeString,

.TimeYear


Dotfields 157

.TimeDateString

.TimeDateTime

.TimeDay

String that display the date in the same format set in the Windows Registry.Category tagnameUsage Tagname.TimeDateString


Analog or Indirect Message tagname.Data Type Message (read-only)See Also .TimeDate, .TimeDay, .TimeDateTime, .TimeHour, .TimeMinute,


.TimeYear

Real Tagname.field used to display the fractional number of days that have passed since an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeDateTime


Analog or Indirect Message tagname.Data Type Real (read-only)See Also .TimeDate, .TimeDateString, .TimeDay, .TimeHour, .TimeMinute,


.TimeYear

Integer Tagname.field used to display the day an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeDay


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values Value may be 1 - 31.See Also .TimeDate, .TimeDateString, .TimeDateTime, .TimeHour, .TimeMinute,


.TimeYear


158 Chapter 2

.TimeHour

.TimeMinute

.TimeMonth

Integer Tagname.field used to display the hour of the day that an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeHour


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values Value may be 0 - 23.See Also .TimeDate, .TimeDateString, .TimeDay, .TimeDateTime, .TimeMinute,


.TimeYear

Integer Tagname.field used to display the minute that an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeMinute


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values Value may be 0 - 59.See Also .TimeDate, .TimeDateString, .TimeDay, .TimeDateTime, .TimeHour,


.TimeYear

Integer Tagname.field used to display the month that an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeMonth



.TimeMinute, .TimeMsec, .TimeSecond, .TimeTime, .TimeTimeString,

.TimeYear


Dotfields 159

.TimeMsec

.TimeSecond

.TimeTime

Integer Tagname.field used to display the time in milliseconds that an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeMsec



.TimeMinute, .TimeMonth, .TimeSecond, .TimeTime, .TimeTimeString,

.TimeYear

Integer Tagname.field used to display the time in seconds that an I/O value provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeSecond



.TimeMinute, .TimeMsec, .TimeMonth, .TimeTime, .TimeTimeString,

.TimeYear

Integer Tagname.field used to display the time in milliseconds (since midnight) that an I/O value was provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeTime


Analog or Indirect Message tagname.Data Type Integer (read-only)


160 Chapter 2

Valid Values Value may be 0 - 86399999.See Also .TimeDate, .TimeDateString, .TimeDay, .TimeDateTime, .TimeHour,

.TimeMinute, .TimeMsec, .TimeMonth, .TimeSecond, .TimeTimeString,

.TimeYear


Dotfields 161

.TimeTimeString

.TimeYear

.TopIndex

Message Tagname.field used to display the time and day of an I/O value provided by an I/O server when the I/O connection is valid.

Category TagnameUsage Tagname.TimeTimeString


Analog or Indirect Message tagname.Data Type Message (read-only)See Also .TimeDate, .TimeDateString, .TimeDay, .TimeDateTime, .TimeHour,

.TimeMinute, .TimeMsec, .TimeMonth, .TimeSecond, .TimeTime,

.TimeYear

Integer Tagname.field used to display the year is four digits that an I/O value was provided by an I/O server when the I/O connection is valid.

Category tagnameUsage Tagname.TimeTime


Analog or Indirect Message tagname.Data Type Integer (read-only)Valid Values Any year in the format ####. For example 1998.See Also .TimeDate, .TimeDateString, .TimeDay, .TimeDateTime, .TimeHour,

.TimeMinute, .TimeMsec, .TimeMonth, .TimeSecond, .TimeTime,

.TimeTimeString

Determines the corresponding integer index of the top-most item in a List box.

Category windows controlUsage [ErrorNumber=]GetPropertyI("ControlName.TopIndex",

Tagname);[ErrorNumber=]SetPropertyI("ControlName.TopIndex",Number);


ListBox_1.Tagname An Integer tagname that holds the property value

when the function is processed.Number The index number that defines the top-most item in

the List box.


162 Chapter 2

Remarks This property is available only in runtime.Data Type Integer (read/write)Applies To List boxes. Example(s) The following statement sets the TopIndex of the List box object "ListBox_1"

to a value of 14:

SetPropertyI("ListBox_1.TopIndex",14);

See Also GetPropertyI(), SetPropertyI(), .ListIndex, .NewIndex


Dotfields 163

.TotalPages

.UnAck

Contains the total number of pages (one screen full of alarms) in the distributed alarm object.

Category alarmsUsage [ErrorNumber=]GetPropertyI("ObjectName.TotalPages",

Tagname);



when the function is processed.Remarks This read-only dotfield contains the total number of alarm pages contained in

a named distributed alarm display object.Data Type Integer (read-only)Example(s) The following statement returns the total number of alarm pages contained in

distributed alarm object "AlmObj_1" to the Integer tagname AlmTotalPage:

GetPropertyI("AlmObj_1.TotalPages",AlmTotalPages);

See Also GetPropertyI(), .NextPage, .PrevPage, .PageNum

Controls the alarm acknowledgement status of local alarm(s).Category alarmsUsage Tagname.UnAck=0


Analog tagname or Alarm Group.Remarks Set this dotfield to a value of 0 to acknowledge any outstanding alarm(s)

associated with the specified tagname/group. When the specified tagname is an Alarm Group, all unacknowledged alarms associated with the tagnames within the specified group are acknowledged. When the specified tagname is any other type, only the unacknowledged alarm associated with that tagname is acknowledged. Setting this dotfield to a value other than 0 has no meaning, and the results are undefined.

Data Type Discrete (read/reset only)Valid Values 0


164 Chapter 2

Example(s) The following statement acknowledges any alarm associated with a tagname Tag1.

Tag1.UnAck=0;

This statement acknowledges all unacknowledged alarms within the alarm group named PumpStation.

PumpStation.UnAck = 0;

Note .UnAck has an inverse dotfield called .Ack. When an alarm has been acknowledged, .Ack will be set to 1.

See Also .Ack, Ack(), .Alarm, .AlarmAckModel


Dotfields 165

.UpdateCount

.UpdateInProgress

Incremented each time an update has occurred for the associated Trend.Category historicalUsage Tagname.UpdateCount


Remarks This dotfield is linked directly to the historical retrieval sub-system. Whenever new data is requested from the Historical Trend associated with the specified Hist Trend tagname, the historical retrieval sub-system goes out to disk and retrieves the specified data. Once the retrieval process is completed, this dotfield is incremented by a value of 1. .UpdateCount is used as a trigger in many of the function calls related to Historical Trends to cause recalculation of the function.

Data Type Integer (read-only)Valid Values Any positive IntegerExample(s) The following statement uses the QuickScript function

HTGetValueAtScooter() to retrieve the value of Pen1 at the Right Scooter's current position. Since a change to any variable within a function's parameter list causes the function to be re-evaluated, each time a retrieval (update) is completed, and the value of .UpdateCount is incremented, this statement is re-evaluated.

MyRealTag=HTGetValueAtScooter(MyHistTrendTag,MyHistTrendTag.UpdateCount,2,MyHistTrendTag.ScooterPosRight,1,"PenValue");

See Also .UpdateInProgress, .UpdateTrend

Equal to 1 if a Historical Retrieval is in progress; otherwise equal to 0.Category historicalUsage Tagname.UpdateInProgress



166 Chapter 2

Remarks This dotfield is linked directly to the historical retrieval sub-system. Whenever new data is requested from the Historical Trend associated with the specified Hist Trend tagname, the historical retrieval sub-system goes out to the disk and retrieves the specified data. During the retrieval process this dotfield's value is set to 1. Once the process is completed, ..UpdateInProgress is reset to 0. .UpdateInProgress is used in many of the function calls related to Historical Data Trends.

Most Historical Trend screens have a mechanism that an operator uses to scroll through the data on the Trend. As the operator manipulates the controls on the screen, the Historical Subsystem verifies that the data on the screen is current. If the operator scrolls the trend to a section in time that is not currently displayed or sitting in memory, the subsystem goes out to disk and retrieves the requested data. Since this process can take some time, the system provides a way for the designer of the Historical Trend object to alert the operator that the requested data is currently being retrieved. Without this feedback, the operator may not be aware that the system is performing the requested task.

Data Type Discrete (read-only)Value Values 0 = No update in progress

1 = Update in progressExample(s) The following statement is commonly used as the expression in a Visibility

link on a text object near or on the scroll buttons on a Historical Trend. When the historical subsystem is retrieving the requested data, this expression evaluates to a value of 1. Otherwise, if the Historical Trend is up-to-date, the expression evaluates to a value of 0.

MyHistTrendTag.UpdateInProgress

See Also .UpdateCount, .UpdateTrend


Dotfields 167

.UpdateTrend

.Value

Causes a Historical Trend chart to update using all current values.Category historicalUsage Tagname.UpdateTrend


Remarks Historical Trends do not automatically update themselves. A change must be made to either the Chart Start or the Chart Length in order for the chart to update and display the current values for the specified tagnames. By using this dotfield in a Touch Pushbutton Action QuickScript, the operator can update the chart at any time in runtime.

You can also use this dotfield in a QuickScript if other dotfields associated with the Historical Trend are going to be changed. This will ensure an up-to-date display on the Historical Trend Chart.

Setting this dotfield to a value other than 1 has no meaning, and the results are undefined.

Data Type Discrete (write only)Valid Values 1Example(s) The following statement causes the Historical Trend associated with the Hist

Trend tagname MyHistTrendTag to update with the current values of all parameters:

MyHistTrendTag.UpdateTrend=1;

Contains the value of the specified tagname. This is also the default dotfield for every tagname within the system. If no other dotfield is specified, this dotfield is assumed.

Category tagnameUsage Tagname.Value

Parameter DescriptionTagname Any tagname except Hist Trend tagname.

Remarks This is the default dotfield for every tagname within the system. If no other dotfield is specified, this dotfield is assumed. You will rarely need to use this dotfield. However, in some instances, it makes a calculation or parameter usage clearer, therefore, it can be useful as a documentation tool.

Data Type Depends on (is the same as) the specified tagname's type (read/write).


168 Chapter 2

Example(s) The following statement sets the value of the Memory Integer tagname MyTag equal to 100:

Tagname.Value=100;

Which is functionally identical to:

Tagname=100;


Dotfields 169

.ValueThe default property for all InTouch windows control wizards. Changes made to this property are synchronized in the InTouch tagname and the windows control wizards.

Category windows controlUsage [ErrorNumber=]GetPropertyM("ControlName[.Value]",Tagname)

;[ErrorNumber=]SetPropertyM("ControlName[.Value]", Value);[ErrorNumber=]GetPropertyI("ControlName[.Value]",Tagname);[ErrorNumber=]SetPropertyI("ControlName[.Value]",Value);[ErrorNumber=]GetPropertyD("ControlName[.Value]",Tagname);[ErrorNumber=]SetPropertyD("ControlName[.Value]",Value);

Note The initial value of tagnames assigned to either a List box or Combo box cannot be used to initialize the value of the List box or Combo box.Parameter DescriptionControlName Name of the windows control, e.g., ChkBox_4.Tagname A valid tagname that contains the integer count of

the items in the list.[.Value] This property is optional. If not specified, the

function will always assume the .Value property is being used.

Value The actual value to be written or a valid InTouch tagname (of the same type as the property to be written to) that holds the property value to be written when the function is processed.

Remarks This property is read/write during development and runtime. If the .Value is accessed by associating a tagname to either a List box or a Combo box, it is read-only. If the .Value is assigned to a Check box, Radio button, or Text box it is read/write. The value specified at development serves as the default for runtime.

Data Type Message (read/write) for Text boxes, List boxes and Combo boxes.Integer (read/write) for Radio buttonsDiscrete (read/write) for Check boxes.

Applies To Text boxes, List boxes, Combo boxes, Check boxes and Radio buttons.Example(s) The following statement sets the Value of the Radio Button object

"RadioButton_1" to a value of 4:

SetPropertyI( "RadioButton_1.Value",4 );

See Also GetPropertyM(), SetPropertyM(), GetPropertyI(), SetPropertyI(), GetPropertyD(), SetPropertyD()


170 Chapter 2

.VisibleDetermines whether the windows control is visible in the window.

Category windows controlUsage [ErrorNumber=]GetPropertyD("ControlName.Visible",Tagname)

;[ErrorNumber=]SetPropertyD("ControlName.Visible",Number);


ListBox_1.Tagname A tagname (of the same type to be returned) that

holds the property value when the function is processed.

Number A discrete value. Or, a Discrete tagname that holds the value to be written when the function is processed.

Remarks This property is read/write in both development and runtime.Data Type Discrete (read/write)Valid Values 0 = Control is invisible

1 = Control is visibleApplies To Text boxes, List boxes, Combo boxes, Check boxes and Radio buttons. Example(s) The following statement creates an invisible Text box named "TextBox_1".

SetPropertyD("TextBox_1.Visible",0);



InTouch QuickScript Functions 171

C H A P T E R 3

InTouch QuickScript Functions

InTouch QuickScripting is one of the most powerful features of an InTouch application. The InTouch QuickScript capabilities allow you to execute commands and logical operations based on specified criteria being met. For example, a key being pressed, a window being opened, a value changing, and so on.

QuickFunctions are QuickScripts you create that are called from other QuickScripts and animation link expressions (see Note below). The reused code is stored in one QuickScript and in one location, thereby supporting update of all QuickScript instances with one edit session.

Note A "trigger" tagname must be used as a parameter for the QuickFunction to force the Animation Link to update. For example, using the tagname $Second as the parameter for the QuickFunction will cause the expression for the Animation Link to be evaluated every time $Second changes value thus, resulting in the QuickFunction being called every second.

By using InTouch QuickScripts, a wide variety of customized and automated system functions can be created.


172 Chapter 3

Abs()

Ack()

Returns the absolute value (unsigned equivalent) of a specified number.Category mathSyntax Result=Abs(Number);

Parameter DescriptionNumber Any number, Real or Integer tagname.

Remarks The absolute value of Number is calculated and returned to Result.Example(s) Abs(14) will return 14

Abs(-7.5) will return 7.5

Acknowledges any unacknowledged InTouch alarm.Category alarmSyntax Ack Tagname;

Parameter DescriptionTagname Any InTouch tagname, Alarm Group, or Group

Variable.Remarks This function can be applied to a tagname, Alarm Group or Group Variable.

(A Group Variable is a tagname that has the name of an Alarm Group assigned to it.)

Example(s) The following statements can be used on a push button to acknowledge any unacknowledged alarm:Ack $System; (All alarms)

Ack Tagname;

Ack GroupName;

Ack GroupVariable;

See Also almAckAll(), almAckGroup() almAckTag(), almAckDisplay(), almAckRecent(), almAckPriority(). almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()



ActivateApp()

AddPermission()

Activates another currently running windows application. Category systemSyntax ActivateApp TaskName;

Parameter DescriptionTaskName The task this function will activate.

Remarks TaskName is the exact text string, including spaces, that appears on the Task Bar or in the Task Manager (accessed by right-clicking the Taskbar in Windows NT and then clicking Task Manager or Ctrl+Alt+Delete).

Example(s) The following example checks to see if the command prompt is running. If it is running, it brings it to the foreground and gives it focus. Otherwise, it launches a command prompt and starts the edit.com DOS program inside the command prompt. IF InfoAppActive( InfoAppTitle("cmd")) == 1 THENActivateApp InfoAppTitle("cmd");

ELSEStartApp "cmd /c edit";

ENDIF;

See Also StartApp(), InfoAppTitle()

Attempts to reach the account Account located on domain Domain Category securitySyntax DiscreteTag=AddPermission( "Domain", "Group",

AccessLevel);

Parameter DescriptionDomain Name of the domain or local machine in which

the group is located.Group Windows user group.AccessLevel InTouch AccessLevel that is associated with the

given groupRemarks Valid for OS security mode only. An attempt is made to reach the account

Account located on domain Domain. If successful, a TRUE is returned and the access level iAccessLevel is assigned to the account in the internal records in InTouch for use during authorization when a user logs on. In all other cases, a FALSE is returned.

Example(s) DiscreteTag=AddPermission( "wonderware_hq","InTouchAdmins", 9000);DiscreteTag=AddPermission("ravih01", "InTouchUsers", 5000);

See Also PostLogonDialog(), InvisibleVerifyCredentials(), IsAssignedRole(), AttemptInvisibleLogon(), QueryGroupMembership().


174 Chapter 3

almAckAll()

almAckDisplay()

almAckGroup()

Acknowledges all alarms in current query including those not currently displayed in the alarm summary display object.

Category alarmsSyntax [Result=]almAckAll(ObjectName,Comment);

Parameter DescriptionObjectName The name of the alarm object. For example,

AlmObj_1.Comment Alarm acknowledgment comment.

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) MessageTag = “Acknowledge All by” + $Operator;

almAckAll(“AlmObj_1”, MessageTag);

See Also Ack(), almAckGroup(), almAckTag(), almAckDisplay(), almAckRecent(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()

Acknowledges only those alarms currently visible in the alarm summary display object.

Category alarmsSyntax [Result=]almAckDisplay(ObjectName,Comment);



Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almAckDisplay(“AlmObj_1”, “Display Acknowledgement”);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckRecent(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()

Acknowledges all alarms that are contained by a named Distributed Alarm Display Instance as a result of the display’s last query AND where the resultant alarm contains the same alarm group name and provider name.

Category alarmsSyntax [Result=]almAckGroup(ObjectName, ApplicationName,

GroupName, Comment);

Parameter Description



ObjectName The name of the alarm object. For example, AlmObj_1.

ApplicationName The name of the Application for example, \\node1\Intouch

GroupName The name of the Group for example, $SystemComment Alarm acknowledgment comment.

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) MessageTag = “Acknowledge group, Turbines, by” +

$Operator; almAckGroup(“AlmObj_1”, “\Intouch”,“Turbine”, MessageTag);

See Also Ack(), almAckAll(), almAckDisplay(), almAckTag(), almAckRecent(), almAckPriority(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()


176 Chapter 3

almAckPriority()

almAckRecent()

Acknowledges all alarms that are contained by a named Distributed Alarm Display Instance as a result of the display’s last query AND where the resultant alarms are of the specified priority range having same provider name and group name.

Category alarmsSyntax [Result=]almAckPriority(ObjectName, ApplicationName,

GroupName, FromPri, ToPri, Comment);


AlmObj_1.ApplicationName The name of the Application for example,

\\node1\IntouchGroupName The name of the Group for example, $SystemFromPri Starting priority of alarms. For example, 100.ToPri Ending priority of alarms. For example, 900.Comment Alarm acknowledgment comment.

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almAckPriority(“AlmObj_1”,“\\node1\Intouch”,

“Turbines”, 10, 100, “almAckPriorityComment”);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()

Acknowledges the most recent alarms that have occurred.Category alarmsSyntax [Result=]almAckRecent(ObjectName,Comment);



Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almAckRecent(“AlmObj_1”, $DateString);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()



almAckSelect()

almAckSelectedGroup()

Acknowledges only those alarms selected in the alarm summary display object.

Category alarmsSyntax [Result=]almAckSelect(ObjectName,Comment);



Remarks For a list of returned error numbers, see APPENDIX A.Example(s) IF ($Hour > 0 and $Hour < 8) THEN

AckTag = “NightShift”;

ELSEAckTag = “Day Shift”;

ENDIF;

almAckSelect (“AlmObj_1”,AckTag);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckRecent(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag()

Acknowledges all alarms with same provider and group names that have the same group name as one or more of the alarms that are selected within the named Distributed Alarm Display Control instance.

Category alarmsSyntax [Result=]almAckSelectedGroup(ObjectName,Comment);



RemarksExample(s) MessageTag = “Acknowledge selected groups by” +

$Operator;

almAckSelectedGroup (“AlmObj_1”, MessageTag);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckRecent(), almAckSelect(), almAckSelectedPriority(), almAckSelectedTag()


178 Chapter 3

almAckSelectedPriority()

almAckSelectedTag()

Acknowledges all alarms with same provider and group names that have the same priority value as one or more of the alarms that are selected within the named Distributed Alarm Display Control instance.

Category alarmsSyntax [Result=]almAckSelectedPriority(ObjectName, Comment);



Remarks The priorities are calculated from the selected alarm records. The Min. and the Max. priorities are taken.

Example(s) MessageTag = “Acknowledge selected priorities by” +$Operator;

almAckSelectedPriority (“AlmObj_1”, MessageTag);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckRecent(), almAckSelect(), almAckSelectedGroup(), almAckSelectedTag()

Acknowledges all alarms that have the same Tagname from the same provider and group name and having the same priority as one or more of the selected alarms within the named Distributed Alarm Display Control instance.

Category alarmsSyntax [Result=]almAckSelectedTag(ObjectName,Comment);



RemarksExample(s) MessageTag = “Acknowledge selected tagnames by” +

$Operator;

almAckSelectedTag (“AlmObj_1”, MessageTag);

See Also Ack(), almAckAll(), almAckGroup(), almAckTag(), almAckDisplay(), almAckRecent(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority()



almAckTag()Acknowledges all alarms that are contained by the named Distributed Alarm Display instance as a result of the display’s last query and given the tagname.

Category alarmsSyntax [Result=]almAckTag(ObjectName, ApplicationName,

GroupName, Tagname, FromPri, ToPri, Comment);


AlmObj_1.ApplicationName The name of the Application. For example,

\\node1\Intouch.GroupName The name of the Group. For example, $System.Tagname The name of the alarm tagname.FromPri Starting priority of alarms. For example, 100.ToPri Ending priority of alarms. For example, 900.Comment Alarm acknowledgment comment.

RemarksExample(s) almAckTag(“AlmObj_1”, “\\node1\Intouch”, “Turbines”,

“Valve1”, 10, 100,“Value”, “LoLo”, “almAckTagComment”);

See Also Ack(), almAckAll(), almAckGroup(), almAckDisplay(), almAckRecent(), almAckSelect(), almAckSelectedGroup(), almAckSelectedPriority(), almAckSelectedTag(0


180 Chapter 3

almDefQuery()

almMoveWindow()

Performs a query to update a named Distributed Alarm Display instance using the default properties.

Category alarmsSyntax [Result=]almDefQuery(ObjectName);


AlmObj_1.Remarks The default query properties are specified during development.

For a list of returned error numbers, see APPENDIX A.Example(s) almDefQuery(“AlmObj_1”);

See Also almQuery(), almSetQueryByName()

Scrolls for a named Distributed Alarm Display instance window.Category alarmsSyntax [Result=]almMoveWindow(ObjectName,Options,Repeat);


AlmObj_1.Option The type of action to perform:

Type DescriptionLineDn One line down.LineUp One line up.PageDn One page down.PageUp One page up.Top To the top of the list.Bottom To the bottom of the list.PageRt One page to the right.PageLf One page to the left.Right To the end of the list (right side).Left To the beginning of the list (left side).

Repeat The number of times this operation should be repeated.

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almMoveWindow(“AlmObj_1”, ”Bottom”, 0);

almMoveWindow(“AlmObj_1”, ”LineDn”, 3);

almMoveWindow(“AlmObj_1”, ”PageUp”, 0);



almQuery()Performs a query to update a named Distributed Alarm Display instance.

Category alarmsSyntax [Result=]almQuery(ObjectName,AlarmList,FromPri,ToPri,St

ate,Type);


AlmObj_1.AlarmList Sets the Alarm Query/Name Manager alias to

perform the query against, for example, "\intouch!$System" or a Message tagname.

FromPri Starting priority of alarms to display. For example, 100 or integer tagname.

ToPri Ending priority of alarms to display. For example, 900 or integer tagname.

State Specifies type of alarms to display. For example, "UnAck" or Message tagname. Valid states are All, UnAck or Ack.

Type Specifies type of query for example, "Hist" (Historical alarms) or "Summ" (Summary alarms).

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) This statement retrieves all of the historical alarms specified in

MyAlarmListGroup between priority 500 and 600. The alarms will populate alarm display "AlmObj_1."almQuery("AlmObj_1","MyAlarmListGroup",500,600,"All","Hist");

Example of valid syntax for the AlarmList parameter:MyAlarmList

Where MyAlarmList is an alarm list configured from the Name Manager setup.\intouch!GroupA

Where GroupA is an Alarm group defined on the local node.\\NodeXInTouch!GroupB

Where GroupB is an Alarm group defined on Node X.See Also almDefQuery(), almSetQueryByName()


182 Chapter 3

almSelectAll()

almSelectGroup()

Toggles the selection of all the alarms in a named Distributed Alarm Display instance.

Category alarmsSyntax [Result=]almSelectAll(ObjectName);


AlmObj_1.Remarks For a list of returned error numbers, see APPENDIX A.Example(s) If $AccessLevel > 8000 THEN

almSelectAll(“AlmObj_1”);almAckSelect(“AlmObj_1”, “Ack Selected by a Manager”);

ENDIF;

See Also almSelectItem(), almSelectGroup(), almSelectPriority(), almSelectTag(), almUnSelectAll()

Toggles the selection of all alarms that are contained by a named Distributed Alarm Display instance as a result of the display’s last query and where the resultant alarm contains the same alarm group name.

Category alarmsSyntax [Result=]almSelectGroup(ObjectName, ApplicationName,

GroupName);



\\node1\Intouch.GroupName The name of the Group. For example, $System.

Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almSelectGroup(“AlmObj_1”, “\InTouch”, “Turbine”);

See Also almSelectAll(), almSelectItem(), almSelectPriority(), almSelectTag(), almUnSelectAll()



almSelectionCount()

almSelectItem()

Returns the integer value containing the number of alarms selected by the operator in the Distributed Alarm Object.

Syntax [Result=]almSelectionCount(ObjectName);


AlmObj_1.Example(s) Tag1 = almSelectionCount(“AlmObj_1”);

Toggles the selection of the item that is highlighted in an alarm display object.

Category alarmsSyntax [Result=]almSelectItem(ObjectName);


AlmObj_1.Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almSelectItem(“AlmObj_1”);

See Also almSelectAll(), almSelectGroup(), almSelectPriority(), almSelectTag(), almUnSelectAll()


184 Chapter 3

almSelectPriority()Toggles all alarms that are contained by the named Distributed Alarm Display instance as a result of the display’s last query and where the resultant alarms are the specified priority range.

Category alarmsSyntax [Result=]almSelectPriority (ObjectName,

ApplicationName, GroupName, FromPri, ToPri);



\\node1\Intouch.GroupName The name of the Group. For example, $System.FromPri Starting priority of alarms. For example, 100 or

Integer tagname.ToPri Ending priority of alarms. For example, 900 or

Integer tagname.Example(s) almSelectPriority(“AlmObj_1”, “\\node1\Intouch”,

“Turbines”, 10, 100);

See Also almSelectAll(), almSelectItem(), almSelectGroup(), almSelectTag(), almUnSelectAll()



almSelectTag()

almSetQueryByName()

Toggles all alarms that are contained by the named Distributed Alarm Display instance as a result of the display’s last query and given tagname.

Category alarmsSyntax [Result=]almSelectTag (ObjectName, ApplicationName,

GroupName, Tagname, FromPri, ToPri);



\\node1\Intouch.GroupName The name of the Group. For example, $System.Tagname The name of the alarm tagname.FromPri Starting priority of alarms. For example, 100 or


Integer tagname.RemarksExample(s) almSelectTag(“AlmObj_1”, “\\node1\Intouch”, “Turbines”,

“Valve1”, 10, 100);

See Also almSelectAll(), almSelectItem(), almSelectGroup(), almSelectPriority(), almUnSelectAll()

Start a new alarm query for the named instance of the Distributed Alarm Display Control using the query parameters associated with a user defined (favorite) query name.

Category alarmsSyntax [Result=]almSetQueryByName(ObjectName, QueryName);


AlmObj_1.QueryName The name of the query as created by using “Query

Favorites”Remarks This is a query for the particular instance of the Distributed Alarm Display.

There may be several such displays on the screen, each with its own query.Example(s) almSetQueryByName(“AlmObj_1”, “Turbine Queries”);

See Also almQuery(), almDefQuery()


186 Chapter 3

almShowStats()

almSuppressAll()

Displays the alarm display object statistics screen.Category alarmsSyntax [Result=]almShowStats(ObjectName);


AlmObj_1.Remarks For a list of returned error numbers, see APPENDIX A.Example(s) almShowStats(“AlmObj_1”);

Suppress the display of all current and future instances of the alarms in the current query including those not currently displayed in the alarm summary display object.

Category alarmsSyntax [Result=] almSuppressAll(ObjectName);


AlmObj_1.Remarks This function works like almAckAll(), identifying which alarms to

suppress by identifying all alarms that you would see if you looked at the display and scrolled up and down to look at them all.

Example(s) almSuppressAll(“AlmObj_1”);

See Also almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressPriority(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()



almSuppressGroup()Suppress the display of current and future occurrences of the alarms that belong to a given Group name.

Category alarmsSyntax [Result=]almSuppressGroup(ObjectName, ApplicationName,

GroupName);


AlmObj_1.ApplicationName The name of the application. For example,

\\node1\InTouchGroupName The name of the Group. For example, $System

Example(s) almSuppressGroup(“AlmObj_1”, “\InTouch”, “Turbines”);

See Also almSuppressAll(), almSuppressTag(), almSuppressDisplay(), almSuppressPriority(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()


188 Chapter 3

almSuppressDisplay()

almSuppressPriority()

Suppress the display of current and future occurrences of those alarms visible in the alarm summary display object.

Category alarmsSyntax [Result=]almSuppressDisplay(ObjectName);


AlmObj_1.Remarks This function works like the corresponding almAckDisplay() function,

identifying which alarms to suppress by identifying all alarms that are currently displayed.

Example(s) almSuppressDisplay(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressPriority(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()

Suppress the display of current and future occurrences of any alarm of the specified priority range, having the same Provider name and Group name.

Category alarmsSyntax [Result=]almSuppressPriority(ObjectName,

ApplicationName, GroupName, FromPri, ToPri);



\\node1\Intouch.GroupName The name of the Group. For example, $System.FromPri Starting priority of alarms. For example, 100 or


Integer tagname.Example(s) almSuppressPriority(“AlmObj_1”, “\\node1\Intouch”,

“Turbines”, 10, 100);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()



almSuppressRetain()

almSuppressSelected()

Retain alarm suppression for all following queries.Category alarmsSyntax [Result=]almSuppressRetain (ObjectName,

SuppressionRetainFlag);


AlmObj_1.SuppressionRetainFlag Any Discrete or Analog tagname, 0 or non-zero

value. TRUE if suppression information is retained for following queries, FALSE otherwise.

Remarks If the flag is 0, when the alarm query is changed, the suppression filters will be discarded.

Example(s) almSuppressRetain(“AlmObj_1”, TRUE);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressPriority(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()

Suppress the display of future occurrences of the alarms selected in the alarm summary display object.

Category alarmsSyntax [Result=]almSuppressSelected (ObjectName);


AlmObj_1.Remarks This functions works like the almAckSelect() function, identifying the

alarms by the ones selected in the display object.Example(s) almSuppressSelected(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressPriority(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()


190 Chapter 3

almSuppressTag()Suppress the display of current and future occurrences of any alarm emitted by a given tagname name, having the same Provider, Group name and Priority range.

Category alarmsSyntax [Result=]almSuppressTag(ObjectName, ApplicationName,

GroupName, TagName, FromPri, ToPri, AlarmClass,AlarmType);



\\node1\Intouch.GroupName The name of the Group. For example, $System.TagName The name of the alarm tagname.FromPri Starting priority of alarms. For example, 100 or


Integer tagname.AlarmClass The alarm class of the alarm. For example, “Value.”AlarmType The alarm type of the alarm. For example, “HiHi.”

RemarksExample(s) almSuppressTag(“AlmObj_1”, “\\node1\Intouch”,

“Turbines”, “Valve1”, 10, 100, “Value”, “LoLo”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressDisplay(), almSuppressPriority(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag(), almUnSuppressAll()



almSuppressSelectedGroup()Suppress the display of current and future occurrences of the alarms that belong to the same groups of one or more selected alarms having the same Provider name within the named Distributed Alarm Display Control.

Category alarmsSyntax [Result=]almSuppressSelectedGroup(ObjectName);


AlmObj_1.Remarks This functions works like the almAckSelectedGroup() function,

identifying the alarms that are selected, then identifying the groups to which they belong, and suppressing future occurrences of the alarms from those groups.

Example(s) almSuppressSelectedGroup(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressSelected(), almSuppressSelectedPriority(), almSuppressSelectedTag()


192 Chapter 3

almSuppressSelectedPriority()

almSuppressSelectedTag()

Suppress the display of current and future occurrences of the alarms that belong to the same priority of one or more selected alarms having the same Provider name and Group tag within the named Distributed Alarm Display Control.

Category alarmsSyntax [Result=]almSuppressSelectedPriority(ObjectName);


AlmObj_1.Remarks The priorities are calculated from the selected alarm records. The min and

the max priorities are taken.

This function works like the almAckSelectedPriority() function, identifying the alarms selected in the display, then identifying the corresponding priorities of those alarms, and suppressing future occurrences of alarms with the same priorities.

Example(s) almSuppressSelectedPriority(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTagName(), almSuppressDisplay(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedTag(), almAckSelectedPriority()

Suppress the display of current and future occurrences of any alarm that belongs to the same Tagname name of one or more selected alarms having the same Provider name, Group name and Priority range.

Category alarmsSyntax [Result=]almSuppressSelectedTag(ObjectName);


AlmObj_1.RemarksExample(s) almSuppressSelectedTag(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressSelectedAlarm(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almAckSelectedTag(), almUnSuppressAll()



almUnSelectAll()

almUnSuppressAll()

Unselects all the selected alarms in a named Distributed Alarm Display instance.

Category alarmsSyntax [Result=]almUnSelectAll(ObjectName);


AlmObj_1.Remarks For a list of returned error numbers, see Appendix A.Example(s) If $AccessLevel == 9999 THEN

almAckSelect(“AlmObj_1”, “Comment”);{This alarm can beacknowledged by only Administrator}

ELSEalmUnSelectAll(“AlmObj_1”);

ENDIF;

See Also almSelectAll(), almSelectItem(), almSelectGroup(), almSelectPriority(), almSelectTag()

Clear all suppressed alarms.Category alarmsSyntax [Result=] almUnSupressAll(ObjectName);


AlmObj_1.Example(s) almUnSupressAll(“AlmObj_1”);

See Also almSuppressAll(), almSuppressGroup(), almSuppressTag(), almSuppressDisplay(), almSuppressPriority(), almSuppressRetain(), almSuppressSelected(), almSuppressSelectedGroup(), almSuppressSelectedPriority(), almSuppressSelectedTag()


194 Chapter 3

ArcCos()

ArcSin()

Given a number between -1 and 1 (inclusive), this function will return an angle between 0 and 180 degrees whose cosine is equal to that number.

Category mathSyntax Result=ArcCos(Number);


Remarks The arc cosine value of Number is calculated and returned to Result.

For a list of returned error numbers, see APPENDIX A.Example(s) ArcCos(1) will return 0

ArcCos(-1) will return 180

See Also Cos(), Sin(), Tan(), ArcSin(), ArcTan()

Given a number between -1 and 1 (inclusive), this function will return an angle between -90 and 90 degrees whose sine is equal to that number.

Category mathSyntax Result=ArcSin(Number);


Remarks The arc sine value of Number is calculated and returned to Result.

For a list of returned error numbers, see APPENDIX A.Example(s) ArcSin(1) will return 90

ArcSin(-1) will return -90

See Also Cos(), Sin(), Tan(), ArcCos(), ArcTan()



ArcTan()

AttemptInvisibleLogon()

Given a number, this function will return an angle between -90 and 90 degrees whose tangent is equal to that number.

Category mathSyntax Result=ArcTan(Number);


Remarks The arc tangent of Number is calculated and returned to Result.

For a list of returned error numbers, see APPENDIX A.Example(s) ArcTan(1) will return 45

ArcTan(0) will return 0

See Also Cos(), Sin(), Tan(), ArcCos(), ArcSin())

Attempts to logon to InTouch using the supplied credentials.Category securitySyntax DiscreteTag=AttemptInvisibleLogon( "UserId",

"Password", "Domain" );

Parameter Description UserId A valid user account name.Password Password of the user.

Domain Name of the local machine, workgroup or domain to which the user belongs. This column applies only if the current security type is OS based.

DiscreteTag Return value: returns TRUE if authentication is successful.. Otherwise, it returns FALSE.

Remarks An attempt is made to logon to InTouch using the supplied credentials ( Domain is ignored if the security mode is not OS ). If the logon attempt succeeds, then TRUE is returned and the system tags $OperatorDomain, $OperatorName, $AccessLevel and $Operator are updated accordingly. If the Logon attempt fails, then FALSE is returned and the currently logged on user ( if any ) continues to be the current user.

Example(s) AnalogTag=InvisibleVerifyCredentials( "ravi","Password", "wonderware_hq" ); \\ security is OS basedAnalogTag=InvisibleVerifyCredentials( "ravi","Password", "" ); \\ security is either InTouch orAppServer based

See Also PostLogonDialog(), InvisibleVerifyCredentials(), IsAssignedRole(), QueryGroupMembership(), AddPermission().


196 Chapter 3

ChangePassword()Displays the Change Password dialog box allowing the logged on operator to change his/her password.

Category securitySyntax [Result=]ChangePassword();

Parameter Description[Result] Returns one of the following integer values:

0 = Cancel was pressed.1 = OK was pressed.

Remarks If using touch screen applications, there is an option to use the alphanumeric keyboard.

Example(s) Errmsg=ChangePassword();

This QuickScript, if placed on a button or called based on a Condition or Data Change QuickScript, will open a dialog box (with optional keyboard) prompting the user to enter the current password, the new password and verification of the new password.



Cos()

DialogStringEntry()

Returns the cosine of an angle given in degrees. Category mathSyntax Result=Cos(Number);


Remarks The cosine of Number is calculated and returned to Result.Example(s) Cos(90) will return 0

Cos(0) will return 1

Wave = 50 * Cos(6 * $Second);

See Also Sin(), Tan(), ArcCos(), ArcSin(), ArcTan()

Displays an alphanumeric keyboard on the screen, allowing the operator to change the current string value of a Message tagname in the Tagname Dictionary.

Category miscSyntax [Result=]DialogStringEntry(MessageTag_Text,

UserPrompt_Text);


0 = Cancel was pressed.1 = OK was pressed.-1 = Internal error.-2 = Could not initiate.-3 = Tagname not defined.-4 = Tagname is not a Message type.-5 = Unable to write.

MessageTag_Text Specifies the name of the Message tagname to be modified. (This function requires a string for this parameter, therefore, you must identify the tagname by its name within quotes or use the .Name field without quotes. A Message tagname used as a pointer is also acceptable. See the following Example.

UserPrompt_Text Specifies the user message to display at the top of the keyboard.

Remarks This function is used primarily in applications containing touch screens.Example Errmsg=DialogStringEntry(MyMessageTag.Name, "Enter a

new string...");

Errmsg=DialogStringEntry("MyMessageTag","Enter a newstring...");


198 Chapter 3

Parameters could also act as "pointers" to other tagnames, allowing the function to be dynamic during runtime.

Errmsg=DialogStringEntry(MessageTagX, MessageDisplay);

Using the above example, input links can be assigned to each of the pointer tagnames, allowing the user to modify any or all of the function parameters before processing the function. For example, the following QuickScript would bring up an alphanumeric keyboard, allowing modification of MyMessageTag while displaying the message "Enter a new string..." at the top of the keyboard:

MessageTagX="MyMessageTag"; {assign the stringMyMessageTag (which is actually the tagname to bemodified) to the Memory Message tagname MessageTagX}

MessageDisplay="Enter a new string..."; {assign the newmessage string to the Memory Message tagnameMessageDisplay}

Errmsg=DialogStringEntry(MessageTagX, MessageDisplay);{quotes are not required because MessageTagX was definedas a Message tagname}

See Also DialogValueEntry()



DialogValueEntry()Displays the numeric keypad on the screen, allowing the user to change the current value of a Discrete, Integer or Real tagname in the Tagname Dictionary.

Category miscSyntax [Result=]DialogValueEntry(ValueTag_Text,

LowLimit,HighLimit,UserPrompt_Text);


0 = Cancel was pressed.1 = OK was pressed.-1 = Highlimit<=Lowlimit.-2 = Could not initiate.-3 = Tagname not defined.-4 = Tagname is not a Discrete, Integer or Real type.-5 = Write failed.

ValueTag_Text Specifies the name of the Discrete, Integer or Real tagname to be modified. (This function requires a string for this parameter; therefore, you must identify the tagname by its name within quotes or use the .Name dotfield without quotes or use a Message tagname as a pointer. See the following Example.)

LowLimit Specifies the minimum allowable value for the tagname. (This should be >= the tagname's definition for Min Value, Min Raw or Min EU, as applicable).

HighLimit Specifies the maximum allowable value for the tagname. (This should be <= the tagname's definition for Max Value, Max Raw or Max EU, as applicable).

UserPrompt_Text Specifies the user message to display at the top of the keypad.

Remarks This function is used primarily in applications containing touch screens.Example(s) Errmsg=DialogValueEntry(MyIntegerTag.Name,

MyIntegerTag.MinEU, MyIntegerTag.MaxEU, "Enter a newvalue...");

Errmsg=DialogValueEntry("MyIntegerTag", -100, 100,"Enter a new value...");

Parameters could also act as "pointers" to other tags, allowing the function to be dynamic during runtime.

Errmsg=DialogValueEntry(TagnameX, Min, Max,MessageDisplay);


200 Chapter 3

Using the above example, input links can be assigned to each of the pointer tagnames, allowing the user to modify any or all of the function parameters before processing the function.For example, the following QuickScript would bring up the numeric keypad, allowing modification of MyIntegerTag using a Min and Max limit of -100 and 100 (respectively), while displaying the message "Enter a new value..." at the top of the keypad:TagnameX="MyIntegerTag"; {assign the string MyIntegerTag(which is actually the tagname to be modified) to theMemory Message tagname TagnameX}

Min=-100; {assign the minimum value allowed for thetagname to the Memory Real/Integer tagname Min}

Max=100; {assign the minimum value allowed for thetagname to the Memory Real/Integer tagname Max}

MessageDisplay="Enter a new value..."; {assign the newmessage string to the Memory Message tagnameMessageDisplay}

Errmsg=DialogValueEntry(TagnameX, Min, Max,MessageDisplay); {quotes are not required becauseTagnameX was defined as a Message tagname. By assigninga Discrete, Integer or Real tagname to TagnameX, thefunction will modify that assigned tagname}

See Also DialogStringEntry()



DText()

EnableDisableKeys()

Exp()

Dynamically changes a Message tagname based on the value of a Discrete tagname.

Category stringSyntax MsgTag=DText(Discrete_Tag,OnMsg,OffMsg);

Parameter DescriptionMsgTag Message tagname.Discrete_Tag Discrete tagname.OnMsg Message that will be displayed when the value of

Discrete_Tag equals 1 (True, On, Yes). OffMsg Will be the message displayed when

Discrete_Tag equals 0 (False, Off, No).Example(s) MessageTag=Dtext(DiscreteTag, DiscreteTag.OnMsg,

DiscreteTag.OffMsg);

If Dtext(D_Tag, "True", "False") == "True" THENMessage="D_Tag contains a value of 1";

ELSEMessage="D_Tag contains a value of 0";

ENDIF;

Enables/Disables key filters for the Alt,Escape and Windows keysCategory ViewSyntax EnableDisableKeys(int AltKey,int EscKey,int WinKey);

Parameter DescriptionAltKey Integer to enable or disable key filters for the Alt key,

0=disable, 1=enableEscKey Integer to enable or disable key filters for the Escape

key, 0=disable, 1=enableWinKey Integer to enable or disable key filters for the

Windows key, 0=disable, 1=enableRemarks Enables/Disables Alt,Escape and Windows keysExample(s) EnableDisableKeys(0,0,0); // enable all three keys

EnableDisableKeys(1,1,1); // disable all three keysEnableDisableKeys(0,0,1); // enable Alt and Escape keys,disable Windows key.

Returns the result of e raised to a power.Category math


202 Chapter 3

Syntax Result=Exp(Number);

Parameter DescriptionNumber Any number, or, Real or Integer tagname.

Remarks The exponential of Number is calculated and returned to Result.Example(s) Exp(1) will return 2.718...

The range for this function is -88.72 to 88.72.



FileCopy()Copies a SourceFile to a DestFile, similar to the DOS Copy command or the Copy function in Windows File.

Category systemSyntax [Result=]FileCopy(SourceFile,DestFile,DoneTag);

Parameter DescriptionSourceFile Source filename (including the full path).DestFile Destination filename (including the full path) or

directory name (see the following Example). DoneTag Name of a tagname that FileCopy() function will

use to report the progress of the copy procedure. This parameter must be a string indicating the name of the tagname (not the actual tagname itself). So if your done tagname is called Monitor, you would provide "Monitor" or Monitor.name, not just Monitor.

Remarks When the FileCopy() function is used it immediately returns a 1 if the procedure was successfully initiated. It returns a 0 if another procedure is already in progress (the new procedure could not be initiated) or -1 if there is an error. Using this return value, the initiation of the FileCopy() function can be monitored:Status=FileCopy("C:\*.TXT", "C:\BACKUP", "Monitor");

Status is an Integer tagname to which the 1, -1 or 0 will be written. FileCopy() function is performed in the background so that it will not interfere with the operation of InTouch. DoneTag allows the progress of the copy operation to be monitored by an application or a user. In this way, the user can be alerted to any errors which might occur AFTER the procedure was initiated. This is different than the Status returned above, which indicates whether the copy procedure has been successfully initiated.Once the copy procedure has been successfully initiated, the value of DoneTag is then assigned. The value is set to 0 while the procedure is still in progress. It is set to 1 when the procedure is successfully completed or -1 if there is an error before the procedure could be completed.Normally, the SourceFile and DestFile will be names of files. However, if a single file is being copied with FileCopy() function, the destination can be a directory:

FileCopy("C:\DATA.TXT", "C:\BACKUP", "Monitor");

This will copy the file "DATA.TXT" to a directory called "BACKUP" on the "C:\" drive. The tagname Monitor will be set to 1 when this is complete.If the SourceFile contains any wildcards, however, the DestFile MUST be a directory (not a filename) or the function will return an error code:

FileCopy("C:\*.TXT", "C:\BACKUP", "Monitor");

This will copy all the .TXT files from the C:\ root directory to the directory C:\BACKUP. The tagname Monitor will be set to 1 when this is complete.


204 Chapter 3

FileDelete()

FileCopy() does not work when used with an asynchronous QuickFunction. Use FileCopy() only with synchronous QuickFunctions.

See Also FileDelete(), FileMove(), FileReadFields(), FileReadMessage(). FileWriteFields(), FileWriteMessage()

Deletes unnecessary or unwanted files. Category systemSyntax [Result=]FileDelete(Filename);

Parameter DescriptionFilename File name to be deleted.

Remarks If the file can be found and successfully deleted, the function will return 1. Otherwise, the function will return 0.

FileDelete() does not accept wildcard characters. For example * and ?. Using wildcard characters will return an error (0) "Could not find file."

FileDelete() does not work when used with an asynchronous QuickFunction. Use FileDelete() only with synchronous QuickFunctions.

Example(s) Status=FileDelete("C:\DATA.TXT");

Status is a 1 if it finds a file called "DATA.TXT" in the C:\ root directory, or a 0 if it does not find the file.

See Also FileCopy(), FileMove(), FileReadFields(), FileReadMessage(). FileWriteFields(), FileWriteMessage()



FileMove()Similar to FileCopy() function except that it moves the file from one location to another instead of making a copy.

Category systemSyntax [Result=]FileMove(SourceFile,DestFile,DoneTag);

Parameter DescriptionSourceFile Source filename (including the full path).DestFile Destination filename (including the full path).DoneTag The name of a tagname that FileMove() function will

use to report the progress of the move procedure. This parameter must be a string indicating the name of the tagname (not the actual tagname itself). So, if your done tagname is called Monitor, you would provide "Monitor" or Monitor name, not just Monitor.

Remarks When the FileMove() function is used, it immediately returns a 1 if the procedure was successfully initiated. It returns a 0 if another procedure is already in progress (the new procedure could not be initiated) or a -1 if there is an error. Using this return value, the initiation of the FileMove() function can be monitored:Status=FileMove("C:\DATA.TXT", "D:\DATA.TXT","Monitor");

Status is a Integer tagname to which the 1, -1 or 0 will be written. FileMove() function is performed in the background so that it will not interfere with the operation of InTouch. The purpose of the DoneTag is to allow the progress of the move operation to be monitored by an application or a user. In this way, the user can be alerted to any errors that might occur AFTER the procedure was initiated. This is different than the Status returned above, which indicates whether the move procedure has been successfully initiated.

FileMove() does not work when used with an asynchronous QuickFunction. Use FileMove() only with synchronous QuickFunctions. Once the move procedure has been successfully initiated, the value of DoneTag is then assigned. The value is set to 0 while the procedure is still in progress. It is set to 1 when the procedure is successfully completed or -1 if there is an error before the procedure could be completed.If the SourceFile and DestFile are located on the same drive, the function can simply change the file's directory reference (where the computer keeps the name and location of the file on disk) without actually moving any data. In this case, the move procedure will be very fast, regardless of the size of the file. If the SourceFile and DestFile are located on different drives, the time the move takes will vary with the size of the file. This is because the data must be transferred from one physical disk to another.

Example(s) FileMove("C:\DATA.TXT","C:\BACKUP\DATA.TXT","Monitor");


206 Chapter 3

Note The Filemove() has a DONE flag. no other Filemove Function should be called before the previous function has finished.

This will move the file called "DATA.TXT" from the root directory of the "C" drive to a directory called "BACKUP." The tagname Monitor will be set to 1 when this is complete.

This function can also be used to rename files when the SourceFile and DestFile specify the same directory but different filenames.FileMove ("C:\DATA.TXT","C:\DATA.BAK","Monitor");

See Also FileCopy(), FileDelete(), FileReadFields(), FileReadMessage(). FileWriteMessage(),FileWriteFields()



FileReadFields()Reads a Comma Separated Variable (CSV) record from a specified file.

Category systemSyntax [Result=]FileReadFields(Filename,FileOffset,StartTag,

NumberOfFields);

Parameter DescriptionFilename Specifies the file to read from.FileOffset Specifies the location in the file to start reading.StartTag Specifies the name of an InTouch tagname where

the first data item will be written to. The name of this tagname must end with a number (such as MyTag1). This parameter must be a string indicating the name of the tagname (not the actual tagname itself). So, if your tagname is called MyTag1, you would provide “MyTag1” or MyTag1.name, not just MyTag1.

NumberOfFields Specifies the number of fields to read (the number of comma-separated fields in each record in the file).

Remarks If StartTag is MyTag1 and NumberOfFields is 3, then 3 fields are read from the file and are stored in MyTag1, MyTag2 and MyTag3. These tagnames with consecutive names must be first created in InTouch and may be of different types (Integer, Message, and so on).

Example(s) If the first line of C:\DATA\FILE.CSV is: This is text,3.1416, 5

The following QuickScript will read this line and store "This is text" into MyTag1, 3.1416 into MyTag2 and 5 into MyTag3:BytePosition=FileReadFields ("C:\DATA\FILE.CSV", 0,"MyTag1", 3);

The function returns the new byte position after the read. You can use this return value as the FileOffset for the next read.FileReadFields("C:\DATA\FILE.CSV",BytePosition,"MyTag1",3);

Message tagnames in InTouch can store a maximum of 131 characters.See Also FileCopy(), FileMove(), FileDelete(), FileReadMessage(),

FileWriteMessage(), FileWriteFields()


208 Chapter 3

FileReadMessage()Reads a specified number of bytes (or a whole line) from a specified file.

Category systemSyntax [Result=]FileReadMessage(Filename,FileOffset,

Message_Tag, CharsToRead);

Parameter DescriptionFilename Specifies the file to read from.FileOffset Specifies the location in the file to start reading. Message_Tag Specifies where to store the data read from the file. A

maximum of 131 characters can be stored.CharsToRead Specifies how many bytes to read from the file. For

processing text files, CharsToRead can be set to 0. The function will then read up to the next LF (linefeed) in the file, or up to 131 characters which ever comes first.

Example(s) FileReadMessage ("C:\DATA\FILE.TXT", 0, MsgTag, 0);

The first line will be read from file "C:\DATA\FILE.TXT" and stored into MsgTag. The function returns the new byte position after the read. You can use this return value as the FileOffset for the next read.

See Also FileCopy(), FileMove(), FileDelete(), FileReadFields(). FileWriteFields(), FileWriteMessage()



FileWriteFields()Writes a Comma Separated Variable (CSV) record to a specified file.

Category systemSyntax [Result=]FileWriteFields(Filename,FileOffset,StartTag,

NumberOfFields);

Parameter DescriptionFilename Specifies the file in which to write. If Filename

does not exist, it will be created.FileOffset Specifies the location in the file to start writing.

If FileOffset is -1, the function will write to the end of the file.

StartTag Specifies the name of an InTouch tagname where the first data item will come from. The name of this tagname must end with a number (such as MyTag1). This parameter must be a string indicating the name of the tagname (not the actual tagname itself). So, if your tagname is called MyTag1, you would provide “MyTag1” or MyTag1.name, not just MyTag1.

NumberOfFields Specifies the number of fields to write (the number of comma-separated fields in each record in the file).

Remarks If StartTag is MyTag1 and NumberOfFields is 3, then 3 fields are written to the file (from MyTag1, MyTag2 and MyTag3). These tags with consecutive names must first be created in InTouch and may be of different types (Integer, Message, etc.).

Example(s) The following QuickScript will write the line "This is text, 3.1416, 5" to the first line of C:\DATA\FILE.CSV. "This is text" is the value currently in MyTag1, 3.1416 is in MyTag2 and 5 is in MyTag3:FileWriteFields ("C:\DATA\FILE.CSV", 0, "MyTag1", 3);

The function returns the new byte position after the write. You can use this return value as the FileOffset for the next write.The following QuickScript will write the line "This is text, 3.1416, 5" to the end line of C:\DATA\FILE.CSV. "This is text" is the value currently in MyTag1, 3.1416 is in MyTag2 and 5 is in MyTag3:FileWriteFields ("C:\DATA\FILE.CSV", -1, "MyTag1", 3);

See Also FileCopy(), FileDelete(), FileMove(), FileReadFields(), FileReadMessage(). FileWriteMessage()


210 Chapter 3

FileWriteMessage()Writes a specified number of bytes (or a whole line) to a specified file.

Category systemSyntax [Result=]FileWriteMessage(Filename,FileOffset,

Message_Tag,LineFeed);

Parameter DescriptionFilename Specifies the file to write to. If Filename does not

exist, it will be created.FileOffset Specifies the location in the file to start writing.

If FileOffset is -1, the function will write to the end of the file.

Message_Tag Specifies the characters to write to the file. LineFeed Specifies whether or not to add a linefeed after

the write operation. When writing to a text file, set the LineFeed to 1.

Remarks The function returns the new byte position after the write. You can use this return value as the FileOffset() function for the next write.

Example(s) The following statement writes a Message tagname called MsgTag to the end of file C:\DATA\FILE.TXT:FileWriteMessage ("C:\DATA\FILE.TXT", -1, MsgTag, 1);

See Also FileCopy(), FileDelete(), FileMove(), FileReadFields(), FileReadMessage(), FileWriteFields()



GetNodeName()

GetPropertyD()

Returns the NetDDE node name to a string variable.Category systemSyntax GetNodeName(Tagname,NodeNum);

Parameter DescriptionTagname InTouch Message tagname that will hold the

node name.NodeNum Integer that specifies the character length for the

Message tagname.Remarks When this QuickScript executes, the GetNodeName() function will read

the local node name and return it to Tagname. (NodeNum sets the character length for the Message tagname.)

Example(s) GetNodeName("MyNodeTag",131);

If MyNodeTag == “Master” THENMessageTag = “This is the Primary Machine!”;

ENDIF;

Retrieves the specified property's discrete value during runtime.Category GOTSyntax [ErrorNumber=]GetPropertyD("ControlName[.Property]",Tag

name);

Parameter DescriptionControlName Name of a windows control. For example, ChkBox_1

or the name of an alarm object. For example, AlmObj_1.

.Property Windows control or alarm object property.

For more information on these properties, see Chapter 2, "Dotfields."

Tagname A valid InTouch tagname (of the same type to be returned) that will hold the property value when the function is processed.

Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyI(), GetPropertyM(), SetPropertyD(), SetPropertyI(),

SetPropertyM()


212 Chapter 3

GetPropertyI()

GetPropertyM()

Retrieves the specified property's integer value during runtime.Category GOTSyntax [ErrorNumber=]GetPropertyI("ControlName.[Property]",Tag

name);






Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyD(), GetPropertyM(), SetPropertyD(), SetPropertyI(),

SetPropertyM()

Retrieves the specified property's message value during runtime.Category GOTSyntax [ErrorNumber=]GetPropertyM("ControlName.[Property]",Tag

name);






Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyD(), GetPropertyI(), SetPropertyD(), SetPropertyI(),

SetPropertyM()



Hide

HideSelf

Hides various windows from within a QuickScript. A Hide() function must precede the name of each window to be hidden.

Category miscSyntax Hide Window;

Parameter DescriptionWindow A window name or Message tagname that contains a

window name.Remarks During runtime, if the window does not exist, the statement is ignored. If

the QuickScript is only hiding or showing windows, it is best to use the Touch Pushbutton links Show Window or Hide Window instead of this function.

If a local Message tagname is used as a parameter to hide a window, the following error message appears:

"Expecting window name – must be string expression"

To avoid this message, prefix the Message tagname with a plus (+) sign. For example:

DIM Test AS message;Test = "MyWindow1";Hide ""+Test;

Example(s) Hide "My Popup Alarm Window";

See Also Hideself, Show, ShowAt(), ShowTopLeftAt(), ShowHome

Hides the currently active window.Category miscSyntax HideSelf;

Remarks This function can only be used in a Touch Pushbutton Action QuickScript.See Also Hide, Show


214 Chapter 3

HTGetLastError()Determines if there was an error during the last retrieval of a specified pen.

Category historicalSyntax [Result=]HTGetLastError(Hist_Tag,UpdateCount,PenNum);

Parameter DescriptionHist_Tag Historical Trend tagname representing the name of

the trend.UpdateCount Integer representing the trend's .UpdateCount field.PenNum Integer tagname or value representing the pen

number (from 1-8)[Result=] The following results may be returned:

Result Description0 No Error1 General Server Error2 Old Request3 File Error4 Server Not Loaded5 Trend/Pen Passed in Function Does Not

Exist6 Trend Name Tag Does Not Exist in

Database7 Pen # Passed to Function is invalid (not

in range of 1 to 8).8 No tagname/non-logged tagname exists

for the pen number.Example(s) The following statement retrieves the error for the last retrieval of Pen3 of

the trend with the tagname Trend1 and places the result in the Integer tagname ResultCode:[ResultCode=]HTGetLastError("Trend1",Trend1.UpdateCount,3);

In an animation Analog Value Display QuickScript the following statement would be used:HTGetLastError("Trend1",Trend1.UpdateCount,3);



HTGetPenName()

HTGetTimeAtScooter()

Returns the tagname of the tagname currently used for the specified pen # of the specified trend.

Category historicalSyntax MessageResult=HTGetPenName(Hist_Tag,UpdateCount,PenNum)

;

Parameter DescriptionHist_Tag HistTrend tagname representing the name of the

trend.UpdateCount Integer representing the trend's .UpdateCount field.PenNum Integer tagname or value representing the pen

number (from 1-8). A Message tagname is returned representing the specified pen's tagname.

Example(s) The following statement retrieves the tagname for Pen2 of the trend with the tagname Trend1 and places the result in the Message tagname TrendPen:TrendPen=HTGetPenName("Trend1",Trend1.UpdateCount,2);

Returns the time in seconds since 00:00:00 hours GMT, January 1, 1970 for the sample at the scooter location specified by ScootNum and ScootLoc.

Category historicalSyntax IntegerResult=HTGetTimeAtScooter(Hist_Tag,UpdateCount,

ScootNum,ScootLoc);

Parameter DescriptionHist_Tag HistTrend tagname representing the name of a trend.UpdateCount Integer representing the trend's .UpdateCount field.ScootNum Integer representing the left or right scooter:

1=Left Scooter2=Right Scooter

ScootLoc Real number representing the trend's .ScooterPosRight or .ScooterPosLeft field.

Remarks UpdateCount, ScootNum, and ScootLoc cause the expression to be evaluated when any of these parameters change. This ensures that the expression is evaluated after new retrievals or after a scooter moves.

Example(s) The following statement retrieves the time in seconds for the value at the current scooter location for the left scooter of the trend labeled Trend1:HTGetTimeAtScooter("Trend1",Trend1.UpdateCount,1,Trend1.ScooterPosLeft);


216 Chapter 3

HTGetTimeStringAtScooter()Returns the string containing the time/date for the sample at the scooter location specified by ScootNum and ScootLoc.

Category historicalSyntax MessageResult=HTGetTimeStringAtScooter(Hist_Tag,

UpdateCount,ScootNum,ScootLoc,Format_Text);


trend.UpdateCount Integer representing the trend's .UpdateCount fieldScootNum Integer representing the left or right scooter:



Format_Text String specifying the time/date format to use. The following Format_Text strings are acceptable:"Date", "Time", "DateTime", "DOWShort" (Wed, for example), and "DOWLong" (Wednesday, for example).

Remarks UpdateCount, ScootNum, and ScootLoc cause the expression to be evaluated when any of these parameters change. This ensures that values are updated after new retrievals or after a scooter moves. The format of the string determines the contents of the return value.

Example(s) The following statement retrieves the date/time for the value at the current scooter location for the right scooter of the trend labeled Trend1. The value is stored in the Message tagname NewRightTimeString and is in "Time" format:NewRightTimeString=HTGetTimeStringAtScooter("Trend1",Trend1.UpdateCount,2,Trend1.ScooterPosRight,"Time");



HTGetValue()Returns a value of the requested type for the entire trend's specified pen. The UpdateCount parameter will cause the expression to be evaluated after a retrieval is complete.

Category historicalSyntax RealResult=HTGetValue(Hist_Tag,UpdateCount,PenNum,

ValType_Text);


trend.UpdateCount Integer representing the trend's .UpdateCount field.PenNum Integer tagname or value representing the pen

number (from 1-8).ValType_Text String indicating the type of value to return:

Type Description"PenAverageValue" Average for entire trend."PenMaxValue" Max for entire trend."PenMinValue" Min for entire trend."PenMaxEU" Max Engineering Units for

entire trend."PenMinEU" Min Engineering Units for

entire trend."PenStdDev" Standard Deviation for

entire trend.When the ValType_Text parameter is used with the HTGetValue function, make sure that one of the valid types listed above is used.

Remarks A Memory Real tagname is returned representing the calculated value of the given type.

Example(s) The following statement obtains the standard deviation for the data retrieved for the trend, Trend1, Pen2. The value is stored in the Memory Real tagname LeftHemisphereSD:LeftHemisphereSD=HTGetValue("Trend1",Trend1.UpdateCount,2, "PenStdDev");


218 Chapter 3

HTGetValueAtScooter()Returns a value of the requested type for the sample at the specified scooter position, trend and pen #. The UpdateCount parameter will cause the expression to be evaluated after a retrieval is complete.

Category historicalSyntax RealResult=HTGetValueAtScooter(Hist_Tag,UpdateCount,

ScootNum,ScootLoc,PenNum,ValType_Text);


trend.UpdateCount Integer representing the trend's .UpdateCount field.ScootNum Integer representing the left or right scooter:



PenNum Integer tagname or value representing the pen number (from 1-8).

ValType_Text String indicating the type of value to return::Type Description"PenValue" Value at scooter position."PenValid" 0 if value is invalid, 1 if valid.When the ValType_Text parameter is used with the HTGetValueAtScooter function, make sure that one of the valid types listed above is used.

Remarks A Memory Real tagname is returned representing the calculated value for "PenValue." A Memory Discrete tagname is returned representing the value for "PenValid."

Example(s) The following statement stores a 1 if the value is an actual sample or a 0 if the value is invalid for Pen3 of trend Trend1 in the Memory Discrete tagname ValidFlag for the right scooter's current position:ValidFlag=HTGetValueAtScooter("Trend1",Trend1.UpdateCount,2, Trend1.ScooterPosRight,3,"PenValid");



HTGetValueAtZone()Returns a value of the requested type for the data contained between the right and left scooter positions for a trend's specified pen. The UpdateCount parameter will cause the expression to be evaluated after a retrieval is complete.

Category historicalSyntax RealResult=HTGetValueAtZone(Hist_Tag,UpdateCount,

Scoot1Loc,Scoot2Loc,PenNum,ValType_Text);

Parameter DescriptionHist_Tag HistTrend tagname representing the name of a

trend.UpdateCount Integer representing the trend's .UpdateCount

field.Scoot1Loc Real representing the trend's .ScooterPosLeft

field.Scoot2Loc Real representing the trend's .ScooterPosRight

field.PenNum Integer tagname or value representing the pen

number (from 1-8).ValType_Text String indicating the type of value to return:

Type Description"PenAverageValue" Average for zone between

the right and left scooter."PenMaxValue" Max for zone between the

right and left scooter."PenMinValue" Min for zone between the

right and left scooter."PenMaxEU" Max Engineering Units for

zone between the right and left scooter.

"PenMinEU" Min Engineering Units for zone between the right and left scooter.

"PenStdDev" Standard Deviation for zone between the right and left scooter.

When the ValType_Text parameter is used with the HTGetValueAtZone function, make sure that one of the valid types listed above is used.

Remarks A Memory Real tagname is returned representing the calculated value of the given type. Specifying constant values for Scoot1Loc and Scoot2Loc has no effect and are only used to trigger the processing of the function for the purpose of updating display lines. The function uses the trend tagname's .ScooterPosLeft and .ScooterPosRight directly from the runtime database for determining zone boundaries.


220 Chapter 3

HTScrollLeft()

HTScrollRight()

Example(s) The following statement calculates the average value for the data between the right and left scooters of trend "Trend1", Pen1. The value is stored in the Memory Real tagname AvgValue:AvgValue=HTGetValueAtZone("Trend1",Trend1.UpdateCount,Trend1.ScooterPosLeft,Trend1.ScooterPosRight,1,"PenAverageValue");

Sets the start time of the trend to a value older than the current start time by a percentage of the trend's width. The effect is to scroll the date/time of chart to the left by a given percentage.

Category historicalSyntax HTScrollLeft(Hist_Tag,Percent);


trend.Percent Real number representing the percent of the chart to

scroll (0.0 to 100.0)Example(s) The following statement scrolls the time/date for a trend with a tagname of

Trend1 by 10%:HTScrollLeft("Trend1",10.0);

If the current display starts at 12:00:00 PM and the display width is 60 seconds, then, the new trend will start at 11:59:54 AM (after the function is processed)

Sets the start time of the trend to a value newer than the current start time by a percentage of the trend's width. The effect is to scroll the date/time of chart to the right by a given percentage.

Category historicalSyntax HTScrollRight(Hist_Tag,Percent);


trend.Percent Real number representing the percentage of the chart

to scroll (0.0 to 100.0)Example(s) The following statement scrolls the time/date for a trend with a tagname of

Trend1 by 20%:HTScrollRight("Trend1",20.0);

If the current display starts at 12:00:00 PM and the display width is 60 seconds, then, the new trend will start at 12:00:12 PM (after the function is processed).



HTSelectTag()

HTSetPenName()

Displays the Select Tag dialog box and the operator can select a different tagname for specified pen. (The dialog box only lists the tagnames that have been defined for historical logging (Log Data option selected) in the Tagname Dictionary.

Category historicalSyntax HTSelectTag();

Remarks HTSelectTag() shows ALL tags that have their Log Data option selected. However, it is possible to use the Tag Browser's filter to display a smaller set of tagnames. For example all tagnames which begin with "A." It is NOT possible however, to use the HTSelectTag() function to display the all tagnames in the Tagname Dictionary, only historical tagnames are displayed.

Example(s) The following QuickScript can be used in a Touch Pushbutton Action QuickScript. The QuickScript will cause the Tag Browser to appear in WindowViewer. The user can then select a tagname from the list. This tagname will be used as pen 1 by the Historical Object named HistTrend.HTSetPenName( "HistTrend", 1, HTSelectTag( ) );

See Also HTSetPenName()

Assigns a different tagname to a trend's pen.Category historicalSyntax HTSetPenName(Hist_Tag,PenNum,Tagname);


trend.PenNum Integer tagname or value representing the pen

number (from 1-8) and Tagname is a string representing the new tagname to assign to the pen.

Tagname String representing the new tagname to assign to the pen.

Remarks This QuickScript function is the only method to add tagnames from a distributed history provider during runtime.

Example(s) In the following statement Pen3 of Trend1 will use OutletPressure as the new tagname.HTSetPenName("Trend1",3,"OutletPressure");

In the following statement TrendPen4 of Trend1 will use the distributed tagname HistPrv1.Tag1 as the tagname.HTSetPenName("Trend1",TrendPen4,"HistPrv1.Tag1");

See Also HTSelectTag();


222 Chapter 3

HTUpdateToCurrentTime()

HTZoomIn()

Causes the data to be retrieved and displayed with an end time equal to the current time. The start time will be equal to EndTime minus the Width of the chart.

Category historicalSyntax HTUpdateToCurrentTime(Hist_Tag);


trend.Example(s) The following statement retrieves and displays data for the historical

tagname "Trend1" at the current time:HTUpdateToCurrentTime("Trend1");

If it is now 3:04 PM and the width of the trend is 60 seconds, the new end time will be 3:04 PM. The new start time will be 3:03 PM.

Calculates a new chart width and start time. If the trend's .ScooterPosLeft is 0.0 and the .ScooterPosRight is 1.0, then the new chart width equals the old chart width divided by two. The new start time will be calculated based on the value of LockString.

Category historicalSyntax HTZoomIn(Hist_Tag,LockString);


trend.LockString String representing the type of zoom:

Type Description"StartTime" Keep start time equal to before zoom"Center" Keep center time equal to before zoom"EndTime" Keep end time equal to before zoom

Remarks If the scooter positions are not at the ends, the new chart width is the time between .ScooterPosLeft and .ScooterPosRight. In this case, the value of LockString is not used. The minimum chart width is 1 second. The scooter positions will be set to .ScooterPosLeft=0.0 and .ScooterPosRight=1.0 after the zoom.

Example(s) The following statement zooms the display by a factor of two and maintain the same start time for the trend tagname "Trend1." Trend1.ScooterPosRight is equal to 1.0 and Trend1.ScooterPosLeft is equal to 0.0. If the start time before zooming was 1:25:00 PM and the chart width was 30 seconds (after zooming), the start time will still be 1:25:00. The chart width will be 15 seconds.HTZoomIn("Trend1","StartTime");



HTZoomOut()Calculates a new chart width and start time. The new chart width is the old chart width multiplied by two. The new start time will be calculated based on the value of LockString.

Category historicalSyntax HTZoomOut(Hist_Tag,LockString);


trend.LockString String representing the type of zoom:

Type Description"StartTime" Keep start time equal to before zoom"Center" Keep center time equal to before zoom"EndTime" Keep end time equal to before zoom

Remarks The scooter positions have no effect on HTZoomOut but will be set to .ScooterPosLeft=0.0 and .ScooterPosRight=1.0 after the zoom.

Example(s) The following statement zooms the display by a factor of two and maintain the same center time for the trend tagname "Volume." If the start time before zooming was 2:15:00 PM and the chart width was 30 seconds, the start time after zooming will still be 2:14:45. The chart width will be 60 seconds and the center of the trend will remain at 2:15:15.HTZoomOut("Volume","Center");


224 Chapter 3

InfoAppActive()

InfoAppTitle()

Tests whether an application is active.Category systemSyntax DiscreteResult=InfoAppActive(AppTitle);

Parameter DescriptionAppTitle String representing application to report on.

Example(s) InfoAppActive("Calculator") will return 0{if it is not running}The application title for a particular application can be determined using the InfoAppTitle() function.The following QuickScript example uses InfoAppActive to inspect the list of tasks running on the system. If a task called Notepad is running it will return a result of 1. Thus one can avoid launching a second instance of Notepad. If InfoAppActive returns a value of 0 (Notepad is not already running) then Notepad can be launched.IF InfoAppActive( InfoAppTitle( "Notepad" ) ) == 1 THENActivateApp InfoAppTitle( "Notepad" );

ELSEStartApp "Notepad";

ENDIF;

Returns the Application Title or Windows Task list name of a specified program which is currently running.

Category systemSyntax MessageResult=InfoAppTitle(“ProgramEXEName”);

Parameter DescriptionProgramEXEName String representing program to report on.

Example(s) The following statement will process ProgramEXEName, "calc", to return "Calculator." The actual program name is calc.exe. Do not use the ".exe" in the Program EXE name string.InfoAppTitle("calc") will return "Calculator"

InfoAppTitle("excel") will return "Microsoft Excel"



InfoDisk()Returns information about a specific local (or network) disk drive.

Category systemSyntax IntegerResult=InfoDisk(“Drive”,InfoType,Trigger);

Parameter DescriptionDrive String or Message tagname representing drive letter.InfoType Integer representing information type:

Type Description1 Returns the total size (in bytes) of the

disk drive.2 Returns the available space free (in

bytes) on the disk drive.3 Returns the total size (in kilobytes) of

the disk drive.4 Returns the available space free (in

kilobytes) on the disk drive.Trigger Executes the InfoDisk function every time the value

of Trigger changes. Trigger can be any tagname (not limited to system variables). This parameter is used for expression fields in animation links only, any value can be used as a place holder when InfoDisk() is used in a QuickScript, because this parameter has no effect in a QuickScript.

Remarks Information about the disk drive specified by Drive is returned to IntegerTag.

Example(s) The following statement executes every minute and returns the current value. If used in a value display analog animation link it will refresh once per minute.InfoDisk("C", 1, $Minute) will return 233869345{total size in bytes}

InfoDisk("C", 2, $Minute) will return 3238935{free space in bytes}

InfoDisk("C", 3, $Minute) will return 228388{total size in kilobytes}

InfoDisk("C", 4, $Minute) will return 3163{free space in kilobytes}

Comment 1 kilobyte = 1024 bytesAs in other functions where single characters are used, if the Message tagname (used for Drive) provided to InfoDisk() function contains more than one character, only the first character of the tagname will be used. Since the function relies upon information returned from the operating system, the values may be erroneous on operating systems containing drives which are larger than 2 gigabytes.


226 Chapter 3

InfoFile()Returns information about a specific file or subdirectory.

Category systemSyntax IntegerResult=InfoFile(“Filename”,”InfoType”,Trigger);

Parameter DescriptionFilename String representing filename to act on actual string or

Message tagname.InfoType Integer representing type of information to retrieve:

Type Description1 Does the file exist? Returns 1 if the

filename is an actual file. Returns 2 if the filename is a sub-directory. Returns 0 if the function cannot find the file.

2 File size (in bytes).3 File Date/Time (in seconds since Jan-1-

1970).4 Number of files that match the filename

description. Values greater than 1 will be returned only in wildcard searches in which more than one file matching the search criterion is found.

Trigger Any tagname. Trigger will execute the InfoFile function every time the value of Trigger changes. This parameter is used for expression fields in animation links only. Any value can be used as a place holder when InfoFile() is used in a QuickScript, because this parameter has no effect in a QuickScript.

Remarks Information about the file specified by Filename is returned to IntegerTag. The Filename has to include the full path name to the file, but can include wildcard characters (*, ?).

Example(s) The following statement executes every minute and return the following values:InfoFile("c:\IT56\view.exe", 1, $Minute) will return1 {file found}

InfoFile("c:\InTouch\view.exe", 2, $Minute) will return634960 {file size}

InfoFile("c:\InTouch\view.exe", 3, $Minute) will return736701852 {secs since 1-1-70}

InfoFile("c:\InTouch\*.exe", 4, $Minute) will return17 {found 17 EXE files}



InfoInTouchAppDir()

InfoResources()

Int()

Returns the current InTouch application directory.Category systemSyntax MessageResult=InfoInTouchAppDir();

Remarks The current InTouch application directory is returned into MessageResult. Example(s) InfoInTouchAppDir();

will return"c:\ProgramFiles\FactorySuite\InTouch\DemoApp1\1024"

Returns various system resource values.Category mathSyntax IntegerResult=InfoResources(ResourceType,Trigger);

Parameter DescriptionResourceType Integer representing resources to monitor.

Remarks The particular system resource specified by the integer ResourceType is stored in IntegerResult..

Example(s) The following statement executes every minuteand returns the current value:InfoResources(1, $Minute) will return 54 {% free}InfoResources(2, $Minute) will return 36 {% free}InfoResources(3, $Minute) will return 11524093

{bytes}InfoResources(4, $Minute) will return 14 {tasks}System resource values:Case 1&Case 2 GDI and USER are hard-coded to return

'50%' on Windows NT and Windows 2000.

Case 3) On Windows NT and Windows 2000, returns"free bytes of paging file."

Case 4) On Windows NT and Windows 2000, returnsthe result of searching of all the top-level windows. Itonly counts the windows that are visible and do not haveany owners. This is not the actual "number of taskscurrently running" in the system. Its closestapproximation would be the count of items on theApplications tab when you run the Task Manager inWindows NT, or the Close Program window that appearswhen you press CTRL+ALT+D in Windows 2000.

Returns the next integer less than or equal to a specified number.Category mathSyntax IntegerResult=Int(Number);


228 Chapter 3

InvisibleVerifyCredentials()

IOGetApplication()


Remarks When dealing with negative real numbers, this function will return the integer farthest from zero.

Example(s) Int(4.7) will return 4

Int(-4.7) will return -5

Checks to verify the credentials of the given user without logging the user on to InTouch.

Category securitySyntax AnalogTag=InvisibleVerifyCredentials( "UserId",

"Password", "Domain" );

Parameter DescriptionUserId Windows OS User account name that is part of local

machine, workgroup or domain.Remarks If the supplied combination of user, password and domain are valid then the

corresponding access level associated with the user is returned as an integer, in all other cases -1 is returned. This call does not change the currently logged on user.

Example(s) AnalogTag=InvisibleVerifyCredentials( "john","Password", "corporate_hq" );

See Also PostLogonDialog(), AttemptInvisibleLogon(), IsAssignedRole(), QueryGroupMembership(), AddPermission().

Returns the application name defined for a specific Access Name to the specified tagname.

Category miscSyntax IOGetApplication(“AccessName”);

Parameter DescriptionAccessName The existing Access Name to return the application

for.Remarks The Access Name may be specified as a literal string, or it may be a string

value provided by other InTouch tagnames or functions. The following example would return the application name for the Access Name MyAccess1, to the tagname MyTag1.

Example(s) MyTag1 = IOGetApplication("MyAccess1");



IOGetNode()

IOGetTopic()

IOReinitialize()

Returns the node information (address) defined for a specific Access Name to the specified tagname.

Category miscSyntax IOGetNode(“AccessName”);

Parameter DescriptionAccessName The existing Access Name to return node

information for.Remarks The Access Name may be specified as a literal string, or it may be a string

value provided by other InTouch tagnames or functions. The following example would return the node information for the Access Name MyAccess1, to the tagname MyTag1.

Example(s) MyTag1 = IOGetNode("MyAccess1");

Returns the topic name defined for a specific Access Name to the specified tagname.

Category miscSyntax IOGetTopic(“AccessName”);

Parameter DescriptionAccessName The existing Access Name to return the topic for.

Remarks The Access Name may be specified as a literal string, or it may be a string value provided by other InTouch tagnames or functions. The following example would return the topic name for the Access Name MyAccess1, to the tagname MyTag1.

Example(s) MyTag1 = IOGetTopic("MyAccess1");

Closes all existing I/O conversations and restarts the entire process of setting up I/O conversations. All I/O points are affected when this function executes.

Category miscSyntax IOReinitialize();

Remarks This function performs the same operation as the same as the Reinitialize I/O command on the WindowViewer Special menu.


230 Chapter 3

IOSetAccessName()Modifies the application or topic name portions of a Access Name during runtime which allows implementing of hot-backup strategies for InTouch.

Category miscSyntax IOSetAccessName(“AccessName”, “NodeName”, “AppName”,

“TopicName”);

Parameter DescriptionAccessName The existing Access Name to assign the new

AppName and Topic Name values to. Actual string or Message tagname.

NodeName The new NodeName to assign. Actual string or Message tagname.

To use the existing node name, type "" without a string. To use the local node, type " ". Notice the blank space.

AppName The new Application Name to assign. Actual string or Message tagname.

TopicName The new Topic Name to assign. Actual string or Message tagname.

Remarks The Access Name, NodeName, Application Name and Topic Name values may be specified as literal strings, or they may be string values provided by other InTouch tagnames or functions. For example, the Access Name MyAccess1 can be changed to point to the "EXCEL" application and the "Sheet1" topic by:

Example(s) IOSetAccessName("MyAccess1","MyComputer1","EXCEL","[Book1.xls]Sheet1");

or,Number = 1;

AccNameString = “MyAccess” + Text(Number, "#");

IOSetAccessName(AccNameString, "", "EXCEL","[Book1.xls]Sheet1");

If an empty string is specified for a Topic, then the Access Name’s current Application value is retained and its Topic value is updated. For example, the following changes the Application Name for access name MyAccess2 to "excel" without affecting its current Topic value:IOSetAccessName("MyAccess2", "", "excel", "");

Likewise, if an empty string is specified only for an Application Name, then the tag’s current Topic value is retained and its Application value is updated. For example, the following changes the Topic for tagname MyAccess3 to "Sheet2" without affecting its current Application Name value:



IOSetItem()

IOSetAccessName("MyAccess3", "","","[Book1.xls]Sheet2");

When IOSetAccessName() is processed, there is a time delay as the existing conversation is terminated and the new conversation is initiated. During this time, any attempted POKEs or writes to the new topic will be lost.

Changes the access name and/or item in an I/O type tagname .Reference field.

Category miscSyntax IOSetItem(“Tagname”,”AccessName”,”Item”);

Parameter DescriptionTagname Any InTouch IO tagname enclosed in quotes.AccessName The AccessName to change to the tagname to.Item The Item to change the tagname to.

Example(s) IOSetItem(TagName, AccessName, Item)

The Tagname, AccessName, and Item values may be specified as literal strings, or they may be string values provided by other InTouch tagnames or functions. For example, the .Reference field of tagname MyTag1 can be changed to point to the "excel" access name and the "R1C1" item by:IOSetItem("MyTag1", "[Book1.xls]excel", "R1C1");

or by,Number = 1;

TagNameString = "MyTag" + Text(Number, "#");

IOSetItem(TagNameString, "[Book1.xls]excel", "R1C1");

If an empty string ("") is specified for both the Access Name and Item values, then the tagname is deactivated. For example, the tagname MyTag2 is deactivated by:IOSetItem("MyTag2", "", "");

If an empty string is specified only for an Item, then the tag’s current Item value is retained and its AccessName value is updated. For example, the following changes the Access Name for tagname MyTag3 to "excel2" without affecting its current Item value:IOSetItem("MyTag3", "[Book1.xls]excel2", "");

Likewise, if an empty string is specified only for an AccessName, then the tagname’s current Item value is retained and its AccessName value is updated. For example, the following changes the Item for tagname MyTag3 to "R1C2" without affecting its current Access Name value:IOSetItem("MyTag4", "", "R1C2");


232 Chapter 3

IOStartUninitConversations()

IsAnyAsynchFunctionBusy()

When WindowViewer is started, it automatically processes an initiate request to start all I/O conversations. If an I/O server program does not respond to WindowViewer's initiate request, you can force WindowViewer to try again to establish the I/O conversation by executing this function in a QuickScript.

Category miscSyntax IOStartUninitConversations();

Remarks This function performs the same operation as the same as the Start Uninitiated Conversations command on the WindowViewer Special menu.

Used to find out if any asynchronous QuickFunctions are running. This function can be used to make the QuickScript that calls an asynchronous QuickFunction wait for all other asynchronous QuickFunctions to complete processing. This allows the QuickScript to re-synchronize itself.

Category systemSyntax DiscreteTag=IsAnyAsynchFunctionBusy(timeout);

Parameter DescriptionDiscreteTag A Discrete tagname to which a value is returned as

follows:If the function times out while waiting for all executing QuickFunctions to complete, a 1 (true) is returned to DiscreteTag.If there are no asynchronous QuickFunctions running, a value of 0 (false) will be returned immediately, or the QuickFunction will wait for the timeout to elapse. It will also return a 0 if after timing out there are no asynchronous QuickFunctions running.

timeout An integer value representing the number of seconds to wait to determine if any asynchronous QuickFunctions are running.

A value of zero (0) means not to wait.Example(s) Assume you want to connect to several SQL databases using asynchronous

QuickFunctions and, you know that it will take 2 minutes to make those connections. First, you would execute the asynchronous QuickFunctions to connect to the SQL databases. Next, you would launch the function, IsAnyAsynchFunctionBusy(120) to allow enough time for SQL to make the connections before completing the QuickFunction.



IsAssignedRole()

Log()

However, if after 2 minutes the connections have not been made and the asynchronous QuickFunctions are still busy trying to make the connections, a value of 1 (true) will be returned by the IsAnyAsynchFunctionBusy() function. You can now display an error message telling the operator that the SQL connections were unsuccessful.Use the following Window On Show QuickScript:IF IsAnyAsynchFunctionBusy(120) == 1 THENSHOW "SQL Connection Error Dialog";

ENDIF;

Used to find out if current logged on user has the indicated role.Category securitySyntax DiscreteTag=IsAssignedRole( "RoleName" );

Parameter DescriptionRoleName The role associated with a AppServer user.

Remarks Valid for AppServer security mode only and applies to the currently logged on user. If a user is currently logged on and if he has the role lpszRoleName assigned to him in Galaxy IDE, then a TRUE is returned. In all other cases a FALSE is returned.

Example(s) DiscreteTag=IsAssignedRole( "Administrator" );

See Also AttemptInvisibleLogon(), PostLogonDialog(), InvisibleVerifyCredentials(), QueryGroupMembership(), AddPermission().

Returns the natural log of a number.Category mathSyntax RealResult=Log(Number);


Remarks The natural log of Number is calculated and returned to RealResult. Natural log of 0 is undefined.

Example(s) Log(100) will return 4.605...

Log(1) will return 0


234 Chapter 3

LogMessage()

LogN()

Logoff()

Writes a user-defined message to the Wonderware Logger.Category miscSyntax LogMessage(“Message_Tag”);

Parameter DescriptionMessage_Tag String to log to Wonderware Logger. Actual string or

Message tagname.Remarks This is a very powerful function for troubleshooting InTouch scripting. By

strategically placing LogMessage() functions in your scripts you can determine the order of QuickScript execution, performance of scripts and identify the value of tags both before they are changed and after they have been effected by the QuickScript. Each message posted to the Wonderware Logger is stamped with the exact date and time.

Example(s) LogMessage("Report Script is Running");

The above statement would print the following to the Wonderware Logger:94/01/14 15:21:14 WWSCRIPT Message:Report Script isRunning.

LogMessage(“The Value of MyTag is “ + Text(MyTag, “#”));

MyTag+MyTag + 10;

LogMessage(“The Value of MyTag is “ + Text(MyTag, “#”));

For more information on the Wonderware Logger, see your online FactorySuite System Administrator's Guide.

Returns the values of the logarithm of x to base n.Category mathSyntax Result=LogN(Number,Base);

Parameter DescriptionNumber Any number, Real or Integer tagname.Base Integer to set log base. Number or Integer

tagname.Remarks Base 1 is undefined.Example(s) LogN(8, 3) will return 1.89279

LogN(NumberTag, BaseTag) will return 0.564 if NumberTagcontains 3 and BaseTag contains 7

Logs the user off of InTouch.Category security



Pi()

PlaySound()

Syntax DiscreteTag = LogOff();

Parameter DescriptionN/A

Remarks Logs off the currently logged on user and sets the current user status to the default none operator.

Example(s) DiscreteTag = LogOff();

See Also PostLogonDialog(), InvisibleVerifyCredentials(), IsAssignedRole(), AttemptInvisibleLogon(), QueryGroupMembership(), AddPermission().

Returns the value of Pi.Category mathSyntax RealResult=Pi();

Example(s) Pi() will return 3.1415926

Plays a wave form sound specified by a .wav filename.Category miscSyntax PlaySound(“SoundName”,Flags);

Parameter DescriptionSoundName String or Message tagname that represents sound file

to play.Flags Flags can be one of the following:

Type Description0 Play sound synchronously (default)1 Play sound asynchronously2 Do not use default sound. Playsound is

the filename of a .wav file. PlaySound can also accept an entry name from the [Sounds] section of the Windows Registry file. As an example, if you have an entry in the Windows Registry file like the followingMouseClick=C:\Sounds\Click.wavyou can enter MouseClick as the SoundName.

3 NOT USED!4 NOT USED!5-7 NOT USED!


236 Chapter 3

PostLogonDialog()

PrintHT()

8 Repeat the sound until the next time PlaySound() is called. For Windows 2000.

9 PlaySound() is called. For Windows NT.

16 Do not stop any currently playing sound.

Example(s) PlaySound ("c:\horns.wav",1);

The sound must fit in available physical memory and be playable on an installed wave form audio device driver. The directories searched for sound files are in order: the current directory; the windows directory; the windows system directory; the directories listed in the PATH. If a specified .wav sound cannot be found, go to your Start menu, point to Settings, click Control Panel, then double-click on the Sounds icon, setup your default sound. If the default sound cannot be found, no sound is played.

Brings up the InTouch Logon Dialog and returns TRUE.Category securitySyntax DiscreteTag=PostLogonDialog();

Remarks Brings up the InTouch Logon Dialog and returns TRUE.Example(s) DiscreteTag=PostLogonDialog();

See Also InvisibleVerifyCredentials(), AttemptInvisibleLogon(), IsAssignedRole(), QueryGroupMembership(), AddPermission().

Can be used in a button for printing the Historical Trend chart associated with the specified Hist Trend type tagname. The Historical Trend must be visible on the screen when using this function.

Category historicalSyntax PrintHT("Trend_Tag");

Parameter DescriptionTrend_Tag History Trend tagname. Actual string or Message

tagname.Remarks NoneExample(s) PrintHT("HistTrend1");



PrintScreen()Prints the specified screen.

Category miscSyntax PrintScreen(ScreenOption, PrintOption );

Parameter DescriptionScreenOption 1 - Client Area of View (no menus)

2 - Window Area (everything in WindowViewer's window including menus)

Invalid options (including 0) default to Client AreaPrintOption 1 - Best Fit (fills to either Vert or Horz, preserving the

image's aspect ratio)

2 - Vert Fit (fills the image to the Vertical dimension of the page -- preserves aspect ratio)

3 - Horz Fit (fills the image to the horizontal dimension of the page -- preserves aspect ratio)

4 - Stretch to Page (fills the image to the FULL page -- can distort aspect ratio)

Invalid options (including 0) default to Best FitRemarks Popup style windows outside of View's area are clipped in any mode.

Additionally, other "On Top" applications such as, Debugger in On Top mode, will be printed if they overlap WindowViewer's window.

This QuickScript function works similar to the PrintWindow() function except for the number of windows that get printed. The amount of time View waits can be controlled by adding the following line to the INTOUCH.INI file:PrintScreenWait=10000

Where 10000 represents the number of milliseconds to wait.


238 Chapter 3

Fonts are printed as fonts, objects are bit mapped and printed as such. Windows with white backgrounds that contain only fonts are printed very fast. Windows with colored backgrounds that contain many objects will take longer to print.To ensure that text in a window prints properly, it is recommended that "True Type" fonts are used for the text fields in all windows that will be printed.

When printing push buttons, the text on the button may appear "cut off" because the font used for the button text is the "System" font, which is not a "True Type" font. And, the "System" font in the printer is slightly different than the "System" font used on the screen. If this should occur, try expanding the button.

If the printer is being used to print alarms, a second printer is required to use the PrintScreen() function.

PrinScreen() does not print properly if any window is overlapping a distributed alarm display, combo box, text box, radio button, checkbox, and so on.



PrintWindow()Prints the specified window.

Category miscSyntax PrintWindow("Window",Left,Top,Width,Height,Options);

Parameter DescriptionWindow The name of the window to print. Actual string or

Message tagname.Left A floating point number whose units are inches

to set the left margin. Number or Real tagname.Top A floating point number whose units are inches

to set the top margin. Number or Real tagname.Width A floating point number whose units are inches

that sets the width of the printout. This can be 0 to default to largest aspect ratio or can be a specific width. Number or Real tagname.

Height A floating point number whose units are inches that set the height of the printout. This can be 0 to default to largest aspect ratio or can be a specific height. Number or Real tagname.

Options A discrete value, 0 or 1, that is only used if Width and Height are 0. If Options is 1, the window is printed with the largest aspect ratio that is an integer multiple of the window size. Discrete number or Discrete tagname.If Options is 0, the window is printed with the largest aspect ratio that fits on the page.

If the window contains a bitmap, set Options to 1 to prevent the bitmap from being stretched.

Remarks Many reports can be queued using this function. (It is recommended that PrintWindow() function be used in place of the PrintHT() function and user initiated prints from the Historical Trend runtime dialog box whenever the entire screen is to be printed, not just the trend chart.)When this function is processed, View loads the window in an "off screen" memory area. View then waits 10 seconds to allow all of the DDE variables to be updated. The window is then sent to the printer. The window specified does not need to be open or visible to be printed. The amount of time View waits can be controlled by adding the following line to the INTOUCH.INI file:PrintWindowWait=10000

Where 10000 represents the number of milliseconds to wait.Fonts are printed as fonts, objects are bit mapped and printed as such. Windows with white backgrounds that contain only fonts are printed very fast. Windows with colored backgrounds that contain many objects will take longer to print.


240 Chapter 3

To ensure that text in a window prints properly, it is recommended that "True Type" fonts are used for the text fields in all windows that will be printed.

When printing push buttons, the text on the button may appear "cut off" because the font used for the button text is the "System" font, which is not a "True Type" font and the "System" font in the printer is slightly different than the "System" font used on the screen. If this should occur, try expanding the button.

If the printer is being used to print alarms, a second printer is required to use the PrintWindow() function.

PrintWindow() does not print properly if any window is overlapping a distributed alarm display, combo box, text box, radio button, checkbox, and so on.

If a window is not focused, ListBox, ComboBox and other Windows/AcitveX controls (such as Active TagBrowser) will not appear in the window printout. If the window is focused, the printout will be ok.

In other words, the print button has to be on the same window to be printed. When the print button is on a window other than the window to be printed, ListBox, ComboBox and other ActiveX controls will be missing from the printout.

To get avoid this problem, use Show(), ShowAt(), or almMoveWindow() functions to help the window get focused before use PrintWindow() function.

Example(s) The following On True Condition QuickScript prints a three page report every day at 8:30 AM:

Condition $Hour == 8 AND $Minute == 30

Script Body PrintWindow("1st Shift Summary",1,1,0,0,0);

PrintWindow("2nd Shift Summary",1,1,0,0,0);

PrintWindow("3rd Shift Summary",1,1,0,0,0);

The PrintWindow() function returns a 1 if the window name exists and could be queued to print. Otherwise, it returns 0. Therefore, status of the function can be monitored.Status=PrintWindow("Shift Summary",1,1,0,0,0);

Status is a Discrete tagname to which the 1 or 0 will be written.



QueryGroupMembership()

RecipeDelete()

RecipeGetMessage()

Category securitySyntax DiscreteTag=QueryGroupMembership( "Domain", "Group" );

Parameter DescriptionDomain Name of the domain or local machine in which

the group is locatedGroup Name of the domain or local machine in which

the group is located.Remarks Valid for OS security mode only and applies to the currently logged on

user. If a user is currently logged on and if he part of the group lpszGroup which is located on the domain lpszDomain then a TRUE is returned and in all other cases a FALSE is returned.

Example(s) DiscreteTag=QueryGroupMembership( "corporate_hq","InTouchAdmins" ); DiscreteTag=QueryGroupMembership("JohnS01", "InTouchUsers" );

See Also BOOL PostLogonDialog(), InvisibleVerifyCredentials(), BOOL IsAssignedRole(), AttemptInvisibleLogon(), AddPermission().

Deletes a Recipe Name from the specified recipe template file.Category recipeSyntax RecipeDelete("Filename","RecipeName");

Parameter DescriptionFileName Recipe template file that will be acted upon by

the function. Actual string or Message tagname.RecipeName Specific recipe in the designated recipe template

file that will be deleted by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. Actual string or Message tagname.

Example(s) The following statement deletes the recipe "Recipe1" from the recfile.csv file:RecipeDelete("c:\recipe\recfile.csv", "Recipe1");

Writes an error code to an Analog tagname and the corresponding error code message to a Message tagname.

Category recipe


242 Chapter 3

Syntax RecipeGetMessage(Analog_Tag,Message_Tag,Number);

Parameter DescriptionAnalog_Tag Actual Integer or Real tagname with no quotes or

constants.Message_Tag Actual Message tagname with no quotes or string

literal.Number This parameter sets the maximum string length

returned to the Message_Tag. InTouch Message tagnames have a maximum length of 131 characters. Use 131 for this parameter unless you have reduced the maximum string length of Message_Tag in the InTouch Tagname Dictionary. This parameter can be a constant or an Integer tagname containing a number.

Example(s) By using the RecipeGetMessage() function in an InTouch Data Change QuickScript, the corresponding error code can be written to an Analog tagname and the associated error code message can be written to a Message tagname:Data Change Script Tagname[.field]:ErrorCodeScript body:RecipeGetMessage(ErrorCode,ErrorMessage,131);

This QuickScript will automatically execute whenever the value of the Analog tagname ErrorCode changes. When this QuickScript executes, the RecipeGetMessage() function will read the current numeric value of the tagname ErrorCode and return the message associated with that value to the tagname ErrorMessage.ErrorCode = RecipeLoad("c:\App\recipe.csv","Unit1","cookies");

RecipeGetMessage(ErrorCode, ErrorMessageTag, 131);



RecipeLoad()Loads a specific recipe to a specific unit of tagnames.

Category recipeSyntax RecipeLoad("Filename","UnitName","RecipeName");

Parameter DescriptionFileName Name of the recipe template file that will be

acted upon by the function. The FileName can be a string constant or a Message tagname that contains the name of the recipe template file.

UnitName Name of the specific unit in the designated recipe template file that will be used by the function. The RecipeLoad() function requires the user to provide the UnitName. The RecipeSelectUnit() function returns a value to this parameter. The UnitName can be a string constant or a Message tagname that contains the name of the unit.

RecipeName Name of the specific recipe in the designated recipe template file that will be used by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. The RecipeName can be a string constant or a Message tagname that contains the name of the recipe.

Example(s) The following statement causes the values defined for the recipe named Recipe1 (in the recfile.csv file) to be loaded into the tagnames defined for Unit:RecipeLoad("c:\recipe\recfile.csv", "Unit1","Recipe1");


244 Chapter 3

RecipeSave()Saves a newly created recipe or to save changes made to an existing recipe to the specified recipe template file.

Category recipeSyntax RecipeSave("Filename","UnitName","RecipeName");

Parameter DescriptionFileName Name of the recipe template file that will be acted

upon by the function. The FileName can be a string constant or a Message tagname that contains the name of the recipe template file.

UnitName Name of the specific unit in the designated recipe template file that will be used by the function. The RecipeLoad() function requires the user to provide the UnitName. The RecipeSelectUnit() function returns a value to this parameter. The UnitName can be a string constant or a Message tagname that contains the name of the unit.

RecipeName Name of the specific recipe in the designated recipe template file that will be used by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. The RecipeName can be a string constant or a Message tagname that contains the name of the recipe.

Example(s) The following example will save changes made to the recipe named Recipe3 in the recfile.csv file. If Recipe3 does not currently exist in the recfile.csv file, it will be created. The values will then set the values of the tagnames defined for Unit2:RecipeSave("c:\recipe\recfile.csv", "Unit2","Recipe3");



RecipeSelectNextRecipe()Selects the next Recipe Name currently defined in the recipe template file.

Category recipeSyntax RecipeSelectNextRecipe("Filename", RecipeName, Number);


upon by the function. Actual Message tagname.RecipeName Name of the specific recipe in the designated recipe

template file that will be used by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. Actual Message tagname with out quotes or a string literal.

Number If a function has to fill a parameter with characters, this field sets the maximum string length returned to the parameter. In InTouch, string (Message) tagnames have a maximum length of 131 characters. Use 131 for this parameter unless you have reduced the maximum string length of the InTouch tagname. Number or Integer tagname.

Example(s) The following statement causes the system to read the current value of the tagname RecipeName and return the next recipe on file. If the value of RecipeName is blank or cannot be found, the first recipe on file is returned. If RecipeName currently contains the last Recipe Name on file, it is returned unchanged. (Recipes are saved in the order in which they are created.)RecipeSelectNextRecipe("c:\recipe\recfile.csv",RecipeName, 131);


246 Chapter 3

RecipeSelectPreviousRecipe()Selects the previous Recipe Name currently defined in the recipe template file.

Category recipeSyntax RecipeSelectPreviousRecipe("Filename",RecipeName,

Number);



template file that will be used by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. Actual Message tagname with out quotes or a string literal.

Number If a function has to fill a parameter with characters, this field sets the maximum string length returned to the parameter. In InTouch, Message tagnames have a maximum length of 131 characters. Use 131 for this parameter unless you have reduced the maximum string length of the InTouch tagname. Number or Integer tagname.

Example(s) The following statement causes the system to read the current value of the tagname RecipeName and return the previous Recipe Name on file. This returned string will be stored in RecipeName and will overwrite the current value. If the value of RecipeName is blank or cannot be found, the last recipe on file is returned. If RecipeName currently contains the first Recipe Name on file, it is returned unchanged. (Recipes are saved in the order in which they are created.)RecipeSelectPreviousRecipe("c:\recipe\recfile.csv",RecipeName, 131);



RecipeSelectRecipe()Selects a specific Recipe Name currently defined in the recipe template file.

Category recipeSyntax RecipeSelectRecipe("Filename",RecipeName,Number);



template file that will be used by the function. The RecipeLoad(), RecipeSave() and RecipeDelete() functions require the user to provide the RecipeName. The RecipeSelectRecipe() function returns a value to this parameter. Actual Message tagname without quotes or a string literal.

Number If a function has to fill a parameter with characters, this field sets the maximum string length returned to the parameter. In InTouch, Message tagnames have a maximum length of 131 characters. Use 131 for this parameter unless you have reduced the maximum string length of the InTouch tagname. Number or Integer tagname.

Example(s) The following statement causes the Select a Recipe dialog box to open:RecipeSelectRecipe("c:\recipe\recfile.csv", RecipeName,131);

Once a recipe is selected from the dialog box, its name is returned to the tagname RecipeName.


248 Chapter 3

RecipeSelectUnit()Selects the unit of tagnames to which the current recipe values will be loaded.

Category recipeSyntax RecipeSelectUnit("Filename", UnitName,Number);


upon by the function. Actual Message tagname.UnitName Name of the specific unit in the designated recipe

template file that will be used by the function. The RecipeLoad() function requires the user to provide the UnitName. The RecipeSelectUnit() function returns a value to this parameter. Actual Message tagname with out quotes or a string literal.

Number If a function has to fill an parameter with characters, this field sets the maximum string length returned to the parameter. In InTouch, string (Message) tagnames have a maximum length of 131 characters. Use 131 for this parameter unless you have reduced the maximum string length of the InTouch tagname. Number or Integer tagname.

Example(s) The following statement causes the Select a Unit dialog box to open:RecipeSelectUnit("c:\recipe\recfile.csv", UnitName,131);

Once a Unit is selected, its name is returned to the tagname UnitName.Both the RecipeSelectRecipe() and RecipeSelectUnit() functions are used in conjunction with the RecipeLoad() function.For more information on combining functions, see the "Combining Recipe Functions" section of your online Recipe Manager User's Guide.



ReloadWindowViewer()

RestartWindowViewer()

Allows the user control over reloading WindowViewer.Category systemSyntax ReloadWindowViewer();

Remarks This function will automatically update WindowViewer. It is used to update an application when the automatic update Network Application Development (NAD) functions are not used. This function can be used with $ApplicationChanged to determine when a NAD update has occurred and then provide an update of the View node without interrupting the operation of that node. When using the Notify clients command, the operator may want to delay the update until a later time. This function can be placed in a Touch Pushbutton Action QuickScript. Therefore, an operator can peform a dynamic update of WindowViewer when it is convenient. This function effectively replaces the RestartWindowViewer() function.

See Also $ApplicationChanged

Allows the user control over shutting down and restarting WindowViewer.Category systemSyntax RestartWindowViewer();

Remarks This function will shut down and restart WindowViewer. It is used to update an application when the automatic update Network Application Development (NAD) functions are not used. This function can be used with $ApplicationChanged to determine when a NAD update has occurred and then provide an update of the View node by shutting down and restarting WindowViewer. When using the Notify Clients command, the operator may want to delay the update until a later time. This function can be placed in a touch Push button Action QuickScript. Therefore an operator can perform an automatic shutdown and restart of WindowViewer when it is convenient. This function has generally been superceded by the ReloadWindowViewer() function which updates the View node without shutting down Viewer.

See Also $ApplicationChanged; ReloadWindowViewer()


250 Chapter 3

Round()Rounds a real number to a specified precision.

Category mathSyntax RealResult=Round(Number,Precision);

Parameter DescriptionNumber Any number, Real or Integer tagname.Precision Sets the precision to which the number will be

rounded. Number, Real or Integer tagname.Remarks The Precision parameter sets the precision to which the Number will be

rounded.Example(s) Round(4.3, 1) will return 4

Round(4.3, .01) will return 4.30

Round(4.5, 1) will return 5

Round(-4.5, 1) will return -4

Round(106, 5) will return 105

Round(43.7, .5) will return 43.5

See Also Trunc()



SendKeysSends keys to an application. To the receiving application, the keys appear to have been entered from the keyboard. This capability may be used to enter data into the application or to give commands to the application. Most keyboard keys can be used in a SendKeys statement. Each key is represented by one or more characters such as A for the letter A or {ENTER} for the Enter key.

Category miscSyntax SendKeys KeySequence;

Parameter DescriptionKeySequence Any key sequence or Message tagname.

Remarks To specify more than one key, concatenate the codes for each character. For example, to specify the dollar sign ($) key followed by a (b), enter $b. The following lists the valid send keys for unique keyboard keys:Key Code Key CodeBACKSPACE {BACKSPACE}

or {BS}HOME {HOME}

BREAK {BREAK} INSERT {INSERT}CAPSLOCK {CAPSLOCK} LEFT {LEFT}DELETE {DELETE} or

{DEL}NUMLOCK {NUMLOCK}

DOWN {DOWN} PAGE DOWN {PGDN}END {END} PAGE UP {PGUP}ENTER {ENTER} or ~

(tilde)PRTSC {PRTSC}

ESCAPE {ESCAPE} or {ESC}

RIGHT {RIGHT}

F1 {F1}* TAB {TAB}UP {UP}

* All functions keys are entered the same.Special keys (SHIFT, CTRL and ALT) have their own key codes:Key CodeSHIFT + (plus) CTRL ^ (caret) ALT % (percent)

Example(s) If two special keys are to be used together, a second set of parentheses is required. The following statement is used to hold down the CTRL key while pressing the ALT key followed by p:SendKeys "^(%(p))";

Commands can be preceded by the ActivateApp command to direct the keystrokes to the proper application.


252 Chapter 3

SetPropertyD()

The following statement gives the computer focus to Excel and send the key combination CTRL+P (which may run a previously defined print macro assigned to run with the key combination CTRL+P):ActivateApp "Microsoft Excel";

SendKeys "^(p)";

Or, the following can be used to open the Logon dialog box in WindowViewer:SendKeys "%(SYL)";

In a button labeled HELP you could use the following QuickScript:SendKeys "{F1}";

Microsoft’s enhancements to the Hardware Abstraction Layer in Windows may keep this function from operating on some PCs.

Specifies the property's discrete value that is to be written during runtime.Category GOTSyntax [ErrorNumber=]SetPropertyD("ControlName.Property",

DiscreteTag);

Parameter DescriptionControlName Name of a windows control, for example, ChkBox_1

or the name of an alarm object, for example, AlmObj_1.



DiscreteTag A discrete value, or Discrete tagname that holds the value to be written when the function is processed. Typical usage:0=Control is disabled1=Control is enabled

Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyD(), GetPropertyI(), GetPropertyM(), SetPropertyI(),

SetPropertyM()



SetPropertyI()

SetPropertyM()

Specifies the property's integer value that is to be written during runtime.Category GOTSyntax [ErrorNumber=]SetPropertyI("ControlName.Property",

Integer);





Integer A number or Integer tagname.Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyD(), GetPropertyI(), GetPropertyM(), SetPropertyD(),

SetPropertyM()

Specifies the property's message value that is to be written during runtime.Category GOTSyntax [ErrorNumber=]SetPropertyM("ControlName.Property",

"MessageTag");





MessageTag The string that will be written to the ControlName's property. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.See Also GetPropertyD(), GetPropertyI(), GetPropertyM(), SetPropertyI(),

SetPropertyI()


254 Chapter 3

Sgn()

Show

Determines the sign of a value (whether it is positive, zero, or negative).Category mathSyntax IntegerResult=Sgn(Number);


Remarks If the input number is positive, the result will be 1. Negative numbers will return a -1 and 0 will return a 0.

Example(s) Sgn(425) will return 1

Sgn(0) will return 0

Sgn(-37.3) will return -1

Displays a specified window. (Window name must be enclosed in quotation marks.)

Category miscSyntax Show "Window";

Parameter DescriptionWindow The name of the window to display. Actual string or

Message tagname.Remarks Window must match the name of an existing window or a window that will

be created. During runtime, if the window does not exist, WindowViewer ignores the statement. If the name of the window changes, it must be changed in the QuickScript as well.

If a local Message tagname is used as a parameter to show a window, the following error message appears:

"Expecting window name - must be string expression"

To avoid this message, prefix the Message tagname with a plus (+) sign. For example:

DIM Test AS message;

Test - "MyWindow1";

Show ""+Test;Example(s) Show "Alarm Summary Window";

If the QuickScript is only hiding or showing windows, it is recommended that the Show Window or Hide Window links be used instead. If these are used and the window name changes, InTouch will automatically make the change.

See Also Hide, Hideself, ShowAt(), ShowHome, ShowTopLeftAt()



ShowAt()Specifies the horizontal and vertical pixel location of a window when it is shown.

Category miscSyntax ShowAt("Window",Horiz,Vert);

Parameter DescriptionWindow The name of the window. Actual string or Message

tagname.Horiz Horizontal pixel location. Any number or Integer

tagname.Vert Vertical pixel location. Any number or Integer

tagname.Remarks When the window opens, it will be centered on the horizontal and vertical

coordinates. The window will not be centered if one of its edges extends off-screen. A best fit to that edge would be performed.

Example(s) In the following statement, 100 represents the horizontal pixel location and 200 represents the vertical:ShowAt("Window Name",100,200);

Analog Input objects can also be created and linked to Memory tagnames, for example, TagHoriz and TagVert, to dynamically change the window's position during runtime. In this case, the statement would be entered as:ShowAt("Boiler Room 7 Details",TagHoriz,TagVert);

The following statement determines the pixel locations of an object, the internal tagnames $ObjHor and $ObjVer can be assigned to analog output links that will display the locations for the currently selected object. A window can be made to appear centered on top of an object or pushbutton by using the $ObjHor and $ObjVer tagnames in a QuickScript linked to the object or pushbutton. ShowAt("Window Name",$ObjHor,$ObjVer);

See Also $ObjHor, $ObjVer, ShowTopLeftAt(), Show, ShowHome, Hide, Hideself


256 Chapter 3

ShowHome

ShowTopLeftAt()

Displays the "home" window(s). Home windows are those you selected to open automatically when WindowViewer is started. (The home windows are selected in the WindowViewer Properties - Home Windows property sheet.)

Category miscSyntax ShowHome;

See Also Show, ShowAt(), ShowTopLeftAt(), ShowHome, Hide, Hideself

Specifies the horizontal and vertical pixel location of the top left corner of a window when it is shown.

Category miscSyntax ShowTopLeftAt("Window",Horiz,Vert);

Parameter DescriptionWindow The name of the window. Actual string or

Message tagname.Horiz Horizontal pixel location. Any number or Integer

tagname.Vert Vertical pixel location. Any number or Integer

tagname.Remarks When the window opens, its top left corner will be positioned where the

horizontal and vertical coordinates meet. (The uppermost left corner of the screen is pixel location 0,0.) This function works exactly the same as the ShowAt() function, except it controls where the top left corner of the window will appear.This function loads a window in memory and then moves it to the new location. The original location (when the window was saved in WindowMaker) remains regardless of where the window is moved.

See Also Show, ShowAt(), ShowHome(), Hide, Hideself



Sin()

SPCConnect()

Returns the sine of an angle given in degrees.Category mathSyntax Result=Sin(AngleNumber);

Parameter DescriptionAngleNumber Angle in degrees. Any number, Real or Integer

tagname.Remarks The sine of Number is calculated and returned to Result.Example(s) Sin(90) will return 1

Sin(0) will return 0

wave = 100 * Sin (6 * $second);

See Also Cos(), Tan(), ArcCos(), ArcSin(), ArcTan()

This function is used in conjunction with automatic data collection datasets. Before an Automatic data collection dataset will start collecting data, this function must be used to indicate to SPC which user the node is.

Category SPCSyntax SPCConnect(“User”,”Password”);

Parameter DescriptionUser Database user name. Actual string or Message

tagname.Password User's password. Actual string or Message tagname.

Remarks Executing this function will connect the user to the database and start all automatic data collection datasets using this user ID. If there is no password defined for the database, you can use the following QuickScript.

Example(s) SPCConnect(“User1”, “”);

See Also SPCDisconnect()


258 Chapter 3

SPCDatasetDlg()

SPCDisconnect()

This function is used to display the SPCPro Dataset Configuration dialog box in WindowViewer. New Datasets can be added and deleted. There are no parameters or any return value.

While WindowViewer is running, current dataset and product information will be grayed out, certain fields can't be changed.

New Datasets and Products can be added while WindowViewer is running.

If New Datasets and Products are added and saved:

If running in Autocollection mode, the Autocollection cycle will be restarted, possible data loss during the initialization phase of the datasets.

It is recommended that you use the NewProduct SPC DDE Item to add Products during runtime, not through the SPCDatasetDlg() function, this will prevent the restart of the Autocollection mode.

Category SPCSyntax SPCDatasetDlg();

Remarks Executing this function will open the SPCPro Dataset Configuration dialog box in WindowViewer

Example(s) SPCDatasetDlg();

See Also SPCSelectDataset()

This function is used to disconnect an Agent from a SPC Pro database. When this function is used, all datasets that were assigned to the Agent that was disconnected will stop collecting.

Category SPCSyntax SPCDisconnect();

Remarks Executing this function will disconnect the user from the database and stop all automatic data collection datasets.

Example(s) SPCDisconnect();

See Also SPCConnect()



SPCDisplayData()

SPCLocateScooter()

This function is designed to allow convenient scrolling of the chart to any date and time. You can use a tagname to monitor the status of the SPC data search. Status will contain a 0 if SPC found data and 1 if it could not find data for the specified time period.

Category SPCSyntax [Status=]SPCDisplayData("Dataset", "DateString",

"TimeString", RangeInHours );

Parameter DescriptionDataset Represents an actual Dataset name. Actual string or

Message tagname.DateString Represents the date in the format mm/dd/yy. Actual

string or Message tagname.TimeString Represents the Time in the format hh:mm:ss. Actual

string or Message tagname.RangeInHours Represents the Hours of data to display. Any number

or Integer tagname.Example(s) StatusTag = SPCDisplayData("Dataset", "DateString",

"TimeString" , RangeInHours);

This function is designed to allow convenient scrolling of the Scooter to any valid sample number. The Scooter tagname defined in the dataset will be updated with the X-Bar sample value. Setting SampleNumber to 0 hides/disables the Scooter.

Category SPCSyntax SPCLocateScooter( "Dataset", SampleNumber );


Message tagname.SampleNumber Represents any valid sample number. Any number or

Integer tagname.See Also SPCMoveScooter()


260 Chapter 3

SPCMoveScooter()

SPCSaveSample()

This function is designed to allow convenient scrolling of the Scooter to any valid sample number. The Scooter tagname defined in the dataset will be updated with the X-Bar sample value.

Category SPCSyntax SPCMoveScooter( "Dataset", IncrementValue );


Message tagname.IncrementValue Represents any valid number. Positive to scroll

forwards and Negative to scroll backwards. Any number or Integer tagname.

See Also SPCLocateScooter()

Saves a manually input sample. This function is used in conjunction with the SPCSetMeasurement function.

Category SPCSyntax SPCSaveSample("Dataset");

Parameter DescriptionDataset Actual dataset name. Actual string or Message

tagname.Remarks Processing this function will force the sample to be entered into the

specified Dataset name. It will use the current values of the manual input variables for the measurements in the sample. The input values are set either via the DDE tagnames MI_Mx (x =the measurement number form 1 to 25) or by using the SPCSetMeasurement() function (measurements 1 to 300). You will need to re-initiate DDE conversations to update the values of the MI_Mx tags.

See Also SPCSetMeasurement()



SPCSelectDataset()

SPCSelectProduct()

Opens a dialog box from which the user may select a direct dataset.Category SPCSyntax DatasetName=SPCSelectDataset()

Remarks This QuickScript causes the Select a Dataset dialog box to open.Once a Dataset name is selected, the function returns it to the DatasetName tagname. This selection can also be used to change the DatasetName of an Indirect Dataset.

See Also SPCSelectProduct(), SPCDatasetDlg()

Opens a dialog box from which the user may select a product in a given dataset.

Category SPCSyntax ProductName=SPCSelectProduct(Dataset);

Remarks Processing this QuickScript causes the Select a Product dialog box to open.Once a Product name is selected, the function returns it to the ProductName tagname. This name can now be used to change the collected product in the Dataset.

See Also SPCSelectDataset(), SPCSetProductDisplayed(), SPCSetProductCollected()


262 Chapter 3

SPCSetControlLimits()

SPCSetMeasurement()

Allows convenient manual or event driven input of the control limit values for a Control Chart.

Category SPCSyntax SPCSetControlLimits("Dataset",XUCL,XLCL);

Parameter DescriptionDataset Contains the actual Dataset name. Actual string or

Message tagname.XUCL Represents the value to be used for the UCL of the

chart. Number or Real tagname.XLCL Represents the value to be used for the LCL of the

chart. Number or Real tagname.Remarks These measurements are saved to the sample by processing

SPCSaveSample().See Also SPCSaveSample(), SPCSetRangeLimits(), SPCSetSpecLimits(),

SPCSetMeasurement()

Allows convenient manual or event driven inputs of analog measurement values by processing the QuickScript.

Category SPCSyntax SPCSetMeasurement("Dataset",Measurement,Value);

Parameter DescriptionDataset Contains the actual Dataset name. Actual string

or Message tagname.Measurement Represents a measurement number (from 1 to

300). Any number or Integer tagname.Value The value to be written to the specified

measurement number. Any number or Real tagname.

Remarks Use SPCSaveSample() once all measurements are set to save the data to the database. You will need to re-initiate DDE conversations to update the values of the MI_Mx tags.

See Also SPCSaveSample()



SPCSetProductCollected()

SPCSetProductDisplayed()

Changes the product being collected in a specified Dataset.Category SPCSyntax SPCSetProductCollected("Dataset","Product");


or Message tagname.Product Contains the Product name under which data

should be collected. Actual string or Message tagname.

Remarks This function does not change the product being displayed. It is possible to collect data for one product and display data for another by using this function to collect and the SPCSetProductDisplayed() function to display.

Example(s) SPCSetProductCollected("Data5838", "Widgets");

See Also SPCSelectProduct(), SPCSetProductDisplayed()

Changes the product being displayed in a specified Dataset.Category SPCSyntax SPCSetProductDisplayed("Dataset","Product");


or Message tagname.Product Contains the product name for which data will be

displayed. Actual string or Message tagname.Example(s) SPCSetProductDisplayed("ADataSetName", "AProductName");

See Also SPCSelectProductt(), SPCSetProductCollected()


264 Chapter 3

SPCSetRangeLimits()

SPCSetSpecLimits()

Allows convenient manual or event driven input of the Control Limits for a Range Chart.

Category SPCSyntax SPCSetRangeLimits("Dataset",RUCL,RLCL);

Parameter DescriptionDataset Contains the actual Dataset name. Actual string or

Message tagname.RUCL Represents the value to be used for the UCL for a

Range Chart. Number or Real tagname.RLCL Represents the value to be used for the LCL for a

Range Chart. Number or Real tagname.See Also SPCSetControlLimits(), SPCSetSpecLimits()

Allows convenient manual or event driven input of the specification limit values for a Control Chart.

Category SPCSyntax SPCSetSpecLimits("Dataset",XUSL,XLSL);


or Message tagname.XUSL Represents the value to be used for the chart's

USL. Number or Real tagname.XLSL Represents the value to be used for the chart's

LSL. Number or Real tagname.See Also SPCSetControlLimits(), SPCSetRangeLimits()



SQLAppendStatement()

SQLClearParam()

SQLClearStatement()

Continues a SQL statement using the contents of string. Errors are returned in the function return.

Category SQLSyntax [ResultCode=]SQLAppendStatement(ConnectionID,

"SQLStatement");

Parameter DescriptionConnectionID A Memory Integer tagname created by the user to

hold the number (ID) assigned by the SQLConnect function to each database connection.

SQLStatement Actual statement to append.Example(s) ResultCode=SQLAppendStatement(ConnectionID,

"where tablename.columnname=(any value or string)");

See Also SQLConnect(), SQLClearStatement()

Clears the value of the specified parameter. SQLSetParam must be called again before calling the SQLExecute() function.

Category SQLSyntax [ResultCode=]SQLClearParam(SQLHandle,ParameterNumber);

Parameter DescriptionSQLHandle Integer value returned by SQL when a

SQLPrepareStatement() function is used.ParameterNumber The actual parameter within the SQL statement to

modify.See Also SQLPrepareStatement(), SQLExecute()

Releases the resources associated with the statement specified by SQLHandle.

Category SQLSyntax [ResultCode=]SQLClearStatement(ConnectionID,SQLHandle);



SQLHandle Integer value returned by SQL when a SQLPrepareStatement() function is used.

See Also SQLConnect(), SQLPrepareStatement()


266 Chapter 3

SQLClearTable()

SQLCommit()

Deletes all records in a database table, but keeps the table.Category SQLSyntax [ResultCode=]SQLClearTable(ConnectionID,"TableName");



TableName The name of the database table you want to access.

Example(s) To delete all records in the table BATCH1, the following statement would be used:

ResultCode=SQLClearTable(ConnectionID,"BATCH1");

See Also SQLConnect(), SQLClearStatement()

The SQLCommit() command defines the end of a group of transaction commands. The group of commands performed between the SQLTransact() command and the SQLCommit() command is called a transaction set. A transaction set is handled like a single transaction. After the SQLTransact() command is issued, all subsequent operations will not be committed to the database until the SQLCommit() command is issued.

Category SQLSyntax [ResultCode=]SQLCommit(ConnectionID);



Note Use caution when writing QuickScripts that include the SQLCommit() command. Since the processing time is multiplied by the number of commands in a transaction set, including numerous commands will significantly slow performance.



Example ResultCode = SQLTransact( ConnectionID);

ResultCode = SQLInsertPrepare( ConnectionID, TableName,BindList, SQLHandle );

ResultCode = SQLInsertExecute( ConnectionID, BindList,SQLHandle );



ResultCode = SQLInsertEnd( ConnectionID, SQLHandle );

ResultCode = SQLCommit( ConnectionID);

{Database keeps the 3 Inserts }

See Also SQLRollback(), SQLTransact(), SQLCommit()


268 Chapter 3

SQLConnect()Connects InTouch to the database specified in the ConnectString.

Category SQLSyntax [ResultCode=]SQLConnect(ConnectionID,"ConnectString");

Parameter DescriptionConnectionID A Memory Integer tagname created by the

user to hold the number (ID) assigned by the SQLConnect function to each database connection.

ConnectString String that identifies the database and any additional logon information used in SQLConnect() function.

Example(s) The following statements connects to IBM OS/2 Database Manager and to the database named SAMPLE:

[ResultCode=]SQLConnect(ConnectionID,"DSN=OS2DM;DB=SAMPLE");

This function returns a value to the ConnectionID variable that is used as a parameter in all subsequent SQL Functions.

The ConnectString identifies the database system and any additional logon information. It is entered in the following format:

"DSN=data source name[;attribute=value[;attribute=value]...]"



The attributes required by each database vary. QELIB recognizes the following attributes for all databases:Attribute ValueDSN The name of the data source as configured in

the Microsoft ODBC Administrator.DLG When enabled (DLG=1), displays a dialog

box that allows you to input of connection string information.

DRV For compatibility with SQL Access for InTouch version 4.11, this value is used if a data source name (DSN) is not present in the connection string. QELIB changes it to the data source name.

UID Logon ID.PWD Password.MODIFYSQL Used by QELIB to ensure compatibility

between the SQL used in the application and the SQL used in the database. When set to 1 (default), the database driver expects ODBC-compliant Syntax, which it will modify as necessary for the underlying database system. When set to 0, the database driver expects and supports the native Syntax of the underlying database system. This enables you to continue using applications developed with the SQL supported by the QELIB 1.0 database drivers.

REREADAFTERUPDATE If enabled (set to 1), QELIB rereads a record from the database after updating it. This is useful for getting the correct value of auto-updated columns such as time stamps.

REREADAFTERINSERT If enabled (set to 1), QELIB rereads a record from the database after inserting it. This is useful for getting the correct value of auto-updated columns such as time stamps.

For more information on the attributes supported by a specific database, see your online SQL Access Manager User's Guide.

See Also SQLDisconnect()


270 Chapter 3

SQLCreateTable()

SQLDelete()

Creates a table in the database using the parameters in the named Table Template. Table Templates (defined in the SQL.DEF file) determine the structure of a database table.

Category SQLSyntax [ResultCode=]SQLCreateTable(ConnectionID,TableName,

TemplateName);



TableName Name of the database table you want to access.TemplateName Name of the template definition you want to use.

Example(s) The following statement creates a table named BATCH1 with the column names and types defined in TEMPLATE:

ResultCode=SQLCreateTable(ConnectionID,"BATCH1","TEMPLATE");

When a parameter is entered in a QuickScript surrounded by quotation marks, for example, "Parameter1", that exact string will be used. If no quotation marks are used, Parameter1 is assumed to be a tagname and the system will access the InTouch Tagname Dictionary for the value of the tagname, Parameter1. For example:

"c:\main\file" vs. location

Where location is an InTouch Message tagname.

"c:\main\file" is a literal string

See Also SQLConnect()

Deletes a record or multiple records.Category SQLSyntax [ResultCode=]SQLDelete(ConnectionID,TableName,

WhereExpr);

Note The SQLDelete() function cannot contain a null WhereExpression.





TableName The name of the database table to access. WhereExpression Defines a condition that can be either true or false

for any row of the table. The function extracts only those rows from the table for which the condition is true. The expression must be in the following format:

ColumnName comparison_operator expression. Note If the column is a character data type, the expression must be in single quotes.

Example(s) The following example will select all rows whose name column contains the value EmployeeID:

name='EmployeeID'

The following example will select all rows containing part numbers from 100 to 199:

partno>=100 and partno<200

The following example will select all rows whose temperature column contains a value that is greater than 350:

temperature>350

The following statement deletes all records in table BATCH1 whose lot number is equal to 65:

ResultCode=SQLDelete(ConnectionID,"BATCH1","lotno=65");



272 Chapter 3

SQLDisconnect()

SQLDropTable()

SQLEnd()

Disconnects the user from the database. Category SQLSyntax [ResultCode=]SQLDisconnect(ConnectionID);




Destroys a table.Category SQLSyntax [ResultCode=]SQLDropTable(ConnectionID,TableName);



TableName Name of database table name you want to access.Example(s) The following statement destroys the table BATCH1, once this command

is given, the table name will no longer recognized and will not respond to any commands:

ResultCode=SQLDropTable(ConnectionID,"BATCH1");


This is used after a SQLSelect() function to free resources that were being used to store the Results Table.

Category SQLSyntax [ResultCode=]SQLEnd(ConnectionID);



See Also SQLConnect(), SQLSelect()



SQLErrorMsg()

SQLExecute()

Retrieves the text error message associated with a specific ResultCode. ErrorMsg is the InTouch Memory Message tagname (maximum 131 characters) associated with ResultCode.

Category SQLSyntax SQLErrorMsg(ResultCode);

Parameter DescriptionResultCode An integer variable returned from most SQL

functions. It is returned as a 0 if the function was successful and a negative integer if it fails.

For more information on these codes, see APPENDIX A, "Troubleshooting QuickScript Functions."

Example(s) ErrorMsg=SQLErrorMsg(ResultCode);


Executes the SQL statement. If the statement is a select statement, the BindList parameter designates the name of the BindList to use for binding the database columns with tagnames. If the BindList is NULL, no tagnames relationships are formed. For example, the SQL statement could be Create View, Insert, etc. Errors are returned in the function return. If the statement has been "prepared," the statement handle returned from the prepare should be passed. If the statement has not been prepared, the statement handle should be zero (0).

Category SQLSyntax [ResultCode=]SQLExecute(ConnectionID,BindList,

SQLHandle);



BindList Defines which InTouch tagnames are used and which database columns they are associated with.


See Also SQLConnect(),SQLPrepareStatement()Note SQLExecute() function can only be called once for a statement that has not been prepared. If the statement has been prepared, it can be called numerous times.


274 Chapter 3

SQLFirst()

SQLGetRecord()

SQLInsert()

Selects the first record of the Results Table created by the last SQLSelect() function. A SQLSelect() function must be processed before using this command.

Category SQLSyntax [ResultCode=]SQLFirst(ConnectionID);




Retrieves the record specified by RecordNumber from the current selection buffer.

Category SQLSyntax [ResultCode=]SQLGetRecord(ConnectionID,Record Number);



RecordNumber Actual record number to retrieve.Example(s) ResultCode=SQLGetRecord(ConnectionID,3);


Inserts a new record into the referenced table using the values of the tagnames in the supplied BindList. The BindList parameter defines which InTouch tagnames are used and which database columns they are associated.

Category SQLSyntax [ResultCode=]SQLInsert(ConnectionID,TableName,

BindList);



SQLInsertEnd()



TableName Name of the database table you want to access.BindList Defines which InTouch tagnames are used and

which database columns they are associated with.Example(s) The following statement inserts a new record into table ORG with the

tagname values specified in List1:

ResultCode=SQLInsert(ConnectionID,"ORG","List1");

Note The following three functions can be used in place of the standard SQLInsert() function to quickly insert records into a file. The SQLInsert() function is a one step operation that inserts and ends the statement. Because of this, the next time a SQLInsert() function is called, another whole operation is done again. This takes much longer than using the three functions below. The three functions below break these steps apart, so that once you do a SQLInsertPrepare() function, you can do as many SQLInsertExecute() functions you want, as fast as you want, then do a SQLInsertEnd() when finished.

Releases the statement.Category SQLSyntax [ResultCode=]SQLInsertEnd(ConnectionID,SQLHandle);



SQLHandle Integer value returned by SQL when a SQLPrepareStatement() function is used



276 Chapter 3

SQLInsertExecute()

SQLInsertPrepare()

Execute the already prepared statement.Category SQLSyntax [ResultCode=]SQLInsertExecute(ConnectionID,BindList,

SQLHandle);



BindList Defines which InTouch tagnames are used and which database columns they are associated with.



Creates and prepares an Insert statement for execution. The Insert statement is not processed. The SQLHandle parameter is an Integer tagname that will contain a value after the statement is processed.

Category SQLSyntax [ResultCode=]SQLInsertPrepare

(ConnectionID,TableName,BindList,SQLHandle);



TableName The name of the database table to access.BindList Defines which InTouch tagnames are used and

which database columns they are associated with.SQLHandle Integer value returned by SQL when a

SQLPrepareStatement() function is used.See Also SQLConnect(), SQLPrepareStatement()



SQLLast()

SQLLoadStatement()

Selects the last record of the Results Table created by the last SQLSelect() function. A SQLSelect() function must be processed before using this command.

Category SQLSyntax [ResultCode=]SQLLast(ConnectionID);



Example(s) ResultCode=SQLLast(ConnectionID);


Reads the statement contained in FileName. At this point the statement is similar to one created by SQLSetStatement() function, and can be appended to via SQLAppendStatement() function, or executed by SQLExecute() function. There can be only one statement per file. However, SQLAppendStatement() function can be used to append something to the statement if SQLPrepareStatement() function or SQLExecute() function has not been called.

Category SQLSyntax [ResultCode=]SQLLoadStatement(ConnectionID,FileName);



FileName The name of the file name in which the information is contained.

Remarks Prepare the SQL Statement that has been created by either SQLSetStatement, or SQLLoadStatement functions. The statement handle is returned.

Example(s) ResultCode=SQLLoadStatement(ConnectionID,”C:\InTouchAppname\SQL.txt”)

SQL.txt = Select ColumnName from TableName whereColumnName>100;

See Also SQLConnect(), SQLAppendStatement(), SQLExecute(), SQLPrepareStatement


278 Chapter 3

SQLManageDSN()

SQLNext()

SQLNumRows()

Runs the Microsoft ODBC Manager setup program. This can be used to add, delete and modify all data source names.

Category SQLSyntax SQLManageDSN(ConnectionID);



Selects the next record of the Results Table created by the last SQLSelect() function. A SQLSelect() function must be processed before using this command.

Category SQLSyntax [ResultCode=]SQLNext(ConnectionID);



Example(s) ResultCode=SQLNext(ConnectionID);


Indicates how many rows met the criteria specified in the last SQLSelect() function. For example, if a WhereExpression is used to select all rows with a column name AGE, where AGE is equal to 45, the number of rows returned could be 40 or 4000. This may determine which function is processed next.

Category SQLSyntax SQLNumRows(ConnectionID);





SQLPrepareStatement()

Example(s) The following statement returns the number of rows selected to the Integer tagname NumRows:

NumRows=SQLNumRows(ConnectionID);


A SQLPrepareStatement() prepares an existing SQL statement for use by the SQLSetParam() function. A statement can be created by using either a SQLSetStatement(), or SQLLoadStatement(). The statement handle is returned.

Category SQLSyntax [ResultCode=]SQLPrepareStatement(ConnectionID,

SQLHandle);




Remarks A matching SQLClearStatement() must be called to free up system resources.

To properly call a stored procedure use the following:

ResultCode = SQLSetStatement(ConnectionID,"exec sp_MyStoredProc");

Example(s) ResultCode=SQLPrepareStatement(ConnectionID,SQLHandle);

See Also SQLConnect(), SQLSelect(), SQLSetStatement(), SQLLoadStatement()


280 Chapter 3

SQLPrev()

SQLRollback()

Selects the previous record of the Results Table created by the last SQLSelect() function.

Category SQLSyntax [ResultCode=]SQLPrev(ConnectionID);



Remarks A SQLSelect() function must be processed before using this command.Example(s) ResultCode=SQLPrev(ConnectionID);


The SQLRollback() command reverses, or "rolls back," the most recently committed transaction set. A transaction set is a group of commands issued between the SQLTransact() command and the SQLCommit() command or the SQLRollback() command. A transaction set is handled like a single transaction. After the SQLTransact() command is issued, all subsequent operations are not committed to the database until the SQLCommit() command is issued.

Category SQLSyntax [ResultCode=]SQLRollback(ConnectionID,);



Example(s) ResultCode =SQLTransact( ConnectionID);

ResultCode = SQLInsertPrepare( ConnectionID, TableName,BindList, SQLHandle );


ResultCode = SQLInsertEnd( ConnectionID, SQLHandle );

ResultCode =SQLRollback( ConnectionID);

{Ignores all commands after Transact() Databaseunchanged }

See Also SQLCommit(), SQLTransact()



SQLSelect()Instructs the database to retrieve information from a table. When a SQLSelect() function is processed, a temporary Results Table is created in memory, containing records that can be browsed using SQLFirst(), SQLLast(), SQLNext() and SQLPrev() functions.

Note Always use the SQLEnd() function after a SQLSelect() to free resources that were being used to store the Results Table.

Category SQLSyntax [ResultCode=]SQLSelect(ConnectionID,TableName,BindList,

WhereExpr,OrderByExpr);




which database. WhereExpression Defines a condition that can be either true or false for

any row of the table. The command extracts only those rows from the table for which the condition is true. The expression must be in the following format:

ColumnName comparison_operator expression.Note If the column is a character data type, the expression must be in single quotes.The following example will select all rows whose name column contains the value EmployeeID:

name='EmployeeID'




temperature>350


282 Chapter 3

WhereExpression Example

WhereExpr - Memory message TagOrderByExpr - Memory message TagSpeed_Input - Memory Real - User Input AnalogSerial_Input - Memory Message - User Input String

Analog Example WhereExpr = "Speed = " + text(Speed_Input,"#.##");

Tip Because Speed_Input is a number it must be converted to text so it can be concatenated to the where expression string.

String Example WhereExpr = "Ser_No = ‘" +Serial_input + "’";

Tip Because Serial_Input is a string it must have single quotes around the value for example:WhereExpr = “Ser_No=’125gh’”;

String Example using the like statement

WhereExpr = "Ser_No like ‘" + "125%’"

Tip When using Like the % char can be used as a wild card.

String and Analog Example using And

WhereExpr = "Ser_No = ‘" + Serial_input+ "’" + " and " + "Speed = " +text(Speed_Input,"#.##");OrderByExpr = "";

Tip If the order does not matter, use a null string as shown above.

SQLSelect using WhereExpr tagname

ResultCode =SQLSelect(Connect_Id,TableName,BindList,

WhereExpr,OrderByExpr);

Error_msg = SQLErrorMsg( ResultCode );

SQLSelect WhereExpr built in function

ResultCode =SQLSelect(Connect_Id,TableName,BindList,

“Ser_No = ‘" + Serial_input + "’",OrderByExpr);

Error_msg = SQLErrorMsg( ResultCode );

Always call the SQLEnd(Connect_Id) function when the SQLSelect() has been completed. If the SQLEnd() function is not called the resources will not be released and your application will run out of memory.



OrderByExpression Defines the columns and direction for sorting. Only column names can be used to sort and the expression must be in this form:

ColumnName [ASC|DESC]

The following example will sort the selected table by the manager column in ascending order:

"manager ASC"

You can also sort by multi-columns where the expression is in the form:

ColumnName [ASC|DESC],ColumnName [ASC|DESC]

The next example will sort the selected table by the temperature column in ascending order and the time column in descending order:

"temperature ASC, time DESC"Example(s) The following statement records from the table BATCH using a BindList

named List1, whose column name type contains cookie. It will present the information sorted by the amount column in ascending order and the sugar column in descending order:

ResultCode=SQLSelect(ConnectionID,"BATCH","List1","type='cookie'","amount ASC, sugar DESC");

The following statement selects all of the data in the database, do not specify a value for the WhereExpression and OrderByExpression:

ResultCode=SQLSelect(ConnectionID,"BATCH","List1","","");

See Also SQLFirst(), SQLConnect(), SQLLast(), SQLNext(), SQLPrev(), SQLEnd(), SQLSelect()


284 Chapter 3

SQLSetParamChar()

SQLSetParamDate()

SQLSetParamDateTime()

Sets the value of the specified parameter to the specified string. SQLSetParamChar() function may be call multiple times before executing, resulting in the parameter value being set to the concatenation of all values sent. Lengths of 0 (zero) are ignored.

Category SQLSyntax [ResultCode=]SQLSetParamChar(SQLHandle,ParameterNumber,

ParameterValue,MaxLen);


SQLPrepareStatement() function is used.ParameterNumber Actual parameter number in the statement.ParameterValue Actual value to set.MaxLen Maximum size of the column with which this

parameter is associated. This setting determines whether the parameter is of varying character or long varying character type. If MaxLen is less than or equal to the largest character string allowed by the database, then the parameter is varying character type. If greater, long varying character type.

Example(s) ResultCode=SQLSetParamChar(SQLHandle,ParameterNumber,ParameterValue,MaxLen);

See Also SQLPrepareStatement()

Sets the value of the specified date parameter to the specified string.Category SQLSyntax [ResultCode=]SQLSetParamDate(SQLHandle,ParameterNumber,

ParameterValue);


SQLPrepareStatement() function is used.ParameterNumber Actual parameter number in the statement.ParameterValue Actual value to set.

Example(s) ResultCode=SQLSetParamDate(SQLHandle,ParameterNumber,ParameterValue);


Sets the value of the specified date-time parameter to the specified string.Category SQL



Syntax [ResultCode=]SQLSetParamDateTime(SQLHandle,ParameterNumber,ParameterValue,Precision);


SQLPrepareStatement() function is used.ParameterNumber Actual parameter number in the statement.ParameterValue Actual value to set.Precision The length of the date-time value to be assigned. It

is the number of characters in ParameterValue to use.

Example(s) ResultCode=SQLSetParamDateTime(SQLHandle,ParameterNumber,ParameterValue,Precision);



286 Chapter 3

SQLSetParamDecimal()

SQLSetParamFloat()

SQLSetParamInt()

Sets the value of the specified decimal parameter to the specified string. Precision is the number of digits in the value and Scale is the number of digits to the right of the decimal point.

Category SQLSyntax [ResultCode=]SQLSetParamDecimal(SQLHandle,

ParameterNumber,ParameterValue,Precision,Scale);


SQLPrepareStatement() function is used.ParameterNumber Actual parameter number in the statement.ParameterValue Actual value to set.Precision The length of the date-time value to be assigned. It

is the number of characters in ParameterValue to use.

Scale Number of digits to the right of decimal point.Example(s) ResultCode=SQLSetParamDecimal(SQLHandle,

ParameterNumber,ParameterValue,Precision, Scale);


Sets the value of the specified parameter to the specified ParameterValue.Category SQLSyntax [ResultCode=]SQLSetParamFloat(SQLHandle,

ParameterNumber,ParameterValue);



Example(s) ResultCode=SQLSetParamFloat(SQLHandle,ParameterNumber,ParameterValue);


Sets the value of the specified parameter to the specified ParameterValue.Category SQLSyntax [ResultCode=]SQLSetParamInt(SQLHandle,ParameterNumber,

ParameterValue);





Example(s) ResultCode=SQLSetParamInt(SQLHandle,ParameterNumber,ParameterValue);



288 Chapter 3

SQLSetParamLong()

SQLSetParamNull()

Sets the value of the specified parameter to the specified ParameterValue.Category SQLSyntax [ResultCode=]SQLSetParamLong(SQLHandle,ParameterNumber,

ParameterValue);



Example(s) ResultCode=SQLSetParamLong(SQLHandle,ParameterNumber,ParameterValue);


Sets the value of the specified parameter to the NULL.Category SQLSyntax [ResultCode=]SQLSetParamNull(SQLHandle,ParameterNumber,

ParameterType,Precision,Scale);




SQLPrepareStatement() function is used.ParameterNumber Actual parameter number in the statement.ParameterType Data type of the specified parameter:

Type DescriptionChar Blank Padded fixed

length stringVar Char Variable Length StringDecimal BCD NumberInteger 4-byte Signed integerSmall integer 2-byte signed integerFloat 4-byte floating pointDouble Precision Float

8-byte floating point

DateTime 4-byte date time valueDate 2-byte date time valueTime 2-byte date time valueNo Type No Data Type

Precision Decimal value's precision, the max. size of the char., or the length in bytes of the date-time value.

Scale Decimal value's scale. This value is required only if applicable to the parameter being set to null.

Remarks No type may be used if a call to SQLSetParam has already been done on this parameter.

Example(s) ResultCode=SQLSetParamNull(SQLHandle,ParameterNumber,ParameterType,Precision,Scale);



290 Chapter 3

SQLSetParamTime()

SQLSetStatement()

Sets the value of the specified time parameter to the specified string.Category SQLSyntax [ResultCode=]SQLSetParamTime(SQLHandle,ParameterNumber,

ParameterValue);



Example(s) ResultCode=SQLSetParamTime(SQLHandle,ParameterNumber,ParameterValue);


Starts a SQL statement buffer using the contents of SQLStatement, on the established connection, ConnectionID. There can be one SQL Statement buffer per ConnectionID. Errors are returned in the function return.

Category SQLSyntax [ResultCode=]SQLSetStatement(ConnectionID,SQLStatement)

;



SQLStatement Actual statement, see the following example.



Example(s) ResultCode=SQLSetStatement(ConnectionID,"Select LotNo,LotName from LotInfo");

In the example below the SQLHandle is set to zero so the statement does not have to call SQLPrepare(Connect_Id, SQLHandle) before the execute statement. Because the SQLHandle was not created by the SQLPrepare to properly end this select use the SQLEnd function instead of the SQLClearStatement().

SQLSetStatement( Connect_Id, “Select Speed, Ser_Nofrom tablename where Ser_No =’” + Serial_input +“’”);

SQLExceute(Connect_Id,0);

In the example below the SQLHandle is created by the SQLPrepareStatement and used in the SQLExceute function. To end this select statement use SQLClearStatement to free up resources and free the SQLHandle.


SQLPrepareStatement(Connect_Id,SQlHandle);

SQLExceute(Connect_Id,SqlHandle);


SQLPrepareStatement(Connect_Id,SQlHandle);

SQLExceute(Connect_Id,SqlHandle);



292 Chapter 3

SQLTransact()

SQLUpdate()

The SQLTransact() command defines the beginning of a group of transaction commands. The group of commands performed between the SQLTransact() command and the SQLCommit() command is called a transaction set. A transaction set is handled like a single transaction. After the SQLTransact() command is issued, all subsequent operations will not be committed to the database until the SQLCommit() command is issued.

Category SQLSyntax [ResultCode=]SQLTransact(ConnectionID);



Note Exercise caution when writing QuickScripts that include the SQLTransact() command. Since the processing time is multiplied by the number of commands in a transaction set, including numerous commands will significantly slow performance.

See Also SQLCommit(), SQLRollback()

Modifies a record to update the record with the current tagname values.Category SQLSyntax [ResultCode=]SQLUpdate(ConnectionID,TableName,BindList,

WhereExpr);






which database columns they are associated with.WhereExpression Defines a condition that can be either true or false

for any row of the table. The function extracts only those rows from the table for which the condition is true. The expression must be in the following format:

ColumnName comparison_operator expression.

Note If the column is a character data type, the expression must be in single quotes.

The following example will select all rows whose name column contains the value EmployeeID:

name='EmployeeID'




temperature>350

Example(s) The following statement updates all records in the table BATCH, whose lot number is 65, to the current values of the tagnames specified in the BindList "List1":

ResultCode=SQLUpdate(ConnectionID,"BATCH","List1","lotno=65");

Note Be sure that all records are unique. If identical records exist in a table, both will be updated.



294 Chapter 3

SQLUpdateCurrent()

Sqrt()

Takes the currently selected record and updates it with any new InTouch values. The following example will update the currently selected record.

Category SQLSyntax [ResultCode=]SQLUpdateCurrent(ConnectionID);



Example(s) ResultCode=SQLUpdateCurrent(ConnectionID);


Causes InTouch to automatically calculate the square root of the value, which follows the statement.

Category mathSyntax RealResult=Sqrt(Number);


Example(s) AnalogTag1=Sqrt(AnalogTag2);



StartAppAutomatically starts another Windows application.

Category systemSyntax StartApp "AppName";

Parameter DescriptionAppName Actual program name of the application to be started,

for example, Wordpad.exe.It is recommended that the .EXE extension of the program name be entered. Command line parameters may also be entered, if the executable supports them.

Long file names do not work. However, using the following example using the DOS equivalent for a long file name will work.

If the long file name is:C:\Program files\Microsoft Office\Office\Excel. Use C:\Progra~1\Micros~2\Office\Excel (Dos equivalent).StartApp "C:\Progra~1\Micros~2\Office\Excel";

If Winfile is used and all file details are shown the center column in the window will show the Dos equivalent file path.

Example(s) The following statement starts the Microsoft Windows Wordpad program.StartApp "Wordpad.exe";

See Also ActivateApp()


296 Chapter 3

StringASCII()Returns the ASCII value of the first character in a specified Message tagname.

Category stringSyntax IntegerResult=StringASCII("Char");

Parameter DescriptionChar Alphanumeric character or Message tagname.

Remarks The ASCII value of the first character in Char will be returned to IntegerResult. When this function is processed, only the single character is tested or affected. If the Message tagname provided to StringASCII contains more than one character, only the first character of the tagname will be tested.

Example(s) StringASCII("A") will return 65

StringASCII("A Mixer is Running") will return 65

StringASCII("a mixer is running") will return 97

See Also StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringChar()Returns the character corresponding to a specified ASCII code.

Category stringSyntax MessageResult=StringChar(ASCII);

Parameter DescriptionASCII ASCII code or Integer tagname.

Remarks The ASCII character specified by ASCII is returned to MessageResult. One use of this function may be to add ASCII characters not normally represented on the keyboard to Message tagnames.

Example(s) ControlString=MessageTag+StringChar(13)+StringChar(10);

A [Carriage Return (13)] and [Line Feed (10)] have been added to the end of MessageTag and passed to ControlString. Inserting characters out of the normal 32-126 range of displayable ASCII characters can be very useful for creating control codes for external devices such as printers or modems.A common use of this function is for SQL commands. The where expression sometimes requires double quotes around string values, so StringChar(34) is used.

See Also StringASCII(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


298 Chapter 3

StringFromIntg()Converts an integer value into its string representation in another base.

Category stringSyntax MessageResult=StringFromIntg(Number,Base);

Parameter DescriptionNumber Number to convert. Any number or Integer tagname.Base Base to use in conversion. Any number or Integer

tagname.Remarks Integer is converted to the Base specified and the result is stored in

MessageResult.Example(s) StringFromIntg(26, 2) will return "11010"

StringFromIntg(26, 8) will return "32"

StringFromIntg(26, 16) will return "1A"

See Also StringASCII(), StringChar(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringFromReal()Converts a real value into its string representation, either as a floating-point number or in exponential notation.

Category stringSyntax MessageResult=StringFromReal(Number,Precision,"Type");

Parameter DescriptionNumber Is converted to the Precision and Type specified and

the result is stored in Message Result. Number or Real tagname.

Precision Specifies how many decimal places will be shown. Any number or Integer tagname.

Type Determines the display method:Type Description"f" Display in floating-point notation."e" Display in exponential notation with a

lower-case "e.""E" Display in exponential notation with an

upper-case "E."Example(s) StringFromReal(263.355, 2,"f") will return "263.36"

StringFromReal(263.355, 2,"e") will return "2.63e2"

StringFromReal(263.55, 3,"E") will return "2.636E2"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


300 Chapter 3

StringFromTime()Converts a time value (in seconds since Jan-01-1970) into a particular string representation. The time value should be UTC equivalent (number of seconds since Jan-01-1970 GMT). The value returned reflects the local time.

Category stringSyntax MessageResult=StringFromTime

(SecsSince1-1-70,StringType);

Parameter DescriptionSecsSince1-1-70 Is converted to the StringType specified and the result

is stored in MessageResult. StringType Determines the display method:

Type Description1 Displays the date in the same format set

from the windows control Panel. (Similar to that displayed for $DateString.)

2 Displays the time in the same format set from the Windows control Panel. (Similar to that displayed for $TimeString.)

3 Displays a 24-character string indicating both the date and time: "Wed Jan 02 02:03:55 1993"

4 Displays the short form for the day of the week: "Wed"

5 Displays the long form for the day of the week: "Wednesday"

Example(s) StringFromTime(86400, 1) will return "1/2/70"

StringFromTime(86400, 2) will return "12:00:00 AM"

StringFromTime(86400, 3) will return "Fri Jan 0200:00:00 1970"

StringFromTime(86400, 4) will return "Fri"

StringFromTime(86400, 5) will return "Friday"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringFromTimeLocal()Converts a time value (in seconds since Jan-01-1970) into a particular string representation. The value returned reflects Local time.

Category stringSyntax MessageResult=StringFromTimeLocal(SecsSince1-1-70,

StringType);

Parameter DescriptionSecsSince1-1-70 Is converted to the StringType specified and the result

is stored in MessageResult. StringType Determines the display method:

Type Description1 Displays the date in the same format set

from the windows control Panel. (Similar to that displayed for $DateString.)

2 Displays the time in the same format set from the Windows control Panel. (Similar to that displayed for $TimeString.)

3 Displays a 24-character string indicating both the date and time: "Wed Jan 02 02:03:55 1993"

4 Displays the short form for the day of the week: "Wed"

5 Displays the long form for the day of the week: "Wednesday"

Example(s) StringFromTimeLocal(86400, 1) will return "1/2/70"

StringFromTimeLocal (86400, 2) will return "12:00:00 AM"

StringFromTimeLocal (86400, 3) will return "Fri Jan 0200:00:00 1970"

StringFromTimeLocal (86400, 4) will return "Fri"

StringFromTimeLocal (86400, 5) will return "Friday"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


302 Chapter 3

StringInString()Returns the position in Text where SearchFor first occurs.

Category stringSyntax IntegerResult=StringInString("Text","SearchFor",

StartPos,CaseSens);

Parameter DescriptionText Is searched for occurrences of SearchFor. If multiple

occurrences of SearchFor are found, the location of the first one will be returned to IntegerTag. Actual string or Message tagname.

SearchFor The string to be searched for in Text. Actual string or Message tagname.

StartPos An integer that determines where in Text the search will begin. Any number or Integer tagname.

CaseSens Parameter determines whether the search will be case sensitive (0=no and 1=yes). Any number or Integer tagname.

Example(s) StringInString("The mixer is running", "mix", 1, 0)will return 5

StringInString("Today is Thursday", "day", 1, 0)will return 3

StringInString("Today is Thursday", "day", 10, 0)will return 15

StringInString("Today is Veteran's Day", "Day", 1, 1)will return 20

StringInString("Today is Veteran's Day", "Night", 1, 1)will return 0

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringLeft()Returns the number of characters specified by Chars starting with the leftmost character of text.

Category stringSyntax MessageResult=StringLeft("Text",Chars);

Parameter DescriptionText Actual string or Message tagnameChars Number of characters to return or Integer tagname.

Remarks If Chars is set to 0, the entire string will be returned.Example(s) StringLeft("The Control Pump is On", 3) will return

"The"

StringLeft("Pump 01 is On", 4) will return"Pump"

StringLeft("Pump 01 is On", 96) will return"Pump 01 is On"

StringLeft("The Control Pump is On", 0) will return"The Control Pump is On"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringInString(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


304 Chapter 3

StringLen()

StringLower()

Returns the length of text to integer result.Category stringSyntax IntegerResult=StringLen("Text");

Parameter DescriptionText Actual string or a Message tagname

Remarks The length (in characters) of Text returned to IntegerTag. All the characters in the Message tagname, including those not normally displayed on the screen are counted.

Example(s) StringLen("Twelve percent") will return 14

StringLen("12%") will return 3

StringLen("The end." + StringChar(13)) will return 9

The carriage return character is ASCII 13.See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(),

StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()

Converts all the uppercase characters in text to lower case, and places the resulting string in MessageResult.

Category stringSyntax MessageResult=StringLower("Text");

Parameter DescriptionText String to be converted to lower case. Actual

string or a Message tagname.Remarks Lower case characters, symbols, numbers and other special characters will

not be affected. Example(s) StringLower("TURBINE") will return "turbine"

StringLower("22.2 Is The Value") will return"22.2 is the value."

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringMid()Extract from text the specific number of characters specified by Chars, starting at the position StartChar. This function is slightly different from its counterparts StringLeft() function and StringRight() function in that it allows the user to specify both the start and end of the string which is to be extracted from the Message tagname.

Category stringSyntax MessageResult=StringMid("Text",StartChar,Chars);

Parameter DescriptionText Actual string or a Message tagname StartChar Specifies the position of the first character to extract.

Any number or Integer tagname.Chars Specifies the total number of characters to return.

Any number or Integer tagname.Example(s) StringMid("The Furnace is Overheating",5,7,) will return

"Furnace"

StringMid("The Furnace is Overheating",13,3) will return"is "

StringMid("The Furnace is Overheating",16,50) willreturn"Overheating"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


306 Chapter 3

StringReplace()Replaces or changes specific parts of a provided string. Using this function can take a string tagname and replace characters, words or phrases.

Category stringSyntax MessageResult=StringReplace(Text,SearchFor,ReplaceWith,

CaseSens,NumToReplace,MatchWholeWords);

Parameter DescriptionText The string that you wish to change. Actual string or

Message tagname.SearchFor The string you wish to search for and replace. Actual

string or Message tagname.ReplaceWith The replacement string. Actual string or Message

tagname.CaseSens Determines whether the search will be case sensitive.

(0=no and 1=yes) Any number or Integer tagname.NumToReplace Determines the number of occurrences you wish to

replace. (-1=all) Any number or Integer tagname.MatchWholeWords Determines whether the function will limit its

replacement to whole words. (0=no and 1=yes) Any number or Integer tagname.If MatchWholeWords is turned on (set to 1) and the SearchFor is set to "and", the "and" in "handle" would not be replaced. If the MatchWholeWords is turned off (set to 0), it would be replaced.

Example(s) StringReplace("In From Within","In","Out",0,1,0) returns"Out From Within" (replaces only the first one)

StringReplace("In From Within","In","Out",0,-1,0)returns"Out From without" (replaces all occurrences)

StringReplace("In From Within","In","Out",1,-1,0)returns"Out From Within" (replaces all that match case)

StringReplace("In From Within","In","Out",0,-1,1)returns"Out From Within" (replaces all that are whole words)

The StringReplace() function does not recognize special characters, such as @#$%&*(). It reads them as delimiters. For example, if the function StringReplace() (abc#,abc#,1234,0,1,1) is processed, there will be no replacement. The # sign is read as a delimiter instead of a character.

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringRight()Returns the number of characters specified by Chars starting at the rightmost character of text.

Category stringSyntax MessageResult=StringRight("Text",Chars);

Parameter DescriptionText Actual string or Message tagname. Chars The number of characters to return or Integer

tagname.Remarks If Chars is set to 0, the entire string will be returned.Example(s) StringRight("The Pump is On", 2) will return

"On"

StringRight("The Pump is On", 5) will return"is On"

StringRight("The Pump is On", 87) will return"The Pump is On"

StringRight("The Pump is On", 0) will return"The Pump is On"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


308 Chapter 3

StringSpace()Generates a string of spaces either within a Message tagname or within an expression.

Category stringSyntax MessageResult=StringSpace(NumSpaces);

Parameter DescriptionNumSpaces Number of spaces to return. Any number or Integer

tagname.Remarks StringSpace() function returns a string of spaces of a length specified by

NumSpaces.Example(s) All spaces are represented by the "×" character:

StringSpace(4) will return "××××"

"Pump" + StringSpace(1) + "Station" will return"Pump×Station"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()



StringTest()Tests the first character of text to determine whether it is of a certain type.

Category stringSyntax DiscreteResult=StringTest("Text",TestType)

Parameter DescriptionText String that function will act on. Actual string or

Message tagname.TestType Determines one of the following:

Type Description1 Alphanumeric character ('A'-'Z', 'a-z'

and '0-9')2 Numeric character ('0'- 9')3 Alphabetic character ('A-Z' and 'a-z')4 Upper-case character ('A'-'Z')5 Lower-case character ('a'-'z')6 Punctuation character (0x21-0x2F)7 ASCII characters (0x00 - 0x7F)8 Hexadecimal characters ('A'-'F' or 'a'-'f'

or '0'-'9')9 Printable character (0x20-0x7E)10 Control character (0x00-0x1F or 0x7F)11 White Space characters (0x09-0x0D or

0x20)Remarks StringTest() function will return a positive value to DiscreteResult if the

first character in Text is of the type specified by TestType. If the StringTest() function contains more than one character, only the first character of the tagname will be tested.

Example(s) StringTest("ACB123",1) will return 1

StringTest("ABC123",5) will return 0

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringToIntg(), StringToReal(), StringTrim(), StringUpper(), Text()


310 Chapter 3

StringToIntg()Converts the numeric value of a Message tagname to an integer value to which mathematical calculations can be applied.

Category stringSyntax IntegerResult=StringToIntg("Text");


Message tagname.Remarks When this statement is evaluated, the system reads the first character of the

string for a numeric value. If the first character is other than a number (blank spaces are ignored), the string's value is equated to zero (0). If the first character is found to be a number, the system continues to read the subsequent characters until a non-numeric value is seen.

Example(s) If Text="ABCD", then IntegerTag=0.

If Text="22.2 is the Value", then IntegerTag=22 (sinceintegers are whole numbers).

If Text="The Value is 22", then IntegerTag=0.

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToReal(), StringTrim(), StringUpper(), Text()



StringToReal()Converts the numeric value of a Message tagname to a real (floating point) value to which mathematical calculations can be applied.

Category stringSyntax RealResult=StringToReal("Text");


Message tagname.Remarks When this statement is evaluated, the system reads the first character of the

string for a numeric value. If the first character is other than a number (blank spaces are ignored), the string's value is equated to zero (0). If the first character is found to be a number, the system continues to read the subsequent characters until a non-numeric value is seen.

Example(s) If Text="ABCD", then RealTag=0.

If Text="22.261 is the Value", then RealTag=22.261.

If Text="The Value is 22", then RealTag=0.

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringTrim(), StringUpper(), Text()


312 Chapter 3

StringTrim()Removes unwanted spaces from text.

Category stringSyntax MessageResult=StringTrim("Text",TrimType);

Parameter DescriptionText String that will be trimmed of spaces. Actual string or

Message tagname.TrimType Determines one of the following:

Type Description1 Remove leading spaces (left of the first

non-space character)2 Remove trailing spaces (right of the last

non-space character)3 Remove all spaces except for single

spaces between wordsRemarks Text is searched for white-spaces (ASCII 0x09-0x0D or 0x20) which are to

be removed. TrimType determines the method used by the function:Example(s) All spaces are represented by the "×" character.

StringTrim("×××××This×is×a××test×××××", 1) will return"This×is×a××test×××××"

StringTrim("×××××This×is×a××test×××××", 2) will return"×××××This×is×a××test"

StringTrim("×××××This×is×a××test×××××", 3) will return"This×is×a×test"

The StringReplace() function can be used to remove ALL spaces from a specified Message tagname. Simply replace all the space characters with a "null."

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringUpper(), Text()



StringUpper()

Tan()

Converts all the lowercase characters in text to uppercase.Category stringSyntax MessageResult=StringUpper("Text");

Parameter DescriptionText String to be converted to uppercase. Actual string

or Message tagname.Remarks Upper case characters, symbols, numbers and other special characters will

not be affected. Example(s) StringUpper("abcd") will return "ABCD."

StringUpper("22.2 is the value") will return "22.2 ISTHE VALUE"

See Also StringASCII(), StringChar(), StringFromIntg(), StringFromReal(), StringFromTime(), StringFromTimeLocal(), StringInString(), StringLeft(), StringLen(), StringLower(), StringMid(), StringReplace(), StringRight(), StringSpace(), StringTest(), StringToIntg(), StringToReal(), StringTrim(), Text()

Returns the tangent of an angle given in degrees.Category mathSyntax Result=Tan(AngleNumber);

Parameter DescriptionAngleNumber The angle in degrees. Any number, Real or Integer

tagname.Example(s) Wave = 10 + 50 * Tan(6 * $Second);

Tan(45) will return 1Tan(0) will return 0

See Also Cos(), Sin(), ArcCos(), ArcSin(), ArcTan()


314 Chapter 3

Text()

Trunc()

Causes a message type tagname to display the value of an Analog (Integer or Real) tagname based upon the specified Format_Text.

Category stringSyntax MessageResult=Text(Analog_Tag,"Format_Text");

Parameter DescriptionAnalog_Tag Any number, or, Real or Integer tagname to convert.Format_Text Format to use in conversion. Actual string or

Message tagname.Example(s) MessageTag=Text(Analog_Tag,"#.00");

MessageTag is a message type tagname, 66 is either an Integer or Real tagname and "#0.00" represents the display format for the equated value:If Analog_Tag=66, then MessageTag=66.00.

If Analog_Tag=22.269, then MessageTag=22.27.

If Analog_Tag=9.999, then MessageTag=10.00.

LogMessage("The current value of FreezerRoomTemp is:" +Text (FreezerRoomTemp, "#.#"));

In the following example, MessageTag will be set to "One=1 Two=2".MessageTag = "One + " + Text(1,"#") + StringChar(32) +"Two +" + Text(2,"#");

See Also StringFromIntg(), StringToIntg(), StringFromReal(), StringToReal()

Truncates a real (floating point) number by simply eliminating the portion to the right of the decimal point.

Category mathSyntax ResultNumericTag=Trunc(Number);


Remarks This function will accomplish the same result as placing the contents of a Real tagname into an Integer tagname.

Example(s) Trunc(4.3) will return 4

Trunc(-4.3) will return -4

See Also Round()



TseGetClientId()

TseQueryRunningOnConsole()

Returns a string version of the client ID (the TC/IP address of the client) if the View application is running on a Terminal server client. Otherwise, it returns an empty string.

Category Terminal ServicesSyntax MessageResult=TseGetClientId();

Parameter DescriptionMessageResult A message type tagname that displays the client ID.

Remarks This ID is used internally to generate SuiteLink server names and logger file names.

Example MsgTag=TseGetClientID();

Client IP Address, for example, 10.103.202.1 would be returned to MsgTag.

Returns a non-zero integer value if the View application is running on a Terminal server console. Otherwise, it returns a value of zero (0).

Category Terminal ServicesSyntax Result=TseQueryRunningOnConsole();

Parameter DescriptionResult Returns 0 if View is not running on a TS console.

Remarks NoneExample IntTag=TseQueryRunningOnConsole();

Returns IntTag=1 if View is running on a Terminal Server console.


316 Chapter 3

TseQueryRunningOnClient()

wcAddItem()

Returns a non-zero integer value if the View application is running on a Terminal server client. Otherwise, it returns a value of zero (0).

Category Terminal ServicesSyntax Result=TseQueryRunningOnClient();

Parameter DescriptionResult Returns 0 if View is not running on a TS client.

Remarks NoneExample IntTag=TseQueryRunningOnClient();

Returns IntTag=1 if View is running on a Terminal Server client.

Adds the supplied string to the List box or Combo box. If the List box or Combo box was not created as sorted, the string is added to the end of the list. Otherwise the string is inserted into the list and the list is sorted.

Category windows controlSyntax [ErrorNumber=]wcAddItem("ControlName","MessageTag");

Parameter DescriptionControlName The name of the windows control object. For

example, ListBox_1. Actual string or Message tagname.

MessageTag The message string to be displayed. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement adds the contents of the message string to the List

box when the window (using On Show Window QuickScript) containing the List box is opened:wcAddItem("ListBox_1", "Chocolate");

wcAddItem("ListBox_1", "Vanilla");

wcAddItem("ListBox_1", "Strawberry");

See Also wcInsertItem()



wcClear()

wcDeleteItem()

Removes all items from the List box or Combo box.Category windows controlSyntax [ErrorNumber=]wcClear("ControlName");



Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement clears all items in a Combo box when a Touch

Pushbutton Action QuickScript is executed:wcClear("ListBox_1");

Deletes the item associated with the item index argument in both List and Combo boxes.

Category windows controlSyntax [ErrorNumber=]wcDeleteItem("ControlName",ItemIndex);



ItemIndex A number corresponding to the position of the item. Any number or Integer tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement deletes the 3rd item in a list when a Touch

Pushbutton Action QuickScript is executed:wcDeleteItem("ListBox_1", 3);


318 Chapter 3

wcDeleteSelection()Deletes the currently selected item from the list.

Category windows controlSyntax [ErrorNumber =]wcDeleteSelection("ControlName");



Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement deletes the currently selected item in a Combo box

list when a Touch Pushbutton Action QuickScript is executed:wcDeleteSelection("ListBox_1");



wcErrorMessage()Returns a message string describing the error.

Category windows controlSyntax ErrorMessage=wcErrorMessage(ErrorNumber);

Parameter DescriptionErrorMessage Message tagname.ErrorNumber Number returned by all windows control functions.

Any number or Integer tagname.Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes, Text boxes, Combo boxes, Check boxes and Radio buttons.Example(s) If an error occurs while a list is being loaded, display the text description of

the error into the Message tagname ErrorDescription. In this example, a String Value Output animation link was assigned to the tagname ErrorDescription to display the error message.On Show Window QuickScript:ErrorNumber=wcLoadList("ListBox_1","c:\InTouch\recipe.txt");

ErrorDescription=wcErrorMessage(errornumber);

This function can also be used with all windows control functions to display error messages:ErrorNumber=wcAddItem("ListBox_1","United States");

ErrorMsg=wcErrorMessage(ErrorNumber);


320 Chapter 3

wcFindItem()Determines the corresponding index of the first item in the List box or Combo box that matches the supplied Message string.

Category windows controlSyntax [ErrorNumber=]wcFindItem

("ControlName","MessageTag",DiscreteTag,Tagname);



MessageTag The message string to be compared. Actual string or Message tagname.

DiscreteTag Determines the type of the string comparison. One of the following discrete values can be assigned:0=case-insensitive1=case-sensitive

Tagname Actual name of an Integer tagname.Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes, Text boxes, Combo boxes, Check boxes and Radio buttons.Example(s) If an error occurs while a list is being loaded, display the text description of

the error into the Message tagname ErrorDescription. In this example, a String Value Output animation link was assigned to the tagname ErrorDescription to display the error message.



wcGetItem()Returns the value property of the item string associated with the corresponding ItemIndex in the List box or Combo box.

Category windows controlSyntax [ErrorNumber=]wcGetItem("ControlName",ItemIndex,

Tagname);




Tagname Actual name of a Real or Integer tagname. The wcGetItem function will place the numeric value corresponding to the item, into this tagname upon return from the function.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement returns the string value of the 10th item in a

Combo box to the Message tagname ListSelection when a Touch Pushbutton Action QuickScript is executed:wcGetItem("Combobox_1", 10, ListSelection);

If item 10 in the list is "Vanilla" then ListSelection will contain the string Vanilla.


322 Chapter 3

wcGetItemData()Determines the integer value associated with the list item identified by the parameter ItemIndex.

Category windows controlSyntax [ErrorNumber=]wcGetItemData("ControlName",ItemIndex,

Tagname);




Tagname Actual name of a Real or Integer tagname. The wcGetItemData function will place the numeric value corresponding to the item into this tagname upon return from the function.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement retrieves the numeric value associated with the 5th

item in a List box and returns it to the Integer tagname ItemValue when an InTouch Pushbutton Action QuickScript is executed:wcGetItemData("ListBox_1", 5, ItemValue);

If the 5th item in the list is assigned the integer value 4500, the tagname ItemValue will contain 4500.

See Also wcSetItemData()



wcInsertItem()Inserts the Message string into the list. ItemIndex is the corresponding index number of the position in the List box that will receive the string. Unlike wcAddItem(), wcInsertItem() will not sort a list, even if it was created as a sorted List box or Combo box.

Category windows controlSyntax [ErrorNumber=]wcInsertItem("ControlName",ItemIndex,

"MessageTag");



ItemIndex A number corresponding to the position of the item to be added. If this parameter is -1, the string is added to the end of the list. Any number or Integer tagname.

MessageTag Contains the string to insert at the position indicated by ItemIndex. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement inserts a new item called "Blueberry" into a List

box at 4th location from the top when a Touch Pushbutton Action QuickScript is executed.wcInsertItem("ListBox_1", 4, "Blueberry");

See Also wcAddItem()


324 Chapter 3

wcLoadList()Replaces the contents of the List box or Combo box with the items contained in the FileName.

Category windows controlSyntax [ErrorNumber=]wcLoadList("ControlName","Filename");



Filename Contains the name of a file in pure ASCII format. If a complete path name is not supplied as part of the message parameter, the function will check the application directory for the message file. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement loads a properly formatted list (located in

c:\InTouch.32\wclist.txt.) into a Combo box when the window (On Show Window QuickScript) containing the Combo box is opened:wcLoadList("Combobox_1", "c:\InTouch.32\wclist.txt");

See Also wcAddItem(), wcSaveList()



wcLoadText()Replaces the contents of the Text box with the contents of the FileName.

Category windows controlSyntax [ErrorNumber=]wcLoadText("ControlName", "Filename");



Filename Contains the name of a file in pure ASCII format. If a complete path name is not supplied as part of the message parameter, the function will check the application directory for the message file. Actual string or Message tagname.

Remarks The wcLoadText() function only supports pure ASCII files such as those created using Microsoft's Notepad program.

For a list of returned error numbers, see APPENDIX A.For advanced file viewing capabilities see the document viewer from the FactorySuite's Productivity Pack.

Applies To Text boxes.Example(s) The following statement loads a Notepad text file

(c:\InTouch.32\readme.txt.) into a Text box when the window (On Show Window QuickScript) containing the Text box is opened:wcLoadText("Textbox_1", "c:\InTouch.32\readme.txt");


326 Chapter 3

wcSaveList()Replaces the contents of the FileName with the items listed in the List box or Combo box object.

Category windows controlSyntax [ErrorNumber=]wcSaveList("ControlName","Filename");



Filename Contains the name of a file in pure ASCII format. If the file does not exist, it is created. The items can subsequently be loaded into the list object with the wcLoadList() function. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To List boxes and Combo boxes.Example(s) The following statement saves the current items in a List box in a file

(c:\InTouch.32\newlist.txt) when a Touch Pushbutton Action QuickScript is executed:wcSaveList("ListBox_1", "c:\InTouch.32\newlist.txt");

If external ASCII files are used to fill the List and Combo boxes they must follow specific formatting and contain specific information. Format:ControlType, ListCountListItem, ItemDataListItem, ItemData : : : :ListItem, ItemDataFor example: A list file is to be loaded to a Combo box and it contains three items to choose from and those items have no item data assigned (refer to the function wcSetItemData() function for more information on item data). The format of the file would appear as:COMBOBOX, 3Chocolate, 0Vanilla, 0Strawberry, 0Description: COMBOBOX is the control type. The ListCount is 3 for Chocolate, Vanilla, and Strawberry it's 3 items. Chocolate is then listed as the first ListItem or index 1. Vanilla as index 2, and finally Strawberry as 3. Each of these index items has a data value of 0.

See Also wcLoadList(), wcSetItemData()



wcSaveText()Saves the text contained in the Text box to FileName. If the file doesn't exist, it will be created. If it does exist, it must be read/write.

Category windows controlSyntax [ErrorNumber=]wcSaveText("ControlName","Filename");



Filename Contains the name of a file in pure ASCII format. If a complete path name is not supplied the function will be saved in the application directory. If the file does not exist, it is created. The items can subsequently be loaded into the list object with the wcLoadList() function. Actual string or Message tagname.

Remarks For a list of returned error numbers, see APPENDIX A.Applies To Text boxes.Example(s) The following statement saves the current information entered in a Text

box to a file in c:\InTouch.32\newtext.txt when a Touch Pushbutton Action QuickScript is executed:wcSaveText("Textbox_1", "c:\InTouch.32\newtext.txt");

The wcSaveText() function only saves in a pure ASCII file such as those created using Microsoft's Notepad program.

See Also wcLoadList()


328 Chapter 3

wcSetItemData()Assigns an integer value of the item (Number) to the item in the list specified by ItemIndex. This function allows the assignment of a number to a string.

Category windows controlSyntax [ErrorNumber=]wcSetItemData("ControlName",ItemIndex,

Number);



ItemIndex An integer value specifying the order the requested items are to be displayed. Any number or Integer tagname.

Number An integer value representing the item data. Any number or Integer tagname.

Remarks Complete lists containing the items can be created externally (i.e. notepad) and then loaded using one function call. The list must be properly formatted as shown in the description of the wcSaveList() function.

For a list of returned error numbers, see APPENDIX A.Example(s) A recipe has three ingredients; flour, sugar and salt. The quantity of flour is

4500 grams, sugar is 1500 and salt is 325 grams. The values are assigned to each of the List box items by using a Data Change QuickScript triggered by what Recipe (tagname, RecipeName) is selected:wcSetItemData("ListBox_1", 1, 4500); {set 1st item inthe list (flour)=4500}

wcSetItemData("ListBox_1", 2, 1500); {set 2nd item inthe list (sugar)=1500}

wcSetItemData("ListBox_1", 3, 325); {set 3rd item inthe list (salt)=325}

The wcGetItemData() function is used to return the value (item data) associated with the list item. The parameter Tagname contains the returned numeric value. This parameter could be an I/O Integer tagname that writes directly to the real world device.

See Also wcLoadList(), wcSaveList(), wcGetItemData()



WWControl()Allows you to Restore, Minimize, Maximize, or Close an application from InTouch.

Category miscSyntax WWControl("AppTitle","ControlType");

Parameter DescriptionAppTitle The name of the application title to be controlled. The

application title for a particular application can also be determined using the InfoAppTitle() function. Actual string or Message tagname.

ControlType Determines how the application is controlled as follows (these actions are identical to clicking on their corresponding selections in the application's Control Menu). Actual string or Message tagname.Type Description"Restore" Activates and displays the application's

window."Minimize" Activates a window and displays it as

an icon."Maximize" Activates and displays the application's

window."Close" Closes an application.

Example(s) WWControl("Calculator","Restore");

WWControl(InfoAppTitle("View"), "Close");

See Also InFoAppTitle(), ActivateApp(), StartApp()


330 Chapter 3

WWExecute()Executes a command (using the DDE protocol) to a specified Application and Topic.

Category WWDDESyntax [Status=]WWExecute("Application","Topic","Command");

Parameter DescriptionApplication Application to send an execute command to. Actual

string or Message tagname.Topic Topic within application to send an execute command

to. Actual string or Message tagname.Command Command to send. Actual string or Message

tagname.Remarks The Command string will be sent to the particular Application and Topic

specified. Example(s) The following statement executes a macro in Excel:

Macro="Macro1!TestMacro";

Command="[Run(" + StringChar(34) + Macro +StringChar(34)+ ",0)]";

WWExecute("excel","system",Command);

When WWExecute("excel","system",Command); is processed, the following will be sent to Excel (and TestMacro will run):[Run("Macro1!TestMacro")]

The following QuickScript executes a macro in Microsoft Access:WWExecute("MSAccess","system","MyMacro");

The WWExecute function returns 1 if the application is running, the topic exists, and the command was sent successfully. It returns 0 when the application is busy and -1 when there is an error. Therefore, the status of this command can be monitored: The WWExecute function returns 1 if the application is running, the topic exists, and the command was sent successfully. It returns 0 when the application is busy and -1 when there is an error. Therefore, the status of this command can be monitored:Status=WWExecute("excel","system",Command);

Status is an Integer tagname to which the 1, -1 or 0 will be written.



WWPoke()Pokes a value (using a DDE protocol) to a specified Application, Topic, and Item.

Category WWDDESyntax [Status=]WWPoke("Application","Topic","Item",

"TextValue");

Parameter DescriptionApplication Application to send Poke command to. Actual string

or Message tagname.Topic Topic within application to send Poke command.

Actual string or Message tagname.Item Item within topic to Poke. Actual string or Message

tagname.TextValue A message variable or string. If the value you wish to

send is a number, you can convert it using the Text(), StringFromIntg(), or StringFromReal() functions. Actual string or Message tagname.

Remarks In this statement, the value TextValue will be sent to the particular Application, Topic, and Item specified.

Example(s) The following statement converts a value to text and will poke to an Excel spreadsheet cell:String=Text(Value,"0");

WWPoke("excel","[Book1.xls]sheet1","r1c1",String);

For more information on using Excel 5.0 with InTouch (DDE) see you InTouch User's Guide.The behavior for WWPoke() from within the Application "View" to "View" is undefined and is not supported. The WWPoke() command is not guaranteed to succeed in this instance, and the command will probably time-out without the desired results.The WWPoke() function returns 1 if the application is running, the topic and item exist, and the value was sent successfully. It returns 0 when the application is busy and -1 when there is an error. Therefore, the status of this command can be monitored:Status=WWPoke("excel","[Book1.xls]sheet1","r1c1",String);

Status is an Integer tagname to which the 1, -1 or 0 will be written.See Also Text(), StringFromIntg(), StringFromReal()


332 Chapter 3

WWRequest()Makes a one-time request for a value (using a DDE protocol) from a particular Application, Topic, and Item.

Category WWDDESyntax WWRequest(Application,Topic,Item,ValueMsg_Tag);

Parameter DescriptionApplication Application to Request data from. Actual string or

Message tagname.Topic Topic within application to request data from. Actual

string or Message tagname.Item Item within topic to request data from. Actual string

or Message tagname.ValueMsg_Tag A Message tagname enclosed in quotes, which will

contain the requested value from the Application, Topic, and Item. Actual string or Message tagname.

Remarks In this statement, the DDE value in the particular Application, Topic, and Item will be returned into ValueMsg_Tag. The value will be returned as a string into a Message Tag. If the value is a number, you can then convert it using the StringToIntg() or StringToReal() functions.

Example(s) The following statement requests a value from an Excel spreadsheet cell and convert the resulting string into a value:WWRequest("excel","[Book1.xls]sheet1","r1c1",Result);

Value=StringToReal(Result);

The WWRequest() function returns 1 if the application is running, the topic and item exist, and the value was returned successfully. It returns 0 when the application is busy and -1 when there is an error. Therefore, the status of this command can be monitored:Status=WWRequest("excel","[Book1.xls]sheet1","r1c1",Result);

Status is an Integer tagname to which the 1, -1 or 0 will be written.See Also StringToIntg(), StringToReal()


OLE Automation and InTouch 333

C H A P T E R 4

OLE Automation and InTouch

Microsoft Object Linking and Embedding (OLE) technology supports a wide variety of information exchange and manipulation facilities between client and server. InTouch can act as a client to many of these servers. An InTouch application can be used to inform the server of tagname value changes, allowing the server to perform whatever actions are programmed into it. This functionality can be used to extend the capabilities of InTouch beyond those already built in.

This chapter provides a brief outline of the OLE Automation architecture. Procedures for using OLE Automation through these InTouch extensions are also described. As InTrack is an OLE Automation server, it is used for many of the examples.

Elements of OLE AutomationIn a very simplified form, OLE provides a standardized communications facility between a client and a server.

The automation object component of OLE provides Object Oriented Programming facilities in this client/server environment. The server provides specific computational skills through object classes. The client asserts how the skills are used by creating objects and accessing their members. OLE provides the communication link between the client and server.

To understand automation objects, it is necessary to have a basic understanding of Object Oriented Programming concepts.

• Objects are identifiable and unique entities that can be created based on an object class.

• Classes define a related set of properties (data) and methods (functions). Hence, all objects of the same class have the same set of properties and methods, though each object might have different values for its properties.

InTouch OLE Automation Client ExtensionsInTouch extensions provide easy access to InTrack automation objects using three primary components:


334 Chapter 4

• Eight additional built-in functions have been added to InTouch.

• A unary operator indicates the start of an OLE Automation expression.

• An InTrack OLE Browser provides templates and online Help for all InTrack automation object classes. The Browser is accessed through the InTrack OLE button in the lower right corner of the Script Editor dialogs.

InTouch Automation ExpressionsAll references to automation objects within InTouch start with a percent sign and are followed by a name that identifies the object reference. The name must start with an alpha character and can consist of alpha, numeric and underscore characters. Names are case insensitive and global. Examples of different object names are:

• %ObjectName (or %objectName or %objectname)

• %Lot5

• %lot_5

• %aMachine

• %A_Machine

• %Sublot

Do not confuse object names with InTouch tagnames. You can have an OLE Automation object and an InTouch tag with the same name (except for the percent prefix).

Object ReferencesThese “percent names” are specifically referred to as object references because they are pointers to automation objects. Two different names can access the same object using the following InTouch script statement:%Object1 = %Object2;

After executing this statement both object references “point” to the same automation object.

Object reference names are automatically defined when first used during runtime. They are global—you can initialize them in one script and use them in another script.

As with most object-oriented programming languages, the “dot” operator is supported for referencing the properties and methods of an object. The following example shows the use of the dot operator to set an object property to the value 5:%Object.Property = 5;

OLE_CreateObject OLE_IsObjectValidOLE_GetLastObjectError OLE_ReleaseObjectOLE_GetLastObjectErrorMessage OLE_ResetObjectErrorOLE_IncrementOnObjectError OLE_ShowMessageOnObjectError



Nested Objects (Dot Operators)If objects are members of other objects, the “dot” operator can be used multiple times. Setting the property of a nested object to the value 6 would appear as:%Object.Property_For_Nested_Object.Property = 6;

There are a few specific rules for working with the dot operator:

1. No embedded spaces can be placed within the specification of the object reference and any member references:

• No space between the percent sign and the start of the object reference name.

• No space between the object reference name, the “dot” operator and the name of the class member.

• No space between the property name of a nested object, the “dot” operator and the name of the property of the nested object.

2. The number of characters for the entire specification cannot exceed 98 counting from (and including) the percent sign to the last member reference.

For example, the length of the specification %Object.Property is 16 characters, and the length of the specification %Object.Property_For_Nested_Object.Property is 44 characters.

Data Type Conversions, InTouch to OLENot all InTouch data types are supported by the OLE extensions. The following summarizes the supported data types and data conversions. Note that the conversion occurs at runtime and not in WindowMaker. Hence, the data conversion can cause unexpected results with no error reported.

Integer 32-bit signed value. Converts to the following data types:To Real The value is floated.To Message Standard conversion to a

sequence of decimal digits - possibly prefixed by a minus sign.

To Discrete Converts to TRUE (1) if value is not zero, else FALSE (0).

Real 64-bit resolution. InTouch computes using 64-bit resolution but stores the results in 32-bit resolution tags. The automation object interface works with the higher resolution. Converts to the following data types:To Integer The real value is truncated.To Message Standard conversion to a

sequence of decimal digits and decimal point possibly prefixed by a minus sign.

To Discrete Converts to TRUE (1) if value is not zero, else FALSE (0).


336 Chapter 4

RestrictionsTwo important restrictions apply to InTouch automation object extensions:

• Extensions are available only from within InTouch scripts.

Message A string limited to 131 characters (InTouch constraint). Data conversions are more complex for this data type and are a more likely source of runtime errors.To Integer Same as the InTouch built-in

function StringToIntg. If the string starts with a number (ignoring spaces but including a minus sign) the number is converted. Anything else results in a zero value.

To Real Same as the InTouch built-in function StringToReal. If the string starts with a number (ignoring spaces but including a minus sign) the number is converted. Anything else results in a zero value.

To Discrete Converts to an integer then applies rule to convert an integer to a discrete.

To Object Reference This conversion is needed only in a few very special cases and should be avoided. Misuse of this conversion facility can cause WindowViewer to exit with a fatal error. This conversion will report an error with any input other than a string generated by conversion of an object reference.

Discrete Converts to the following data types:To Integer One if TRUE, else zero.To Real One if TRUE, else zero.To Message “0” for False and “-1” for

True.Object Reference In general, object references should not be used in any

context where data conversion might occur. Converts to the following data types:To Message A specially formatted string

that includes the hexadecimal representation of the object reference.



• The extensions use “late binding”—most errors cannot be identified until the script has been executed.

Creating an Object: OLE_CreateObjectAutomation objects are created via the InTouch built-in system function OLE_CreateObject. The syntax for this function is:OLE_CreateObject(%Object, “className”);

where:

This function has no return value.

Example

For example, to create an object of the InTrack class Sublot the statement would be:OLE_CreateObject(%Sublot, “InTrack.Sublot”);

Misspelling “className” is a frequent error that cannot be identified within WindowMaker. The error will not be identified and reported until you execute the function in WindowViewer To avoid misspellings, use the OLE_CreateObject templates found in the InTrack OLE Browser.

When an object is first created, its properties are automatically set to applicable defaults by the server.

Note An object reference name does not require initialization with a call to OLE_CreateObject. In a previous example an assignment statement was used to associate an object reference with an object.

Managing an Object: OLE_ReleaseObjectAn object is valid as long as at least one object refers to it. However, it is good practice to release an object that is no longer in use to conserve system resources. To release an object:

1. Create a new object with the same object reference name.

When you create a new automation object with the same name as an existing automation object reference, the original automation object is released and the new object is associated with the original name. For example:OLE_CreateObject(%Object, “InTrack.Sublot”);

OLE_CreateObject(%Object, “InTrack.DateTime”);

The first statement causes an object of class Sublot to be created and referenced by %Object. The second statement releases the object of class Sublot, then creates an object of class DateTime and associates it with %Object.

OLE_CreateObject The function that creates the automation object%Object Name used to reference the automation objectclassName The name of the class provided by the OLE Server


338 Chapter 4

2. Use the built-in OLE_ReleaseObject system function. The syntax for this function is:

OLE_ReleaseObject(%objectName);

where:

There is no return value for this function and it never fails.

3. Set a reference to a second object.

The syntax to set an automation object to another automation object is:%object1 = %object2;

where:

In this example any object associated with %object1 is released.

Testing for a Valid Object: OLE_IsObjectValidAfter the relationship between an object reference and an OLE Automation object has been broken via the OLE_ReleaseObject function, the reference is “invalid.” Using an invalid reference in any object expression will result in an error at runtime.

An InTouch built-in system function OLE_IsObjectValid enables validity checking of an object reference. The syntax for this function is:OLE_IsObjectValid(%objectName);

where:

This function returns a discrete (Boolean) value indicating if the %objectName is currently bound to a valid automation object.

Getting a Property ValueA property is a named attribute that defines an object’s characteristics or an aspect of its behavior. The dot operator separates the object reference from the name of the property. When a tag is allowed in an InTouch script, the following syntax can be used to return the value of an automation object’s property:%Object.Property

%objectName The name of the automation object reference

%object1 Is the object reference to be “pointed” to the same object as %object2. The automation object previously associated with %object1 will be released.

%object2 Automation object to reference with the name, %object1. It must be of the same type.

%objectName The name of the automation object reference to release from memory



where:

If the property of an object is itself an object, the “dot” operator can be used multiple times; as in the following example:%Object.Property1.Property2

where:

Using multiple dots translates into multiple “get property” operations. In this example a simple “get” is done for %Object.Property1, which, according to OLE Automation standards, returns a reference to the nested object. This returned reference is used to perform another simple “get” for Property2. This could be performed manually with two InTouch script statements:%tempObject = %Object.Property1;

%tempObject.Property2;

This sequence of actions is important for several reasons:

1. Errors resolving property names can occur for each dot operator.

2. Multiple dots can be used in a variety of contexts to simplify coding, such as getting properties, setting priorities and calling methods.

Example 1

The goal is to increment an InTouch tag value if it is the first day of the month between 1:00 a.m. and 2:00 a.m. This code fragment illustrates several concepts:

OLE_CreateObject(%DateTime, "InTrack.DateTime");

%DateTime.SetLocalTime();

IF (%DateTime.Day == 1) AND (%DateTime.Hour > 1) AND(%DateTime.Hour < 2)

THENTag = Tag + 1;

ENDIF;

OLE_ReleaseObject(%DateTime);

Example 2

This example illustrates use of the multiple “dot” operator. The goal is to get some capacity information about a machine resource into InTouch tags for displaying to an operator. The example is highly contrived, but illustrates getting properties in a variety of InTouch expression contexts.

%Object Automation object referenceProperty An object attribute

%Object Automation object reference.Property1 A property of %Object. Note that the property can be an

embedded object or a reference to another object. InTouch and OLE automatically handle both cases.

Property2 A property of the nested object from which a value is to be retrieved.


340 Chapter 4

For simplicity, it is assumed that the object %Machine has been created as an instance of InTrack.Machine, and that appropriate information has been loaded from the InTrack database (the mechanics of this are described in later sections).

NumerUnitsTag = %Machine.Capacity.Quantity;

TypicalWeightTag = %Machine.Capacity.Quantity * 40.6;

ContrivedLoadingTag = Log(%Machine.Capacity.Quantity) + 1;

UnitsNameTag = %Machine.Capacity.Units;

Setting a PropertyThe value of an input or output object property can be set using three methods:

• Use an assignment statement (described in this section).

• Pass the property reference as an output parameter to a method.

• Call a method to set one or multiple properties of an object in a single action (new values are passed as parameters). These facilities are class specific. Refer to the method references in the chapters that follow for more information.

Note References to properties of automation objects cannot be passed as “by reference” (output) parameters to DLL functions called from InTouch scripts. The value of an object property cannot be changed by a DLL function.

The basic syntax for setting an object property value through an assignment statement is as follows:%Object.Property = Value;

where:

As with getting object properties, if the property of an object is itself an object, the “dot” operator can be used multiple times:%Object.Property1.Property2 = Value;

where:

This one InTouch statement using multiple “dot” operators is equivalent to:%tempObject = %Object.Property1;

%tempObject.Property2 = Value;

Example

%Object Automation object referenceProperty An object attributeValue Value that you want to assign to the object attribute

%Object Automation object referenceProperty1 A property of %Object that is of type objectProperty2 A property of the nested object that is to have its value

set



The first line of this example creates an automation object of the Amount class named %PrimaryAmt. The second and third lines of script set the %PrimaryAmt automation object’s Quantity property to “100” and the Units property to “each.”OLE_CreateObject(%PrimaryAmt, “InTrack.Amount”);

%PrimaryAmt.Quantity = 100;

%PrimaryAmt.Units = “each”;

Calling a MethodCalling a member method of an automation object is the typical way a client asks the server to do work on its behalf. The following syntax illustrates how to call a method on an automation object:resultValue = %Object.Method(Parameter1, Parameter2, ...);

%Object.Method(Parameter1, Parameter2, ...);

where:

RestrictionsThe following restrictions apply to calling methods:

• Methods can be called as a “subroutine” (no return value). If the method does return a value, it is discarded.

• If a return value is to be used, it must be assigned unmodified. The method call cannot be a term in an expression.

• Typically, script execution is blocked until the method returns from processing, unless the method performs transactions that require user interaction through dialogs.

• You must insure that the correct number of parameters is passed. There is no support for OLE “optional” parameters.

resultValue A data value returned by the method.%Object Automation object reference.Method Action performed by the automation object.Parameters Information to be passed into or returned from the

method. The number of parameters is defined by the method being called. Parameters can be read only or input/output.


342 Chapter 4

Parameter TypesSome restrictions apply to the types of data that can be passed to an Automation method from InTouch.

Note that some methods are “polymorphic,” and can take several different types of data for the same parameter. InTouch supports this facility for input-only parameters.

Output ParametersInTouch does not differentiate between method parameters that are input only and input/output. If the parameter can be updated, a value is stored into it.

A parameter can be updated if:

• The parameter is the name of a read/write InTouch tag.

• The parameter is an object reference name.

• The parameter specifies an object property.

In the following InTouch statement the first three parameters will be updated, since each meets the corresponding option listed above. The other parameters will not be updated.%Obj1.Method(tag1, %obj2, %obj3.property1.property2, tag1

+ 3,%obj4.property + 0);

Return ValuesTo capture the return value of a method, the left side of the assignment must be:

• The name of a read / write InTouch tag.

• An object reference name.

• An object property specification.

Example 1

Assume that an automation object of class SerialNumbers has been created and named %SerialNumbers. The following script statement will add the serial number “1234” to the serial numbers in the %SerialNumbers collection object:

Data Type May be represented as aInteger Constant, expression, read-only tag, read/write tag, or

read/write OLE Automation propertyReal Constant, expression, read-only tag, read/write tag, or

read/write OLE Automation propertyMessage Constant, expression, read-only tag, read/write tag, or

read/write OLE Automation propertyDiscrete Constant, expression, read-only tag, read/write tag, or

read/write OLE Automation propertyObject Object reference name or read/write OLE Automation

property



returnCode = %SerialNumbers.Add(“1234”);

Example 2

Assume that an automation object of the Sublot class has been created and named %Sublot_Object. You want to use the Sublot Ship method, which contains two parameters that are automation objects, %PrimaryAmt and %SecondaryAmt:ReturnCode = %Sublot_Object.Ship (%PrimaryAmt,

%SecondaryAmt,“customerName”) ;

where:

Sample

You want to ship 100 manuals (primary amount), each weighing 2 pounds (secondary amount) to a customer (Wonderware). You must create the parameter automation objects, %PrimaryAmt and %SecondaryAmt, and set their properties, before you can call the Ship method. Each step is outlined below:

1. Create an Amount object to represent the primary quantity and set the properties:OLE_CreateObject(%PrimaryAmt, “InTrack.Amount”);%PrimaryAmt.Quantity = 100;%PrimaryAmt.Units = “each”;

2. Create an Amount object to represent the secondary quantity and set the properties:OLE_CreateObject(%SecondaryAmt, “InTrack.Amount”);%SecondaryAmt.Quantity = 2;%SecondaryAmt.Units = “pounds”;

3. Call the Ship method on the %Sublot_Object using the following syntax:returnCode = %Sublot_Object.Ship(%PrimaryAmt,

%SecondaryAmt,“Wonderware”);

InTouch Error HandlingWhen handling errors, determine if the error was caused by using OLE Automation incorrectly, or if the error was returned from the OLE server. InTouch identifies OLE errors in a message box and records them in the WWLogger.

InTouch script execution is not terminated by an OLE error. The action taken depends on the task at the time of the error:

• If it occurs during a get property operation, zero or an empty string is returned for the properties value.

• If it occurs on a set property operation, the property value is not changed.

%PrimaryAmt Amount object identifying the primary quantity to ship%SecondaryAmt Amount automation object identifying the secondary

quantity to shipcustomerName Name of the customer receiving the shipment


344 Chapter 4

• If it occurs on a method call, the method is not invoked, no changes are made to any, and the return value for the method is zero or an empty string.

To assist with error handling, five system reporting functions are provided:

• OLE_GetLastObjectError

• OLE_GetLastObjectErrorMessage

• OLE_ResetObjectError

• OLE_ShowMessageOnObjectError

• OLE_IncrementOnObjectError

Details for these functions are provided below.

OLE_GetLastObjectErrorTo get the error number for the last reported error through the Microsoft “last error” variable:value = OLE_GetLastObjectError();

where:

OLE_GetLastObjectErrorMessage To get the error message (description) for the last reported error:value = OLE_GetLastObjectErrorMessage();

where:

OLE_ResetObjectErrorThe value of the “last error” is changed only when an error occurs. It is not reset upon successful completion of an OLE Automation action. In some cases application development is made easier by setting the “last error” to a known state, performing several OLE Automation actions, then testing for a change in the “last error” value. This function will set the Microsoft internal “last error” value to zero. The syntax for this function is:OLE_ResetObjectError();

value Is an integer into which the error number is stored.Error numbers are internally unsigned 32-bit integers. InTouch does not have the same integer range, so error codes that use high-order bits will not be returned correctly.

value Is a string (message) set to the error message.This text also is presented in the error message box. It contains embedded carriage return and line feed characters. If the text exceeds the 131-character string limit imposed by InTouch, the message is truncated.



OLE_ShowMessageOnObjectErrorThis function controls the display and required operator input when an OLE interface error or OLE exception occurs. While this message box is displayed, the script that caused the error is blocked from running until the message box is acknowledged (for example, the OK button is clicked). Background scripts will continue to execute.

An OLE interface error involves a failure to communicate with the Microsoft OLE infrastructure provided by the Microsoft Windows-NT operating system. It does not reflect a processing error identified by an OLE server.

An OLE exception can be caused either by the OLE infrastructure or OLE server.

The syntax for this function is:OLE_ShowMessageOnObjectError(discreteTag);

where:

The following script disables the display of the OLE error message box for a call to the Create method of the object %Lot. After the method call, the OLE error message box is re-enabled for display on any subsequent error.OLE_ShowMessageOnObjectError(0);

%Lot.Create("abc");

OLE_ShowMessageOnObjectError(1);

OLE_IncrementOnObjectErrorThis function increments an integer tag if an OLE interface error or OLE exception occurs.

Note If the OLE_ShowMessageOnObjectError function is executed with the discrete tag enabled, the value is incremented after the OLE error message box is displayed and acknowledged.

An OLE interface error involves a failure to communicate with the Microsoft OLE infrastructure provided by the Microsoft Windows-NT operating system. It does not reflect a processing error identified by an OLE server.

An OLE exception can be caused either by the OLE infrastructure or OLE server.

The tag specified by this function will be incremented on each error until another call specifies a different tag. The tag is not remembered across executions of WindowViewer.

The syntax for this function is:OLE_IncrementOnObjectError(integerTag);

discreteTag Defines the name of the Boolean (discrete) value that indicates whether to display a message box to a user if an OLE error or exception occurs, where:-1 = display message box (default) 0 = do not display message box


346 Chapter 4

where:

The following script increments the value of the variable referenced by the errorCount tag by 1 each time an OLE interface error or OLE exception occurs.OLE_IncrementOnObjectError(errorCount);

Frequent Automation Object ErrorsFrequent errors when using InTouch OLE Automation extensions and their remedies are listed below.

• OLE object reference name has not been defined.

An object reference name has been used to reference a property (%object.property) or call a method (%object.method(parameter) ) before being associated with an object. Check that the object reference name is not misspelled. Verify the name associated with an object by using the InTouch system function OLE_CreateObject or by assigning one object reference to another.

• Unknown property or method name.

Verify that the property or method name is spelled correctly.

• Attempt to update read-only property.

This error is obvious when the read only property is on the left side of an assignment statement. It is more difficult to spot when it is being updated as a return parameter from a method call.

• Type mismatch.

The data being passed as a parameter for update is not correct. This indicates that automatic data conversion does not have enough information to take the correct action. Manually assign the data to an InTouch tag of the correct type and use the tag.

• Invalid class string.

This generally indicates that the class name (second parameter) in an OLE_CreateObject function call is misspelled.

• Parameter not optional.

Check that the correct number of parameters is being passed.

• Unexpected results but no error reported.

Data type conversion is performed at runtime. Accidentally assigning a string to an integer would not generate an error; however, you may get a result of zero if the string does not start with digits.

• Object reference path element is not an OLE object.

When using multiple “dot” operators, this error occurs if one of the properties in the path is not an embedded object or object reference.

integerTag Defines the name of the integer tag to be incremented upon error or exception.


Troubleshooting QuickScript Functions 347

A P P E N D I X A

Troubleshooting QuickScript Functions

Several InTouch QuickScript functions return a value based on the status of their processing. This value, known as the result code or error code, can be used to determine the relative success of that function's processing. This appendix describes the result codes for Windows Controls, Recipe, and SQL QuickScript functions. Also described are the SPC DDE Items available for obtaining Dataset information and for controlling chart operations.

Error Messages for Windows Controls and Distributed Alarms

The Window Controls and Distributed Alarm QuickScript functions return a value based on the result of processing the QuickScript function. The return value, used for error diagnostics, can be assigned to an Integer tagname. For example:

ErrorNumber = wcGetItem("ControlName", Number, Tagname);

Where:

ErrorNumber is an Integer tagname that holds the returned error value. The return value of the function can be passed to the wcErrorMessage()function. The wcErrorMessage() function returns a string description of the error. For example:

ErrorMsg = wcErrorMessge(ErrorNumber);

Where:

ErrorMsg is a Message tagname that holds the text description of the returned error.

The following table describes the ErrorNumber numeric values:

Error Number Description 0 Success-1 General failure-2 Insufficient memory available-3 Property is read-only-4 Specified item already present


348 Appendix A

* -x represents any other number.

Troubleshooting Recipe Script FunctionsTo retrieve the error code of a Recipe Function, it must be equated to an InTouch integer tagname. For example:

ErrorCode = RecipeLoad(FileName, UnitName, RecipeName);

The RecipeLoad() function will set the value of the tagname ErrorCode to 0 if it is successful. If the RecipeLoad() fails, it will set the analog tagname, ErrorCode, to the number for the specific error condition. The following is a listing of the possible Error Codes and their corresponding error messages and descriptions:

-5 Object name unknown-6 Property name unknown-x* Unknown error

Value Error Message Description0 Success The called recipe function executed

successfully.-1 No Such Recipe

TemplateThe specified recipe template filename does not exist.

-2 View Not Active The recipe function called by another program cannot execute because WindowViewer is not running.

-3 Out of Memory There is not enough memory to complete the current activity.

-4 Line too long in recipe template file

A line in the recipe template file has exceeded the maximum allowed length.

-5 Truncated line in the recipe file

A line in the recipe template file has been truncated.

-6 Not a valid recipe template file

The specified filename is not a valid .CSV recipe template file.

For more information on unit or recipe names, see your online Recipe Manager User's Guide.

-7 Expecting unit" or "recipe"

A unit name or recipe name is missing from the recipe template file.

For more information on unit or recipe names, see your online Recipe Manager User's Guide.

Error Number Description



Displaying Recipe Error Code MessagesEach Recipe Function returns a number that represents the error condition for the function. By using the RecipeGetMessage() function in an InTouch Data Change QuickScript, the corresponding error code can be written to an analog tagname and the associated error code message can be written to a message tagname.

To do so, the following Data Change QuickScript would be used:

RecipeGetMessage(ErrorCode, ErrorMessage, 131);

This QuickScript will automatically execute whenever the value of the analog tagname ErrorCode changes. When this QuickScript executes, the RecipeGetMessage() function will read the current numeric value of the tagname ErrorCode and return the message associated with that value to the tagname ErrorMessage.

-8 No units defined in recipe template file

No units have been defined in the recipe template file Units Definition template.

-9 Recipe name not found in recipe template file

The specified recipe name is not defined in the recipe template file.

-10 Unit name not found in recipe template file

The specified unit name is not defined in the unit definition template file

-12 Expecting "Analog", "Discrete", "Message"

An incorrect type has been entered for an item in the recipe template file. Valid types are Analog, Discrete or Message only.

-13 Type of tagname mismatches "Analog," "Discrete," or "Message"

The tagname specified is incorrect for the item type, e.g., a recipe item is defined as Analog and a message tagname has been defined in the unit for it.

-14 Invalid discrete value, expecting "0", "1"

An incorrect value has been entered for a Discrete in the recipe template file. The valid values for a Discrete are 0 or 1.

-15 Unable to open temporary file

The temporary file cannot be opened; could possibly be due to inadequate disk space.

-16 Write error while saving recipe template file

An error has occurred while saving the recipe template file.

-17 User did not select The user selected Cancel in the Select a Recipe dialog box instead of a recipe name.

-19 Recipe template in use by another application

The recipe template file specified is open and, therefore, cannot be accessed by WindowViewer.

Value Error Message Description


350 Appendix A

SPC DDE Item NamesSPC DDE items are available for obtaining Dataset information and for controlling chart operations. The application name is SPC. The topic name is the Dataset name.

Note All SPC DDE Items are used in the same way for distributed SPC as they are for non-distributed SPC, except the topic name must be an InDirect Dataset name for distributed SPC.

SPC Control and Display DDE ItemsThe Control and Display DDE Items are used to control and display information about the topic Dataset. Control DDE items are shared by all nodes. They are the dataset values for the collected product of the remote dataset. Display DDE items are local to each node. They are the sample values for the displayed product on the local node.

Sample modifications can be applied to collected and displayed products of locally any datasets. Modification made by clicking on a chart display will affect the displayed product. The SPC DDE items modify the collected product. The displayed product and the collected product have their own current samples which is the most recently recorded sample.

Alarms are evaluated and stored for collected and displayed products. They are only reported during runtime for the collected product.

Note With the addition of displayed and collected products, many SPC DDE Items apply only to the collected product. These items are flagged in the following lists by an asterisk (*) preceding the SPC DDE Item name.

Item Name DDE Type Access DescriptionAutoCollection Discrete R/W Enables/disables automatic data

collection.*CalculateControlLimits Discrete R/W Set to 1 to start control limit calculation.DatasetName Message

(32)R/W Sets the Dataset Name used by an

Indirect Dataset.HistogramLCL Real RO Displays the Histogram's Lower Control

Limits based on population.HistogramUCL Real RO Displays the Histogram's Upper Control

Limits based on population.Kurtosis Real RO Distribution shape of Histograms.LastSampleDisplayed Integer R/W Sets the last sample number displayed by

the Dataset.*ManualInputDialog Discrete R/W Set to 1 to display built-in Manual Input

Dialog Box.MeasurementsPerSample Integer RO Displays the configured number of

measurements per sample.



NewProduct Message(32)

R/W Used to create new Product Name.

NewProductCtrlTitle Message(32)

R/W Used to set the Control chart title of a new product created with the NewProduct Function.

NewProductParetoTitle Message(32)

R/W Used to set the Pareto chart title of a new product created with the NewProduct Function.

NewProductHistTitle Message(32)

R/W Used to set the Histogram chart title of a new product created with the NewProduct Function.

*ProductCollected Message(32)

R/W Changes the Product Name collected by the Dataset.

ProductDisplayed Message(32)

R/W Changes the Product Name displayed by the Dataset.

SampleSize Integer RO Sample size for NP Dataset.SamplesPerControlChart Integer R/W Sets the number of samples displayed in a

Control Chart.SamplesPerHistogram Integer R/W Sets the number of samples displayed in a

Histogram.SamplesPerLimitCalc Integer R/W Sets the number of samples used in a

control limit calculation.SamplesPerPareto Integer R/W Sets the number of samples used in a

Pareto Chart display.SelSPCOutSpecMsg Message RO Alarm Message tag for "Sample outside

specification Limit."Skewness Real RO Displays the variance from the mean on

Histograms.SPCAllowSampDelMod Discrete R/W Toggles right click menu options Delete

and Modify sample options on and off.SPCConnection Discrete RO Set to 0 if the connection is lost to the

server.SPCConnectType Message RO Displays whether the node is connected

as a agent (Server) or Client.

Item Name DDE Type Access Description


352 Appendix A

SPC Current Sample DDE ItemsAll Current Sample DDE Items pertain to the last collected sample of a given Dataset. They can be used to change the raw data and the limits associated with the Dataset Name. To change information about the current sample, you must write to the appropriate DDE Item then set the CurrentUpdate DDE Item to 1. This will have the effect of re-entering the sample and will cause any required calculations to be performed. The SPC program will reset the CurrentUpdate DDE Item to 0 after the sample has been entered. Once the next sample to be collected has started a collection cycle, the current sample DDE items can no longer be updated.

Current sample DDE items are shared among all nodes. These item values represent the last collected sample of a collected product.

For distributed SPC, initially all the values are set to zero. SPC connects to the database and checks for new data every 5 seconds. The item values are updated whenever new information is found. Modifications to the current sample values are buffered locally until the CurrentUpdate item is set to 1. Then the values are placed in a current sample packet and sent to the remote dataset node for analysis and storage. Current sample modifications that indicate a different collected product and a current sample number that is not the last recorded sample will be rejected by the Server.

SPCLowDBSpace Discrete RO Used to monitor the Microsoft SQL Server Database. Only works with Microsoft SQL Server Databases. It will equal 1 when the database is low on space. Can be used to stop AutoCollection, and alert an operator to allocate more space or free hard disk space. It will automatically toggle between 1 and 0 depending upon the status of the SQL Database.

SPCResetRunRules Discrete R/W Used to reset the application of run rules on the incoming samples. This is important when collecting data for a new batch, you may not want the run rules to apply to samples from the new batch. You may want to reset the rules for the new batch.




Note With the addition of displayed and collected products, all of the "Current" SPC DDE Items apply only to the collected product.

Item Name DDE Type Access DescriptionCurrentCauseCode Integer R/W Sets the Special Cause Code number

for the current sample.CurrentCauseString Message

(128)RO Displays the description of the Special

Cause Code number for the current sample.

CurrentComment Message(50)

R/W Used to read/write any miscellaneous comments associated with the current sample.

CurrentCp Real RO Displays the capability for the current sample.

CurrentCpk Real RO Displays the centered capability for the current sample.

CurrentDate Message(8)

R/W Sets the Date for the current sample in the format DD/MM/YY. If incorrectly entered, defaults to the current Date.

CurrentFlag Discrete R/W Sets a Flag for the current sample.CurrentIgnoreValue Discrete R/W Sets the current sample to be ignored

when the Control Chart is AutoScaled.CurrentMx Real R/W Sets the individual measurement value

for the current sample. (x=1 to 25.)CurrentR Real RO Displays the range for the current

sample.CurrentRBar Real R/W Sets the average range at the current

sample.CurrentRLCL Real R/W Sets the range Lower Control Limit.CurrentRUCL Real R/W Sets the range Upper Control Limit.CurrentSample Real RO Displays the value of the last sample

point (i.e., X, C, P).CurrentSampleBar Real R/W Sets the current sample average at this

sample point.CurrentSampleNumber Integer RO Displays the last sample number

collected.CurrentTarget Real R/W Sets the target value at this sample

point.CurrentTime Message

(8)R/W Sets the Time for the current sample in

the format HH:MM:SS. If incorrectly entered, defaults to the current Time.

CurrentUpdate Discrete R/W To change information entered about the sample in any of the current fields, set this Item to 1.

CurrentXLCL Real R/W Sets current sample Lower Control Limit (LCL).


354 Appendix A

CurrentXLSL Real R/W Sets current sample Lower Specification Limit (LSL).

CurrentXUCL Real R/W Sets current sample Upper Control Limit (UCL).

CurrentXUSL Real R/W Sets current sample Upper Specification Limit (USL).

SPC2L3Out2SD Integer RO Alarm counter for Alarm "2 of the last 3 samples outside of 2 standard Deviation SS."

SPC2L3Out2SDMsg Message RO Alarm Message tag for "2 of the last 3 samples outside of 2 standard Deviation SS."

SPC4L5Out1SD Integer RO Alarm counter for Alarm "4 of the last 5 samples outside of 1 standard Deviation SS."

SPC4L5Out1SDMsg Message RO Alarm Message tag for "4 of the last 5 samples outside of 1 standard Deviation SS."

SPCConSampAltUpDn Integer RO Alarm counter for Alarm "Consecutive samples Alternating Up and Down."

SPCConSampAltUpDnMsg Message RO Alarm Message tag for "Consecutive samples Alternating Up and Down."

SPCConSampln1SD Integer RO Alarm counter for Alarm "Consecutive samples Inside 1 standard Deviation."

SPCConSampln1SDMsg Message RO Alarm Message tag for "Consecutive samples Inside 1 standard Deviation."

SPCConSamplncDec Integer RO Alarm counter for Alarm "Consecutive samples Increasing or Decreasing."

SPCConSamplncDecMsg Message RO Alarm Message tag for "Consecutive samples Increasing or Decreasing."

SPCConSampOneSideCL Integer RO Alarm counter for Alarm "Consecutive samples on one side of centerline."

SPCConSampOneSideCLMsg Message RO Alarm Message tag for "Consecutive samples on one side of centerline."

SPCConSampOut1SD Integer RO Alarm counter for Alarm "Consecutive samples outside 1 standard Deviation."

SPCConSampOut1SDMsg Message RO Alarm Message tag for "Consecutive samples outside 1 standard Deviation."

SPCNLNOutNSD Integer RO Alarm counter for Alarm "? Of the last ? samples outside ? standard deviations."

SPCNLNOutNSDMsg Message RO Alarm Message Tag for "? Of the last ? samples outside ? standard deviations."




SPCNLNOutNSDSS Integer RO Alarm counter for Alarm "? Of the last ? samples outside ? standard deviations SS."

SPCNLNOutNSDSSMsg Message RO Alarm Message tag for "? Of the last ? samples outside ? standard deviations SS."

SPCOutRCtrl Integer RO Alarm counter for the Range Chart Alarm "Range outside Control Limit."

SPCOutRCtrlMsg Message RO Alarm Message for the Range Chart Alarm "Range outside Control Limit."

SPCOutXCtrl Integer RO Alarm counter for the X Chart Alarm "Sample outside Control Limit."

SPCOutXCtrlMsg Message RO Alarm Message for the X Chart Alarm "Sample outside Control Limit."

SPCOutSpec Integer RO Alarm counter for Alarm "Sample outside specification Limit."

SPCOutSpecMsg Message RO Alarm Message tag for "Sample outside specification Limit."

SPCRecalculateCp Discrete R/W When set to "1", the engine will recalculate Cp and Cpk values for the current dataset when the next sample is collected. After this sample is collected, the value of this item will reset to "0". To recalculate Cp and Cpk again, set this value to "1" again. When set to "1" . the next collected sample will have recalculated CP and CPK values. Then is automatically set back to "0" after the sample is collected.

Note This item ONLY affects Cp and Cpk values. It will not affect Control Limits or Run Rules.

SPCResetAlarmCounters Discrete R/W Resets all alarm counters.SPCResetRunRules Discrete R/W Used to reset the application of run

rules on the incoming samples. Applies to the current product collected. When turned on, run rules are reset and previous samples will not apply in calculations such as "4 out of 5 samples outside of 1 standard deviation" alarms. This action only occurs once and run rules will resume as normal. This item must be reset and then turned again for the reset action to take place again.



356 Appendix A

SPC Manual Input DDE ItemsThe Manual Input DDE Items are used to create custom manual input windows. To use the manual input items, set the values of the appropriate items and then set the MI_Save DDE Item to 1. This will cause the information in the other MI fields to be entered as a new sample. The SPC program will reset the MI_Save DDE Item to 0 (zero) after the sample has been entered.

For distributed SPC, manual input DDE items are private to each node. The values are buffered locally at each node until the DDE item MI_Save is set to 1. Once MI_Save is set to 1, the values are placed in a manual input packet and sent to the remote dataset node for analysis and storage.

Note With the addition of displayed and collected products, all of the "Manual" SPC DDE Items apply only to the collected product.

Item Name DDE Type Access DescriptionMI_CauseCode Integer R/W Sets the Special Cause Code

number for the manually input sample.

MI_CauseString Message(127)

RO Displays the description of the Special Cause Code number input for the sample.

MI_Comment Message(50)

R/W Used to read/write any miscellaneous comments entered for the sample.

MI_Date Message(8)

R/W Sets the Date for the current sample. The Date must be entered in the format DD/MM/YY. If incorrectly entered, the Date will default to the current Date.

MI_Flag Discrete R/W Sets a flag for the manually input sample.

MI_IgnoreValue Discrete R/W Sets the current sample to be ignored when the Control Chart is AutoScaled.

MI_Mx Real R/W Sets the value for the designated manually input measurement (x=1 to 25).

MI_Save Discrete R/W Saves the information manually entered in the other MI fields as a new sample.



SPC Selection DDE ItemsThe Selection DDE Items can be used to view detailed information about any sample. The DDE Item Selection is used to enter the number of the sample to be displayed. Once entered, the SPC program will update all of the other Selection Items with the detailed information for the Selection sample number.

Old data cannot be changed, but Special Cause Codes, Flags and/or Comments can be added by setting the appropriate items then setting the SelectionUpdate itemto 1.

This will cause the selection sample record to be modified with the new values. The SPC program will reset the SelectionUpdate DDE item to 0 (zero) after the updated sample has been entered.

For distributed SPC, selected sample DDE items are private to each node. They are the sample values recorded by the remote node for a specified sample number of the collected product. When the Selection DDE item is set to a sample number, the sample information is retrieved from the remote node's sample file. Old data cannot be changed, but Special Cause Codes, Flags, and Comments can be added by changing the appropriate DDE item and setting the SelectionUpdate item to 1. When SelectionUpdate is set to 1, the Special Cause Code, Comment, Flag, and Ignore Value items are sent to the remote node in a packet for storage.

Note When the MI_Save item is set to 1, the value of all MI items are written to the respective Current DDE Items and the CurrentSampleNumber item is indexed by 1.

MI_Time Message(8)

R/W Sets the Time for the current sample. The Time must be entered in the format HH:MM:SS. If incorrectly entered, the Time will default to the current time.



358 Appendix A

Note With the addition of displayed and collected products, all of the "Selection" SPC DDE Items apply only to the collected product.

Item Name DDE Type Access DescriptionSelection Integer R/W Setting this item to a sample

number will update all of the selection items with the appropriate data for that sample.

SelectionCauseCode Integer R/W Sets the Special Cause Code number for the selected sample.

SelectionCauseString Message(128)

RO Displays the description of the entered Special Cause Code.

SelectionComment Message(50)

R/W Used to read/write any miscellaneous comments entered for the selected sample.

SelectionCp Real RO Displays the capability for the selected sample.

SelectionCpk Real RO Displays the centered capability for the selected sample.

SelectionDate Message(8)

RO Displays the date for the selected sample.

SelectionFlag Discrete R/W Sets a Flag of the selected sample.

SelectionIgnoreValue Discrete R/W Sets the selected sample to be ignored when the Control Chart is AutoScaled.

SelectionMx Real RO Displays the value for the individual measurements (x=1-25) comprising the sample.

SelectionProduct Message(32)

RO Displays the Product Name for the selected sample.

SelectionRUCL Real RO Displays the range UCL for the selected sample.

SelectionRLCL Real RO Displays the range LCL for the selected sample.

SelectionR Real RO Displays the range for the selected sample.

SelectionRBAR Real RO Displays the average range at the selected sample.

SelectionSample Real RO Displays the value of the selected sample point.



SelectionSampleBar Real RO Displays the selected sample average at the selected sample point.

SelectionTarget Real RO Displays the target value at the selected sample.

SelectionTime Message(8)

RO Displays the Time for the selected sample.

SelectionUpdate Discrete R/W Updates changes in Selection fields.

SelectionXUSL Real RO Displays sample Upper Specification Limit.

SelectionXLSL Real RO Displays sample Lower Specification Limit.

SelectionXUCL Real RO Displays sample Upper Control Limit.

SelectionXLCL Real RO Displays sample Lower Control Limit.

SelSPC2L3Out2SDMsg Message RO Alarm Message tag for "2 of the last 3 samples outside of 2 standard Deviations SS."

SelSPC4L5Out1SDMsg Message RO Alarm Message tag for "4 of the last 5 samples outside of 1 standard Deviation SS."

SelSPCConSampAltUpDnMsg Integer RO Alarm message for Alarm "Consecutive samples Alternating Up and Down."

SelSPCConSampln1SDMsg Message RO Alarm Message tag for "Consecutive samples Inside 1 standard Deviation."

SelSPCConSamplncDecMsg Message RO Alarm Message tag for "Consecutive samples Increasing or Decreasing."

SelSPCConSampOneSideCLMsg Message RO Alarm Message tag for "Consecutive samples on one side of centerline."

SelSPCConSampOut1SDMsg Message RO Alarm Message tag for "Consecutive samples outside 1 standard Deviation."

SelSPCNLNOutNSDMsg Message RO Alarm Message Tag for "? Of the last ? samples outside ? standard deviations."

SelSPCNLNOutNSDSSMsg Message RO Alarm Message tag for "? Of the last ? samples outside ? standard deviations SS."



360 Appendix A

Note Multiple Indirect Datasets can be setup and linked to the same real Dataset. Then the Selection value of each Indirect Dataset can be set to a different sample number. This allows you to view detail information of multiple samples within a Dataset.

Troubleshooting SQL Script FunctionsAll SQL Functions return a ResultCode that can be used for troubleshooting. The SQLErrorMsg() function returns the Error Message associated with the ResultCode. For example:ErrorMsg=SQLErrorMsg(ResultCode);

where:

ErrorMsg is a memory message tagname.

ResultCode is an integer value obtained from a previous SQL function.

Result Code Error MessagesFor Result Codes that are not documented here, please refer to your specific database documentation and be sure to check the Wonderware Logger for any additional information.

The SQLErrorMsg() function will set the value of the InTouch message tagname ErrorMsg. The following is a listing of some of the possible SQL Result Codes and their corresponding error messages and descriptions:

SelSPCOutRCtrlMsg Message RO Alarm Message for the Range Chart Alarm "Range outside Control Limit."

SelSPCOutXCtrlMsg Message RO Alarm Message for the X Chart Alarm "Sample outside Control Limit."

SelSPCOutSpecMsg Message RO Alarm Message tag for "Sample outside specification Limit."

Result Code Error Message Description0 No errors occurred The command was successful-5 No more rows to fetch The last record in the table has been reached-1001 Out of memory There is insufficient memory to perform this

function-1002 Invalid connection The ConnectionId passed to the function is not

valid-1003 No bind list found The specified Bind List name does not exist-1004 No template found The specified Table Template name does not

exist.




-1005 Internal Error An internal error occurred. Call Technical Support.

-1006 String is null Warning - the string read from the database is null.

-1007 String is truncated Warning - the string read from the database is longer than 131 characters and is truncated on a select.

-1008 No Where clause There is no Where clause on Delete.-1009 Connection failed Check Wonderware Logger for a more detailed

description of the failed connect.-1010 The database specified on

the DB= portion of the connect string does not exist

The specified database does not exist.

-1011 No rows were selected A SQLNumRows(), SQLFirst(), SQLNext(), or SQLPrev() command was attempted without executing a SQLSelect() command first.

-4149 The connection, statement, or query handle you provided is not valid

Column type may be incorrectly defined. For example, if a Table Template is defined with a column type of character instead of char for a dBASE file, an error will be returned.

Result Code Error Message Description


362 Appendix A

Specific Database Error Messages

Oracle

Sybase or Microsoft SQL Server

Error Message SolutionORA-03112 - Host String Syntax error

If you are not running NETINIT.EXE, place it in the Windows Startup group. If you are running NETINIT.EXE and want to establish more than one connection or session, you will need to allocate memory. Do this by setting the WIN_REMOTE_SESSIONS parameter in the CONFIG.ORA file equal to the number of required connections. The following example will allocate memory for 4 connections:WIN_REMOTE_SESSIONS=4

ORA-3121 - No interface driver connected

Start the SQL*NET TSR appropriate for your networking system before entering Windows and using InTouch SQL Access.

ORA-6435 - NetBIOS: Unable to add local name to name table

The network software (Novell, LAN Manager, etc.) must be running.

ORA-09301 - Local kernel only supported in standard mode

Specify the server name ("SRVR=") in the connection string.

ORA-06430 - Unable to make connection

Verify that the attributes in the connection string are accurate and in correct order.

Error Message SolutionYou cannot have more than one statement active at a time

You are trying to execute a SQL command after executing a SQLSelect(). Execute a SQLEnd() to free system resources from the SQLSelect() or; Use a separate ConnectionId for the second statement.

There is not enough memory available to process the command

Try rebooting the client workstation.

Invalid object name table name The table name does not exist in the database you are using. Try DB=database name.



dBASE

Error Message SolutionFile or DLL not found For Windows, the QEDBF.DLL must

either be in your current directory or in the windows system directory in your DOS path.

Invalid connection Make sure you have appropriate DLLs in your path. For DBF support, you will need QLDBF.DLL.

The connection or statement handle you provided is not valid

For more information, check the Wonderware Logger. There may be a syntax error in your SQL statement.


364 Appendix A


365

Index
Symbols$AccessLevel 19$AlarmPrinterError 20$AlarmPrinterNoPaper 20$AlarmPrinterOffline 21$AlarmPrinterOverflow 21$ApplicationChanged 22$ApplicationVersion 22$ChangePassword 23$ConfigureUsers 23$Date 24$DateString 24$DateTime 24$Day 25$HistoricalLogging 25$Hour 26$InactivityTimeout 26$InactivityWarning 27$LogicRunning 27$Minute 28$Month 28$Msec 28$NewAlarm 29$ObjHor 29$ObjVer 29$Operator 30$OperatorEntered 31$PasswordEntered 32$Second 32$StartDdeConversations 32$System 33$Time 33$TimeString 33, 34$Year 34
AAlarm Dotfields

.Ack 44

.AckDev 44, 46

.AckROC 46

.AckValue 48

.Alarm 48

.AlarmAccess 50

.AlarmAckModel 50

.AlarmClass 52

.AlarmComment 52

.AlarmDate 54

.AlarmDev 54

.AlarmDevCount 56

.AlarmDevDeadband 56

.AlarmDevUnAckCount 57

.AlarmDisabled 57

.AlarmDsc 58

.AlarmDscCount 58

.AlarmDscDisabled 60

.AlarmDscEnaabled 60

.AlarmDscInhibitor 61

.AlarmDscUnAckCount 61

.AlarmEnabled 63

.AlarmGroup 63

.AlarmGroupSel 64

.AlarmHiDisabled 64

.AlarmHiEnabled 65

.AlarmHiHiDisabled 65

.AlarmHiHiEnabled 66

.AlarmHiInhibitor 66, 68

.AlarmLimit 68

.AlarmLoDisabled 70

.AlarmLoEnabled 70

.AlarmLoInhibitor 70

.AlarmLoLoDisabled 72

.AlarmLoLoEnabled 72

.AlarmLoLoInhibitor 72

.AlarmMajDevDisabled 74

.AlarmMajDevEnabled 74

.AlarmMajDevInhibitor 75

.AlarmMinDevDisabled 75

.AlarmMinDevEnabled 77

.AlarmMinDevInhibitor 77

.AlarmName 79

.AlarmOprName 79

.AlarmOprNode 81

.AlarmPri 81

.AlarmProv 83

.AlarmROC 83

.AlarmROCCount 85

.AlarmROCDisabled 85

.AlarmROCEnabled 86

.AlarmROCInhibitor 86

.AlarmROCUnAckCount 88

.AlarmState 88

.AlarmTime 89

.AlarmTotalCount 89

.AlarmType 90

.AlarmUnAckCount 90

.AlarmUserDefNum1 91


.AlarmUserDefStr 93

.AlarmValDeadband 94

.AlarmValue 94

.AlarmValueCount 95

.AlarmValueUnAckCount 95

.DevTarget 99

.Freeze 101

.HiHiLimit 102

.HiHiSet 102

.HiHiStatus 103

.HiLimit 103

.HiSet 104

.HiStatus 104

.ListChanged 105

.LoLimit 106

.LoLoLimit 108

.LoLoSet 109

.LoLoStatus 109

.LoSet 108

.LoStatus 111

.MajorDevPct 111

.MajorDevSet 112

.MajorDevStatus 112


366

.MinorDevPct 118

.MinorDevSet 118

.MinorDevStatus 119

.NextPage 123

.Normal 124

.NumAlarms 124

.PageNum 126

.PendingUpdates 131

.PrevPage 131

.PriFrom 133

.PriTo 133

.ProviderReq 133

.ProviderRet 135

.QueryState 143

.QueryType 143

.ROCPct 148

.ROCSet 148

.ROCStatus 149

.Successful 153

.SuppressRetain 155

.TotalPages 163

.UnAck 163Alarm Functions

AalmSelectGroup 182Ack 172almAckAll 174almAckDisplays 174almAckGroup 174almAckPriority 176almAckRecent 176almAckSelect 177almAckSelectedGroup 177almAckSelectedPriority 178almAckSelectedTag 178almAckTag 179almDefQuery 180almMoveWindow 180almQuery 181almSelectAll 182almSelectionCount 183almSelectItem 183almSelectPriority 184almSelectTag 185almSetQueryByName 185almShowStats 186almSuppressAll 186almSuppressDisplay 188almSuppressGroup 187almSuppressPriority 188almSuppressRetain 189almSuppressSelected 189almSuppressSelectedGroup 191almSuppressSelectedPriority 192almSuppressSelectedTag 192almSuppressTag 190almUnSelectAll 193almUnSuppressAll 193Error Messages 347Error Numbers 347

Alarm System Tagnames$AlarmPrinterError 20

$AlarmPrinterNoPaper 20$AlarmPrinterOffline 21$AlarmPrinterOverflow 21$NewAlarm 29$System 33

Application System Tagnames$ApplicationChanged 22$ApplicationVersion 22

DdBase Error Messages 363Dotfields

.Ack 44

.AckDev 44, 46

.AckROC 46

.AckValue 48

.Alarm 48

.AlarmAccess 50

.AlarmAckModel 50

.AlarmClass 52

.AlarmComment 52

.AlarmDate 54

.AlarmDev 54

.AlarmDevCount 56

.AlarmDevDeadband 56

.AlarmDevUnAckCount 57

.AlarmDisabled 57

.AlarmDsc 58

.AlarmDscCount 58

.AlarmDscDisabled 60

.AlarmDscEnabled 60

.AlarmDscInhibitor 61

.AlarmDscUnAckCount 61

.AlarmEnabled 63

.AlarmGroup 63

.AlarmGroupSel 64

.AlarmHiDisabled 64

.AlarmHiEnabled 65

.AlarmHiHiDisabled 65

.AlarmHiHiEnabled 66

.AlarmHiInhibitor 66, 68

.AlarmLimit 68

.AlarmLoDisabled 70

.AlarmLoEnabled 70

.AlarmLoInhibitor 70

.AlarmLoLoDisabled 72

.AlarmLoLoEnabled 72

.AlarmLoLoInhibitor 72

.AlarmMajDevDisabled 74

.AlarmMajDevEnabled 74

.AlarmMajDevInhibitor 75

.AlarmMinDevDisabled 75

.AlarmMinDevEnabled 77

.AlarmMinDevInhibitor 77

.AlarmName 79

.AlarmOprName 79

.AlarmOprNode 81

.AlarmPri 81

.AlarmProv 83

.AlarmROC 83


367

.AlarmROCCount 85

.AlarmROCDisabled 85

.AlarmROCEnabled 86

.AlarmROCInhibitor 86

.AlarmROCUnAckCount 88

.AlarmState 88

.AlarmTime 89

.AlarmTotalCount 89

.AlarmType 90

.AlarmUnAckCOunt 90



.AlarmUserDefStr 93

.AlarmValDeadband 94

.AlarmValue 94

.AlarmValueCount 95

.AlarmValueUnAckCount 95

.Caption 96

.ChartLength 96

.ChartStart 98

.Comment 98

.DevTarget 99

.DisplayMode 99

.Enabled 99

.EngUnits 101

.Freeze 101

.HiHiLimit 102

.HiHiSet 102

.HiHiStatus 103

.HiLimit 103

.HiSet 104

.HiStatus 104

.ListChanged 105

.ListCount 105

.ListIndex 106

.LoLimit 106

.LoLoLimit 108

.LoLoSet 109

.LoLoStatus 109

.LoSet 108

.LoStatus 111

.MajorDevPct 111

.MajorDevSet 112

.MajorDevStatus 112

.MaxEU 114

.MaxRange 114

.MaxRaw 116

.MinEU 116

.MinorDevPct 118

.MinorDevSet 118

.MinorDevStatus 119

.MinRange 119

.MinRaw 121

.Name 121

.NewIndex 123

.NextPage 123

.Normal 124

.NumAlarms 124

.OffMsg 126

.OnMsg 126

.PageNum 126

.Pen1-.Pen8 128

.PendingUpdates 131

.PrevPage 131

.PriFrom 133

.PriTo 133

.ProviderReq 133

.ProviderRet 135

.Quality 135

.QualityLimit 139

.QualityLimitString 139

.QualityStatus 139

.QualityStatusString 141

.QualitySubstatus 141

.QualitySubstatusString 143

.QueryState 143

.QueryType 143

.RawValue 145

.ReadOnly 145

.Reference 147

.ReferenceComplete 147

.ROCPct 148

.ROCSet 148

.ROCStatus 149

.ScooterLockLeft 149

.ScooterLockRight 151

.ScooterPosLeft 151

.ScooterPosRight 153

.Successful 153

.SuppressReatin 155

.TagID 155

.TimeDate 155

.TimeDateString 157

.TimeDateTime 157

.TimeDay 157

.TimeHour 158

.TimeMinute 158

.TimeMonth 158

.TimeMsec 159

.TimeSecond 159

.TimeTime 159

.TimeTimeString 161

.TimeYear 161

.TopIndex 161

.TotalPages 163

.UnAck 163

.UpdateCount 165

.UpdateInProgress 165

.UpdateTrend 167

.Value 167, 169

.Visible 170

EError Messages

Alarm Functions 347dBase 363Displaying Recipe Error Messages 349Oracle Database 362Recipe Functions 348SQL Server 362Sybase Database 362


368

Windows Control Functions 347Error Numbers

Alarm Functions 347Recipe Functions 348Windows Control Functions 347

FFieldbus Data Quality Specifications 135Functions

Abs 172Ack 172ActivateApp 173almAckAll 174almAckDisplay 174almAckGroup 174almAckPriority 176almAckRecent 176almAckSelect 177almAckSelectedGroup 177almAckSelectedPriority 178almAckSelectedTag 178almAckTag 179almDefQuery 180almMoveWindow 180almQuery 181almSelectAll 182almSelectGroup 182almSelectionCount 183almSelectItem 183almSelectPriority 184almSelectTag 185almSetQueryByName 185almShowStats 186almSuppressAll 186almSuppressDisplay 188almSuppressGroup 187almSuppressPriority 188almSuppressRetain 189almSuppressSelected 189almSuppressSelectedGroup 191almSuppressSelectedPriority 192almSuppressSelectedTag 192almSuppressTag 190almUnSelectAll 193almUnSuppressAll 193ArcCos 194ArcSin 194ArcTan 195ChangePassword 196Cos 197DialogStringEntry 197DialogValueEntry 199DText 201Exp 201FileCopy 203FileDelete 204FileMove 205FileReadFields 207FileReadMessage 208FileWriteFields 209

FileWriteMessage 210GetNodeName 211GetPropertyD 211GetPropertyI 212GetPropertyM 212Hide 213Hideself 213HTGetLastError 214HTGetPenName 215HTGetTimeAtScooter 215HTGetTimeStringAtScooter 216HTGetValue 217HTGetValueAtScooter 218HTGetValueAtZone 219HTScrollLeft 220HTScrollRight 220HTSelectTag 221HTSetPenName 221HTUpdateToCurrentTime 222HTZoomIn 222HTZoomOut 223InfoAppActive 224InfoAppTitle 224InfoDisk 225InfoFile 226InfoInTouchAppDir 227InfoResources 227Int 227IOGetApplication 228IOGetNode 229IOGetTopic 229IOReinitialize 229IOSetAccessName 230IOSetItem 231IOStartUninitConversations 232IsAnyAsynchFunctionBusy 232Log 233LogMessage 234LogN 234Logoff 234OLE_CreateObject 337OLE_IsObjectValid 338OLE_ReleaseObject 338Pi 235PlaySound 235PrintHT 236PrintWindow 237, 239RecipeDelete 241RecipeGetMessage 241RecipeLoad 243RecipeSave 244RecipeSelectNextRecipe 245RecipeSelectPreviousRecipe 246RecipeSelectRecipe 247RecipeSelectUnit 248ReloadWindowViewer 249RestartWindowViewer 249Round 250SendKeys 251SetPropertyD 252SetPropertyI 253


369

SetPropertyM 253Sgn 254Show 254ShowAt 255ShowHome 256ShowTopLeftAt 256Sin 257SLQRollback 280SPCConnect 257SPCDatasetDlg 258SPCDisconnect 258SPCDisplayData 259SPCLocateScooter 259SPCMoveScooter 260SPCSaveSample 260SPCSelectDataset 261SPCSelectProduct 261SPCSetControlLimits 262SPCSetMeasurement 262SPCSetProductCollected 263SPCSetProductDisplayed 263SPCSetRangeLimits 264SPCSetSpecLimits 264SQLAppendStatement 265SQLClearParam 265SQLClearStatement 265SQLClearTable 266SQLCommit 266SQLConnect 268SQLCreateTable 270SQLDelete 270SQLDisconnect 272SQLDropTable 272SQLEnd 272SQLErrorMsg 273SQLExecute 273SQLFirst 274SQLGetRecord 274SQLInsert 274SQLInsertEnd 275SQLInsertExecute 276SQLInsertPrepare 276SQLLast 277SQLLoadStatement 277SQLManageDSN 278SQLNext 278SQLNumRows 278SQLPrepareStatement 279SQLPrev 280SQLSelect 281SQLSetParamChar 284SQLSetParamDate 284SQLSetParamDateTime 284SQLSetParamDecimal 286SQLSetParamFloat 286SQLSetParamInt 286SQLSetParamLong 288SQLSetParamNull 288SQLSetParamTime 290SQLSetStatement 290SQLTransact 292

SQLUpdate 292SQLUpdateCurrent 294Sqrt 294StartApp 295StringASCII 296StringChar 297StringFromIntg 298StringFromReal 299StringFromTime 300StringFromTimeLocal 301StringInString 302StringLeft 303StringLen 304StringLower 304StringMid 305StringReplace 306StringRight 307StringSpace 308StringTest 309StringToIntg 310StringToReal 311StringTrim 312StringUpper 313Tan 313Text 314Troubleshooting 347Trunc 314TseGetClientID 315TseQueryRunningOnClient 316TseQueryRunningOnConsole 315wcAddItem 316wcClear 317wcDelete 317wcDeleteSelection 318wcErrorMessage 319wcFindItem 320wcGetItem 321wcGetItemData 322wcInsertItem 323wcLoadList 324wcLoadText 325wcSaveList 326wcSaveText 327wsSetItemData 328WWControl 329WWExecute 330WWPoke 331WWRequest 332

GGOT Functions

GetPropertyD 211GetPropertyI 212GetPropertyM 212SetPropertyD 252SetPropertyI 253SetPropertyM 253


370

HHistorical Dotfields

.ChartLength 96

.ChartStart 98

.DisplayMode 99

.MaxRange 114

.MinRange 119

.Pen1-.Pen8 128

.ScooterLockLeft 149

.ScooterLockRight 151

.ScooterPosLeft 151

.ScooterPosRight 153

.UpdateCount 165

.UpdateInProgress 165

.UpdateTrend 167Historical Functions

HTGetLastError 214HTGetPenName 215HTGetTimeAtScooter 215HTGetTimeStringAtScooter 216HTGetValue 217HTGetValueAtScooter 218HTGetValueAtZone 219HTScrollLeft 220HTScrollRight 220HTSelectTag 221HTSetPenName 221HTUpdateToCurrentTime 222HTZoomIn 222HTZoomOut 223PrintHT 236

Historical System Tagnames$HistoricalLogging 25

II/O

Tagname Types 36Internal System Variables 19

MMath Functions

Abs 172ArcCos 194ArcSin 194ArcTan 195Cos 197Exp 201Int 227Log 233LogN 234Pi 235Round 250Sgn 254Sin 257Sqrt 294Tan 313Trunc 314

Miscellaneous Functions

DialogStringEntry 197DialogValueEntry 199Hide 213Hideself 213IOGetApplication 228IOGetNode 229IOGetTopic 229IOReinitialize 229IOSetAccessName 230IOSetItem 231IOStartUninitConversations 232LogMessage 234PlaySound 235PrintWindow 237, 239SendKeys 251Show 254ShowAt 255ShowHome 256ShowTopLeftAt 256WWControl 329

OOLE for Process Control (OPC) 135OLE_CreateObject Function 337OLE_IsObjectValid Function 338OLE_ReleaseObject Function 338Oracle Database Error Messages 362

QQuality flags 135QuickScript Functions 171

RRecipe Functions

Displaying Error Messages 349Error Messages 348Error Numbers 348RecipeDelete 241RecipeGetMessage 241, 349RecipeLoad 243RecipeSave 244RecipeSelectNextRecipe 245RecipeSelectPreviousRecipe 246RecipeSelectRecipe 247RecipeSelectUnit 248Troubleshooting 348

RecipeGetMessage 349

SSecurity Functions

ChangePassword 196, 234Security System Tagnames

$AccessLevel 19$ChangePassword 23$ConfigureUsers 23$InactivityTimeout 26$InactivityWarning 27


371

$Operator 30$OperatorEntered 31$PasswordEntered 32

SPC DDE Item NamesControl and Display 350Current Sample 352Manual Input 356Selection 357

SPC FunctionsSPCConnect 257SPCDatasetDlg 258SPCDisconnect 258SPCDisplayData 259SPCLocateScooter 259SPCMoveScooter 260SPCSaveSample 260SPCSelectDataset 261SPCSelectProduct 261SPCSetControlLimits 262SPCSetMeasurement 262SPCSetProductCollected 263SPCSetProductDisplayed 263SPCSetRangeLimits 264SPCSetSpecLimits 264

SQL FunctionsConnectionID Variable 268ConnectString Variable 268Result Code Error Messages 360ResultCode 360SLQRollback 280SQLAppendStatement 265SQLClearParam 265SQLClearStatement 265SQLClearTable 266SQLCommit 266SQLConnect 268SQLCreateTable 270SQLDelete 270SQLDisconnect 272SQLDropTable 272SQLEnd 272SQLErrorMsg 273, 360SQLExecute 273SQLFirst 274SQLGetRecord 274SQLInsert 274SQLInsertEnd 275SQLInsertExecute 276SQLInsertPrepare 276SQLLast 277SQLLoadStatement 277SQLManageDSN 278SQLNext 278SQLNumRows 278SQLPrepareStatement 279SQLPrev 280SQLSelect 281SQLSetParamChar 284SQLSetParamDate 284SQLSetParamDateTime 284SQLSetParamDecimal 286

SQLSetParamFloat 286SQLSetParamInt 286SQLSetParamLong 288SQLSetParamNull 288SQLSetParamTime 290SQLSetStatement 290SQLTransact 292SQLUpdate 292SQLUpdateCurrent 294

SQL Server Error Messages 362SQLErrorMsg 360states of quality 136String Functions

DText 201StringASCII 296StringChar 297StringFromIntg 298StringFromReal 299StringFromTime 300StringFromTimeLocal 301StringInString 302StringLeft 303StringLen 304StringLower 304StringMid 305StringReplace 306StringRight 307StringSpace 308StringTest 309StringToIntg 310StringToReal 311StringTrim 312StringUpper 313Text 314

Substatus Bit-Field 139Sybase Database Error Messages 362System Functions

ActivateApp 173FileCopy 203FileDelete 204FileMove 205FileReadFields 207FileReadMessage 208FileWriteFields 209FileWriteMessage 210GetNodeName 211InfoAppActive 224InfoAppTitle 224InfoDisk 225InfoFile 226InfoInTouchAppDir 227IsAnyAsynchFunctionBusy 232ReloadWindowViewer 249RestartWindowViewer 249StartApp 295

System Tagnames$AccessLevel 19$AlarmPrinterError 20$AlarmPrinterNoPaper 20$AlarmPrinterOffline 21$AlarmPrinterOverflow 21


372

$ApplicationChanged 22$ApplicationVersion 22$ChangePassword 23$ConfigureUsers 23$Date 24$DateString 24$DateTime 24$Day 25$HistoricalLogging 25$Hour 26$InactivityTimeout 26$InactivityWarning 27$LogicRunning 27$Minute 28$Month 28$Msec 28$NewAlarm 29$ObjHor 29$ObjVer 29$Operator 30$OperatorEntered 31$PasswordEntered 32$Second 32$StartDdeConversations 32$System 33$Time 33$TimeString 33$VerifiedUserName 34$Year 34

TTagname Dotfields

.Comment 98

.EngUnits 101

.MaxEU 114

.MaxRaw 116

.MinEU 116

.MinRaw 121

.Name 121

.OffMsg 126

.OnMsg 126

.Quality 135

.QualityLimit 139

.QualityLimitString 139

.QualityStatus 139

.QualityStatusString 141

.QualitySubstatus 141

.QualitySubstatusString 143

.RawValue 145

.Reference 147

.ReferenceComplete 147

.TagID 155

.TimeDate 155

.TimeDateString 157

.TimeDateTime 157

.TimeDay 157

.TimeHour 158

.TimeMinute 158

.TimeMonth 158

.TimeMsec 159

.TimeSecond 159

.TimeTime 159

.TimeTimeString 161

.TimeYear 161

.Value 167Tagname Type Matrix 38Tagname Types 35

I/O 36I/O Discrete 36I/O Integer 37I/O Real 37

IndirectIndirect Analog 37Indirect Discrete 37Indirect Message 37

Memory 36Memory Discrete 36Memory Integer 36Memory Message 36Memory Real 36

Miscellaneous 37Hist Trend 37SuperTags 38Tag ID 37

Terminal Services FunctionsTseGetClientID 315TseQueryRunningOnClient 316TseQueryRunningOnConsole 315

TroubleshootingFunctions 347Recipe Functions 348SQL Functions 360

WWindows Control Dotfields

.Caption 96

.Enabled 99

.ListCount 105

.ListIndex 106

.NewIndex 123

.ReadOnly 145

.TopIndex 161

.Value 169

.Visible 170Windows Control Functions

Error Messages 347Error Numbers 347wcAddItem 316wcClear 317wcDelete 317wcDeleteSelection 318wcErrorMessage 319, 347wcFindItem 320wcGetItem 321wcGetItemData 322wcInsertItem 323wcLoadList 324wcLoadText 325wcSaveList 326wcSaveText 327


373

wsSetItemData 328WWDDE Functions

WWExecute 330WWPoke 331WWRequest 332


374 Index


Documents

Intouch(R) Reference Guide - wccandm.services · Wonderware® FactorySuite™ InTouch® Reference Guide Revision A Last Revision: September 2002 Invensys Systems, Inc