Getting started with the built-in VBA editor

Introduction

Using the built-in VBA editor in IGSS is like using VB(A) in any other program, so the only prerequisite is basic knowledge of the Visual Basic language and knowledge about the IGSS Automation interface as described in Getting started with the IGSS Automation interface.

In IGSS, VBA has been integrated in the Definition and Supervise modules so that coding VBA programs is a natural part of the design process. Furthermore, it gives an opportunity to extend the programmability from the pure runtime database access to include user interface parts too. To obtain these capabilities an additional Automation interface has been implemented in Definition and Supervise.

The following pages will, by a number of examples, introduce the features available.

The Definition/Supervise Automation interface

The interface will give access to:

Application properties like name, type, version, position on screen, etc.
Configuration properties like name, descriptor selection states, etc.
Area and diagram properties like name, position, size, state, etc.
Properties on selected descriptors (ActiveX and Windows button) like position, connected object, etc.
Events when application starts/stops, diagram/area open/close, function key pressed, pop-up menus, button descriptor click and all events from ActiveX controls.

The execution environment

In most applications VBA is integrated in the graphical user interface. In IGSS, the VBA editor has naturally been integrated in the Definition and Supervise modules. So the typical scenario is a program developed in Definition and executed in Supervise.

However, code running in Supervise will be exposed to the moods of the operator. If Supervise is stopped, the code will stop. Therefore IGSS also offers the opportunity to run all or parts of the code in a protected environment independent of Supervise. We call this the VBA executor.

The VBA executor can only be started/stopped by the IGSS Starter and in multiuser systems it runs on the server only. The VBA executor offers the same environment as Supervise, only without the graphic parts.

No matter where your code is running, Definition will be where you do the development using the Visual Basic Editor (VBE).

Starting the Visual Basic Editor (VBE)

Start Definition and in the menu select Tools \ Macro \ Visual Basic Editor and the VBE will appear on your screen.

First time you open the VBE, you will find the project explorer containing one project with the same name as the configuration. This project contains one host object (objects created by the host Definition/Supervise) "Configuration". You can add, remove and change code in the host objects, but never delete or rename them.

The "Configuration" object contains a number of important details.

The object OnlineDB is an instance of the root object IGSSDB of the IGSS Automation interface to the online database. This gives you direct access to the online database without writing any code.
A number of events useful for scheduling your code:
OnDcCodeStart and OnDcCodeStop will give you the opportunity to initialize and clean up your workspace when running in the context of the VBA Executor.
OnSuperviseCodeStart and OnSuperviseCodeStop will give you the opportunity to initialize and clean up your workspace when running in the context of Supervise.
OnTimer schedules your code in intervals given by the property TimerTick.
OnGlobalFKeyPressed comes when a VBA-enabled global function key is pressed.
A number of utility functions that may help you to get information about the configuration.

$images\VBE.gif$

The "IGSSATOMN" interface is provided for backward compatibility and should not be used in new development.

These features will be most of what you need to make simple programs.

We can now make our first lines of code. We will make a simple program that writes values to the analog object "q1" in the Demo configuration. The values are the results of a trigonometric function evaluated on each timer tick.

Dim atm As IGSSATOM

Dim count As Double

Private Sub Configuration_OnSuperviseCodeStart()

TimerTick = 1000 ‘ set timer to come every second (1000 milli sec)

count = 0

Set atm = OnlineDB.Objects("q1").Atoms("value")

End Sub

Private Sub Configuration_OnSuperviseCodeStop()

TimerTick = 0 ‘ Stop the timer

Set atm = Nothing

End Sub

Private Sub Configuration_OnTimer()

atm.Value = 50 + 50 * Sin(count / 10)

count = count + 1

End Sub

If you start the configuration, you will see "q1" start to change the moment Supervise is started and changes stops the moment Supervise is closed.

If you want the updates to take place at the startup of the data collection (DC) module, you can change the event as follows:

Configuration_OnSuperviseCodeStart() to Configuration_OnDCCodeStart()

Configuration_OnSuperviseCodeStop() to Configuration_OnDCCodeStop()

Now the code will run in the VBA executor independently of Supervise.

Debugging the code

Code that does not depend on user actions can be tested in Definition just by having the configuration running in the background while Definition is also running.

Be careful when debugging programs with events and especially fast timer events. If they come while you are editing the code somewhere else in the program, the scope of the editor will change and pretty fast you are in a state that is difficult to get out of. A good practice is to disable the timer and other events, while you are editing or set it to a slow rate. This can be done by setting the TimerTick = 0 in the Properties window for the Configuration object.

If you hold "Shift" down while Supervise is starting the "Configuration_OnSuperviseCodeStart" event will not come and your code will not be started.
In the System Configuration program on the Startup tab, select the check box Disable VBA. Then the VBA executor will not start i.e. "Configuration_OnDCCodeStart" will not be called.

VBA enabling the graphics

Next step is to make our code access the graphically oriented parts of Supervise. Lets take the IGSS diagram first.

In the Diagram menu and the diagram pop-up menu, you get a menu item called View VBA code. When it is selected, the VBE is activated and brought to front and a new host object is created. If it already exists, it is just brought to front. Its name starts with "D_" indicating that it is related to a diagram followed by the name of the diagram another "_" and the name of the area holding the diagram. Each diagram that you VBA-enable, will have its own host object.

This host object gives you information about the specific diagram:

Information about the diagram such as name, size and position on screen, visibility, etc.
Commands to open or close the diagram under program control.
Events when the diagram is opened, closed, activated and deactivated.
Events when one of the function keys of the diagram is pressed.
Events when the diagram pop-up menu is presented or selected.

Examples:

We want the function key F11 to increase the value of "q3" by one and function key F12 to decrease it by one. The code is placed in the host object of the diagram.

First we establish a reference to "q3", when the diagram is opened and we remove the reference when the diagram is closed.

Private atm As IGSSATOM

Private Sub IGSSDiagram_OnOpen()

Set atm = Configuration.OnlineDB.Objects("q3").Atoms("value")

End Sub

Private Sub IGSSDiagram_OnClose()

Set atm = Nothing

End Sub

The IGSSDiagram_OnOpen event will come in both Supervise and Definition. If you want it in Supervise, you may want to change the event handling code to:

Private Sub IGSSDiagram_OnOpen()

If (Application.Mode = APPMODE_RUN) Then

Set atm = Configuration.OnlineDB.Objects("q3").Atoms("value")

End If

End Sub

Then we have to VBA-enable the two function keys by selecting the Run VBA code check box for each of the function keys in the Function Key Assignment dialog box.

And the following code should be added :

Private Sub IGSSDiagram_OnFkeyPressed(ByVal lKeyNo As Long)

Select Case lKeyNo

Case 11 'Fkey 11

atm.Value = atm.Value + 1

Case 12 'Fkey 12

atm.Value = atm.Value - 1

End Select

End Sub

As another example, we could choose to do the same from the pop-up menu.

First we add two new menu items: "q3 add 1" and "q3 subtract 1". When the pop-up menu is a activated by the right mouse click, we get event OnPropertyMenupop-up with a menu id telling which menu item we are going to add. As long as you return not empty strings from this procedure, they are added to the menu. We add our two menu items by the following code

Private Function IGSSDiagram_OnPropertyMenupop-up(ByVal menuID As Long, ByVal ObjectID As Long,

ByVal DescrID As Long) As String

Select Case menuID

Case 0

IGSSDiagram_OnPropertyMenupop-up = "q3 add 1"

Case 1

IGSSDiagram_OnPropertyMenupop-up = "q3 subtract 1"

Case Else

IGSSDiagram_OnPropertyMenupop-up = "" 'empty string to make it stop

End Select

End Function

(If you instead of clicking the diagram background, click on descriptors you will know what you clicked by objectID and descrId.)

Now when we have added the two menu items, we will be notified through the event "OnPropertyMenuSelect", if one of them is clicked. So we can make our calculation.

Private Sub IGSSDiagram_OnPropertyMenuSelect(ByVal menuID As Long)

Select Case menuID

Case 0

atm.Value = atm.Value + 1

Case 1

atm.Value = atm.Value - 1

End Select

End Sub

VBA controls and IGSS descriptors

Some IGSS descriptors can be VBA-enabled. For now, this is limited to button descriptors and ActiveX descriptors.

The method to VBA-enable these descriptors is similar to VBA-enabling diagrams and areas. Right-click the descriptor and choose View VBA code in the pop-up menu.

Descriptors are included into the host object representing the diagram as a VBA control. To be able to address them, each control must have a name. Unless you explicitly give the descriptor a name, the name DIX_xxx will be assigned, where xxx is the descriptor index in the IGSS database. Since these names are pretty difficult to relate to a specific descriptor, you should assign meaningful names to the descriptors. Descriptor name is simply a property in the properties dialog box of the relevant descriptor.

VBA-enabled descriptors will give you features like:

Button descriptor

- Events when clicked

- User defined items in descriptor right-click pop-up menu.

ActiveX descriptor

- All events from ActiveX control

- Access to ActiveX properties

Both descriptors

- Descriptor properties like position, size, etc.

By extending our example we can illustrate the use. We add two button descriptors on our diagram and name them "Add" and "Subtract" and enable VBA for both.

In the host object for our diagram, two new controls with the same names "Add" and "Subtract", are automatically added.
With a few lines of code, we can now add and subtract with the button descriptors.

Private Sub Add_OnButtonClicked()

atm.Value = atm.Value + 1

End Sub

Private Sub Subtract_OnButtonClicked()

atm.Value = atm.Value - 1

End Sub

Moving external code to the built-in VBA

If you already have some code written for your IGSS32, version 2 configurations, you can still use it after your configuration has been moved to version 3, if you just make the few changes listed in the paragraph "Moving from version 2 to version 3" in the Getting started with the IGSS Automation interface topic.

You can also choose to move it into the built-in VBA editor to benefit from having it as part of the configuration and avoid thinking about bringing external programs up.

You can move your class modules into VBA custom class modules, your general module into VBA custom general modues an so forth. You do not have to use the OnlineDB object or any other of the new objects if you do not need to you can simply instantiate your IGSDB as you have always done.

Your initialization routines should, however, be called from Configuration_OnDCCodeStart() or Configuration_OnSuperviseCodeStart().