You are on page 1of 39

ClearSCADA Automation Interface

Reference Manual

CONTROL
MICROSYSTEMS
SCADA products... for the distance
48 Steacie Drive
Kanata, Ontario
K2K 2A9
Canada

Telephone:
613-591-1943
Facsimile:
613-591-1022
Technical Support: 888-226-6876
888-2CONTROL

1 Table of Contents
1

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

INTRODUCTION............................................................................................ 4

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

3.1

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

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

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

5.1

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

5.2

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

5.3

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

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

6.1

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

6.2

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

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

7.3.7
7.3.8
7.3.9
7.3.10
7.3.11
7.3.12
7.3.13
7.3.14
7.3.15
7.3.16
7.3.17
7.3.18
7.3.19
7.3.20
7.3.21
7.3.22
7.3.23

Find......................................................................................................... 19
FullName ................................................................................................ 20
GetSecurity ............................................................................................. 20
ID ............................................................................................................ 21
InstanceID............................................................................................... 22
Interface.................................................................................................. 22
List .......................................................................................................... 23
LoadConfigFile........................................................................................ 23
Move....................................................................................................... 24
Name ...................................................................................................... 24
Property .................................................................................................. 25
PropertyOverride .................................................................................... 25
References ............................................................................................. 26
Rename .................................................................................................. 26
SaveConfigFile ....................................................................................... 27
SetSecurity ............................................................................................. 27
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

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

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

4 Scxv6 Server Classes


There are 6 classes included in the SCX6 Automation Interface. These are described in
detail below:
ScxV6Aggregate
Class
Enable
Index
Interface
Property
ScxV6Class
ID
Name
ScxV6Object
Aggregate
Class
Convert
Copy
Create
Description
Find
FullName
GetSecurity
ID
InstanceID
Interface
List
LoadConfigFile
Move
Name
Property
PropertyOverride
References
Rename
SaveConfigFile
SetSecurity
TemplateID
ScxV6Objects
Count
Item
ScxV6Server

Abstraction of an SCX6 Aggregate


SCX6 class name of the referenced aggregate
Indicates/controls whether aggregate is enabled
Index of a multi-aggregate
Allows calling of methods on the aggregate
Provides interface to properties of aggregate
Container class for the SCX6 class of an object
The numerical Id of the SCX6 class
The string name of the SCX6 class
Abstraction of an SCX6 database object
Returns aggregate as instance of ScxV6Aggregate
Returns class of object as instance of ScxV6Class
Convert object to named class
Copy referenced object
Create an object of a specified class
Return value of first user defined search string
Find an object by name within referenced group
Returns full name of referenced object
Returns security settings of object
Returns Object ID of referenced object
Returns ObjectID of instance in which object is
found
Allows calling of methods on objects
Returns a collection of ScxV6Objects
Loads config of referenced object from file
Move object to another group
Returns name of referenced object
Provides interface to properties of object
Interface to property overrides on templates
Returns a collection of ScxV6Objects linked to
referenced object
Rename referenced object
Saves config of referenced object to file
Set security of referenced object
Returns ObjectID of template in which object is
found
Collection of instances of ScxV6Object
The number of objects in the collection
Retrieves a single object from the collection
Abstraction of an SCX6 system

ClearSCADA Automation Interface Reference

AcceptAlarmByCookie
BuildDate
BuildNumber
Connect
CreateObject
DeleteObject
Disconnect
FindObject
LookupObject
Objects
RootObject
Systems
ScxV6Systems
Count
Item

Accepts an active alarm


The build date of the automation interface
The build number of the automation interface
Connects to an SCX6 system
Creates an object in the SCX6 database
Deletes an object from the SCX6 database
Disconnects from the SCX6 system
Returns a reference to an object with a given name
located in the SCX6 database
Returns a reference to an object with a given ID
located in the SCX6 database
Returns a collection of objects of a given class
located in the SCX6 database
Return the root of the SCX6 database
Returns a collection of SCX6 systems defined in
the SCX V6 Client control panel
Collection of SCX6 system names
The number of systems defined in the SCX V6
Client control panel applet
Returns the name of a system

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

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

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
Dim oHis

As ScxV6Object
As ScxV6Aggregate

' Find the point 'testing' in the SCX6 database

ClearSCADA Automation Interface Reference

10

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

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
oHis.Property
oHis.Property
oHis.Property

properties
("Compress")
= True
("MinimumTime")
= 300
("TrendInterval") = "1H"

ClearSCADA Automation Interface Reference

12

oHis.Property ("TrendOffset")

ClearSCADA Automation Interface Reference

= "M-55M"

13

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

' 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

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")
oHis.Property ("MinimumTime")
oHis.Property ("TrendInterval")
oHis.Property ("TrendOffset")

ClearSCADA Automation Interface Reference

=
=
=
=

True
300
"1H"
"M-55M"

16

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

' 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

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

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

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

' 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

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
Dim oGrp
As
Dim oPnts
As
Dim iNumPnts As

called testing
ScxV6Object
ScxV6Objects
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 Servers 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

' 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

' 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

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

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 Servers 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 nonzero 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

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

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

Dim obj2 As ScxV6Object


Set obj2 = points.Item(6)

MsgBox obj2.FullName

ClearSCADA Automation Interface Reference

30

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
AlarmAcceptedOK
AlarmAlreadyAccepted
AlarmIDInvalid
AlarmNotExist
NotEnoughPriv
UndefinedAcceptError

Value
0
1
2
3
4
5

Comment
Alarm accepted OK
Alarm already accepted
Alarm cookie is invalid
Alarm does not exist
Not enough privileges to accept this alarm
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

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
Dim oSvr

As Long
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

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

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

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

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

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

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

Set oSystems = objServer.Systems


' Store the number of enabled systems
sSystemName = objSystems.Item (1)

ClearSCADA Automation Interface Reference

39

You might also like