KEYWORDS DDE GETOBJECT PATHNAME CLASS VB EDITOR WITHEVENTS HMI 1.0 TYPE LIBRARY HMI.TAG

Transcription

1 Document Number: IX_APP00113 File Name: SpreadsheetLinking.doc Date: January 22, 2003 Product: InteractX Designer Application Note Associated Project: GetObjectDemo KEYWORDS DDE GETOBJECT PATHNAME CLASS VB EDITOR WITHEVENTS HMI 1.0 TYPE LIBRARY HMI.TAG While precautions have been taken in the preparation of this note, CTC 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. This document is a tutorial on the following topics: What is DDE? What does the GetObject function do? Lesson 1: Setting up Excel for linking to InteractX Lesson 2: How to display tag data from InteractX in Excel Lesson 3: How to write tag data from Excel into InteractX Lesson 4: How to launch Excel from InteractX Runtime Lesson 5: How to start and stop tag data updates from InteractX within Excel Lesson 6: Applying what you learned What is DDE? Dynamic Data Exchange is an established protocol for exchanging data between Microsoft Windows-based programs. The DDE protocol is a set of messages and guidelines that sends messages between applications that share data. It uses shared memory to exchange data between applications. Applications can use the DDE protocol for one-time data transfers and for continuous exchanges in which applications send updates to one another as new data becomes available. DDE is most useful for data exchanges that do not require ongoing user interaction. Usually, an application provides a method for the user to establish the link between the applications exchanging the data. Once that link is established, the applications exchange data without further user involvement. DDE can be used to implement a broad range of application features for example: Linking to real-time data, such as to stock market updates Performing data queries between applications, such as a spreadsheet querying a database for accounts past due What does the GetObject function do? The GetObject function is a powerful tool that, simply stated, is used to return a reference to an object provided by an ActiveX component. That object is frequently associated with a document or file. In this case, the object we are interested in discussing is our HMI Application object. The HMI Application object is only available for reference while the InteractX Runtime system is running. Page: 1

2 The GetObject function s syntax is: GetObject([pathname] [,class]), where Pathname Variant (String). The full path and name of the file containing the object to retrieve. This is an optional parameter. If pathname is omitted, class is required. Class Variant (String). A string representing the class of the object. The class argument uses the syntax appname.objecttype and has these parts: Appname Variant (String). The name of the application providing the object. This is required. Objecttype Variant (String). The type or class of object to create. This is required. For example: Dim MyApp As HMI.Application appname Set MyApp = GetObject(, HMI.Application ) objecttype class Use the GetObject function when there is a current instance of the object or if you want to create the object with a file that is already loaded. The following series of steps and examples will help demonstrate the GetObject functionality more clearly. Lesson 1: Setting up Excel for linking to InteractX After launching Excel, click on the Tools item in the main menu. Place the mouse over Macro to expand its options, and then select Visual Basic Editor. This action will launch the Microsoft Visual Basic Editor. Page: 2

3 Next, click on the Tools item in the main menu of the Microsoft Visual Basic Editor and select the References option. In the References dialog box, find the HMI 1.0 Type Library. There may be two separate instances listed in the selection box. Highlight them one at a time to check the Location description at the bottom. The correct Library is the one showing a location path in the directory where InteractX is installed. Select this instance of the HMI 1.0 Type Library by checking the box to the left and clicking the OK button. Page: 3

4 In the Project Explorer window to the left, double click on the Sheet1 (Sheet1) option to open the Code window. You can also highlight the Sheet1 (Sheet1) option and click View, then Code from the main menu. Lesson 2: How to display tag data from InteractX in Excel Set up a simple InteractX application with an Exit button, a Maintained button, and a Numeric Display on a panel. Assign tag1 to the Numeric Display s output. Assign the _HMI_ShowFrame system tag to the Maintained button s input and output. Finally, set up the Communications to use the Simulator device driver. In the Tag Editor, configure tag1 with a ramp function to simulate rapid value changes. Use an address such as: Channel1.Device1.ramp(100,0,100,1). You are now ready to write some sample VB code that will allow you to display tag1 s values in both the Numeric Display in Runtime and in your Excel worksheet. Don t forget to reference the HMI 1.0 Type Library in Excel s VB Editor, as we described before. After you finish entering the code, make sure you save it and then close the Excel application. It may be helpful to save your workbook in the same folder as the InteractX application you created above. Start by declaring tag1 as a variable. The WithEvents keyword specifies that GetObject.xls is an object variable used to respond to events triggered by our InteractX application. We are linking the tag in Excel with the tag in InteractX. By declaring it WithEvents, it will now appear in the Object dropdown control in the top left. Dim WithEvents tag1 As HMI.Tag Select the Worksheet option from the leftmost dropdown control, then Activate from the one on the right. The code will be automatically inserted like this: Private Sub Worksheet_Activate() Next, we will use some simple error handling for the purposes of this lesson. Page: 4

5 Now we are ready to apply the GetObject function. We are also checking whether InteractX Runtime is running or not. We will add a simple message box as a reminder that Runtime should be launched before executing the code. Dim App As HMI.Application Set App = GetObject(, "HMI.Application") If App Is Nothing Then MsgBox "InteractX Runtime is not running." We will now retrieve the tag data from InteractX and make sure it is linked to our tag in Excel before ending the sub-routine. Else Set tag1 = App.Tags("tag1") Select the tag1 option from the leftmost dropdown control, then ChangeValue from the one on the right. The code will be automatically inserted in a separate section. Private Sub tag1_changevalue(byval NewValue As Variant) We again use our simple form of error handling. The goal in this last part of the code is to link events in InteractX to events in the worksheet. When the value of tag1 changes in Runtime, it will also change in the worksheet. The updated values will be displayed in cell B1. Range("B1").Value = NewValue Your finished product should look something like this: Dim WithEvents tag1 As HMI.Tag Private Sub Worksheet_Activate() Dim App As HMI.Application Set App = GetObject(, "HMI.Application") If App Is Nothing Then MsgBox "InteractX Runtime is not running." Else Set tag1 = App.Tags("tag1") Private Sub tag1_changevalue(byval NewValue As Variant) Range("B1").Value = NewValue Page: 5

6 You are now ready to test it out. Launch Runtime of your application. You should see the Numeric Display tool quickly counting up to 100 and resetting itself back to 0. Press the _HMI_ShowFrame Maintained button and resize your window so that part of your desktop is visible. Launch Excel and open the workbook where you wrote your VB script. Simply opening your workbook will not run your code. In this example, you must activate your worksheet to execute the code. You may do so by clicking on the Sheet2 tab and clicking back on the Sheet1 tab, thus activating it. Now you should see that cell B1, as we specified in the code, displays the same tag values as the Numeric Display in Runtime. Lesson 3: How to write tag data from Excel into InteractX Set up another simple InteractX application with an Exit button, a Maintained button, a Numeric Display, and a Message Display on a panel. Assign tag1 to the Numeric Display s output and tag2 to the Message Display s output. Assign the _HMI_ShowFrame system tag to the Maintained button s input and output, like before. Open a new Excel workbook, launch the VB Editor and remember to reference the HMI 1.0 Type Library. With the sample VB code below, the tag data you enter in the Excel worksheet will also be written to the tags in your InteractX application. You will then see your tag values displayed on the tools in Runtime. With this example, you will be able to enter a numeric value for the Numeric Display and a string value for the Message Display directly into Excel. After you finish entering the code, make sure you save it, then close the Excel application, but not before saving your workbook in the same folder as the InteractX application. Start by declaring tag1 and tag2 as variables. We are now associating the tags in Excel with the tags in InteractX. Dim tag1 As HMI.Tag Dim tag2 As HMI.Tag Select the Worksheet option from the leftmost dropdown control, then Activate from the one on the right. The code will be automatically inserted like this: Private Sub Worksheet_Activate() Some simple error handling for this lesson Use the GetObject function and check whether or not InteractX Runtime is running. The message box will let you know if it is not. Dim App As HMI.Application Set App = GetObject(, "HMI.Application") If App Is Nothing Then MsgBox "InteractX Runtime is not running." We will now link the tags in Excel to the tags in InteractX. Else Set tag1 = App.tags("tag1") Set tag2 = App.tags("tag2") Page: 6

7 Select the Worksheet option in the leftmost dropdown above, then Change in the dropdown to the right. The code will be automatically inserted like this: Private Sub Worksheet_Change(ByVal Target As Range) The code below will detect if there is a change in the content of cell B1 and ensure that our tag1 variable is initialized. If both of these conditions are true, then the new value is written to tag1, which the Numeric Display will then reflect in Runtime. If Target.Count = 1 Then If Target = Range("B1") And Not (tag1 Is Nothing) Then tag1.value = Target.Value Similarly, we check for a change in the content of cell B2 and make sure that our tag2 variable is initialized. If both conditions hold true, then this new value will be written to tag2 and shown in the Message Display. ElseIf Target = Range("B2") And Not (tag2 Is Nothing) Then tag2.value = Target.Value Your finished product should look like this: Dim tag1 As HMI.Tag Dim tag2 As HMI.Tag Private Sub Worksheet_Activate() Dim App As HMI.Application Set App = GetObject(, "HMI.Application") If App Is Nothing Then MsgBox "InteractX Runtime is not running." Else Set tag1 = App.tags("tag1") Set tag2 = App.tags("tag2") Private Sub Worksheet_Change(ByVal Target As Range) If Target.Count = 1 Then If Target = Range("B1") And Not (tag1 Is Nothing) Then tag1.value = Target.Value ElseIf Target = Range("B2") And Not (tag2 Is Nothing) Then tag2.value = Target.Value Page: 7

8 Let s test it out. Launch Runtime of your application. Press the _HMI_ShowFrame Maintained button and resize your window so that part of your desktop is visible. Launch Excel and open the workbook where you wrote your VB script. You will have to activate your worksheet, like in the previous example, by clicking on the Sheet2 tab and then clicking back on the Sheet1 tab. In your worksheet, click on cell B1 and enter a number between 0 and 100. You should see the Numeric Display in Runtime reflect this value as well. Now, click on cell B3 and enter a word, such as hello. The Message Display in Runtime should update to reflect the string you entered. Lesson 4: How to launch Excel from InteractX Runtime The next two lessons are optional and enhance the code we learned above by adding some useful features. In the first one, we will add a button to our panel and configure it to launch the Excel workbook that links to the InteractX application in Runtime. Open the InteractX application you created for Lesson 3 and enable VBA for that panel. Add a Momentary button, right mouse click on it to bring up the context sensitive menu, or CSM, and select the View Code option. This action causes the VB Editor to launch and automatically enters the ButtonPressed event for the Momentary button. It is helpful to rename your button to something more descriptive or indicative of its function. Private Sub LaunchExcel_ButtonPressed() We will now use the GetObject function to retrieve an instance of the Excel Workbook object associated with the worksheet we previously created. In other words, we are using the GetObject function to get a reference to a specific Microsoft Excel worksheet. In this example, we are using the pathname parameter of the GetObject function. The following code employs a shortcut for the pathname which relies on the desired Excel workbook existing in the InteractX application folder. Application.Path returns the path of the InteractX application currently running and the last part appends the name of the desired Excel workbook, found in the application folder. Dim WorkBook As Object Set WorkBook = GetObject(Application.Path & "GetObject.xls") You could also use the entire path of the workbook as the pathname parameter of the GetObject function, especially if you had saved your workbook somewhere other than the InteractX application folder. Simply add quotation marks around the path, like this: Dim WorkBook As Object Set WorkBook = GetObject("C:\Program Files\InteractX\ Applications\GetObjectDemo\ GetObject.xls") The next line of code will tell Excel to become visible. We use the worksheet s Application property to make Microsoft Excel visible by invoking its Visible property. This property can be set to either True or False and thus show or hide the object. WorkBook.Application.Visible = True Page: 8

9 We also want to tell the Excel to continue running after our variables go out of scope by making sure the UserControl property is True, otherwise Microsoft Excel will quit when the last object in the session is released. This happens because when the UserControl property of an object is False, the object is released when the last reference to the object is released. WorkBook.Application.UserControl = True We will use the Activate method in order to bring our Excel workbook to the front of the z-order. One useful example of this is if you were running InteractX Runtime in full screen mode and placed focus on it. You would no longer be able to view the Excel workbook that you launched, as it would go to the background. Through the Activate method, we could place focus on the workbook and bring it to the foreground simply by clicking on our original Momentary button. WorkBook.Application.Windows("GetObject.xls").Activate The last part of the code simply launches Microsoft Excel. We prefer to do this at the end so that, once Excel is launched, the window that comes to the front has already found and opened the specified workbook. The AppActivate function activates and changes focus to the specified application window. We tell it what to activate by specifying the title displayed in the title bar of the application window, which in this case is Microsoft Excel. AppActivate "Microsoft Excel" Your finished product should look like this: Private Sub LaunchExcel_ButtonPressed() Dim WorkBook As Object Set WorkBook = GetObject(Application.Path & " GetObject.xls") WorkBook.Application.Visible = True WorkBook.Application.UserControl = True WorkBook.Application.Windows("GetObject.xls").Activate AppActivate "Microsoft Excel" In order to test it, launch Runtime of your application. Press the newly created LaunchExcel button. You should see the specified Excel workbook come to the foreground in a new window. Place focus back on your InteractX Runtime panel and you should see the Excel window hide in the background. Press the LaunchExcel button again and our Excel workbook window comes to the foreground again. Lesson 5: How to start and stop tag data updates from InteractX within Excel In this lesson, we are going to add some code to help us start and stop the tag data updates on the worksheet. By doing so, we will not have to switch focus to a different worksheet and back to activate the code. We can easily control when the worksheet should update with the tag data and when it should not. You may use the InteractX application you created in Lesson 2, but you should open a new Excel workbook and save it in the application folder. Enter the word START in cell D1 and STOP in cell E1. Once you launch Excel s VB Editor, remember to reference the HMI 1.0 Type Library. Page: 9

10 Declare GetObject.xls using the WithEvents keyword in order to make it an object variable responding to events triggered by our InteractX application. It will now appear in the Object dropdown control in the top left. Dim WithEvents tag1 As HMI.Tag Select the Worksheet option in the leftmost dropdown above, then SelectionChange in the dropdown to the right. The code will be automatically inserted like this: Private Sub Worksheet_SelectionChange(ByVal Target As Range) We detect if there is a change in the selection of cells in the worksheet. In other words, clicking or highlighting different cells. If the specific cell D1, or START, is clicked on, then our code will run. Clicking on cell D1 will execute the GetObject function to see if InteractX Runtime is running and to get tag data. With Target.Count =1, we ensure that the code will only execute when the single cell D1 is clicked on and not when it is part of a group of highlighted cells. If Target.Count = 1 Then If Target = Range("D1") Then Dim App As HMI.Application Set App = GetObject(, "HMI.Application") Link the tags in the Excel worksheet to the tags in InteractX to retrieve tag data: Set tag1 = App.Tags("tag1") Once again, we are detecting if there is a change in the selection of cells in the worksheet. We have another condition stating that if cell E1, or the STOP cell is the one selected, then we are no longer interested in receiving the tag data from the InteractX application. The link between the application and the worksheet is essentially dissolved. ElseIf Target = Range("E1") Then Set tag1 = Nothing Select the tag1 option from the Object dropdown control on the left, then ChangeValue from the one on the right. The code will be automatically inserted in a separate section. Private Sub tag1_changevalue(byval NewValue As Variant) We conclude by linking the events in InteractX to events in the worksheet. When the value of tag1 changes in Runtime, it will also change in the worksheet. The updated value will be displayed in cell B1 each time it changes. We also add our form of simple error handling. Range("B1").Value = NewValue Page: 10

11 Your finished product should look like this: Dim WithEvents tag1 As HMI.Tag Private Sub Worksheet_SelectionChange(ByVal Target As Range) If Target.Count = 1 Then If Target = Range("D1") Then Dim App As HMI.Application Set App = GetObject(, "HMI.Application") Set tag1 = App.Tags("tag1") ElseIf Target = Range("E1") Then Set tag1 = Nothing Private Sub tag1_changevalue(byval NewValue As Variant) Range("B1").Value = NewValue Test your code by launching Runtime of your application. You should see the Numeric Display tool quickly counting up to 100 and resetting itself back to 0. Press the _HMI_ShowFrame Maintained button and resize your window so that part of your desktop is visible. Launch Excel and open the workbook you created for this lesson. You will see that the worksheet does not display the updated tag values shown in the Numeric Display. Use your mouse to click around on different cells before finally clicking on cell D1 or the START cell. As soon as you click on the START cell, the code is executed and the tag values begin to update in cell B1. You should see that cell B1, as we specified in the code, displays the same tag values as the Numeric Display in Runtime. Click cell E1, or the STOP cell and the tag value updates on the worksheet cease. You may start and stop the updates as often as you like. Lesson 6: Applying what you learned The final lesson utilizes a sample InteractX application to demonstrate what we discussed in the previous exercises. We have included an application named GetObjectDemo with this tutorial. The application folder contains a fully functional workbook called GetObject.xls. This workbook should be used to view a demonstration of the final product. Although a functional workbook is provided and the code is fully described, in order to best apply what you learned, it is recommended that you try creating your own workbook and writing the code yourself. You may also try creating a second List for the Input List tool and then adding code to the existing workbook to display the tag values for the list items in List002. Of course as you become more and more familiar with the GetObject function and its uses, you may get more creative with your code. Open the GetObjectDemo application. It consists of a single panel with an Input List and its associated tools. A single List is included containing five list items. All panel objects have been given descriptive names to simplify matters. Select Panel001 in the Application Browser, right mouse click on it and choose the View Code option. This action will launch the VB Editor. The same can be accomplished by selecting the button named LaunchExcel from the Application Browser or the button itself from the panel. This is straight out of Lesson 4. Pressing this button in Runtime will launch the Excel workbook called GetObject.xls. Page: 11

12 Private Sub LaunchExcel_ButtonPressed() Dim WorkBook As Object Set WorkBook = GetObject(Application.Path & "GetObject.xls") WorkBook.Application.Visible = True WorkBook.Application.UserControl = True WorkBook.Application.Windows("GetObject.xls").Activate AppActivate "Microsoft Excel" Find the GetObject.xls workbook in the application folder and open it. Notice that cells B16 and C16 have been designated as the START and STOP cells, as we learned in Lesson 5. Column A shows the list items contained in List001, while Columns B and C are labeled TAG NAME and TAG VALUE, respectively. As you may have already guessed, we have employed the concepts of Lesson 2 to link this worksheet to the InteractX application in order to retrieve tag data. In this case, the tag data we are interested in is the names and values of each of the tags associated with the list items in List001. This information will be displayed in our worksheet. Now launch the VB Editor and let s take a closer look at the code in the workbook. A lot of it should already seem familiar from previous lessons, but we will add some helpful comments in green to refresh your memory. 'Link the tags in the spreadsheet to the tags in InteractX Dim WithEvents input1 As HMI.Tag Dim WithEvents input2 As HMI.Tag Dim WithEvents input3 As HMI.Tag Dim WithEvents input4 As HMI.Tag Dim WithEvents input5 As HMI.Tag Private Sub Worksheet_SelectionChange(ByVal Target As Range) 'If the START cell B16 is clicked the following code 'will execute If Target.Count = 1 Then If Target = Range("B16") Then Dim ListApp As HMI.Application 'Use GetObject to see if InteractX is running 'and get tag data Set ListApp = GetObject(, "HMI.Application") 'Get tag data Set input1 = ListApp.Tags("input1") Set input2 = ListApp.Tags("input2") Set input3 = ListApp.Tags("input3") Set input4 = ListApp.Tags("input4") Set input5 = ListApp.Tags("input5") Page: 12

13 'Update the worksheet with tag names Range("B22").Value = input1.name Range("B23").Value = input2.name Range("B24").Value = input3.name Range("B25").Value = input4.name Range("B26").Value = input5.name 'Update the worksheet with tag values Range("C22").Value = input1.value Range("C23").Value = input2.value Range("C24").Value = input3.value Range("C25").Value = input4.value Range("C26").Value = input5.value 'If the STOP cell C16 is clicked, the link to the 'InteractX application is dissolved ElseIf Target = Range("C16") Then Set input1 = Nothing Set input2 = Nothing Set input3 = Nothing Set input4 = Nothing Set input5 = Nothing 'Link the events in InteractX to events in the worksheet. As each 'tag value changes in Runtime, the new values are updated in the 'worksheet as well. Private Sub input1_changevalue(byval NewValue As Variant) Range("C22").Value = NewValue Private Sub input2_changevalue(byval NewValue As Variant) Range("C23").Value = NewValue Private Sub input3_changevalue(byval NewValue As Variant) Range("C24").Value = NewValue Private Sub input4_changevalue(byval NewValue As Variant) Range("C25").Value = NewValue Private Sub input5_changevalue(byval NewValue As Variant) Range("C26").Value = NewValue 'End the link to events in the InteractX application Page: 13

14 If you want to see how this works, close the Excel workbook then launch Runtime. You can press the Show Frame button and then resize your window. Press the button named Launch Excel and the GetObject workbook should come up. No tag names or values are displayed yet. Once you click the START cell, the tag names and values will be displayed next to the corresponding list items. Press the Load button of the application to load the list into the input List tool. If you then send the list values from the tool, you should see the Numeric Displays and the worksheet cells update. You can modify and send the list item values in Runtime to see the new values in the worksheet. If you click on the STOP cell of the worksheet at any time, you can still make changes and send the list values in Runtime, but they will no longer update in the worksheet. You may start and stop the updates as often as you like. After playing around with the demo application and workbook, you should try to create your own versions of applications and corresponding workbooks with code. As you become more and more familiar with the GetObject function and its uses, you may find more creative ways to write your code or even more useful shortcuts. Keep in mind that this tutorial was written such that less experienced users could follow the principles discussed in each of the lessons. The best way to learn is to apply these concepts to real examples and get some hands-on experience. Page: 14