Built-in VBA Code Interface

The VBA Editor for IGSS is included as a standard feature in the IGSS package at no extra cost. Using the built-in VBA editor here is the same as in any other Windows application -  the only prerequisites are a basic knowledge about the Visual Basic language and about the IGSS Automation interface as described in the topic: IGSS Automation Interface.

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

By way of a number of examples in the following, VBA in an IGSS context will be discussed..

The Definition/Supervise Automation interface

The interface gives 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 start/stop, diagram/area open/close, function key pressed, popup menus, button descriptor click and all events from ActiveX controls.

Execution Environment

In most applications VBA is integrated in the graphical environment. This is in IGSS naturally 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 starter process and in multi-user systems it runs on the server only. The VBA executer offers the same environment as Supervise just without the graphic parts.

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

Starting the VBE

You can then start Definition and select the Tools \ Macro \ Visual Basic Editor menu and the VBE will appear on your screen.
The first time you open the VBE, you will find the project explorer containing one project with the same name as the IGSS 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, OnDcCodeStop: will give you opportunity to initialise and cleanup your workspace when running in the context of VBA Executor
  • OnSuperviseCodeStart and OnSuperviseCodeStop will give you opportunity to initialise and cleanup your workspace when running in the context of Supervise.
  • OnTimer Schedule your code in intervals given by the property TimerTick
  • OnGlobalFKeyPressed comes when an VBA enabled global function key is pressed.

• A number of utility functions that may help you to get information about the configuration.

Note: 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 a simple program that sends in values on the analogue object q1 in the demo configuration. The values are result 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 al the time you can change the event

Configuration_OnSuperviseCodeStart() to Configuration_OnDCCodeStart()
Configuration_OnSuperviseCodeStop() to Configuration_OnDCCodeStop()

Now the code will run in the VBA executor independant of Supervise

Debugging the code

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

Code based on events from Supervise can only be tested in its correct environment and therefore the VBE can be started from Supervise too. When you finished debugging your code and you do not want the end user to access the code directly you can disable this feature in Supervise.

Be careful when debugging programs with events an 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 on a slow rate. This can be done by setting the TimerTick = 0 in the Properties window for the Configuration object.

Tip: If you hold “Shift” down while Supervise is starting the “Configuration_OnSuperviseCodeStart” event will not come and your code will not be started.

Tip: In the set-up program page “Type” check the checkbox “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 graphic oriented parts of Supervise. Lets take the IGSS diagram first.
In the diagram menu and the popup menu you get when you right click a diagram background there is a menu entry “Edit VBA code”. When it is selected the VBE is brought in front and a new host object is created. If it already exists it is just brought in 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 like 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 popup 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 only you may 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 checking the “Run VBA code” check box for each of the function keys in the Function Key Assignment” dialogue.

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 popup menu.

First we add two new menu items “q3 add 1” and “q3 Subtract 1”. When the popup menu is a activated by the right mouse click we get event OnPropertyMenuPopup with a menu id telling which menu item we are going to add. As long at you returns not empty strings from this procedure they are added to the menu. We add our two menu item by the following code

Private Function IGSSDiagram_OnPropertyMenuPopup(ByVal menuID As Long, ByVal ObjectID As Long, 
ByVal DescrID As Long) As String
Select Case menuID
Case 0
IGSSDiagram_OnPropertyMenuPopup = "q3 add 1"
Case 1
IGSSDiagram_OnPropertyMenuPopup = "q3 subtract 1"
Case Else
IGSSDiagram_OnPropertyMenuPopup = "" '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 two menu items we will be notified thru the event “OnPropertyMenuSelect” if one of them are 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

Also some descriptors can be VBA enabled. In this first release it is limited to button descriptors and ActiveX descriptors.

The method to VBA enable these descriptor is similar to VBA enabling diagrams and areas. Right click the descriptor and choose “View VBA code” in the popup 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 gives the descriptor a name it will be given the name DIX_xxx where xxx is the descriptor indec in the IGSS database. Since these names are pretty difficult to relate to a specific descriptor you should name the descriptors. “Descriptor name” is simply a new property in the property sheet of the relevant descriptor.

VBA enabling descriptors will give you features like:

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 them both.

In the host object for our diagram two new controls, with the same names “Add” and “Subtract” , are automatically added.
By 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 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”.

You can also choose to move it into the build in VBA 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 modules 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 initialisation routines should however be called from Configuration_OnDCCodeStart() or Configuration_OnSuperviseCodeStart().