ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

download ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

of 35

Transcript of ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    1/35

    ClearSCADA AutomationInterface

    Training Notes

    Revision 3.0

    30th May, 2007

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    2/35

    ClearSCADA Automation Interface Training Notes

    Revision3.0

    i

    Issue Details

    Issue Date Author Comments

    1.0 5thDecember, 2004 G. Russ Initial Version

    2.0 27thJune, 2005 G. Russ Updated for 2005 Edition

    2.1 6thAugust, 2005 G. Russ Updated for ClearSCADA 2005 Edition

    3.0 30thMay, 2007 R. Rogers Updated for ClearSCADA 2007 Edition

    References

    ClearSCADA Automation Interface Reference Manual

    Required Hardware IBM PC Pentium 4 1Ghz, 256MB RAM

    Required Software

    Windows 2000 SP2 (or higher), Windows XP SP2 (or higher) or Windows2003 Server

    ClearSCADA 2007 Edition Microsoft Word, Excel, or Access with Visual Basic for Applications

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    3/35

    ClearSCADA Automation Interface Training Notes

    Revision3.0

    ii

    Table of ContentsIssue Details .................................................................................................................. iReferences .................................................................................................................... i

    Required Hardware ....................................................................................................... i

    Required Software......................................................................................................... iTable of Contents ..........................................................................................................iiList of Figures............................................................................................................... iiiList of Tables ................................................................................................................ iii1 Object Oriented Concepts.................................................................................. 1

    1.1 Properties....................................................................................................... 21.2 Methods ......................................................................................................... 31.3 Derived Classes and Inheritance ................................................................... 3

    2 Introduction to the Automation Interface ............................................................ 52.1 What is the Automation Interface ................................................................... 52.2

    Supported Programming Languages.............................................................. 6

    2.3 Required ClearSCADA Components ............................................................. 62.4 Adding the Automation Interface to the VBA Project...................................... 62.5 A Simple Example.......................................................................................... 72.6 The VB Object Browser.................................................................................. 82.7 Automation Interface Classes ........................................................................ 9

    3 Connecting to an ClearSCADA System........................................................... 113.1 Security ........................................................................................................ 11

    4 Finding Objects in the ClearSCADA Database................................................ 134.1 ScxV6Server.FindObject .............................................................................. 13

    4.2

    ScxV6Server.LookupObject ......................................................................... 13

    4.3 ScxV6Object.Find......................................................................................... 145 Reading and Modifying ClearSCADA Object Properties.................................. 15

    5.1 ScxV6Object.Property.................................................................................. 155.2 ScxV6Object.Class.Name............................................................................ 16

    6 Creating, Renaming and Deleting ClearSCADA Objects ................................. 186.1 ScxV6Server.CreateObject and ScxV6Object.Create.................................. 186.2 ScxV6Object.Rename.................................................................................. 196.3 ScxV6Server.DeleteObject........................................................................... 20

    7 Collections ....................................................................................................... 217.1 The ScxV6Objects Object ............................................................................ 21

    8

    Calling Methods on ClearSCADA Objects ....................................................... 239 Aggregates ...................................................................................................... 24

    9.1 ScxV6Object.Aggregate ............................................................................... 249.2 ScxV6Aggregate.Enable .............................................................................. 249.3 ScxV6Aggregate.Property and ScxV6Aggregate.Interface .......................... 259.4 CHistory.LoadDataValue and CHistory.LoadDataFile.................................. 25

    10 Templates and Instances................................................................................. 2710.1 CTemplateInstance.TemplateId ................................................................... 2710.2 CScxV6Object.PropertyOverride.................................................................. 2710.3 Reading and Writing Properties in Instances ............................................... 28

    Appendix A VBScript Example............................................................................... 29

    Appendix B

    Inserting Historic Data ........................................................................ 30

    B.1 PresetTimestamp and PresetQuality............................................................ 30B.2 CHistory.LoadDataValue.............................................................................. 30

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    4/35

    ClearSCADA Automation Interface Training Notes

    Revision3.0

    iii

    B.3 CHistory.LoadDataFile ................................................................................. 31

    List of Figures

    Figure 1-1 - Accessing the ClearSCADA Database Schema using Internet Explorer.1

    Figure 2-1 - ClearSCADA DatabaseApplication Interfaces ..................................... 5Figure 2-2 - ClearSCADA Client Configuration...........................................................6Figure 2-3 - SCX V6 Automation Interface in VBA Project References......................7Figure 2-4 - Automation Interface in the Object Browser............................................8Figure 2-5 - Properties of ScxV6Object ......................................................................9Figure 3-1 - Unknown System Name........................................................................11Figure 3-2 - System Offline.......................................................................................11Figure 3-3 - Permission Denied................................................................................12Figure 3-4 - Insuficient Privideges ............................................................................12Figure 4-1 - Accessing Property of a Nothing Object................................................13Figure 5-1 - Attempt to Write to a Read-Only Property.............................................15

    Figure 5-2 - Attempt to Read or Write a Non-Existent Property................................16Figure 6-1 - Non-Existent Class Name .....................................................................18Figure 6-2 - Non-Creatable Class Name ..................................................................18Figure 6-3 - Create in Non-Existent Group ............................................................... 19Figure 6-4 - Create in a Template Instance .............................................................. 19Figure 6-5 - Invalid Object Name..............................................................................19Figure 6-6 - Deleting an Object Referenced by other Objects .................................. 20Figure 7-1 - Calling the List Method on an Object that is not a Group...................... 21Figure 7-2 - Invalid Item Number ..............................................................................21

    Figure 8-1 - Invalid Argument to ClearSCADA Method ............................................23

    Figure 9-1 - Named Aggregate does not Exist..........................................................24Figure 9-2 - Using ViewX to Enable an Aggregate ................................................... 24Figure 9-3 - Accessing Properties or Methods of a Disabled Aggregate ..................25Figure 10-1 - PropertyOverride Called on an Object that is not a Template ............. 27Figure 10-2 - Property Override Called with an Object not in the Template ............. 28Figure 10-3 - Property Override Called on a Non-Existent Field...............................28Figure 10-4 - Attempt to Write to a Property in an Instance that is not Overridden...28

    List of TablesTable 9-1 - OPC Quality Values ...............................................................................26

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    5/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 1

    1 Object Oriented Concepts

    The ClearSCADA database is object-oriented It is a collection of objects(outstations and points for example). Each object has a number of

    Configuration Fields Define the behaviour of the object. For example, allobjects have a Nameproperty which stores the name of the object in theClearSCADA database.

    Data Fields Define the state of the object. For example, all Pointshavea CurrentValuefield which stores the current value of the point.

    NOTE:Configuration and Data Fields and collectively known asproperties.

    Methods Perform actions on objects. For example, all objects whichgenerate alarms have aAcceptmethod which accepts the current active

    alarm on the object.

    In ClearSCADA, the available classes are listed in the Schema which can beaccessed using Internet Explorer by browsing to http:///schema. If theClearSCADA server is running on the local machine, http://localhost/schemawillaccess the schema of the local server.

    NOTE:If you are running a web server such as Apache, IIS etc on the samecomputer as the ClearSCADA server, the ClearSCADA server may not be able torun its web server, and the schema will not be available.

    Figure 1-1 - Accessing the ClearSCADA Database Schema using Internet Explorer

    Exercise

    1. List the ClearSCADA classes by browsing to http://localhost/schema2. Click on the Internalfolder in the schema3. Find the Internal Analog Pointclass

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    6/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 2

    When a user creates an object in the ClearSCADA database, they are creating aninstance of one of the classes listed in the schema. For example, an Internal AnalogPointis an instance of the CPointAlgManualclass and therefore has all theproperties and methods listed in the schema for the CPointAlgManualclass.

    Exercise

    1. Follow the CPointAlgManuallink2. Identify a Configuration Fieldof CPointAlgManual3. Identify a Data Fieldof CPointAlgManual4. Identify a Methodof CPointAlgManual

    1.1 Properties

    Configuration fields are set by the user and define the configuration of the individualinstance of the class (object). The configuration fields are displayed in the object

    properties in ViewX

    Exercise

    1. Create a new Internal Analog Point using ViewX2. Open the Propertiesdialog on the new point3. Compare the Handressproperty on the Manualtab in ViewX to the

    HandressAllowedconfiguration field in the schema. Note that the Display Nameand Descriptionin the schema match the label and tool-tip in ViewX.

    4. Compare the Confirmproperty on the Manualtab in ViewX to theHandressConfirmconfiguration field in the schema.

    5. Note the Typeis Unsigned Byte(a number), but it is displayed in ViewX as a

    drop-down list of text values.6. Examine the Notescolumn in the schema It shows that the property is an

    Enumerationand lists the mapping of numerical values to text values displayedin the drop down.

    1.1.1 Read-Only Conf iguration Fields

    Some configuration fields are listed as Read Onlyin the Notescolumn of theschema. These fields are set by the ClearSCADA server based on the value ofanother configuration field. For example, HighHighColouris based onHighHighColourId.

    Exercise

    1. Find a class with a Read-Only configuration field in the schema

    1.1.2 Data Fields

    Datafields are modified in real time by the ClearSCADA Server. These represent thecurrent value and state of the object. The most relevant data fields of an object aredisplayed in the Viewdialog of the object in ViewX

    Exercise

    1. Right-Click on the Internal Analog Point in ViewX and select View2. Locate the Current Value property

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    7/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 3

    1.2 Methods

    Methods are built in functions that perform actions on an object. For example LogicProgramclasses (such as CLogicSTProgram) define a number of Executemethods.These methods allow the program to be executed with a different number of

    parameters. Methodsare covered in more detail in Section 8.

    NOTE:The Descriptioncolumn in the schema for Execute0, Execute1, to Execute12has ** DEPRECATED Use Execute Method instead **. These methods have beenreplaced by a new method Execute. Deprecated methods are still implemented inClearSCADA for backward compatibility, but should notbe used in when creatingnew ClearSCADA projects.

    1.3 Derived Classes and Inheritance

    A key concept of the Object Oriented paradigm is that of the Derived Class. Consider

    a class (Class A) which has a number of defined properties and methods. Consider aseconds class (Class B) which requires the same functionality that is available toClass A by its properties and methods, but also requires additional properties andmethods that are not defined on Class A. There are two options

    1. Redefine all of the properties and methods defined on Class Aon Class Bandthen defined the additional properties and methods on Class B

    2. Inherit the properties and methods defined on Class A, and only define theadditional properties and methods on Class B

    In the second case

    Class B is Derived From(or is a sub-class of) Class A Class A is a Base Classof class B

    These two expressions are equivalent.

    Inheritance can be multi-levelled. Extending the above example, Class B can beused as the base class for a third class (Class C). Class C would inherit theproperties and methods defined on both Class B and Class A.

    In ClearSCADA:

    A class may have a maximum of onebase class A class may have multiplederived classes Al lproperties and methods defined on the base class are available on the

    derived class There is no limit to the depth (number of levels) of inheritance

    Exercise

    1. Find the CPointAlgManualclass in the schema2. Identify the base class of the CPointAlgManualclass3. Follow the link to the base class4. Find CPointAlgManualin the list of Sub Classes5. Open the properties dialog on the new point in ViewX6. Find some properties that are defined in the base class

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    8/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 4

    NOTE:Typically, base classes cannot be instantiated (i.e. no object of the class canbe created). There are some exceptions, for example CGroup is the base class forCTemplate and CTemplateInstance All of these classes can be instantiated. InClearSCADA, CDBObject is the base class for nearly every class in the database.

    Exercise

    1. Find a class in the schema that is not derived from CDBObject

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    9/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 5

    2 Introduction to the Automation Interface

    2.1 What is the Automation Interface

    The Automation Interface is an application programming interface (API) that allowsthe ClearSCADA database to be accessed using a programming language such asVisual Basic (VB).

    Like ViewX (and OPC/ODBC), the automation interface connects to ClearSCADAservers via the ClearSCADA Data Access Component. Figure 2-1 illustrates how anapplication accesses the ClearSCADA database using the automation interface.

    Main Server

    Computer

    Client Computer

    SCX6 Client

    Interface

    SCX6

    AutomationInterface

    Application

    SCX6 Database

    Standby Server

    Computer

    SCX6 Database

    Figure 2-1 - ClearSCADA DatabaseApplication Interfaces

    Using the automation interface, the programmer can:

    Read and modify properties (that are not read-only) of objects in theClearSCADA database

    Create instances of ClearSCADA classes in the ClearSCADA database Call methods on objects in the ClearSCADA database

    Using the automation interface, the programmer cannot: Modify the contents of Mimics Modify the contents of Logic Programs

    The automation interface is typically used to

    Perform bulk modifications to the ClearSCADA database that are eithertoo repetitive or prone to human error to do manually in ViewX

    Allow an external application to modify the ClearSCADA database (i.e.configure a ClearSCADA database from an MS Access database)

    Allow an external application to modify/control the values of I/O points inthe ClearSCADA database

    Allow an external application to add historical data to the ClearSCADAdatabase

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    10/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 6

    The client is configured using the Configure ClearSCADA Connectionsapplet. Theclient must be configured with a Typeof ClearSCADA Serverto allow the automationinterface to connect to the associated server(s) (see Figure 2-2).

    Figure 2-2 - ClearSCADA Client Configuration

    The ClearSCADA Client handles all connections to redundant servers transparently.As such, a programmer using the automation interface does not need to write codebased upon if the program will be connecting to a lone server or a pair (or trio) ofstandby servers. The code is written as if connecting to a single server.

    2.2 Supported Programming Languages

    Visual Basic (VB) and Visual Basic for Applications (VBA) are the simplestprogramming language to write code which uses the Automation Interface. VBA issupplied with Microsoft Office and is therefore available to users of Access, Wordand Excel without the necessity of buying additional programming software.

    NOTE:When install Microsoft Office, you will need to ensure you install the VisualBasic for Applicationscomponent.

    The remainder of this training document will detail the use of the automationinterface using VBA in Microsoft Excel.

    The automation interface can be used in VB Script with some minor syntacticmodifications to code written in VB/VBA. An example VB Script is provided inAppendix A.

    NOTE:The automation interface can be used in other languages such as C++ - thisis beyond the scope of this course.

    2.3 Required ClearSCADA Components

    In order to use the automation interface, the Data Accesscomponent must beinstalled during the installation of ClearSCADA on the local machine. There is noneed to install the server components.

    2.4 Adding the Automation Interface to the VBA Project

    1. Open the Excel Visual Basic Editor (ToolsMacroVisual Basic Editor)

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    11/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 7

    2. In the Visual Basic Editor, select ToolsReferences3. Enable Scx V6 Automation Interface

    Figure 2-3 - SCX V6 Automation Interface in VBA Project References

    2.5 A Simple Example

    The following code connects to the ClearSCADA system named MAIN, displays thecurrent value of the Internal Analog Point New Analog Point, changes the value ofthe Point to 10, and finally displays the new value of the point.

    Funct i on Mai n( )' Decl are t he vari abl e f or t he Cl ear SCADA Ser verDi m oServer As ScxV6Server

    ' Decl are t he var i abl e f or an Cl ear SCADA Obj ectDi m oObj ect As ScxV6Obj ect

    ' Cr eate t he aut omati on i nt er f ace obj ect whi ch i s our' vi ew of t he Cl ear SCADA Ser verSet oSer ver = New ScxV6Server

    ' Check t hat t he aut omat i on i nt erf ace obj ect was' successf ul l y cr eat edI f ( Not oSer ver I s Not hi ng) Then

    ' Est abl i sh a connect i on t o the Cl ear SCADA ServeroSer ver . Connect "MAI N", "" , ""

    ' Fi nd an obj ect i n the Cl ear SCADA databaseSet oObj ect = oServer . Fi ndObj ect ( "New Anal og Poi nt " )

    ' Check t hat t he obj ect was f oundI f ( Not oObj ect I s Nothi ng) Then' Di spl ay t he val ue of t he Poi nt i n a Message BoxMsgBox (oObj ect . Proper t y( "Cur r ent Val ue") )

    ' Change t he val ue of t he Poi ntoObj ect . Proper t y( "Cur r ent Val ue") = 10

    ' Di spl ay the new val ue of t he Poi nt i n a Message BoxMsgBox (oObj ect . Proper t y( "Cur r ent Val ue") )

    End I fEnd I f

    ' Ti dy upSet oObj ect = Not hi ng

    ' Di sconnect f r omt he Cl ear SCADA Ser ver

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    12/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 8

    oServer . Di sconnectEnd Funct i on

    Exercise

    1. Create a new Internal Analog Pointin the ClearSCADA Database using ViewX2. Enter the program listed above3. Run the program and confirm its results in ViewX4. Modify the program to change the point value to 205. Confirm the program by checking the points value in ViewX

    Exercise

    1. Create another Internal Analog Pointin the ClearSCADA database using ViewX2. Modify the program to change the value of the second point to 12.53. Confirm the program by checking the points value in ViewX

    Exercise (Advanced)1. Create a third Internal Analog Pointin the ClearSCADA database using ViewX2. Modify the program to set the value of the third point to the sum of the values of

    the other two points3. Confirm the program by checking the points value in ViewX

    2.6 The VB Object Browser

    One feature of VBA which makes using the automation interface easier than withother languages is the availability of the Object Browser. The object browser can beaccessed by selecting Object Browserfrom the Viewmenu of the Visual Basic

    Editor. From the object browser, the automation interface classes can be listed byselecting ScxV6DbClientfrom the drop-down list as shown below in Figure 2-4.

    Figure 2-4 - Automation Interface in the Object Browser

    The object browser can be used to display the properties and methods of classesavailable using the automation interface as shown below in Figure 2-5.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    13/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 9

    Figure 2-5 - Properties of ScxV6Object

    2.7 Automation Interface Classes

    Both the ClearSCADA database and the automation interface are Object Oriented.They both allow objects to be created that are instances of classes. However, theclasses defined in the automation interface should not be confused with the classes

    defined in the ClearSCADA database. They are easily distinguished due to theautomation interface classes all starting with ScxV6and the ClearSCADA databaseclasses all starting with C.

    The following sections describe the classes provided by the automation interface.Further information on these classes, and the properties and methods provided bythem, can be found in the ClearSCADA Automation Interface Reference Manual.

    2.7.1 ScxV6Server

    The ScxV6Serverclass provides the functionality required to connect to aClearSCADA system. Multiple operations can be performed on a ClearSCADA

    system using a single instance of this class. If the program connects to multipleClearSCADA systems simultaneously, multiple instances of this class are required.

    This class also contains methods to allow the programmer to create, delete andsearch for objects in the ClearSCADA database.

    2.7.2 ScxV6Object

    The ScxV6Objectclass provides the functionality to examine and modify objects inthe ClearSCADA database. This class is used to reference objects of allClearSCADA database classes. The automation interface does not provide a classfor each different ClearSCADA database class.

    The search functions provided by ScxV6Server return a ScxV6Object

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    14/35

    ClearSCADA Automation Interface Training Notes

    Chapter 2 - Introduction to the Automation Interface Revision 3.0 10

    2.7.3 ScxV6Objects

    The ScxV6Objectsclass is a collection class of ScxV6Object objects. Objects of thisclass can be treated as an array of ScxV6Object objects. The number ofScxV6Object objects of the array can be determined using the Countproperty of the

    ScxV6Objects object. Each ScxV6Object object can be retrieved from the arrayusing the Itemproperty.

    2.7.4 ScxV6Aggregate

    Some ClearSCADA database objects contain (as briefly mentioned in theintroduction)Aggregates. Each Aggregate class, like all other ClearSCADA classes,contains properties (configuration fields and data fields) and methods. Aggregatesallow the same set of properties and methods to be provided on multipleClearSCADA classes in a consistent manner.

    The ScxV6Aggregate automation interface class provides functionality to examine

    and modify ClearSCADA aggregate objects.

    Aggregates will be examined in more detail in Section 9.

    2.7.5 ScxV6Class

    The ScxV6Object and ScxV6Aggregate classes each contain a read-only Classproperty of type ScxV6Class. The Nameproperty of the ScxV6Class provides theprogrammer with the name of the ClearSCADA class (CPointAlgManualfor example)of the ScxV6Object object.

    2.7.6 ScxV6Systems

    The ScxV6Systemsclass is a collection class of strings. Each string in this collectionis the name of a ClearSCADA system defined in the Configure ClearSCADAConnectionsapplet. The ScxV6Server object class contains a read-only Systemsproperty which is used to obtain a ScxV6Sytstems object.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    15/35

    ClearSCADA Automation Interface Training Notes

    Chapter 3 - Connecting to an ClearSCADA System Revision3.0

    11

    3 Connecting to an ClearSCADA System

    Before any operations can be performed on the ClearSCADA database by theautomation interface, the program using the automation interface must first connectand authenticate (log on) to the corresponding ClearSCADA System.

    To connect to the ClearSCADA system, the program must first create an instance ofthe ScxV6Server automation interface object. The syntax for creating the instance ofthe ScxV6Server class will be dependant on the programming language used. InVB/VBA, the Newkeyword is used to create the instance as shown below.

    Set oSer ver = New ScxV6Server

    After the ScxV6Server object has been successfully created, the Connectmethodcan be called on the ScxV6Server object, providing the System Name, Usernameand Password. The following example connects to the ClearSCADA system calledMAINwith no username or password

    oSer ver . Connect "MAI N", "" , ""

    If the specified system has not been registered in the ClearSCADA ClientConfiguration applet (first parameter spelt incorrectly for example), the following errorwill be generated in VB

    Figure 3-1 - Unknown System Name

    If the specified system is offline, or the ClearSCADA Client has not been configuredfor ClearSCADA Access, the following error will be generated in VB

    Figure 3-2 - System Offline

    3.1 Security

    The level of access granted to a program using the automation interface using anygiven Username/Password is the same as in ViewX using the sameUsername/Password. For example, if a given user does not have Configure accessto a given ClearSCADA database object, a program using the automation interfacewith the same Username/Password will not be able to modify the properties of thatClearSCADA database object.

    If an operation on the ClearSCADA database (or any ClearSCADA object in thedatabase) is attempted where the supplied username/password has insufficient

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    16/35

    ClearSCADA Automation Interface Training Notes

    Chapter 3 - Connecting to an ClearSCADA System Revision3.0

    12

    privileges to perform the operation, one of the errors shown below in Figure 3-3 andFigure 3-4 will occur.

    Figure 3-3 - Permission Denied

    Figure 3-4 - Insuficient Privideges

    Exercise

    1. Use the ClearSCADA Service Manager to stop the ClearSCADA Server service2. Rename the C:\ClearSCADADB folder3. Use the ClearSCADA Service Manager to start the ClearSCADA Server service4. Right-click on the ClearSCADA system tray icon and select Start Database5. Click on Start Databaseon the warning dialog6. Right-click on the ClearSCADA system tray icon and select Configuration

    7. Select Securityin the System Configurationfolder of the Server Configurationapplet

    8. Turn on the Enabledtick-box9. Right-click on the server in the Server Configuration applet and selectApply

    Changes10. Close the Server Configuration applet11. Open ViewX and import the fileAutmationInterfaceSecurity.sde

    NOTE:You will may get an Access is denied error This can be ignored.

    The ClearSCADA database will now contain two users admin(password: admin01)and operator(password: operator01). The admin user has full access to theClearSCADA database. The operator user only has Read, Browse, and Controlaccess to the ClearSCADA database.

    Exercise

    1. Logon to the ClearSCADA database in ViewX using the admin user2. Repeat the exercise in Section 2.5 using the operatorusername and password

    in the VB program3. Repeat the exercise in Section 2.5 using an invalid username and password in

    the VB program4. Shutdown the ClearSCADA Server, delete the C:\ScxV6DB folder, rename the

    old C:\ ClearSCADADB back to C:\ ClearSCADADB and restart theClearSCADA Server

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    17/35

    ClearSCADA Automation Interface Training Notes

    Chapter 4 - Finding Objects in the ClearSCADA Database Revision3.0

    13

    4 Finding Objects in the ClearSCADA Database

    In order to examine/modify an object in the ClearSCADA database, an instance ofthe ScxV6Object class must be created which references the ClearSCADA databaseobject. The automation interface provides three methods for obtaining a reference toan object in the ClearSCADA database:

    ScxV6Server.FindObject ScxV6Server.LookupObject ScxV6Object.Find

    Each of these methods returns an instance of ScxV6Object if the requested object isin the ClearSCADA database. The returned object will reference the requestedClearSCADA database object. If the requested object is not in the ClearSCADAdatabase, these functions return the VB reserved Nothingobject.

    It is good programming practice to test for Nothing as shown in the followingexample

    I f ( Not oObj ect I s Nothi ng) Then. . . Do St uf f wi t h oObj ect

    End I f

    If the programmer does not check for Nothing, the error shown below in Figure 4-1 islikely to occur.

    Figure 4-1 - Accessing Property of a Nothing Object

    4.1 ScxV6Server.FindObject

    This method allows the programmer to obtain a reference to an object in theClearSCADA database by providing an absolute object name.

    Exercise

    1. Create an Groupin the ClearSCADA database using ViewX2. Create a new Internal Analog Pointin the group created above using ViewX3. Use the FindObjectmethod of the ScxV6Serverobject to obtain a reference to

    the new point4. Display the current value of the new point

    4.2 ScxV6Server.LookupObject

    This method allows the programmer to obtain a reference to an object in theClearSCADA database by providing an integer Object ID. All objects in theClearSCADA database have a unique Object ID which can be obtained using the IDproperty of the ScxV6Object class.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    18/35

    ClearSCADA Automation Interface Training Notes

    Chapter 4 - Finding Objects in the ClearSCADA Database Revision3.0

    14

    Exercise

    1. Use the ID property of ScxV6Obejct to obtain the ID of the point created in theprevious exercise

    2. Use the LookupObjectmethod of the ScxV6Server object to obtain a reference

    to the point using the ID (declare a new ScxV6Obejct in the VB code to storethis reference)

    3. Display the current value of the new point using the ScxV6Object obtained instep 2

    Exercise (Advanced)

    1. In the schema, locate the definition of the object ID2. Besides using the IDproperty of ScxV6Object, how else could the ID of an

    ClearSCADA database object be obtained

    HINT:Consider the fact that it is a property defined in the schema

    4.3 ScxV6Object.Find

    This method allows the programmer to obtain a reference to an object located in aGroup, (or Template or Instance) in the ClearSCADA database. This method can beused only if the ClearSCADA database object referred to by the ScxV6Objectis aCGroup, (or an object derived from CGroup). This method cannot find objects morethe one level deep in the Group.

    The following code is not valid

    Set oObj ect 1 = oServer . Fi ndObj ect ( Gr oup1)

    Set oObj ect 2 = oObj ect1. Fi nd ( Gr oup2. Obj ect)

    oObject2 will equal Nothing even if the object Group1.Group2.Object exists in theClearSCADA database.

    The following code is valid (provided the object Group1.Group2.Object exists in theClearSCADA database).

    Set oObj ect 1 = oServer . Fi ndObj ect ( Gr oup1)Set oObj ect2 = oObj ect1. Fi nd ( Gr oup2)Set oObj ect 3 = oObj ect2. Fi nd ( Obj ect )

    Exercise

    1. Use the FindObjectmethod of the ScxV6Server object to obtain a reference tothe group created in the previous exercises

    2. Use the Findmethod of the ScxV6Object to obtain a reference to the pointcreated in the group

    3. Display the value of the point

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    19/35

    ClearSCADA Automation Interface Training Notes

    Chapter 5 - Reading and Modifying ClearSCADA ObjectProperties

    Revision3.0

    15

    5 Reading and Modifying ClearSCADA Object Properties

    The exercises in the previous sections demonstrated the reading and writing of theCurrentValueproperty of an Internal Analog Point. This section will show how anyproperty of a ClearSCADA database object can be read, and how properties that arenot read-only can be modified using the automation interface.

    5.1 ScxV6Object.Property

    All properties of and ClearSCADA database object are accessed usingScxV6Object.Property. The syntax on this automation interface property was shownin Section 2.5 as:

    oObj ect . Pr oper t y(" Cur r ent Val ue")

    This statement retrieves the current value of the ClearSCADA database object (aPoint) referenced by oObject. The example also demonstrated that the current valuecould be written to:

    oObj ect . Pr oper t y( "Cur r ent Val ue") = 10

    This statement set the value of the ClearSCADA database object (a Point)referenced by oObject to 10.

    By using the schema to obtain the names and types of the properties of aClearSCADA class, the programmer can access any property on a ClearSCADAdatabase object using the automation interface.

    Exercise

    1. Use the FindObjectmethod of the ScxV6Server object to obtain a reference tothe Internal Analog Point created in the previous exercises

    2. Use the automation interface to display the Full Scaleof the point

    HINT:Full Scale is not defined on CPointAlgManual You will need to look atthe properties of the base class in the schema.

    3. Use the automation interface to change the Full Scale of the point to 200

    HINT:There are three Full Scale properties Standard, Current, and Tuned.

    Only one of them is read-write. If you pick the wrong one, you will get the errormessage shown in Figure 5-1.

    Figure 5-1 - Attempt to Write to a Read-Only Property

    Exercise (Advanced)

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    20/35

    ClearSCADA Automation Interface Training Notes

    Chapter 5 - Reading and Modifying ClearSCADA ObjectProperties

    Revision3.0

    16

    1. Create a new DNP3 Outstationin the ClearSCADA database using ViewX2. Create a new DNP3 Analog Input Pointin the ClearSCADA database using

    ViewX3. Use the automation interface to tie the Outstation to the Point.

    HINT:You will need to determine the ID of the Outstation.

    5.2 ScxV6Object.Class.Name

    As shown in the introduction, the properties defined on each of the ClearSCADAclasses are listed in the schema. The schema shows that different ClearSCADAclasses define different properties. However, ScxV6Object is used to referencedatabase objects of all ClearSCADA classes. If the program using the automationinterface attempts to read from, or write to, a property that does not exist on thereferenced ClearSCADA database object, the error shown in Figure 5-2 will occur.

    Figure 5-2 - Attempt to Read or Write a Non-Existent Property

    Given a ScxV6Object that references an object in the ClearSCADA database, howcan the program know which properties are valid?

    The Classproperty of ScxV6Object allows the programmer to determine theClearSCADA class of the database object referenced by an instance ofScxV6Object. This property returns an object of class ScxV6Class which, in turn, hasa Nameproperty which returns the name of the ClearSCADA class as a string.

    Therefore, the following statement will obtain the class of a ClearSCADA databaseobject referenced by a ScxV6Obejct

    Di m sCl ass As St r i ngsCl ass = oObj ect . Cl ass. Name

    Once the ClearSCADA class has been determined, the program can selectively

    access the ClearSCADA database object properties applicable to that class.

    Exercise

    1. Create a new Link Parameterin the ClearSCADA database using ViewX.2. Create a new Internal Digital Pointin the ClearSCADA database using ViewX.3. Write code to obtain a reference to the object linked to the Link Parameter.

    HINT:The link parameter has a property which is the Object ID of theClearSCADA object it is linked to.

    4. Write a code that determines the ClearSCADA Class of the object linked to theLink Parameter.

    5. Write code that will set the State 0 Descriptionof the linked object to Offif it isan Internal Digital Point.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    21/35

    ClearSCADA Automation Interface Training Notes

    Chapter 5 - Reading and Modifying ClearSCADA ObjectProperties

    Revision3.0

    17

    HINT:Use the VB If Then... ElseIf End If statement, or the Select CaseEnd Select statement.

    6. Write code that will set the Over-range descriptionof the linked object to TooHighif it is an Internal Analog Point.

    7. Test you code by changing the point linked to in the link parameter.

    Exercise (Advanced)

    1. Create a String Parameterin the ClearSCADA database using ViewX.2. Write code that will set the State 0 Descriptionof the linked object to the string

    value of the String Parameter if it is an Internal Digital Point.3. Write code that will set the Over-range Description of the linked object to the

    string value of the String Parameter if it is an Internal Analog Point.

    Exercise (Advanced)

    1. Create another String Parameter in the ClearSCADA database using ViewX.2. Write code that tells the user if the ClearSCADA class name of the object tied to

    the Link Parameter created in the previous exercise is the same as the stringvalue of the new String Parameter.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    22/35

    ClearSCADA Automation Interface Training Notes

    Chapter 6 - Creating, Renaming and Deleting ClearSCADAObjects

    Revision3.0

    18

    6 Creating, Renaming and Deleting ClearSCADA Objects

    The automation interface provides two methods for creating new objects in theClearSCADA database:

    ScxV6Server.CreateObject ScxV6Object.Create

    One method for renaming objects in the ClearSCADA database

    ScxV6Object.Rename

    And one method for deleting objects from the ClearSCADA database

    ScxV6Server.DeleteObject

    6.1 ScxV6Server.CreateObject and ScxV6Object.Create

    These two methods create a new object of the specified ClearSCADA class in theClearSCADA database. If the object is successfully created in the ClearSCADAdatabase, they return an instance of ScxV6Object which references the newly createobject. Refer to the ClearSCADA database schema for a list of class names that canbe created. If the name of a non-existent class is specified, the error shown in Figure6-1 will occur.

    Figure 6-1 - Non-Existent Class Name

    The programmer must also ensure that the specified class is one of the CreatableClasses. Creatable classes have a description string in parentheses after the classname in the schema. If a non-creatable class is specified, an error similar to the oneshown in Figure 6-2 will occur.

    Figure 6-2 - Non-Creatable Class Name

    Exercise

    1. Name a creatable class.2. Name a non-creatable class.

    ScxV6Server.CreateObject requires the absolute name of a Groupor Templateobject in the ClearSCADA database to be specified. The new object will be createdin the specified Group or Template. If the named Group or Template does not exist

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    23/35

    ClearSCADA Automation Interface Training Notes

    Chapter 6 - Creating, Renaming and Deleting ClearSCADAObjects

    Revision3.0

    19

    in the ClearSCADA Database the error shown in Figure 6-3 will occur. If the namedobject is a Template Instance, the error in Figure 6-4 will occur.

    Figure 6-3 - Create in Non-Existent Group

    Figure 6-4 - Create in a Template Instance

    The behaviour of ScxV6Object.Create depends on if the ClearSCADA objectreferenced by the ScxV6Object is a Group/Template or not as follows:

    If the ScxV6Object references a Groupor Template, the new object will becreated in the ClearSCADA database inside the referencedGroup/Template.

    If the ScxV6Object references a Template Instance, the error shown inFigure 6-4 will occur.

    Otherwise, the new object will be created in the Group/TemplatethatClearSCADA object referenced by the ScxV6Object is located in.

    6.2 ScxV6Object.Rename

    This method allows the programmer to rename objects in the ClearSCADAdatabase. This method is typically used to rename objects created with the objectcreating methods described above.

    The programmer must ensure that the new name adheres to the ClearSCADA objectnaming rules. If the supplied name is invalid, an error similar to the one shown in

    Figure 6-5 will occur.

    Figure 6-5 - Invalid Object Name

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    24/35

    ClearSCADA Automation Interface Training Notes

    Chapter 6 - Creating, Renaming and Deleting ClearSCADAObjects

    Revision3.0

    20

    Exercise

    1. Using the automation interface, create a new Groupin the ClearSCADAdatabase.

    2. Using the automation interface, rename the Group created in step 1.3. Use ScxV6Object.Create to create a new object in the Group created in step 1.4. Use ScxV6Server.CreateObject to create a new object in the Group created in

    step 1.

    6.3 ScxV6Server.DeleteObject

    This method allows objects in the ClearSCADA database to be deleted. If the Forceparameter is not set to True, and the object in the ClearSCADA database that isbeing deleted is referenced by other objects, an error similar to the one shown inFigure 6-6 will occur.

    Figure 6-6 - Deleting an Object Referenced by other Objects

    Exercise

    1. Use the automation interface to delete one of the groups (and all objects inside

    the group) created in the previous exercises

    HINT:ScxV6Server.DeleteObject will delete all objects within a Groupif theObject ID of a Groupin the ClearSCADA database is supplied.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    25/35

    ClearSCADA Automation Interface Training Notes

    Chapter 7 - Collections Revision3.0

    21

    7 Collections

    The methods ScxV6Server.Objects and ScxV6Object.List both return a collection ofinstances of ScxV6Object. Each instance will reference an object in the ClearSCADAdatabase that is either an instance of the specified ClearSCADA class, or aninstance of any class derived from the specified ClearSCADA class.

    ScxV6Server.Objects returns all objects in the ClearSCADA database of thespecified class.

    ScxV6Object.List can only be called on ScxV6Object objects that reference aninstance of CGroup, (or instances of classes derived from CGroup) in theClearSCADA database. If the ScxV6Object reference an object which is not aninstance of CGroup(or one of its derived classes), the error shown in Figure 7-1 willoccur.

    Figure 7-1 - Calling the List Method on an Object that is not a Group

    NOTE:ScxV6Object.List only return objects inside the group, it does notreturnobjects that are contained in groups within the referenced Group.

    7.1 The ScxV6Objects Object

    The ScxV6Server.Objects and ScxV6Object.List methods both return an instance ofthe automation interface collection class ScxV6Objects. Instances of ScxV6Objectsare essentially an array of ScxV6Object objects.

    The number of objects in the ScxV6Objects instance can be determined using theScxV6Objects.Count property. The ScxV6Objects.Item property returns the instanceof the ScxV6Obejct at the given index. Index numbers start at 1. If the requestedindex is less the 1, or greater than the number of objects in the collection, the errorshown in Figure 7-2 will occur.

    Figure 7-2 - Invalid Item Number

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    26/35

    ClearSCADA Automation Interface Training Notes

    Chapter 7 - Collections Revision3.0

    22

    Exercise

    1. Create a new group in the ClearSCADA database using ViewX2. Create a new Internal Analog Point in the ClearSCADA database

    3. Create a new Internal Digital Point in the ClearSCADA database4. Use ScxV6Objects.Count to determine the number of CPointAlgManual objectsexist in the new group

    5. Use ScxV6Objects.Count to determine the number of CPointDigitalManualobjects exist in the new group

    6. Use ScxV6Objects.Count to determine the number of CDBObject objects existin the new group

    One of the most common ways of using the ScxV6Objects class is with a For/Nextloop

    Di m oObj ect s as ScxV6Obj ects

    Di m oObj ect as ScxV6Obj ectDi m i Cur r ent Obj ect as I nt eger

    Set oObj ect s = oServer . Obj ects ( CPoi nt Al gManual )

    I f ( Not oObj ect s I s Not hi ng) Then

    For i Cur r ent Obj ect = 1 t o oObj ects. CountSet oObj ect = oObj ect s. I t em ( i Cur r ent Obj ect )

    . . . Do somet hi ng wi t h oObj ect . . .Next

    End I f

    Exercise1. Use the automation interface to set the State 0 Descriptionof all Internal Digital

    Points in the ClearSCADA database to On

    Exercise (Advanced)

    1. Create a new group in the ClearSCADA database2. Create another new group inside the group created in step 13. Create a number of Internal Digital Points in the groups created in steps 1 and 24. Use the automation interface to set the State 0 Description of all Internal Digital

    Points created in step 3 Do so without directly referencing the group created

    in step 2 (i.e. Assume that the name of the group created in step 2 is notknown)

    HINT:You will need to use the automation interface to find instances of CGroup

    Exercise (Advanced)

    1. Repeat the previous exercise, this time creating multiple groups (and multiplelevels).

    HINT:The easiest way to do this is with a recursive function.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    27/35

    ClearSCADA Automation Interface Training Notes

    Chapter 8 - Calling Methods on ClearSCADA Objects Revision3.0

    23

    8 Call ing Methods on ClearSCADA Objects

    The ScxV6Object.Interface method allows the automation interface to call methodson objects in the ClearSCADAV6 database. The format for calling methods in objectsin the ClearSCADA database is as follows:

    oObj . I nter f ace. . . .

    Where is the method defined by the ClearSCADA class and arethe arguments required by the method defined on the ClearSCADA class (refer tothe schema for the number and type of the arguments)

    The following example will accept the current active alarm on the ClearSCADAdatabase object Analog Point with the comment This is a Comment

    Set oObj ect = oSer ver . Fi ndObj ect ( "Anal og Poi nt ")

    I f ( Not oObj ect I s Nothi ng) ThenoObj . I nter f ace. AcceptWi t hComment Thi s i s a Comment

    End I f

    The following example will execute the logic program ST Program

    Set oObj ect = oServer . Fi ndObj ect ( "ST Pr ogr am")

    I f ( Not oObj ect I s Nothi ng) ThenoObj ect . I nt er f ace. Execut e

    End I f

    If the arguments supplied to the ClearSCADA method are incorrect (wrong numberof arguments, or wrong data type) the error shown below in Figure 23 will occur

    Figure 8-1 - Invalid Argument to ClearSCADA Method

    Exercise

    1. Use the automation interface to disable alarms on an Internal Analog Point inthe ClearSCADA database that is not in an active alarm state

    2. In ViewX, Hand Control the Internal Analog Point to a value above its over-range limit Confirm that alarm is not generated

    3. Use the automation interface to enable alarms on the Internal Analog Point4. Confirm that an alarm is generated

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    28/35

    ClearSCADA Automation Interface Training Notes

    Chapter 9 - Aggregates Revision3.0

    24

    9 Aggregates

    AnAggregateis a collection of related ClearSCADA properties and methods that canbe included in a ClearSCADA class. The most common aggregate accessed usingthe automation interface is the Historic (CHistory) aggregate. The Single and DualNetwork (CSingleNetwork and CDualNetwork) aggregates are also used frequentlywhen configuring network outstations. The PSTN (CAdvPSTN) and its derived classare used when configuring dial-up outstations.

    9.1 ScxV6Object.Aggregate

    The Aggregate property of ScxV6Object returns an instance of the ScxV6Aggregateclass which references the named aggregate of the ClearSCADA database objectreferenced by the ScxV6Object object. If the named aggregate does not exist on thereferenced object, the error shown in Figure 9-1 will occur.

    Figure 9-1 - Named Aggregate does not Exist

    Exercise

    1. Use the automation interface to display the class name of the Historicaggregate of any internal point created in the previous exercises.

    HINT:The Class property of the ScxV6Aggregate class is not the same asScxV6Object Use the object browser to determine the data type of thisproperty.

    9.2 ScxV6Aggregate.Enable

    Before the properties and methods defined on the aggregate can be accessed, theaggregate must be enabled. The aggregate may be enabled in ViewX be checkingthe Enablecheck box in the aggregates configuration as shown in Figure 9-2.

    Figure 9-2 - Using ViewX to Enable an Aggregate

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    29/35

    ClearSCADA Automation Interface Training Notes

    Chapter 9 - Aggregates Revision3.0

    25

    The aggregate can also be enabled using the automation interface by setting theEnable property of the ScxV6Aggregate object to True as shown in the followingexample

    Set oAgg = oObj ect . Aggr egate ( "Hi st or i c")

    I f ( Not oAgg I s Nothi ng) ThenoAgg. Enabl e = Tr ue

    End I f

    Similarly, aggregates can be disabled by setting the Enable property of theScxV6Aggregate object to False.

    Exercise

    1. Use ViewX to disable the Historic aggregate of any internal point created in theprevious exercises

    2. Use the automation interface to enable the Historic aggregate disabled in step 13. Confirm the aggregate is enabled in ViewX

    NOTE:You will need to close the properties dialog on the ClearSCADA objectin ViewX and open it again

    If an attempt is made to access the properties and methods of an aggregate that isnot enabled, the error shown in Figure 9-3 will occur.

    Figure 9-3 - Accessing Properties or Methods of a Disabled Aggregate

    9.3 ScxV6Aggregate.Property and ScxV6Aggregate.Interface

    ScxV6Aggregate.Property and ScxV6Aggregate.Interface are identical infunctionality to ScxV6Object.Property and ScxV6Object.Interface. Refer to Sections5 and 8.

    Exercise1. Use the automation interface to enable historic compression of the point that

    had its Historic aggregate enabled in the previous exercise.

    9.4 CHistory.LoadDataValue and CHistory.LoadDataFile

    The CHistory aggregates define the methods LoadDataValueand LoadDataFilewhich allow the automation interface to be used to load historic data into theClearSCADA database for a ClearSCADA database object which has its Historicaggregate enabled.

    The following example stores the value 12.3 with a timestamp of one second past1pm on the 10th December, 2004 with good quality into the point New Analog Point.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    30/35

    ClearSCADA Automation Interface Training Notes

    Chapter 9 - Aggregates Revision3.0

    26

    Di m oHi s As ScxV6Aggr egateDi m oObj As ScxV6Obj ect

    Set oObj = oServer . Fi ndObj ect ( "New Anal og Poi nt ")

    Set oHi s = oObj ect . Aggr egate ( "Hi st or i c")

    oHi s. Enabl e = True

    oHi s. I nt er f ace. LoadDataVal ue 192, "2004- 12- 10 13: 00: 01" , 12. 3

    The first argument to LoadDataValue is the data values Point Qualitywhich has thesame numeric values as OPC Point Qualities. The following qualities are defined inClearSCADA

    Quality Value

    Bad 0

    Uncertain 64

    Good 192Bad Configuration 4

    Not Connected 8

    Device Failure 12

    Sensor Failed 16

    Last Known 20

    Communication Failed 24

    Out of Service 28

    Last Useable 68

    Bad Sensor Calibration 80

    Engineering Units Exceeded 84Sub Normal 88

    Table 9-1 - OPC Quality Values

    The format of the data file read by LoadDataFile is detailed in Appendix B

    CAUTION: Data that is logged by the device drivers on the ClearSCADA Server isarchived more efficiently that data that is logged via the automation interface. This isdue to the fact that data logged by the device driver is practically guaranteed to be inchronological order (most protocols enforce this). Therefore, performance issuesmay arise if large amounts of historic data are logged using the automation interface.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    31/35

    ClearSCADA Automation Interface Training Notes

    Chapter 10- Templates and Instances Revision3.0

    27

    10 Templates and Instances

    The automation interface allows the creation of instances of CTemplate andCTemplateInstance in the ClearSCADA database. The same rules apply in theautomation interface as in ViewX when dealing with templates and instances in theClearSCADA database (i.e. object cannot be created in instances, only overriddenproperties can be modified in instances etc).

    10.1 CTemplateInstance.TemplateId

    An instance of ScxV6Object referencing a CTemplateInstance object in theClearSCADA database has a property, TemplateId which is a reference to atemplate in the ClearSCADA database.

    Exercise

    1. Use the automation interface to create a new template in the ClearSCADAdatabase

    2. Use the automation interface to create a new instance in the ClearSCADAdatabase

    3. Use the automation interface to tie the instance created in step 2 to thetemplate created in step 1

    10.2 CScxV6Object.PropertyOverride

    If the instance of ScxV6Object references a template object in the ClearSCADAdatabase, the PropertyOverride property can be used to query the state of, and

    enable/disable the property overrides of the referenced template. PropertyOverride iscalled in the ScxV6Object referencing the template, and requires the ClearSCADAobject id of the object located in the template, and the name of a configuration field(of the object within the template) to be specified.

    If the object in the ClearSCADA database referenced by the ScxV6Object is not atemplate, the error shown in Figure 10-1 will occur.

    Figure 10-1 - PropertyOverride Called on an Object that is not a Template

    If the object id of the object within the template is not the object id of an object withinthe template (or the object does not exist), the error shown in Figure 10-2 will occur.

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    32/35

    ClearSCADA Automation Interface Training Notes

    Chapter 10- Templates and Instances Revision3.0

    28

    Figure 10-2 - Property Override Called with an Object not in the Template

    If the requested configuration field does not exist on the ClearSCADA databaseobject with the specified object id the error shown in Figure 10-3 will occur

    Figure 10-3 - Property Override Called on a Non-Existent Field

    Exercise

    1. Create a new Internal Analog Point in the template created the previousexercise

    2. Use the automation interface to enable the property override for the Full Scaleconfiguration field of the internal Analog point created in step 1

    3. Confirm the property override in ViewX

    10.3 Reading and Writ ing Properties in Instances

    As with ClearSCADA database objects that are not contained in instances, theautomation interface can be used to read from, and write to, configuration fields ofobjects contained in Template Instatances. However, like ViewX, the ClearSCADAwill not allow the automation interface to set the value of a configuration field that isnot property overridden. If an attempt to write to a property that has not beenoverridden is attempted, the error shown below in Figure 30 will occur

    Figure 10-4 - Attempt to Write to a Property in an Instance that is not Overridden

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    33/35

    ClearSCADA Automation Interface Training Notes

    Appendix A- Inserting Historic Data Revision3.0

    29

    Appendix A VBScript Example

    The following code is the VBScript equivalent of to the example provided in Section2.5. The only differences are

    1. VBScript is type-less (has no data types) Dim statements have no As clause2. VBScript does not support New Objects in VBScript are created using

    CreateObject ()

    ' Decl are t he vari abl e f or t he Cl earSCADA Ser verDi m oSer ver

    ' Decl are t he var i abl e f or an Cl ear SCADA Obj ectDi m oObj ect

    ' Cr eate t he aut omati on i nt er f ace obj ect whi ch i s our' vi ew of t he Cl ear SCADA Ser verSet oServer = Cr eat eObj ect ( "Serck. ScxV6Server" )

    ' Check t hat t he aut omat i on i nt erf ace obj ect was' successf ul l y cr eat edI f ( Not oSer ver I s Nothi ng) Then

    ' Est abl i sh a connecti on t o the Cl earSCADA ServeroSer ver . Connect "MAI N", "" , ""

    ' Fi nd an obj ect i n the Cl ear SCADA databaseSet oObj ect = oServer . Fi ndObj ect ( "New Anal og Poi nt " )

    ' Check t hat t he obj ect was f oundI f ( Not oObj ect I s Not hi ng) Then' Di spl ay t he val ue of t he Poi nt i n a Message Box

    MsgBox (oObj ect . Proper t y( "Cur r ent Val ue") )

    ' Change t he val ue of t he Poi ntoObj ect . Proper t y( "Cur r ent Val ue") = 10

    ' Di spl ay the new val ue of t he Poi nt i n a Message BoxMsgBox (oObj ect . Proper t y( "Cur r ent Val ue") )

    End I fEnd I f

    ' Ti dy upSet oObj ect = Not hi ng

    ' Di sconnect f r omt he Cl ear SCADA ServeroServer . Di sconnect

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    34/35

    ClearSCADA Automation Interface Training Notes

    Appendix A- Inserting Historic Data Revision3.0

    30

    Appendix B Inserting Historic Data

    There are three methods if inserting historical data into the ClearSCADA databaseusing the automation interface.

    B.1 PresetTimestamp and PresetQuality

    The CPointAlgManual, CPointDigitalManual, CPointStringManual, andCPointTimeInternal classes provide the PresetTimestamp and PresetQualityproperties.

    If these properties are set before setting the CurrentValue property, the value will beadded to the historic database with the Timestamp and Quality provided.

    The timestamp provided by PresetTimestamp is interpreted by the server as beingUTC No translation is performed to account for time zones by the server

    The following example stores a value of 10 at 10th December 2004, 1:00:01PM(UTC) with Good Quality (192) in the history of the point New Analog Point

    Di m oObj As ScxV6Obj ect

    Set oObj = oServer . Fi ndObj ect ( "New Anal og Poi nt ")

    oObj . Proper t y ( "Pr esetQual i t y") = 192oObj . Propert y ( "PresetTi meSt amp") = "2004- 12- 10 13: 00: 01"oObj . Proper t y ( "Cur r ent Val ue") = 10

    B.2 CHistory.LoadDataValue

    The Chistory aggregate defines the LoadDataValue method which allows a historicvalue to be added to the history of a point.

    The following example stores a value of 10 at 10th December 2004, 1:00:01PM(Local Time) with Good Quality (192) in the history of the point New Analog Point

    Di m oHi s As ScxV6Aggr egateDi m oObj As ScxV6Obj ect

    Set oObj = oServer . Fi ndObj ect ( "New Anal og Poi nt ")

    Set oHi s = oObj . Aggr egate ( "Hi st ori c")

    oHi s. Enabl e = True

    oHi s. I nt er f ace. LoadDataVal ue 192, "2004- 12- 10 13: 00: 01" , 10

  • 7/23/2019 ClearSCADA Automation Interface Training Rev 3.0 2007.pdf

    35/35

    ClearSCADA Automation Interface Training Notes

    B.3 CHistory.LoadDataFile

    The Chistory aggregate defines the LoadDataFile method which allows a series ofhistoric values to be added to the history of a point from data stored in a file on the

    servers file system.

    The data file is series of comma separated data. Each row in the data file representsa single historic value. The format of each row is:

    , , , , , , ,

    For example, the following line represents a value of 12.3 with good quality at1:15:30PM on the 15th December 2004.

    2004, 12, 15, 13, 15, 30, 12. 3, 192

    The following example loads the historic data file C:\Temp\History.dat into the historyof the point New Analog Point

    Di m oHi s As ScxV6Aggr egateDi m oObj As ScxV6Obj ect

    Set oObj = oServer . Fi ndObj ect ( "New Anal og Poi nt ")

    Set oHi s = oObj ect . Aggr egate ( "Hi st or i c")

    oHi s. Enabl e = True

    oHi s. I nt er f ace. LoadDat aFi l e "C: \ Temp\ Hi st or y. DAT"