clearscada automation interface reference

39
ClearSCADA Automation Interface Reference Manual CONTROL MICROSYSTEMS SCADA products... for the distance 48 Steacie Drive Telephone: 613-591-1943 Kanata, Ontario Facsimile: 613-591-1022 K2K 2A9 Technical Support: 888-226-6876 Canada 888-2CONTROL

Upload: zakirzyanov

Post on 10-Apr-2016

282 views

Category:

Documents


47 download

DESCRIPTION

ClearSCADA Automation Interface Reference

TRANSCRIPT

Page 1: ClearSCADA Automation Interface Reference

ClearSCADA Automation Interface

Reference Manual

CONTROL MICROSYSTEMS SCADA products... for the distance

48 Steacie Drive Telephone: 613-591-1943 Kanata, Ontario Facsimile: 613-591-1022 K2K 2A9 Technical Support: 888-226-6876 Canada 888-2CONTROL

Page 2: ClearSCADA Automation Interface Reference

1 Table of Contents

1 TABLE OF CONTENTS ................................................................................ 2

2 INTRODUCTION............................................................................................ 4

3 REVIEW OF TERMS ..................................................................................... 5

3.1 Object Orientated Programming Terms ......................................................... 5

4 SCXV6 SERVER CLASSES.......................................................................... 6

5 GETTING STARTED IN MICROSOFT VISUAL BASIC ................................ 8

5.1 Project References......................................................................................... 8

5.2 Basic Code Outline ........................................................................................ 8

5.3 Useful Information .......................................................................................... 8

6 GETTING STARTED WITH MICROSOFT EXCEL OR ACCESS.................. 9

6.1 Project References......................................................................................... 9

6.2 Other Information ........................................................................................... 9

7 SCXV6 AUTOMATION INTERFACE CLASSES......................................... 10

7.1 ScxV6Aggregate .......................................................................................... 10 7.1.1 Class....................................................................................................... 10 7.1.2 Enable .................................................................................................... 10 7.1.3 Index....................................................................................................... 11 7.1.4 Interface.................................................................................................. 11 7.1.5 Property .................................................................................................. 12

7.2 ScxV6Class.................................................................................................. 14 7.2.1 ID ............................................................................................................ 14 7.2.2 Name ...................................................................................................... 14

7.3 ScxV6Object ................................................................................................ 16 7.3.1 Aggregate ............................................................................................... 16 7.3.2 Class....................................................................................................... 17 7.3.3 Convert ................................................................................................... 17 7.3.4 Copy ....................................................................................................... 18 7.3.5 Create..................................................................................................... 18 7.3.6 Description (Deprecated) ........................................................................ 19

ClearSCADA Automation Interface Reference 2

Page 3: ClearSCADA Automation Interface Reference

7.3.7 Find......................................................................................................... 19 7.3.8 FullName ................................................................................................ 20 7.3.9 GetSecurity ............................................................................................. 20 7.3.10 ID ............................................................................................................ 21 7.3.11 InstanceID............................................................................................... 22 7.3.12 Interface.................................................................................................. 22 7.3.13 List .......................................................................................................... 23 7.3.14 LoadConfigFile........................................................................................ 23 7.3.15 Move....................................................................................................... 24 7.3.16 Name ...................................................................................................... 24 7.3.17 Property .................................................................................................. 25 7.3.18 PropertyOverride .................................................................................... 25 7.3.19 References ............................................................................................. 26 7.3.20 Rename .................................................................................................. 26 7.3.21 SaveConfigFile ....................................................................................... 27 7.3.22 SetSecurity ............................................................................................. 27 7.3.23 TemplateID ............................................................................................. 28

7.4 ScxV6Objects............................................................................................... 29 7.4.1 Count ...................................................................................................... 29 7.4.2 Item......................................................................................................... 29

7.5 ScxV6Server ................................................................................................ 31 7.5.1 AcceptAlarmByCookie ............................................................................ 31 7.5.2 BuildDate ................................................................................................ 31 7.5.3 BuildNumber ........................................................................................... 32 7.5.4 Connect .................................................................................................. 32 7.5.5 CreateObject........................................................................................... 33 7.5.6 DeleteObject ........................................................................................... 33 7.5.7 Disconnect .............................................................................................. 34 7.5.8 FindObject .............................................................................................. 35 7.5.9 LookupObject.......................................................................................... 35 7.5.10 Objects ................................................................................................... 36 7.5.11 RootObject.............................................................................................. 36 7.5.12 Systems.................................................................................................. 36

7.6 ScxV6Systems............................................................................................. 38 7.6.1 Count ...................................................................................................... 38 7.6.2 Item......................................................................................................... 38

ClearSCADA Automation Interface Reference 3

Page 4: ClearSCADA Automation Interface Reference

2 Introduction The ScxV6DbClient Automation Interface provides a library of objects that a programmer can use to change, modify and control the SCX6 Database. As the name implies, it allows you to automate tasks which would otherwise be time consuming and tedious. Note that the name SCX6 is used to describe the ClearSCADA database throughout this document. When the Automation Interface options are installed using the ClearSCADA installation program, a .dll program file is installed. The .dll file can then be referenced from a variety of standard windows programming interfaces like Visual Basic or Visual C++. The code examples in this document have been done using Microsoft Visual Basic, but the concepts can easily be applied to other programming environments

ClearSCADA Automation Interface Reference 4

Page 5: ClearSCADA Automation Interface Reference

3 Review of Terms

3.1 Object Orientated Programming Terms The automation interface makes use of object orientated programming standards. These standards make use of the following: CLASS: A class is a part of the program that defines the properties, methods and events of one or more object that will be created during execution. OBJECT: An object is an entity created at run time, which requires memory and some resources and is then destroyed when it's no longer needed or when the application ends. A class is a design time only entity, while an object is a run-time entity. An object has both properties and methods as defined in the class. PROPERTY: A property of an object contains data associated with attributes of that object. METHOD: Actions that can be performed on or by an object are called methods.

ClearSCADA Automation Interface Reference 5

Page 6: ClearSCADA Automation Interface Reference

4 Scxv6 Server Classes There are 6 classes included in the SCX6 Automation Interface. These are described in detail below:

ScxV6Aggregate Abstraction of an SCX6 Aggregate Class SCX6 class name of the referenced aggregate Enable Indicates/controls whether aggregate is enabled Index Index of a multi-aggregate Interface Allows calling of methods on the aggregate Property Provides interface to properties of aggregate

ScxV6Class Container class for the SCX6 class of an object ID The numerical Id of the SCX6 class Name The string name of the SCX6 class

ScxV6Object Abstraction of an SCX6 database object Aggregate Returns aggregate as instance of ScxV6Aggregate Class Returns class of object as instance of ScxV6Class Convert Convert object to named class Copy Copy referenced object Create Create an object of a specified class Description Return value of first user defined search string Find Find an object by name within referenced group FullName Returns full name of referenced object GetSecurity Returns security settings of object ID Returns Object ID of referenced object InstanceID Returns ObjectID of instance in which object is

found Interface Allows calling of methods on objects List Returns a collection of ScxV6Objects LoadConfigFile Loads config of referenced object from file Move Move object to another group Name Returns name of referenced object Property Provides interface to properties of object PropertyOverride Interface to property overrides on templates References Returns a collection of ScxV6Objects linked to

referenced object Rename Rename referenced object SaveConfigFile Saves config of referenced object to file SetSecurity Set security of referenced object TemplateID Returns ObjectID of template in which object is

found ScxV6Objects Collection of instances of ScxV6Object

Count The number of objects in the collection Item Retrieves a single object from the collection

ScxV6Server Abstraction of an SCX6 system

ClearSCADA Automation Interface Reference 6

Page 7: ClearSCADA Automation Interface Reference

AcceptAlarmByCookie Accepts an active alarm BuildDate The build date of the automation interface BuildNumber The build number of the automation interface Connect Connects to an SCX6 system CreateObject Creates an object in the SCX6 database DeleteObject Deletes an object from the SCX6 database Disconnect Disconnects from the SCX6 system FindObject Returns a reference to an object with a given name

located in the SCX6 database LookupObject Returns a reference to an object with a given ID

located in the SCX6 database Objects Returns a collection of objects of a given class

located in the SCX6 database RootObject Return the root of the SCX6 database Systems Returns a collection of SCX6 systems defined in

the SCX V6 Client control panel ScxV6Systems Collection of SCX6 system names

Count The number of systems defined in the SCX V6 Client control panel applet

Item Returns the name of a system

ClearSCADA Automation Interface Reference 7

Page 8: ClearSCADA Automation Interface Reference

5 Getting Started in Microsoft Visual Basic

5.1 Project References In order to use the classes defined in the ScxV6DbClient automation interface in Excel or Access, it must be added to the project references. This can be done in the Visual Basic Editor by selecting References from the Project menu and enabling the entry SCX V6 Automation Interface.

5.2 Basic Code Outline In order to run most of the examples in this document you will need the following code:

Sub MethodName() Dim oSvr As ScxV6Server Set oSvr = New ScxV6Server oSvr.Connect "Node Name", "AIUser", "AIPassword" ' Code from the various examples below should be inserted here oSvr.Disconnect End Sub

This code connects the application to the SCX system defined with the name Node Name in the SCX V6 Client control panel applet. The above code will connect to the SCX6 system using the username AIUser and pasword AIPassword. The username and password must match a username/password of a User object in the SCX6 database. The automation interface will be granted the same access rights to the database as any other method of connection (ViewX for example)

5.3 Useful Information In the Visual Basic Editor, the Object Browser can be used to view the classes defined by the automation interface, and the methods and properties that are defined on each class. To access the Object Browser press the F2 key, or select Object Browser from the View menu.

ClearSCADA Automation Interface Reference 8

Page 9: ClearSCADA Automation Interface Reference

6 Getting Started with Microsoft Excel or Access

6.1 Project References In order to use SCXV6 Server Classes in Access or Excel, you will need to add a reference to the SCX6 Automation Interface library. This can be done by selecting References from the Tools menu when in the Visual Basic Editor. To open the Visual Basic editor in Access, create a new Module. In Excel select Tools -> Macro ->Visual Basic Editor. Note that Macros may be disabled in the security settings. To enable Macros select Tools -> Macro ->Security. The Low or Medium settings will allow you to run Macros. You may have to restart Excel for this to take effect. Once you have the References dialogue open, tick the entry “SCX V6 Automation Interface”.

6.2 Other Information 6.2.1.1.1.1.1 Once you have added the References, the information in the previous

section regarding Microsoft Visual Basic can be used.

ClearSCADA Automation Interface Reference 9

Page 10: ClearSCADA Automation Interface Reference

7 SCXV6 Automation Interface Classes

7.1 ScxV6Aggregate

7.1.1 Class

Definition Property Class As String

Description This property returns the SCX6 class name of the referenced Aggregate.

Example The following example stores the SCX6 class name of the historic aggregate of the point testing in sAggClass.

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate Dim sAggClass As String ' Find the point 'testing' in the SCX6 database Set obj = objServer.FindObject ("testing") ' Get the historic aggregate Set oHis = obj.Aggregate ("Historic") ' Enable the historic aggregate oHis.Enable = True ' Store the aggregate class name sAggClass = His.Class

7.1.2 Enable

Definition Property Enable As Boolean

Description This property indicates if the referenced aggregate is enabled. This property can be written to, allowing the aggregate to be enabled or disabled programmatically.

Example This following example enabled the historic aggregate of the point testing

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate ' Find the point 'testing' in the SCX6 database

ClearSCADA Automation Interface Reference 10

Page 11: ClearSCADA Automation Interface Reference

Set obj = objServer.FindObject ("testing") ' Get the historic aggregate Set oHis = obj.Aggregate ("Historic") ' Enable the historic aggregate oHis.Enable = True

7.1.3 Index

Definition Property Index As Long

Description This property returns the index of a multi-aggregate. There are few aggregates that use this feature (Telegen 1150 outstations for example). Refer to the CTelegen1150OS in the SCX6 database schema. The index may be set using this property.

Example This following example sets Threshold1 of the Telegen 1150 TelegenOS to Fixed Increment

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate ' Find the Telegen Oustation ' TelegenOS ' in the SCX6 database Set obj = objServer.FindObject ("TelegenOS") ' Get the Threshold1 Aggregate Set oHis = obj.Aggregate ("Threshold1") ' Enable the Threshold1 aggregate oHis.Enable = True ' Set the Threshold1 aggregate to Fixed Increment oHis.Index = 3

7.1.4 Interface

Definition Property Interface As Object

Description This property provides a means of calling methods defined on the referenced SCX6 aggregate. Before methods of an aggregate can be executed, the aggregate must be enabled. This can be achieved using ViewX, or be using the enable property (refer to Sectio 7.1.2).

ClearSCADA Automation Interface Reference 11

Page 12: ClearSCADA Automation Interface Reference

Example The following example loads the historic data file C:\temp\history.dat into the historic archive of the point testing

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate ' Find the point 'testing' in the SCX6 database Set oObj = objServer.FindObject("testing") ' Get the historic aggregate Set oHis = obj.Aggregate("Historic") ' Enable the historic aggregate (enables historic logging) oHis.Enable = True ' Can now access methods oHis.Interface.LoadDataFile "C:\temp\history.dat"

7.1.5 Property

Definition Property Property (Name As String)

Description This property allows access to the SCX6 property of the referenced SCX6 aggregate. SCX6 properties that are not read-only may be set using this property. Before properties of an aggregate can be accessed, the aggregate must be enabled. This can be achieved using ViewX, or be using the enable property (refer to Sectio 7.1.2).

Example The following example enables the historic aggregate on the point testing and sets the historic logging options on the point

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate ' Find the point 'testing' in the SCX6 database Set oObj = objServer.FindObject("testing") ' Get the historic aggregate Set oHis = obj.Aggregate("Historic") ' Enable the historic aggregate (enables historic logging) oHis.Enable = True ' Can now set properties oHis.Property ("Compress") = True oHis.Property ("MinimumTime") = 300 oHis.Property ("TrendInterval") = "1H"

ClearSCADA Automation Interface Reference 12

Page 13: ClearSCADA Automation Interface Reference

oHis.Property ("TrendOffset") = "M-55M"

ClearSCADA Automation Interface Reference 13

Page 14: ClearSCADA Automation Interface Reference

7.2 ScxV6Class The ScxV6Class automation interface class is a container class which provides information regarding the SCX6 class of a database object referenced by an instance of ScxV6Object. An instance of ScxV6Class is returned by ScxV6Object.Class (refer to section 7.3.2). The programmer should not explicitly create new instances of ScxV6Class.

7.2.1 ID

Definition Property ID As Long

Description This property returns the ID of the SCX6 class.

Example The following example stores the SCX6 class id of the object testing in iClassID

Dim oObj As ScxV6Object Dim oClass As ScxV6Class Dim iClassID As Long ' Find the SCX6 database object called 'testing' Set oObj = objServer.FindObject("testing") ' Get the Class of the SCX6 object Set oClass = oObj.Class ' Store the ID of the SCX6 class iClassID = SCXClass.ID

7.2.2 Name

Definition Property Name As Long

Description This property returns the name of the SCX6 class.

Example The following example stores the SCX6 class name of the object testing in sClassName

Dim oObj As ScxV6Object Dim oClass As ScxV6Class Dim sClassName As String ' Find the SCX6 database object called 'testing' Set oObj = objServer.FindObject("testing")

ClearSCADA Automation Interface Reference 14

Page 15: ClearSCADA Automation Interface Reference

' Get the Class of the SCX6 object Set oClass = oObj.Class ' Store the name of the SCX6 class iClassName = SCXClass.Name

ClearSCADA Automation Interface Reference 15

Page 16: ClearSCADA Automation Interface Reference

7.3 ScxV6Object The ScxV6Object automation interface class provides an abstraction of an object in the SCX6 database. There are several methods and properties defined on the automation interface classes that return an instance of ScxV6Obejct (refer to sections 7.5.8 - ScxV6Server.FindObject and 7.5.9 ScxV6Server.LookupObject for example). These methods and properties each return an instance of ScxV6Object which is linked to an object in the SCX6 database (i.e. a ScxV6Object which references, or refers to a SCX6 database object). Instances of ScxV6Object should not be explicitly created by the programmer as there is no way of linking an explicitly created instance of ScxV6Object to an object in the SCX6 database. Each instance of ScxV6Object can only reference a single object in the SCX6 database (the ScxV6Objects collection allows the programmer to process multiple SCX6 database objects – refer to Section Error! Reference source not found.).

7.3.1 Aggregate

Definition Property Aggregate (Name as String) As ScxV6Aggregate

Description This property returns the named aggregate of the SCX6 database object as an instance of ScxV6Aggregate. If the named aggregate does not exist on the SCX6 database object, this function will generate a run-time error. Refer to Section 7.1

Example The following example enables the historic aggregate of the point test, and configures the historic logging properties of the point

Dim oObj As ScxV6Object Dim oHis As ScxV6Aggregate ' Find Analogue point called 'test' Set oObj = oSvr.FindObject ("test") ' Get the historic aggregate Set oHis = oObj.Aggregate ("Historic") ' Enable the historic option oHis.Enable = True ' SetProperties on Aggregate oHis.Property ("Compress") = True oHis.Property ("MinimumTime") = 300 oHis.Property ("TrendInterval") = "1H" oHis.Property ("TrendOffset") = "M-55M"

ClearSCADA Automation Interface Reference 16

Page 17: ClearSCADA Automation Interface Reference

7.3.2 Class

Definition Property Class As ScxV6Class

Description This property returns the SCX6 class of the referenced object as an instance of ScxV6Class. Refer to section 7.2

Example The following example obtains the SCX6 class name of the database object test and stores it as a string in the variable sClassName

Dim oObj As ScxV6Object Dim oCls As ScxV6Class Dim sClassName As String ' Find Analogue point called 'test' Set oObj = objServer.FindObject ("test") ' Get name of class for ‘test’ Set oCls = oObj.Class sClassName = oCls.Name

7.3.3 Convert

Definition Sub Convert (Class As String)

Description This method converts the referenced object to the named class. If the conversion cannot be performed, a run-time error will be generated. Caution: The automation interface is less restrictive than ViewX in regard to converting database objects. For example, the automation interface will allow digital points to be converted to analogue point types – ViewX does not allow this.

Example The following example converts the point ‘test’ to a DNP3 Binary Input point.

Dim oObj As ScxV6Object ' Find Internal Digital point called 'test' Set oObj = objServer.FindObject ("test")

ClearSCADA Automation Interface Reference 17

Page 18: ClearSCADA Automation Interface Reference

' Convert to DNP3 Binary Input oObj.Convert ("CDNP3BinaryIn")

7.3.4 Copy

Definition Function Copy (NewParentId As Long) As ScxV6Object

Description This method creates a copy of the referenced SCX6 database object in the SCX6 database group according to the following rules

1. If the SCX6 database object referenced by the supplied ID is of class CGroup or CTemplate, the copy is created inside the group referenced by the supplied ID

2. If the SCX6 database object referenced by the supplied ID is of class CTemplateInstance, a run-time error is generated

3. Otherwise, the copy is created in the group containing the object referenced by the supplied ID

Example The following example creates a copy of a point p1 located in group Group1 and places it into the group Group2. It then renames the newly created point to p2 (refer to Section 7.3.20)

Dim oObj As ScxV6Object Dim oObj2 As ScxV6Object Dim oGroup As ScxV6Object ' Find the point called "p1" in group "Group1" Set oObj = objServer.FindObject ("Group1.p1") ' Place copy of object in folder "Group2" Set oGroup = objServer.FindObject ("Group2") Set obj2 = obj.Copy (objgroup.ID) ' Rename copy obj2.Name = "p2"

7.3.5 Create

Definition Function Create (Class As String) As ScxV6Object

Description The object creates a new object of the specified class in the SCX6 database. The returned ScxV6Object references the newly created object.

ClearSCADA Automation Interface Reference 18

Page 19: ClearSCADA Automation Interface Reference

The location of the new object in the SCX6 database is determined according to the following rules

4. If the SCX6 database object referenced by the object the method is called on is of class CGroup or CTemplate, the new object is created inside the group referenced by the object the method is called on

5. If the SCX6 database object referenced by the object the method is called on is of class CTemplateInstance, a run-time error is generated

6. Otherwise, the copy is created in the group containing the object referenced by the object the method is called on

Example The following example creates a new DNP3 Binary Input Point in the group testing and renames it to New Point (refer to Section 7.3.20)

Dim oObj As ScxV6Object Dim oNewObj As ScxV6Object ' Find group called 'testing' Set oObj = objServer.FindObject ("testing") ' Create a DNP3 Binary Input point in folder 'testing' Set oNewObj = oObj.Create ("CDNP3BinaryIn") oNewObj.Rename ("New Point")

7.3.6 Description (Deprecated)

Definition Property Description As String

Description This property returns the value of the first user defined search key of the referenced SCX6 database object. If there is no such search key defined, this property will return a blank string. Historically, the first search key was used to add a description to a database object. All user defined search keys, links, pull down lists etc are directly accessible using Property. The use of the Description property is strongly discouraged.

7.3.7 Find

Definition Function Find (Name As String) As ScxV6Object

Description This method returns the named SCX6 database object located in the Group referenced by the object this method is called on. If the SCX6 database object referenced by the object this method is called on is not of class CGroup (or one of its derived classes), a run-time error will be generated. This method can only be used to obtain references to objects within the

ClearSCADA Automation Interface Reference 19

Page 20: ClearSCADA Automation Interface Reference

group referenced by the object this method is called on; it cannot be used to obtain references to objects in groups within the referenced group. For example, the following code is not valid

Set oSCX6Object1 = oSCX6Server.FindObject ("Group1") Set oSCX6Object2 = oSCX6Object1.Find ("Group2.Object")

Example The following example finds an object called testing in the group group1.

Dim oGrp As ScxV6Object Dim oObj As ScxV6Object ' Find the group called 'group1' Set oGrp = objServer.FindObject ("group1") ' Find object called 'testing' in 'group1' Set oObj = oGrp.Find ("testing")

7.3.8 FullName

Definition Property FullName As String

Description This property returns the full name of the referenced SCX6 database object as a string. The full name is the absolute name of the object within the SCX6 database.

Example The following example stores the full name of a given object into the string sFullName. sFullName will contain the string testing.object1

Dim oObj As ScxV6Object Dim sFullName As String ' Find object called 'testing.object1' Set oObj = objServer.FindObject("testing.object1") ' Get the full name of the object sFullName = oObj.FullName

7.3.9 GetSecurity

Definition Function GetSecurity () As String

ClearSCADA Automation Interface Reference 20

Page 21: ClearSCADA Automation Interface Reference

Description This method returns the security settings of the referenced object as a string. The returned string is a comma separated list of security settings. Each setting will be of one of the following forms:

1. Everyone:<permissions> 2. User:<username>:<permissions> 3. Group:<groupname>:<permissions>

Where: <username> is the full name of an object of class CDBUser located in the SCX6 database <groupname > is the full name of an object of class CDBUserGroup located in the SCX6 database <permissions> is a string of permissions that have been allocated to the user or group e.g. “View + BRS” indicates View and Browse privilege.

Example The following example obtains the security string of the object testing

Dim oObj As ScxV6Object Dim sSecurity As String ' Find object called 'testing' Set oObj = objServer.FindObject ("testing") ' Get current security settings sSecurity = myPoint.GetSecurity ()

7.3.10 ID

Definition Property ID As Long

Description This property returns the ID of the referenced SCX6 database object. Each object in the SCX6 database has a unique ID which is generated when the object is created in the SCX6 database. The ID does not change when the object is moved or renamed unless it is moved into, or out of, and Template.

Example The following example obtains the object ID of the object testing.

Dim oObj As ScxV6Object Dim iID As Integer ' Find object called 'testing' Set oObj = objServer.FindObject ("testing")

ClearSCADA Automation Interface Reference 21

Page 22: ClearSCADA Automation Interface Reference

' Obtain the ID of the object. iID = myPoint.ID

7.3.11 InstanceID

Definition Property InstanceID As Long

Description This property returns the SCX6 object Id of the template instance the referenced object is located in. If the referenced object is not contained in a template instance, this property returns 0.

Example The following example store the Id of the object New Instance in the variable iInstanceID

Dim oObj As ScxV6Object Dim iInstnaceID As Integer ' Find the object 'testing’ in the instance 'New Instance' Set oObj = objServer.FindObject("New Instance.testing") ' Return the Instance ID of my folder called 'testing' iInstnaceID = oObj.InstanceID

7.3.12 Interface

Definition Property Interface As Object

Description The Interface property provides a means of calling methods defined on SCX6 objects.

Example The following example disables alarms on all objects within the group group

Dim obj As ScxV6Object ' Find group 'group' Set obj = objServer.FindObject ("group") ' Disable Alarms on group obj.Interface.DisableAlarms

ClearSCADA Automation Interface Reference 22

Page 23: ClearSCADA Automation Interface Reference

7.3.13 List

Definition Function List (Class As String) As ScxV6Objects

Description This method returns a collection of ScxV6Object objects. Each object in the collection is a reference to an SCX6 database object of the supplied class (or any class derived from the supplied class). The objects referenced by the returned collection are located in the Group referenced by the object the list method was called on. This method does not return references to objects located inside Groups within the referenced SCX6 database object. If the SCX6 database object referenced by the object the list method is called on is not of class CGroup (or a class derived from CGroup), a run-time error will be generated.

Example The following example finds the group testing, obtains a list of Internal Digital Points contained within that group, and stores the number of items in this list in iNumPoints.

'Find the group called testing Dim oGrp As ScxV6Object Dim oPnts As ScxV6Objects Dim iNumPnts As Integer

' Find the group 'testing' Set oGrp = objServer.FindObject ("testing") ' Obtain the list of Internal Digital Points in ' the group 'testing' Set oPnts = myFolder.List("CPointDigitalManual") ' obtain the number of points in the group 'testing' iNumPnts = oPnts.Count

7.3.14 LoadConfigFile

Definition Sub LoadConfigFile (FileName As String)

Description This method loads the configuration of the referenced SCX6 database object from a file on the main SCX6 Server’s operating system file system.

Example The example finds the object testing and sets the configuration of that object based on the contents of the file C:\temp\config

Dim obj As ScxV6Object

ClearSCADA Automation Interface Reference 23

Page 24: ClearSCADA Automation Interface Reference

' Find object called 'testing' Set obj = objServer.FindObject ("testing") ' Load the configuration for the object 'testing' ' from the file C:\temp\config obj.LoadConfigFile ("C:\temp\config")

7.3.15 Move

Definition Sub Move (NewParentId As Long)

Description This method moves the referenced SCX6 database object to another Group within the SCX6 database. The SCX6 object Id of the target group is supplied as an argument to this method.

Example The following example finds the object testing and moves it into the group group1.

Dim oObj As ScxV6Object Dim oGrp As ScxV6Object ' Find my point called test Set oObj = objServer.FindObject ("testing") ' Find the group 'group1' Set oGrp = objServer.FindObject ("group1") ' Move the object 'testing' into the group 'group1' oObj.Move (oGrp.ID)

7.3.16 Name

Definition Property Name As String

Description This property returns the name of the referenced object.

Example The following example finds the object group1.testing and stores the objects name in the string sName. sName will contain the string testing

Dim oObj As ScxV6Object Dim sName As String ' Find my point called test Set oObj = objServer.FindObject("group1.testing")

ClearSCADA Automation Interface Reference 24

Page 25: ClearSCADA Automation Interface Reference

' Obtain the name of the object sName = oObj.Name

7.3.17 Property

Definition Property Property (Name As String)

Description This property allows access to the SCX6 property of the referenced SCX6 database object. SCX6 properties that are not read-only may be set using this property.

Example The following example finds the object testing, stores the id of the objects Help View in iOldID, and finally sets the objects Help View to New Help View

Dim oObj As ScxV6Object Dim iOldID As Integer Dim oNewHelpView As ScxV6Object ' Find the object 'testing' Set oObj = objServer.FindObject ("testing") ' Store the Object ID of the current Help View iOldID = obj.Property ("HelpViewId") ' Find the object 'New Help View' Set oNewHelpView = objServer.FindObject ("New Help View") ' Set the help view of 'testing' to 'New Help View' oObj.Property ("HelpViewId") = oNewHelpView.ID

7.3.18 PropertyOverride

Definition Property PropertyOverride (ObjectId As Long, Field As String) As Long

Description This property allows access to the property override of a configuration field of an object in an SCX6 template. This property can be used to read and write property overrides. This property can only be accessed on a reference to an SCX6 Template object. If this property is accessed on a reference to an SCX6 database object that is not a template, a run time error will occur.

Example The following examples set the property override of the configuration field HelpViewId of the object testing in the SCX6 template template1

ClearSCADA Automation Interface Reference 25

Page 26: ClearSCADA Automation Interface Reference

Dim oObj As ScxV6Object Dim oTemplate As ScxV6Object ' Find object 'template1.testing' Set oObj = objServer.FindObject ("template1.testing") ' Find the template that the object 'testing' is in Set oTemplate = objServer.LookupObject (oObj.TemplateID) ' Enable the Property Override 'HelpViewId' field of ' the object 'testing' oTemplate.PropertyOverride (oObj.ID, "HelpViewId") = 1

7.3.19 References

Definition Function References () As ScxV6Objects

Description This method returns a collection of ScxV6Object objects as an instance of ScxV6Objects (refer to Section 7.3). Each object in the collection is a reference to a SCX6 database object which references the object in the SCX6 database referenced by the ScxV6Object this method is accessed on.

Example The following example stores the number of objects referencing the object testing in the variable iNumReferences

Dim oObj As ScxV6Object Dim oReferences As ScxV6Objects Dim iNumReferences As Integer ' Find the SCX6 database object 'testing' Set oObj = objServer.FindObject ("testing") ' Obtain the list of references. Set oReferences = oObj.references ' Store the number of referenced objects iNumReferences = oReferences.Count

7.3.20 Rename

Definition Sub Rename (Name As String)

Description The method renames the referenced SCX6 database object.

ClearSCADA Automation Interface Reference 26

Page 27: ClearSCADA Automation Interface Reference

Example The following example renames the object testing to not testing

Dim oObj As ScxV6Object ' Find the object 'testing' Set oObj = objServer.FindObject ("testing") ' Rename the object oObj.Rename ("not testing")

7.3.21 SaveConfigFile

Definition Sub SaveConfigFile (FileName As String)

Description This method saves the configuration of the referenced SCX6 database object to a file on the main SCX6 Server’s operating system file system.

Example The following example finds the SCX6 database object testing and saves its configuration to c:\temp\config.cfg

Dim oObj As ScxV6Object ' Find the object 'testing' Set obj = objServer.FindObject ("testing") ' Save the config of the object to C:\temp\config.cfg obj.SaveConfigFile ("c:\temp\config.cfg")

7.3.22 SetSecurity

Definition Sub SetSecurity (Security As String, Recursive As Long)

Description This method sets the security settings of the referenced SCX6 database object as per the string supplied as the Security parameter. Refer to section 7.3.9 for the format of the security string. The Recursive parameter indicates whether the security settings should be applied to all child objects of the references SCX6 database object. The effect of setting this flag to non-zero is to clear the security settings of all child objects. When the SCX6 sever accesses an object with no security settings, the server will use the security setting of the parent object.

ClearSCADA Automation Interface Reference 27

Page 28: ClearSCADA Automation Interface Reference

The server will continue traversing up the database tree until a parent with security settings is found, or the root of the database tree is reached.

Example The following example copies the security setting from the SCX6 object secure and applies them to the SCX6 database object insecure

Dim oObj1 As ScxV6Object Dim oObj2 As ScxV6Object ' Find the database objects 'secure' and 'insecure' Set oObj1 = objServer.FindObject("secure") Set oObj2 = objServer.FindObject("insecure") ' Copy the security settings from 'secure' to 'insecure' oObj2.SetSecurity oObj1.GetSecuity, 1

7.3.23 TemplateID

Definition Property TemplateID As Long

Description This property returns the SCX6 object Id of the template the referenced object is located in. If the referenced object is not contained in a template, this property returns 0.

Example The following example store the Id of the object New Template in the variable iTemplateID

Dim oObj As ScxV6Object Dim iTemplateID As Integer ' Find the object 'testing’ in the instance 'New Template' Set oObj = objServer.FindObject("New Template.testing") ' Store the Template ID of my folder called 'testing' iTemplateID = oObj.TemplateID

ClearSCADA Automation Interface Reference 28

Page 29: ClearSCADA Automation Interface Reference

7.4 ScxV6Objects

7.4.1 Count

Definition Property Count As Long

Description This property returns the number of objects in the list.

Example This code finds all the internal digital points in a group ‘testing’ and displays the number of points in the list.

'Find my folder called testing Dim myFolder As ScxV6Object Set myFolder = objServer.FindObject("testing") 'Return the list of internal digital points in the folder called testing. Dim points As ScxV6Objects Set points = myFolder.List("CPointDigitalManual") 'Display the amount of points in my list. msgbox points.Count

7.4.2 Item

Definition Property Item(Idx As Long)

Description This property returns the selected object from the list.

Example This example gets a list of all internal digital points in a group ‘testing’ and displays the Full Name of the 6th item in the list.

'Find my folder called testing Dim myFolder As ScxV6Object Set myFolder = objServer.FindObject("testing") 'Return the list of internal digital points in the folder called testing. Dim points As ScxV6Objects Set points = myFolder.List("CPointDigitalManual") 'Select the 6th object from the list and display the Full name

ClearSCADA Automation Interface Reference 29

Page 30: ClearSCADA Automation Interface Reference

Dim obj2 As ScxV6Object Set obj2 = points.Item(6) MsgBox obj2.FullName

ClearSCADA Automation Interface Reference 30

Page 31: ClearSCADA Automation Interface Reference

7.5 ScxV6Server

7.5.1 AcceptAlarmByCookie

Definition Function AcceptAlarmByCookie (CookieId As Long, Comment As String) As ScxAcceptResult

Description This method accepts an active alarm identified by the Cookie Id supplied as the first parameter. The Cookie Id of an alarm can be sent within an email alarm redirection using the %I Trip Character (refer to the Alarm Redirections section of the SCX6 Core Guides) A comment for the alarm acceptance can be supplied as the second parameter. If no comment is required, a null string must be passed as the second parameter. This method returns a result of type ScxAcceptResult. The ScxAcceptResult enumeration has the following defined constants

Constant Value Comment AlarmAcceptedOK 0 Alarm accepted OK AlarmAlreadyAccepted 1 Alarm already accepted AlarmIDInvalid 2 Alarm cookie is invalid AlarmNotExist 3 Alarm does not exist NotEnoughPriv 4 Not enough privileges to accept this alarm UndefinedAcceptError 5 Undefined error

Example The following example accepts the alarm with the cookie id stored in iAlarmId and comment stored in sComment and stores the acceptance result iResult.

Dim iAlarmId As Long Dim sComment As String Dim iResult As ScxAcceptResult ' Accept Alarm with Id iAlarmId. Use sComment as the ' acceptance comment iResult = objSCXObject.AcceptAlarmByCookie (iAlarmId, sComment)

7.5.2 BuildDate

Definition Property BuildDate As String

ClearSCADA Automation Interface Reference 31

Page 32: ClearSCADA Automation Interface Reference

Description This property returns the build date of the automation interface. This property may be accessed before a connection to an SCX6 system is established.

Example The following example stores the build date of the automation interface in the string sBuildDate.

Dim sBuildDate As String Dim oSvr As ScxV6Server Set oSvr = New ScxV6Server ' Obtain the build date sBuildDate = oSvr.BuildDate

7.5.3 BuildNumber

Definition Property BuildNumber As Long

Description This property returns the build number of the automation interface. This property may be accessed before a connection to an SCX6 system is established.

Example The following example stores the build number of the automation interface in the string sBuildNum.

Dim sBuildNum As Long Dim oSvr As ScxV6Server Set oSvr = New ScxV6Server ' Obtain the build date sBuildNum = oSvr.BuildNumber

7.5.4 Connect

Definition Sub Connect (Node As String, Username As String, Password As String)

Description This method establishes a connection to the SCX6 system with the name supplied as the first parameter. The named SCX6 system must be defined in the local SCX V6 Client control panel applet. The second and third parameters provide the username and password of a user defined in the SCX6 system named in the first parameter. The username and password are

ClearSCADA Automation Interface Reference 32

Page 33: ClearSCADA Automation Interface Reference

case sensitive. These credentials are used for all subsequent operations in the database using this ScxV6Server object

Example The following example connects to the SCX6 system testing with the username User and password Pass.

Dim oSvr As ScxV6Server Set oScxV6Server = New ScxV6Server ' Connect to the SCX6 system oSvr.Connect "testing", "User", "Pass"

7.5.5 CreateObject

Definition Function CreateObject (Class As String, Group As String) As ScxV6Object

Description This method creates a new object in the SCX6 database and returns a reference to the new object as an instance of ScxV6Object. The SCX6 class of the new object is defined by the first parameter. The SCX6 group that the new object is created in is defined by the second parameter, which must be an absolute name of an object, that is not a template instance, in the SCX6 database If the second parameter is the absolute name of a Group or Template, the new object will be created inside the named group/template. Otherwise, the new object will be created in the parent group of the named object (i.e. will be created inside the same group as the named object). The name $Root defines the root group of the SCX6 database.

Example The following example creates a new Internal Analogue Point in the root of the SCX6 database

Dim oObj As ScxV6Object ' Create the new object Set oObj = oSvr.CreateObject ("CPointAlgManual", "$Root")

7.5.6 DeleteObject

Definition Sub DeleteObject (ID As Long, Force As Long)

ClearSCADA Automation Interface Reference 33

Page 34: ClearSCADA Automation Interface Reference

Description This method deletes the object with the SCX6 object id matching the ID parameter from the SCX6 database. The Force parameter determines if the object is forcibly deleted if other objects in the SCX6 database reference it. If the Force parameter is non-zero, the object will be forcibly removed from the SCX6 database. If the Force parameter is zero, the object will be deleted only if no other objects in the SCX6 database references the object to be deleted. Note: Any instance of the automation interface class ScxV6Object referencing the deleted object will be invalidated after the object is deleted from the SCX6 database.

Example The following example forcibly deletes the object testing from the SCX6 database

Dim oObj As ScxV6Object ' Find the object 'testing' in the SCX6 databse Set oObj = oSvr.FindObject ("testing") ' Delete the object objServer.DeleteObject oObj.ID, 1 ' Note: oObj is now an invalid reference Set oObj = Nothing

7.5.7 Disconnect

Definition Sub Disconnect ()

Description This method disconnects the automation interface from the current SCX6 system

Example The following example connects to the SCX6 system local and then disconnects

Dim oSvr As ScxV6Server ' Create the server object Set objServer = New ScxV6Server ' Connect to the SCX6 system objServer.Connect "local", "UserName", "Password" ' Disconnect from the SCX6 system objServer.Disconnect

ClearSCADA Automation Interface Reference 34

Page 35: ClearSCADA Automation Interface Reference

7.5.8 FindObject

Definition Function FindObject (Name As String) As ScxV6Object

Description This method locates the object with the absolute name provided by the Name parameter in the SCX6 database. The Name parameter must supply the name of the object using the SCX6 database object naming conventions.

Example The following example finds the object testing in the group group1 and assigns it to oObj ScxV6Object obj.

Dim oObj As ScxV6Object ' Find object 'testing' located in 'group1' Set oObj = objServer.FindObject("group1.testing")

7.5.9 LookupObject

Definition Function LookupObject (ID As Long) As ScxV6Object

Description This method locates the object with the SCX6 object id matching the ID parameter in the SCX6 database. This method is usually used to locate an object referenced by another object.

Example The following example obtains the Help View of the SCX6 database object testing and assigns it to oDefView

Dim oObj As ScxV6Object Dim iHelpView As Long Dim oHelpView As ScxV6Object ' Find the object 'testing' in the SCX6 database Set oObj = objServer.FindObject ("testing") ' Obtain the ID of the help view iDefView = oObj.Property ("HelpViewId") Set oHelpView = objServer.LookupObject (iDefView)

ClearSCADA Automation Interface Reference 35

Page 36: ClearSCADA Automation Interface Reference

7.5.10 Objects

Definition Property Objects (Class As String) As ScxV6Objects

Description This property returns all objects in the SCX6 database of the class specified by the Class parameter (and all classes derived from the named class). The objects are return in an instance of ScxV6Objects (refer to Section Error! Reference source not found.).

Example The following example locates all Internal Analogue Points in the SCX6 database and sets their Full Scale to 1000.

Dim oObjs As ScxV6Objects Dim iObj As Interger ' Find all Internal Analogue Points Set oObjs = objServer.Objects ("CPointAlgManual") ' Set Full Scale property of all Internal Analogue Points to 1000 For iObj = 1 To oObjs.Count oObjs.Item (iObj).Property ("FullScale") = 1000 Next

7.5.11 RootObject

Definition Property RootObject As ScxV6Object

Description This property returns the root object of the SCX6 database.

Example The following example finds the root object of the SCX6 database.

Dim objObject As ScxV6Object 'Return the Root object Set objObject = objServer.RootObject

7.5.12 Systems

Definition Property Systems As ScxV6Systems

ClearSCADA Automation Interface Reference 36

Page 37: ClearSCADA Automation Interface Reference

Description This property returns a list of systems that ViewX is currently connected to.

Example This example gets a list of all the enabled client connections on the local machine and displays the name of the 3rd item. This example will not work if less than three client connections are enabled.

'Return the list of systems Dim objSystems As ScxV6Systems Set objSystems = objServer.Systems 'Display the name of the 3rd system MsgBox objSystems.Item(3)

ClearSCADA Automation Interface Reference 37

Page 38: ClearSCADA Automation Interface Reference

7.6 ScxV6Systems The ScxV6Systems class is a collection class which provides the programmer a method of determining the names of the systems defined in the SCX V6 Client control panel applet. Only systems that are enabled in the SCX V6 client will be added to the ScxV6Systems collection.

7.6.1 Count

Definition Property Count As Long

Description This property returns the number of enabled systems defined in the SCX V6 Client controls panel applet. If systems are added or removed (or enabled/disabled) the application using the automation must be restarted in order for this collection to reflect the changes.

Example This example stores the number of enabled systems in iNumSystems.

Dim oSystems As ScxV6Systems Dim iNumSystems As Long ' Obtain the list of enabled systems Set oSystems = objServer.Systems ' Store the number of enabled systems iNumSystems = objSystems.Count

7.6.2 Item

Definition Property Item (Idx As Long)

Description This property returns the name of the SCX6 enabled in the SCX V6 Client control panel applet with the index provided by the Idx parameter. The Idx parameter must be between 1 and the value returned by the Count property described above (inclusive).

Example The following example stores the name of the first SCX6 system enabled in the SCX V6 Client control panel applet in the string sSystemName.

Dim oSystems As ScxV6Systems Dim sSystemName As String

' Obtain the list of enabled systems

ClearSCADA Automation Interface Reference 38

Page 39: ClearSCADA Automation Interface Reference

Set oSystems = objServer.Systems ' Store the number of enabled systems sSystemName = objSystems.Item (1)

ClearSCADA Automation Interface Reference 39