Getting started with the IGSS Automation interface

Automation interface to the IGSS Online Database

The interface will give access to:

Object properties like unit, description and scan interval.
Atom properties like process values, alarm limits and I/O modes.
Alarms on single objects or the complete alarm list.
Alarm start, acknowledgement and end time.
System properties like configuration name and status and system time.
Events when objects are changed, alarm changes and configuration status changes.

The interface is available from all programs and languages which support the Microsoft Automation standard and, since the interface is dual, can call COM interfaces.

This includes among others the Visual Basic (VB) and C/C++ programming languages and all products implementing Visual Basic for Applications (VBA) as a macro language, e.g. all Microsoft Office products.

For the examples mentioned here, the VB/VBA programming environment is used. You can try the examples yourself, if you have either Visual Basic or any of the Microsoft Office products installed. Hints will be given to users of other environments when relevant.

If you want to use the interface from the built-in VBA editor in IGSS, some of the steps have already been done. Refer to Getting started with the built-in VBA editor for more information.

Attaching the interface

In the VBA editor, open the Tools menu and browse through the list of Available References, until you come to the entry IGSS32 v.7.00.00 Online Database Access. Select the check box next to it, and you have attached the IGSS Automation interface.

If the entry does not appear in the list of Available References, click the Browse... button and search for the file dc.exe which contains the Type Library. Dc.exe is found in the folder [IGSS InstallPath]\Gss.

For C/C++ programmers, the files dc.h, dc_i.c and dc_p.c in the \Gss folder may also be of interest, because it contains declarations needed to access the pure COM interface. If you are using Microsoft C/C++, The MFC Class Wizard can produce C++ wrapper classes for the full interface.

Browsing the interface

To see what is in the interface, the Object Browser window is indispensable. In the View menu, select Object Browser or press CTRL + F2.

In the drop-down box in the upper left corner, select the IGSSonline library where you can view all objects in the IGSS library, their methods, properties and events together with a short description and parameter declarations.

Accessing the interface

The only object in the interface that can be directly instantiated is IGSSDB. All other objects are retrieved from collections in IGSSDB or other objects. So you will always have to have at least one instance of IGSSDB to do anything at all. You can accomplish this in one of two ways:

implicitly when declaring the object variable: Dim igss As New IGSSDBor
explicitly in the code module:

Dim igss As IGSSDB
Set igss = CreateObject("DC.IGSSDB")

Now the methods and properties of IGSSDB are available. One property is especially important, since it indicates if a configuration is loaded and active. This is "IsConfigLoaded". If this is not the case, most of the interface cannot be used and will return errors. This is because if there is no configuration running, then there is no online database to access. The following code will check this:

If igss.IsConfigLoaded Then

'Do your database access

Else

'you may try to start the configuration

igss.StartConfig

EndIf

Accessing an IGSS object

Having an instance of the IGSSDB object, you can now get access to the IGSS objects through the collection Objects. Let us now access the analog object q1 by:
Dim flowObject as IGSSOBJECT

Set flowObject = igss.Objects("q1")

Now the static properties of an IGSS object can be accessed. These are properties like description, engineering unit, and number of decimals. The code should look like this:

Dim desc As String

Dim unit As String

Dim dec As Integer

desc = flowObject.Description

unit = flowObject.Unit

dec = flowObject.Decimals

All dynamic properties of the object are in the IGSSATOM objects. We can get these from the collection "Atoms" on the IGSSOBJECT by:

Dim processValue As IGSSATOM

Set processValue = flowObject.atoms("Value")

Now we can get the value, I/O-mode, etc. of the process value by writing:

Dim value as Double

Dim iomode as Integer

value = processValue.Value

iomode = processValue.IOmode

You could also avoid "flowObject" and "processValue" variables and get the value directly by writing:

Value = igss.Objects("q1").Atoms("Value")

If you only need the process value of atoms, there are a few shortcuts that can be used. Directly on the IGSSOBJECT, two primary atoms have been predefined in ProcessIn and ProcessOut. For the analog object these have been defined to "Value" and "Set Point" respectively. So you could also write:

value = flowObject.ProcessIn

Directly on the IGSSDB, there is also general access to any process value using the methods ReadDB and WriteDB. So you could also write:

value = igss.ReadDB("q1!Value")

The syntax for object and atom names are similar to the syntax in the DDE interface.

Using events

To illustrate the use of events, we will go through a little exercise. Let's say we have two IGSS objects, "q1" and "q2", which describe two flows somewhere in our process. We need to calculate the average and notify the user each time a change occurs.

In VBA, events can only be used in class modules, so we have to make the following class module called EventDemo:

Dim igss As IGSSDB

Dim WithEvents q1 As IGSSATOM

Dim WithEvents q2 As IGSSATOM

Sub startSubscription()

Set igss = CreateObject("DC.IGSSDB")

Set q1 = igss.Objects("q1").Atoms("Value")

Set q2 = igss.Objects("q2").Atoms("Value")

End Sub

Sub endSubscription()

Set q1 = Nothing

Set q2 = Nothing

Set igss = Nothing

End Sub

Private Sub calculate()

Dim qsum As Double

qsum = q1.Value + q2.Value

MsgBox "Total flow changed to: " & qsum

End Sub

Private Sub q1_AfterAtomChange()

calculate

End Sub

Private Sub q2_AfterAtomChange()

calculate

End Sub

The "WithEvents" extension to the Dim statements is what's doing all the magic.

Be careful not to spend too much time in the event procedures. Failing to do so may disturb other tasks in the data collection procedure. Good programming practice is to do small tasks in the event procedures and split up bigger task to be processed in, for example, timer events.

Instead of notifying the user, we may choose to update another IGSS object, let's say "q3". All we have to do now is to declare and initialize a new object:

Dim q3 As IGSSATOM

Set q3 = igss.Objects("q3").Atoms("Value")

Then the MsgBox statement can be substituted with:

q3.value = qsum

Of course we have to make sure that q3 has either "out", "in/out" or "local" as its I/O mode, otherwise the statement will fail.

To start the show, we have to instantiate the class module. We do that from a normal module:

Dim evt As New EventDemo

Sub startTheShow()

evt.startSubscription

End Sub

Sub stopTheShow()

evt.endSubscription

End Sub

Moving from version 2 to version 3

A few things in the procedure connecting to the interface has changed from version 2 to version 3. These changes will require a few changes in your programs. The changes are made so that version 2 and version 3 of IGSS can coexist on the same PC and so that also programs interfacing the two versions can coexist.

If you are using VB/VBA you should:

In the References dialog box, detach the interface IGSS Online Database Access and attach IGSS32 v.7.00.00 Online Database Access instead.
Explicit instantiation of the IGSSDB object should change from "CreateObject("IGSSDB")" to "CreateObject("DC.IGSSDB")"
A few parameters have got new data types. The compiler will warn you about the changes needed.

If you are using C/C++ you should

Instead of the type library igssaut.tlb, you should use the type library imbedded in dc.exe
Instead of including the header file iigssaut.h, you should include the header file dc.h and append the file dc_i.c to your project.
A few parameters have got new data types. The compiler will warn you about the changes needed.