HMI Visual Basic Scripting Language

Application Note www.icstriplexisagraf.com February 2004 ISaGRAF is a hybrid control system in which real-time control is executed on target nodes running real-time operating systems, and configuration and HMI are executed on Windows nodes. ISaGRAF allows you to program real-time controls in any of the five IEC61131-3 programmable control languages or in the flow chart language. These languages can also be used to carry out calculations for use in the HMI, but this is not considered to be a good engineering practice. Good practice dictates that only control functions should be executed on the control nodes, and that all calculations necessary only for HMI be executed on the HMI nodes. Prerequisites Before starting, you need to open or create a project. The project must be connected to an OPC server. To configure an OPC Server 1. From the Tools menu, select Servers. 2. Open the Servers Editor, and configure your OPC server (refer to online the help guide for the OPC Servers topic or the Getting Started guide for more information). Examples of calculations that should be done on the HMI include unit conversion for display, formatting and printing reports, managing dialog boxes and user input and data base access. Since the HMI runs on Windows, the language of choice for programming custom HMI functions is Visual Basic (VB). The HMI s Visual Basic (VB) scripting capabilities allow you to write scripts that will be executed periodically, when an OPC variable changes value or when the user moves the mouse over a graphic object or clicks on the object. This technical note describes how to write VB scripts within the HMI. Note: In this application note, you will find the symbol indicating that a line of code extends to the next line. Do not enter this symbol in your code. HMI Visual Basic Scripting Language Table of Contents Prerequisites... 1 Your First Script... 1 Reading and Writing from Variables in an OPC Server3 Assigning a VB Variable Name to OPC Variables3 Variables Editor... 4 Accessing OPC variables from VB Script... 4 Accessing Global VB Variables from the HMI... 4 Change-triggered Scripts... 5 Controlling Graphic Elements via a Script... 5 Calling Excel to Generate a Report... 6 Using an ActiveX Control... 7 Using a Third-party ActiveX Control... 7 Your First Script You must first create or open a mimic on which you will place a graphic element to which you will attach a script. In this example, a button. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 1

To name the button 1. From the Display menu, select Properties List. 2. Type in the name you want (in this case MyButton) instead of the default name. Next, you enter some VB codes, for instance: Private Sub MyButton_Click() Call MsgBox( "MyButton has been clicked") To run the sample script VB scripts will not execute while the Script Editor is in Design mode. You toggle the Design mode on and off using the Design Mode button: Next, you create the VB script for the button. To create a VB Script for the button 1. Right-click MyButton. 2. From the contextual menu, select View Script. The Script Editor appears. This is so that you can turn off VB execution while you work on a script. 1. In Script Editor environment, from the Display menu, select HMI. 2. In the HMI environment, from the Mode menu, select Run. 3. Click MyButton. A message box appears. Note: This message box is modal which means it remains on top of other windows until you click it. The script editor lets you enter the VB script for your button. You must select one of Click, DblClick, MouseEnter, MouseDown, MouseUp, or MouseLeave from the drop-down menu. For example, if you select Click, the editor generates an empty subroutine: Private Sub MyButton_Click() 4. Click OK. Note: When an error occurs, the HMI automatically disables the script engine and returns to Design Mode. Once the error is fixed, you can return to Run mode to execute your scripts. Note: When you first open the editor, the selection Click appears in the pick list, but it is not actually selected. You have to click on the pick list and double-click on Click so that the editor will generate the empty subroutine call. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 2

Reading and Writing from Variables in an OPC Server VB scripts are not limited to user interface. They also have access to OPC variables, that is, the script can read values from an OPC server which retrieves these values directly from the runtime, perform calculations and write values back to the OPC server and therefore to the runtime. This means that VB scripts are powerful enough to be used for actual process control. However, it is not recommended that VB scripts be used for real-time process control because execution time cannot be guaranteed. To use OPC variables within a script, you must first declare them in the Variables collection using the script editor. The declaration of a variable has three parts: The variable name: a user-friendly name that will be used in the script code to refer to the resultant variable object. The reference name: the name used in runtime (by the script editor) to subscribe, read, write and unsubscribe to the variable. The expected variable type: as VB does not own the variable (the OPC server does) and as VB may not be connected to the runtime server that serves it, this expected type is a useful information to know what type of properties can be accessed from this variable. The expected variable type can be: "Any", "Bit", "Register" or "Text". Assigning a VB Variable Name to OPC Variables To read and write OPC variables, the first step is to establish equivalence between the OPC tags and VB variable names. You will then be able to read and write the OPC variables using the VB variable name. To assign a Visual Basic variable name to OPC variables 2. Right-click These Variables as Variables, then from the contextual menu, select Edit The Variables Editor appears. 3. To declare a new variable, double-click New Alias and type the variable s name. 4. Click on the Reference Name column beside the new variable s name to activate the drop-down menu for selecting an OPC variable from the OPC Variable Browser. Note: An OPC Server must be configured. 5. Select an OPC variable, then click Apply. 6. In the Variables editor, select an Expected Type from the list. Choose from any, bit, register and text depending on the type of variable. Note: When expected type is set to Any, only properties that are common to all other types will be accessible in the script code. 1. In the Script Editor, select the Object tab. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 3

Variables Editor You can perform many tasks in the Variables Editor: Add a new variable, by double-clicking New Alias Delete a variable, by right-clicking the variable and selecting Delete Variable from the contextual menu Copy/Paste a variable, by right-clicking the variable and selecting Copy Variable then Paste Variable from the contextual menu Choose/modify the name of the variable, by directly filling in the variable name field Choose/modify the reference name of the variable, by directly filling in the reference name field, or by clicking on the button that appears in the reference name column when a variable is selected (this will launch the variable browser), or by right-clicking the variable and selecting Select Reference Name from the contextual menu. Choose/modify the expected type of the variable, by selecting the expected type in the dropdown menu in the Expected Type field. Enable/disable events for a variable: If the checkbox near the variable name of a particular variable is checked then, events (on value changes for example) will be fired and script associated to this variable will be performed. If the box is unchecked, events will not be fired and associated script will not be performed. Note: When the expected type chosen for a variable does not match the type handled for this variable in the cluster, the status property of this variable will be set to config_error and no "write value" operation will be performed during script execution. Accessing OPC variables from VB Script The following example illustrates the syntax for accessing an OPC variable from a VB script: Private Sub MyButton_Click() Call MsgBox( "Writing var1 to var2", 0) TheseVariables.Item("var2").value = TheseVariables.Item("var1").value value to TheseVariables("var2") as a shortcut. This works for reading the variable but not for writing it. The above script pops up a message box and waits for the user to acknowledge. Then it reads the value of var1 and copies it to var2. Since an OPC variable is actually a complex variable type, access is not limited to its value. Other properties such as MaximumValue, MinimumValue, SecurityLevel, Status, Type, Units can be read but not written from a script while others, such as, UserData and EnableEvents are read/write accessible. For instance: TheseVariables.Item("var2").EnableEvents = True can be used to turn on event handling on var2, i.e. it would call the VB sub var2_value_change() every time the value of var2 changes. Accessing Global VB Variables from the HMI The only way to have global variables (visible to multiple VB modules and visible to the HMI is to create them in TheseVariables. To create global variables In the Script Editor, in the Object tab, right-click These Variables as Variables The Variables Editor appears. Instead of giving the global variables the reference name of an OPC item, type in the variable name followed by a percent sign. Thus the variable n has the reference name n%. To access the variable from within a VB script use the usual VB syntax: TheseVariables.Item("n").value = 3 You can shorten the reference TheseVariables.Item("var2"). reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 4

To access the variable for use in an HMI animation or an HMI send 1. In the HMI environment, from the Animate menu, select Text, then Display Register. The Text Properties window appears. 2. In the Display Register tab, type the variable s reference name preceded by @, for example: @n%. Controlling Graphic Elements via a Script A VB script can control a graphic element. For example, the following script causes MyButton to change shape every time you click it: Private Sub MyButton_Click() TestButton.Item("MyButton").Width = 200 MyButton.Width = MyButton.Width + 1 If MyButton.Width > 300 Then MyButton.Width = MyButton.Width - 100 End If MyButton.Height = MyButton.Height + 1 If MyButton.Height > 40 Then MyButton.Height = MyButton.Height - 20 End If Change-triggered Scripts A change-triggered script runs whenever the value of its trigger variable changes. To write a change-triggered script 1. From the Script Editor menu, select the Object tab. 2. Double-click the variable that you want to use as its trigger variable from the tree view. 3. Choose ValueChange from the script dropdown menu. This creates an empty subroutine: Private Sub var1_valuechange() 4. Fill in the script. The following script copies the value of var1 to var2 every time the value of var1 changes. Private Sub var1_valuechange() TheseVariables.Item("var2").value = TheseVariables.Item("var1").value Note: Make sure var1.enableevents is True otherwise the event handler will not be called. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 5

Calling Excel to Generate a Report The following script opens Excel, reads an Excel file and uses the file as a template to format and print a report: Private Sub PrnRprtBtn6_Click() 'activates a dialog box Begin Dialog ButtonSample 16,32,180,60,"Microsoft" _ & "Excel" OKButton 132,8,40,14 CancelButton 132,28,40,14 Text 10,10,120,150,"Click on OK if you have " _ & "Microsoft Excel installed." Text 10,40,120,150,"Otherwise, click on Cancel" End Dialog 'declares dialog box variable as Dlg1 Dim Dlg1 As ButtonSample Button = Dialog (Dlg1) If button = 0 Then Exit Sub Set MyExcel= GetObject("C:\Program Files\ISaGRAF " _ & "\Hmi\Projects" & "\FermDemo\Template " _ & "Files\report.xls") 'makes Excel visible while printing MyExcel.Application.visible = True Set MyBook = MyExcel.Application.Workbooks _ ("report.xls") MyBook.Windows(1).Visible = True 'writes data into the cells of the template Set MySheet = MyBook.Worksheets("Sheet1") 'makes worksheet visible MySheet.Visible = True MySheet.Activate MySheet.cells( 3, 2).value = TheseVariables.Item _ ("ctr_txt").value MySheet.cells( 4, 2).value = TheseVariables.Item _ ("step").value MySheet.cells( 5, 2).value = TheseVariables.Item _ ("mode").value MySheet.cells( 7, 2).value = TheseVariables.Item _ ("total").value MySheet.cells( 8, 2).value = TheseVariables.Item _ ("ferm_temp").value MySheet.cells( 9, 2).value = TheseVariables.Item _ ("ferm_ph").value MySheet.cells(10, 2).value = TheseVariables.Item _ ("ferm_level").value Set MySheet = Nothing Set MyBook = Nothing Set MyExcel = Nothing You can use the above script as a starting point for your own report generator. Determining what data goes into the report is done in the script. To modify the format, simply open report.xls with Excel, make the desired changes and save. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 6

Using an ActiveX Control Since the HMI is an ActiveX container, ActiveX controls can be linked directly to global variables or OPC variables. The following example uses a Microsoft Slider control to set a Global variable: To use the slider to control n we need to add one line of VB code: Private Sub Slider1_Change() TheseVariables.Item("n").value = Slider1.value Note: The word "control" as used with "ActiveX" has nothing to do with industrial control. It denotes a "widget", that is, a graphic user element intended for interaction with the operator. Using a Third-party ActiveX Control In this example, the slider is used to set the value of global variable n. The button marked "increment n" is used to manually change the value of n to show that the slider refreshes itself properly when n changes under program control. You configure the slider to read the value of n by entering @n% into the Value field in the Variables Links tab of the Properties List window in the HMI. To access the Properties List From the Display menu, select Properties List. You can use third-party ActiveX controls (also called ocx) quite easily. To use an ActiveX, make sure that you have selected a Mimic and that the Mimic is in Design Mode. To add a third-party ActiveX control 1. Copy the ocx file to your hard disk; the location is unimportant as the registry will look after it. However, do not move it after you register it. 2. In the Windows Explorer, right-click the ocx file and from the contextual menu, select Open. If it is the first time that you have registered an ocx, then Windows may prompt for a program with which to open it. If this happens, refer to the online help guide on how to register an ActiveX. Once completed, RegSrv should reply with a message that resembles this: DllRegisterServer in C:\ProgramFiles\ISaGRAF\Program\ activex_name.ocx has succeeded. 3. In the HMI, from the Tools menu, select Preferences, then ActiveX Controls. The ActiveX Controls Configuration window appears. You can connect the Slider to an OPC variable rather than a global variable by choosing from the browser that appears when you click on the Value field. 4. Select the new ocx in the Installed ActiveX Controls browser, then click >> to move it to the Approved ActiveX Controls browser. Note: The name of the Control in the list is not necessarily the same as the filename. reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 7

5. Click OK. 6. From the Insert menu, select Favorites ActiveX Controls, then your object. The following example uses a trend link control supplied with the ISaGRAF Trends package: Conclusion This document serves as an introduction to the HMI Scripting Language feature. It should give you enough information to get started. It is recommended that you acquire a textbook on Visual Basic if you intend to do a lot of programming. The trend link control is inserted on Mimic1. The Start button activates the following script which starts the trend graph: Private Sub StartButton_Click() TrendDisplay.TrendGraph.LiveMode = True The Stop button activates the following script to stope the trend graph: Private Sub StopButton_Click() TrendDisplay.TrendGraph.LiveMode = False reproduced in any form or by any means, without the prior written permission of ICS Triplex ISaGRAF Inc. 8