E3 Scripts Reference Manual

© 2013 Elipse Software Ltda. All rights reserved.

02/04/2013 - Version 4.0
Table of Contents
1 Introduction 4
1.1 Objects 4
1.2 Scripts 5
1.3 Picks 8
1.4 User-Defined Events 15
2 Programming in E3 18
2.1 Programming Environment 18
2.2 Declaring Variables 19
2.3 Getting References to Objects 19
2.4 Accessing Objects 30
2.5 Working with Collections 31
2.6 Set Command 32
2.7 E3Globals 33
2.8 General Events, Methods, and Properties of Objects 41
3 User Libraries 61
3.1 XControls and XObjects 61
3.2 ElipseX Properties 63
4 View 65
4.1 Viewer 65
4.2 Frames and Splitters 91
4.3 Screens and Screen Objects 98
4.4 E3Alarm 222
4.5 E3Browser 234
4.6 E3Chart 242
4.7 E3Playback 285
4.8 Reports 286
5 Server Objects 329
5.1 General Properties 329
5.2 Server's Runtime Objects 331
5.3 Configuration-Only Objects 334
5.4 Drivers 336
5.5 Data Server 392
5.6 Database 408
5.7 Historic 410
5.8 Storage 415
5.9 Formulas 420
5.10 Alarms 424
6 Frequently Asked Questions 452
 CHAPTER

1
Introduction

Scripts are programming language modules which allow you to create procedures associated
to specific events, providing with higher flexibility in the development of applications. Each E3
object (item of an application) has a list of previously defined events, but it is also possible to
define new user-created events.

1.1 Objects
Objects are reusable software components that allow you to maximize use, and increase
quality and productivity of applications.

Each E3 object encapsulates three different parts (properties, methods, and events) that you
can manipulate to obtain the advantages of its functionality in your application.

Properties define the object's attributes, such as the appearance of a Screen control, or an
object's initial value when you start the application.

Methods are functions that perform a specific action with or within an object.

Events are notifications generated by an object as a response to some particular occurrence,

such as a mouse click or a change in a tag value, among others.

One of the main characteristics of objects and object-oriented languages is their ability of
inheritance among each other, that is, they can inherit characteristics of one or more objects,
having the same specific functionalities. So, you can have different objects working together to
provide characteristics of another derived object.

For example, take the object E3Chart. It consists internally of many objects, such as titles,
subtitles, scales, divisions, queries, and pens. Notice how each object contributes for the
functionality of E3Chart as a whole: scales help locating point values, subtitles help identifying
pens and their values, and pens help drawing values in the E3Chart.

By handling objects within the E3Chart, you can create two instances of this object that are
very different from one another. To handle a specific object, you have to access it through a
hierarchy. If both E3Charts are on the same Screen, you should first access the Screen, then
the preferred E3Chart, and then one of its properties or child-objects. When there are many
objects of the same type, usually they can be accessed through a collection. A collection is a
special object that manages a set of similar objects. An example in the E3Chart is the Pens
collection, which allows access to all E3Chart pens.

4 Introduc tion
1.2 Scripts
The language used for E3 Studio scripts is VBScript, a subset of the Visual Basic® language
developed by Microsoft. VBScript has a quick, light, and portable interpreter, developed for
the use in Internet browsers and other applications using ActiveX Controls, Automation
Servers, and Java Applets.

As seen before, scripts are associated to object events. However, to facilitate and increase
development speed, E3 has already incorporated some of the most common actions that can
be made with scripts through wizards called Picks. You can therefore define that a given event
will either run a script, a pick, or a combination of both, in a sequence that is also pre-defined.

Each view at E3 Studio displays at least two tabs on its lower side, Design and Scripts, with the
exception of Database and Alarm Server objects, which do not present the Design tab. The
objects and their child objects can be manipulated in the Design tab; to manipulate their
scripts, use the Scripts tab. The available buttons in the latter are:

Available options for Scripts tab

FIELD ICON ACTION OR FUNCTION

Objects Combo Box Selects the object which
script will be manipulated.

Events Combo Box Selects the event to be

applied to the object.

Script Adds scripts associated to

the event.

Pick Open Screen Adds an Open Screen Pick.

Pick Open Modal Screen Adds an Open Modal Screen

Pick.

Pick Run Application Adds a Run Application Pick.

Pick Load Value Adds a Load Value Pick.

Pick Toggle Value Adds a Toggle Value Pick.

Pick Print Report Adds a Print Report Pick.

Remove selected script or Removes the selected script

Pick or Pick from the Actions List.

Move selected script or Pick Moves the selected action

up up, in the sort order of the
Actions List for the event.

Introduc tion 5
 FIELD ICON ACTION OR FUNCTION
Move selected script or Pick Moves the selected action
down down, in the sort order of the
Actions List for the event.

AppBrowser Opens AppBrowser window.

Find Finds instances of a given

text.

Find previous Selects the previous text

instance in the results list.

Find next Selects the next text instance

in the results list.

Replace Replaces the instances in the

results list with another text
sample.

Create user event Creates a user-customized

event.

Remove user event Removes the user-

customized event.

Edit user event Edits the user-customized

event.

Compile selected script Compiles the selected script,

and shows its errors in the
Messages panel.

Compile all scripts from this Compiles all scripts

event associated to the event.

Compile all events from this Compiles all events

object associated to the object.

The execution order is top-down. To alter the order, just use the and buttons. Use the
button to check for errors in the specified script. The compiler error messages are presented
in the Messages panel, on the lower part of the Scripts tab. Double-click the error in case you
want it to be selected in the script.

6 Introduc tion
 Compiler message

1.2.1 Adding a Script

To add a script to an object, follow these steps:
1. Select the object for which you want to create the script and click the Scripts tab.

Scripts tab

2. Click the icon. The scripts editor is then opened, according to the next figure.

Introduc tion 7
 Adding a script to the object

3. Type the VBScript commands in the text editing box

NOTE: use the underline character whenever you wish to add a line break to make code more
legible. The underline character indicates that the code continues on the next line.

For example:
If intBoilerTemperature3 > 120 and _
intBoilerTemperature4 > 120 Then
bSendAlarm = True
bAlarmOn = True
End If

Each event can have several scripts and several picks associated to it. These are called
Actions. The list of actions can be seen on the upper side of the scripts editing window. Each
object can have any number of events with scripts or picks associated.

NOTE: By right-clicking any of these actions described previously, a menu will open to allow
you to cut, copy, or paste scripts and Picks among events.

1.3 Picks
Picks implement a friendlier way of performing the most common procedures, saving
configuration time. Among them, there are actions such as switching Screens or value
assignments, which are very common while creating a project. Next, there is a description of
the available Picks on Scripts tab.

8 Introduc tion
1.3.1 Open Screen
Opens a Screen or a specific Frame.

Settings for Open Screen Pick

Available options for Open Screen Pick

FIELD DESCRIPTION
Open Screen Selects the Screen to be opened.

In Frame Selects the Frame where the Screen will be

viewed. If it is blank, it will be the main Frame
(_top).

Initial Zoom Defines Screen zoom, when shown.

Parameter Determines the existence (or not) of

configuration parameters for the Screen.

Enable Scrollbar Allows using scrollbars on the Screen.

Specify Screen Position Indicates Screen position, in pixels.

Specify Screen Size Indicates Screen size, in pixels or HIMETRIC.

Window Style Calls the window style dialog (see the

Window Style dialog box topic).

Introduc tion 9
1.3.1.1 Window Style Dialog Box
This dialog box allows you to set the window style to be displayed, by defining title and
availability of borders, and closing, maximizing and minimizing buttons, among others. If the
Use default window settings option is selected, the system disables these window options and
assumes the Viewer default style, as seen in the Viewer tab under Viewer object properties.

Window Style dialog box

10 Introduc tion
1.3.2 Open Modal Screen
Opens a Modal Screen, that is, a Screen that does not allow user interaction with other
Screens while it is active.

Settings for Open Modal Screen Pick

Available options for Open Modal Screen Pick

OPTION DESCRIPTION
Open Screen Selects the Screen to be opened.

Title Defines the window title. This text will be

concatenated to the Screen name.

Initial Zoom Defines Screen zoom, when shown.

Parameter Determines the existence (or not) of

configuration parameters for the Screen.

Enable Scrollbar Allows using scrollbars on the Screen.

Specify Screen Position Determines the frame's position (in pixels) on

the Screen, from the upper left side of the
Screen.

Specify Screen Size Determines Screen's width and height (in

pixels or HIMETRIC).

Introduc tion 11
 OPTION DESCRIPTION
Window Style Allows configuring the window style to be
shown, by defining title, close, maximize and
minimize buttons, among others (see the
Window Style Dialog Box topic).

1.3.3 Run Application

Runs a specific application program.

Settings for Run Application Pick

Available options for Run Application Pick

OPTION DESCRIPTION
Command
By clicking the button it is possible to
browse the disk to select the application file
to run.

Parameters Allows specifying arguments for application

calls.

Start In Determines application's working directory

to be executed.

12 Introduc tion
 OPTION DESCRIPTION
Window Determines the type of window for the
application execution: Normal, Minimized, or
Maximized.

1.3.4 Load Value

Loads a value in a Tag.

Settings for Load Value Pick

Available options for Load Value Pick

OPTION DESCRIPTION
Tag name Specifies the Tag name in which the value will
be loaded. It is possible to select the Tag in
AppBrowser, by clicking the button.

Value Determines the value to be loaded in the Tag.

It is possible to select a data type, by clicking
the arrow key.

Introduc tion 13
1.3.5 Toggle Value
Allows toggling a Tag value. If Tag value is equal to Value1, then Tag gets Value2. If Tag value is
equal to Value2, then Tag gets Value1. If Tag value is different from either Value1 or Value2, Tag
gets Value1.

It is possible to put as many Toggle Value Picks as necessary. This allows checking multiple
values for the same Tag or even for several Tags in the same event.

Settings for Toggle Value Pick

Available options for Toggle Value Pick

OPTION DESCRIPTION
Tag name
By clicking the button, E3 opens
AppBrowser to select the preferred Tag.

Value 1 Determines the first value to be compared. If

Tag value is equal to Value1, Tag gets Value2.

Value 2 Determines the second value to be

compared. If Tag value is equal to Value2,
then Tag gets Value1.

14 Introduc tion
1.3.6 Print Report
Allows printing a Report on a Screen or to a printer.

Settings for Print Report Pick

Available options for Print Report Pick

OPTION DESCRIPTION
Print Report Selects the report to print.

Output Determines the type of Report output:

· Printer: Sends the Report to a printer.

Corresponds to Print method

· Screen: Previews Report printing on

Screen. Corresponds to PrintPreview
method

1.4 User-Defined Events

Although E3 comes with a wide range of events, there are many times when users may wish to
create a specific event for their own application.

An example of user-customized events usage would be a calculation, or a more complex task in

an object, when the generated event comes from another Tag or property.

Introduc tion 15
Although you can create and execute this type of work from the Tag or property generating the
event, there are several advantages in keeping the script next to the object that will suffer
script's action. Among these there is the additional work needed to make an object point to
another one, not to mention the small amount of work needed in maintenance, because if by
any reason it is necessary to modify or delete a Tag or property generating the event, it will not
be necessary to modify a second object.

Another advantage comes from the fact that if you erase the Tag generating the event, the
object does not lose its script, as long as you indicate another event generating source.

Internal events generation also makes the creation of libraries easier, because each time a
library component is inserted into an application, it also brings scripts and calculations that
may be necessary, reducing configuration work.

To generate a new internal event in an object, follow these procedures:

1. Click Create user event , or Create new event , in the Events combo box. E3 then opens
a window for setting event properties.

Window for adding user customized events

Available options on Events window

OPTION DESCRIPTION
Event name Name identifying the event.

Property/expression Expression generating the event. Can be

copied through AppBrowser, by clicking the
button.

Is a true condition Indicates whether the event is an etOnEvent

(the event occurs whenever the expression is
true) or an etWhileEvent (the event occurs
cyclically, at pre-defined intervals).

16 Introduc tion
 OPTION DESCRIPTION
Repeat event every ... ms When filled in, indicates that the event is an
etWhileEvent. Indicates the event repetition
cycle (that is, its periodicity while the
generating expression is true) in
milliseconds.

Change its value Indicates that the event is an

etOnValueChanged, that is, the event occurs
whenever the expression value changes.

Treat disconnection as change Indicates that the connection of the event

generating expression must be considered as
a change or not.

2. Click OK to finish the process and insert the event. It will now be part of the Events combo
box.

3. To alter this event, select it and click Edit user event . The previous window is then
opened again to edit the information on the event.

4. To erase this event, select it and click Remove user event .

IMPORTANT: when you click Remove user event option, event scripts are lost.

Introduc tion 17
 CHAPTER

2
Programming in E3

Although the majority of VBScript aspects apply to scripts programming with E3, some
particularities should be emphasized regarding the implementation of object orientation
concept on the system.

VBScript is a language based on Visual Basic that brings the capacity of scripting to
applications that run on Windows.

VBScript exchanges information with applications using the ActiveX Scripting technology. With
ActiveX Scripting, browsers and other client applications like E3 Viewers can compile scripts
and call functions, among other procedures. This enables scripts developed for an application
or library (that should be executed in a graphical interface) to run either in E3 Viewer or in an
Internet browser, with no need of adaptation on the application side.

Further information about VBScript can be obtained on the VBScript Reference Guide, in Elipse
E3 Program Group.

2.1 Programming Environment

The script-programming environment in E3 Studio can be accessed by right-clicking any object,
and selecting the Properties option. On Scripts tab of the object view, you can see a combo box
where you can define which event will be the script generator. As seen in the previous
chapter, there are two types of events in an E3 object: predefined events, and user-
customized events.

Predefined events vary from object to object, depending on its use and functionality. A Screen
object, for example, has graphical interface related events, like Click (called whenever clicking
the object) or DbClick (called whenever double clicking it); an object like an IODriver, on the
other hand, has communication related events, like OnCommError (called whenever there is a
communication error). You can also define other events for the object, as seen before.

When you associate a script to an event in an object, the typing field presents a procedure
declaration whose definition is automatic and formed by the following text:
Sub ObjectName_EventName()
End Sub

Where ObjectName is the name of the associated object, and EventName is the name of
the aforementioned event. Script commands should come between these two lines.

To help typing the script, you can use AppBrowser. When choosing the preferred method or
property, you can activate the Copy button. The chosen tag, property, or method will be
inserted into the cursor position on the editing board of the script. The cursor position is
shown by an animated blinking arrow.

18 Programming in E3
2.2 Declaring Variables
You can declare variables in two different ways: implicitly, or explicitly.

To declare a variable implicitly, simply use its name on the script. The variable will
automatically be created and initialized with the attribution value, or it will remain empty, in
case it does not receive any value before being used.

This is a quick practice, but if a script is very extensive, it may cause confusion and creation of
more than one variable with the same name, generating bugs in script.

To declare variables explicitly, use the Dim command, as in the next example:
Dim Temperature

You can declare multiple variables separating each variable name by a comma. For example:
Dim Left, Right, Top, Bottom

Because all scripts in E3 are associated to a specific object, variables are always local, valid
only on script's scope. For public or global variables, you must create an Internal Tag and use it
to store the preferred value.

2.3 Getting References to Objects

One of the most important things to consider when you work with scripts inside E3 is the
separation between processes executed in the server and those executed in the client's
interface (E3 Viewer). In order to work with scripts, you can manipulate:

· Server objects via server

· Server objects via E3 Viewer(s)

· E3 Viewer objects via the same E3 Viewer

However, you cannot directly manipulate:

· E3 Viewer objects via server (this is only possible by creating events on E3 Viewer, which are
connected to variables in the server)

· E3 Viewer objects via another E3 Viewer (this is only possible by creating events connected
to variables in the server)

Such limitations come from the fact that, by definition, there is an independence between
what the E3 Viewer station is doing or visualizing and the server, and vice-versa. So, all
activities, both in the server and in E3 Viewer, need to be coordinated either in an
asynchronous way or through events in order to operate harmoniously.

Programming in E3 19
Thus, due to this independence, when creating a script, first you should obtain a correct
reference to the objects you want to manipulate, that is, it is necessary that the object be
found on several E3 modules first.

Remember that when you edit a script, you can use the AppBrowser, which allows the path of
a method or property to be completely copied to the script, then helping you to create scripts.

Therefore, to access external objects being manipulated in a script, some basic guidelines are
used. For example, if you want to manipulate the value of an I/O Tag, the path is Server - Driver
- Folder (if available) - Tag. But if your goal is to manipulate a button on the Screen, the path is
Viewer - Frame (if available) - Screen - Button.

There are basically three script source locations according to the methodology for accessing
objects:

· Server (E3 Server)

· Screens and Frames (E3 Viewer)

· ElipseX (libraries): they may be XObjects (running on the server) or XControls (running on E3
Viewer)

2.3.1 Accessing Server Properties

To access an object running on the server from a Screen Object or an ElipseX, use the
Application.GetObject method.

The word Application returns the application object related to the current object context, and
the GetObject method searches for an object with the given name within Application, on the
server. Example:
Sub Button1_Click()
Application.GetObject("Driver1")._
Item("tag001").AllowRead = False
End Sub

Or
Sub Button1_Click()
Application.GetObject("Driver1.tag001").AllowRead = False
End Sub

The Item method has been used to locate tag001 from a reference to Driver1, because
the Driver is a Tag collection. After the object has been located, its properties and functions
can be freely accessed.

In case you need to accomplish another operation with Driver1 or tag001, another
alternative for this script is:
Sub Rectangle1_Click()
Set obj = Application.GetObject("Driver1")
obj.Item("tag001").AllowRead = False
obj.Item("tag002").AllowRead = False
End Sub

20 Programming in E3
In this case, the variable obj is pointing to the object Driver1, and the next time you want
to access some object descending from Driver1 inside the script, you can use the variable
obj directly. This brings performance enhancement, since each call to GetObject method
accesses the server only once. With this technique, you avoid unnecessary calls to the server.
This example uses the Set command, explained later. Notice that the use of variables also
makes code clearer and more easily modifiable. In case it is necessary to change the object
where you want to execute commands, just change the attribution line of this variable.

The word Application in scripts can indicate either functions executed on E3 Viewer or on the
Server. In this case, the Application object knows beforehand which functions should be
executed in each case. Nevertheless, you cannot execute E3 Viewer functions inside the
server, and it is not possible to execute server functions inside an E3 Viewer.

2.3.2 Accessing Studio Properties

Accessing any server object in a script which runs in Studio can be done by using the
Application.GetObject directive. The word Application returns the application object related
to the current object context, and the GetObject method searches on the load Domain in
Studio for a server object with the path provided. Example (the CustomConfig event is triggered
in Studio):
Sub XControl1_CustomConfig
Application.GetObject("Data.DemoTag1").DocString = "Documentation"
End Sub

2.3.3 Accessing Server Properties from the Server

Take the example of accessing tag properties from another one. In this case, origin and
destination are on the server, even though connected via a Driver1 parent module.

In this case, the Parent declaration should be used. This allows the parent of the object where
the script is, to be firstly accessed; and then, you descend in the hierarchy to look for another
element.

Driver1 is the parent object of Tag1 and Tag2

Example:

Programming in E3 21
 Sub Tag1_OnRead()
Parent.Item("tag002").AllowRead = False
End Sub

If you are inside a group and you want to access the same tag002, you can nest various
Parent commands. For example:

Folder1 is the parent object of Tag1

Example:
Sub Tag1_OnRead()
Parent.Parent.Item("tag002").AllowRead = False
End Sub

2.3.4 Accessing Screen Objects from a Screen Script

In this case, you should only use the Item method, as the objects are children of the Screen.
For example:
Sub Screen1_OnPreShow(vArg)
Item("Rectangle1").Visible = True
End Sub

Rectangle1 is an item from Screen1

22 Programming in E3
2.3.5 Accessing Screen Objects from a Script on Another
Object Screen
In this case, you can use the Parent or the Screen method.

Screen1 is the parent object of Rectangle1 and

Rectangle2

Example:
Sub Rectangle1_Click()
Parent.Item("Rectangle2").Visible = True
End Sub

2.3.6 Changing a Screen or Screen Objects from the Server

This is not possible via scripts, because each data client is a different Screen copy. The
modification of any behavior in the Screen can be done only due to a concept question, from
associations (the server automatically reports all changes in variables chosen for E3 Viewers),
or via explicit information search in the server. The whole graphic interface association
operation is accomplished from client to server and not from server to client. A practical
example is either to change the color of a text in the Screen into green when a tag is turned on
(value 1) or into red when it is turned off (value 0). In this case, simply create a digital
association between Text1 TextColor property and Tag1. This way, you do not need to
create a script, which is preferable, due to execution speed and also simplicity of
maintenance and construction.

Programming in E3 23
 Associating the text color to Tag1 value

Experts in other supervisories might want to create scripts in order to solve this problem. For
example: create an event through a script when the Value property changes its value, during
tag change, and then obtain a reference for the Screen object, finally changing the TextColor
property. Nevertheless, there is no way to call the Screen from the server. Therefore, this is
not adequate. Another way would be to create a script in the E3 Viewer, which is constantly
verifying if the value of Tag1 has changed or not, then change the text color. This type of script
is possible to be accomplished, but it would strongly affect application performance. Thus,
this practice is not recommended.

2.3.7 Accessing ElipseX Objects from the ElipseX Itself

When creating an ElipseX, we can assign properties (XProperties) and insert objects, which
can be Screen objects (XControls) as well as server objects (XObjects). In order to access
XProperties via scripts, just access directly the property name.

Accessing objects of an ElipseX from ElipseX itself

24 Programming in E3
For example, in the previous figure there is an XControl1 with Property1 property, and the
objects Text1 and Rectangle1. This property is a Boolean, and can be accessed like this:
Sub XControl1_OnStartRunning()
XControl1.Property1 = True
End Sub

Or even:
Sub XControl1_OnStartRunning()
Property1 = True
End Sub

If ElipseX has any internal objects, it is possible to use the Item method to get references from
these objects. For example:
Sub XControl1_OnStartRunning()
Item("Text1").Value = "engine"
Item("Rectangle1").ForegroundColor = RGB(212, 208, 20)
End Sub

2.3.8 Externally Accessing Objects of an ElipseX

An ElipseX object can only be accessed externally via its properties, by using the created
instances. It is not possible to access internal objects directly. If the ElipseX is an XControl, it
will behave as a Screen object. For example, in this application:

XControl (example)

To alter XControl's Property1 property, you can write the following script in the button:

Programming in E3 25
 Sub CommandButton1_Click()
Screen.Item("XControl11").Property1 = True
End Sub

Or, alternatively
Sub CommandButton1_Click()
Parent.Item("XControl11").Property1 = True
End Sub

In case of an XObject, insert it into a Data Server.

XObject (example)

A possible script to alter XObject's Value property would be:

Sub CommandButton1_Click()
Application.GetObject("Data.XObject11").Value = 123
End Sub

Or, alternatively:
Sub CommandButton1_Click()
Application.GetObject("Data").Item("XObject11").Value = 123
End Sub

You can also have an XControl accessing an XObject through an XProperty. For example, the
next figure shows an XControl called XControl1 with an XValue property. This property's
type is XObject1, which is also the name of the XObject created.

XControl accessing an XObject (example)

26 Programming in E3
For example, you can link the value of the object Text1 with Value property of XObject1.
This is done via XValue property, created at XControl1. Thus, the value of Value property of
XObject1 will be shown in the object Text1 of XControl1.

Value property

In the project, the instance XObject11 can be linked to the XControl11 instance via a
link at XValue property.

XValue (link)

Programming in E3 27
2.3.8.1 Example of Creating an ElipseX
Suppose a given application needs to supervise and command 10 engines. Each engine must
be represented by a drawing on Screen, displayed in green when operating, and in red when
off. It must also display the engine command on Screen, sending instructions for turning it on
and off. Its speed must also be displayed.

One possibility is creating an XControl called EngineA, with properties State set to Boolean
and Speed set to Double, as seen on the next figure:

XControl definition

1. To indicate color, engine's OverrideFillColor property must be digitally linked to XControl's

State property. Set OverrideFillMode property to 2 - SolidFill.

2. To display speed, Display's Value property must be linked to XControl's Speed property.

3. The Toggle Button switches State property value via a simple link.

Notice that:

· Links within the library are internal, and their format is Control_Name.Property_Name

· The object, after being inserted into the Screen, must have these properties linked to real
Tags, for each engine

· Each EngineA will have a Tag linked to State property

28 Programming in E3
 Viewer

Another broader possibility is to use an XObject for the engine. Thus, all information regarding
the engines remains in objects in the server. Hence, it is possible to create several types of
interface for the engine (XControls), which brings only relevant information from the server,
via XObject.

Then, the object EngineA would have to be modified to point to an XObject, instead of
declaring all properties on itself.

1. Create an XObject called EngineAData, and declare State and Speed properties in it.

2. Create an XControl (EngineA) with just one property, called MyData, of type
EngineAData.

3. EngineAData must be inserted into a data folder in the server, corresponding to each
engine. EngineA, by its turn, will point to the EngineAData needed, with no need to
create new tags.

Programming in E3 29
 Configuration of XObject view

4. The State property, linked to engine's OverrideFillCollor property, is then EngineA.MyData.

State.

5. The Speed property, linked to Display, is then EngineA.MyData.Speed.

2.4 Accessing Objects

Following the object oriented programming encapsulation concept, methods and properties
become associated to their original objects. This means that you always have to indicate the
object, method or property you are accessing.

2.4.1 Properties
In order to refer to object properties, you should use E3 GetObject method. The syntax is the
following:
Application.GetObject("<object>").<property>

Where <object> is the name of the object, and <property> is the desired property. Example:
Application.GetObject("Data.TempTank2").Type

In order to ease typing, it is always advisable to use AppBrowser, which already brings the

30 Programming in E3
correct syntax, avoiding mistakes.

2.4.1.1 Value
In E3, many objects have a standard property, called Value. In this specific case, you can
access this property by using the name of the object itself:
Button1 = False

Which is equivalent to:

Button1.Value = False

Some objects are formed by other objects, and one can access the other through a property,
as follows:
Application.GetObject("Data.Temperatures.Tank2").Type

In this example, Tank2 is part of another object called Temperatures.

2.4.2 Methods
The following syntax exemplifies a method call that does not need parameters:
Application.GetObject("<object>").<method>

Where <object> is the specific object, and <method> is the desired method.

If the method accepts parameters, use the following syntax:

Application.GetObject("<object>").<method>(<parameter>)

Where <parameter> is the parameter needed to be passed to the method. When there is more
than one parameter, use commas to separate them.

If the method returns a result that you want to keep, then the parameters should be placed
between parentheses:
<V> = Application.GetObject("<object>").<method>(<parameter>)

Where <V> is the variable that receives the result of the method.

2.5 Working with Collections

A collection is an object that manages a set of similar objects. The objects contained in a
collection are referred to by indexes, similarly to arrays reference. You can add or remove
individual objects from a collection, as seen in the following example:

Programming in E3 31
 Sub CommandButton1_Click()
' Add a pen to the E3Chart1 object
Screen.Item("E3Chart1").Pens.AddPen "Pen"
End Sub

Sub CommandButton2_Click()
' Removes the first pen
Screen.Item("E3Chart1").Pens.Remove 0
End Sub

NOTE: The first object in a collection has index 1.

All collections have a standard property named Count, which is the number of existing objects
(or children). Example:
Sub CommandButton1_Click()
' Shows a dialog box with the number of pens
MsgBox Screen.Item("E3Chart1").Pens.Count
End Sub

2.5.1 Accessing Objects using the Item Method

Every collection has an Item method, which can be used in order to access any object within
the collection. The Item method accepts an Item parameter, which can be a number (a
positive integer) or the name of the object you want to access within the collection.

In the next examples, the E3Chart object's second Pen color is adjusted:
Sub CommandButton1_Click()
' Changes the color of the third pen
Screen.Item("E3Chart1").Pens.Item(2).Color = RGB(212, 208, 20)
End Sub

Or else:
Sub CommandButton1_Click()
' Changes the color of a pen named "Pen2"
Screen.Item("E3Chart1").Pens.Item("Pen2").Color = RGB(212, 208, 20)
End Sub

Previous commands are equivalent, the first one indicating the Pen index within the
collection, and the second one indicating its name.

2.6 Set Command

VBScript implements the concept of polymorphism from object oriented languages, allowing a
Variant-type variable to assume the form of any object via Set command. This way, a variable
works as a pointer to an object, allowing the access to its methods and properties. Example:
Sub CommandButton1_Click()
Set E3Chart = Screen.Item("E3Chart1")
E3Chart.Pens.Item(2).Color = RGB(212, 208, 20)
End Sub

In this example, the same task of the previous example has been accomplished, but the part
related to getting the specific object has been forgotten. Without the Set command, the same
call must be:
Screen.Item("E3Chart1").Pens.Item(2).Color = RGB(212, 208, 20)

32 Programming in E3
Apparently, there is no advantage in this case, because you will be able to do everything with
a single line of code. But, if you want to perform other operations in the same script right after,
it would be simpler and faster if you avoid placing the call for Item method in all lines.
Sub CommandButton1_Click()
' A bad example:
Screen.Item("E3Chart1").Pens.Item(0).Color = RGB(212, 208, 20)
Screen.Item("E3Chart1").Pens.Item(1).Color = RGB(200, 208, 20)
Screen.Item("E3Chart1").Pens.Item(2).Color = RGB(100, 208, 20)
End Sub

Sub CommandButton1_Click()
' A better example:
Set Pens = Screen.Item("E3Chart1").Pens
Pens.Item(0).Color = RGB(212, 208, 20)
Pens.Item(1).Color = RGB(200, 208, 20)
Pens.Item(2).Color = RGB(100, 208, 20)
End Sub

2.7 E3Globals
E3Globals is an E3 module which contains methods for global use. The
GetCurrentWindowsUserName, GetLocalTime, and GetLocalTimeUTC methods cannot be used
in Links, only in scripts. The rest of the methods can be used in Links, as well as in scripts.

The way of using these methods admits two syntaxes, E3Globals.<method> or simply
<method>, except for the Report object, which E3Globals.<method> syntax is
mandatory.

2.7.1 Methods
This section contains information about the methods of the E3Globals module.

2.7.1.1 BShl
BShl(Value, Bits)

Returns Value left-shifted the number of bits specified in Bits. This method returns an error in
case the Bits parameter is outside the allowed range (from 0 to 31). This method is available in
Links, as well as in scripts.

2.7.1.2 BShr
BShr(Value, Bits, PreserveSign)

Returns Value right-shifted the number of bits specified in Bits. This method returns an error in
case the Bits parameter is outside the allowed range (from 0 to 31). The PreserveSign
parameter is an optional Boolean which, if True, fills in the bits to the left with a copy of the
signal bit. The default value of this parameter (False) fills in the bits to the left with zeroes. This
method is available in Links, as well as in scripts.

Programming in E3 33
2.7.1.3 Choose
Choose(Index, Values)

Returns one of the items specified in Values, based on Index (starts at zero). This method
returns Null in case the value of Index is less than 0 or greater or equal to the number of values
in Values. This method is available in Links, as well as in scripts.

NOTE: The Choose method does not propagate values' quality nor timestamp. If a Link
contains the expression Choose(TagIndex, Tag1.Value, Tag2.Value, Tag3.
Value), the result is the chosen value, however with Good (192) quality and the current
timestamp. In order to preserve this information, you must specify only the object, as for
example Choose(TagIndex, Tag1, Tag2, Tag3).

2.7.1.4 E3Format
E3Format(Value, Format)

Formats the expression in Value using the format specified in Format. This format uses the
same definitions of the Format property of Text, Display, and SetPoint objects. This method is
available in Links, as well as in scripts.

2.7.1.5 GetBit
GetBit(Value, BitIndex)

Returns the value (True or False) of the Value bit specified by BitIndex. This method returns an
error in case the BitIndex parameter is outside the allowed range (from 0 to 31). This method is
available in Links, as well as in scripts.

2.7.1.6 GetComputerName
GetComputerName()

Returns a String containing the name of the local computer. This method is available in Links,
as well as in scripts.

2.7.1.7 GetCurrentWindowsUserName
GetCurrentWindowsUserName()

Returns a String containing the name of the user logged on the current process. This method is
not available in Links, only in scripts.

34 Programming in E3
2.7.1.8 GetLocalTime
GetLocalTime()

Returns the date and time of the local computer, with a precision of milliseconds and in the
local time zone. This method is not available in Links, only in scripts.

2.7.1.9 GetLocalTimeUTC
GetLocalTimeUTC()

Returns the date and time of the local computer, with a precision of milliseconds and in the
UTC (Coordinated Universal Time) time zone. This method is not available in Links, only in
scripts.

2.7.1.10 IIf
IIf(Condition, ExprTrue, ExprFalse)

Returns the expression contained in ExprTrue if the condition evaluated in Condition is true,
and the expression contained in ExprFalse if the condition evaluated is false. This method is
available in Links, as well as in scripts.

NOTE: The IIf method does not propagate values' quality nor timestamp. If a link contains the
expression IIf(Tag1.Value == 0, Tag2.Value, Tag3.Value), the result is
the value of Tag2 or Tag3, however with Good (192) quality and current timestamp. To
preserve this information, you must specify only the object, as for example IIf(Tag1.
Value == 0, Tag2, Tag3).

2.7.1.11 OPCGetLimit
OPCGetLimit(Quality)

Returns the Limit information of an OPC Quality specified by the Quality parameter. This
method is available in Links, as well as in scripts. Possible returned values for this method
are:

· 0: Free

· 1: Low

· 2: High

· 3: Const

Programming in E3 35
2.7.1.12 OPCGetQuality
OPCGetQuality(Quality)

Returns the Quality information of an OPC Quality specified by the Quality parameter. This
method is available in Links, as well as in scripts. Possible returned values for this method
are:

· 0: Bad

· 1: Uncertain

· 2: Not used

· 3: Good

2.7.1.13 OPCGetSubStatus
OPCGetSubStatus(Quality)

Returns the Substatus information (from 0 to 15) of an OPC Quality specified by the Quality
parameter. This method is available in Links, as well as in scripts. The OPC Standard specifies
the following values:

· Good Quality:

· 0: non-specific

· 1: local override

· Bad Quality:

· 0: non-specific

· 1: config error

· 2: not connected

· 3: device failure

· 4: last known value

· 5: comm failure

· 6: out of service

· Uncertain Quality:

· 0: non-specific

36 Programming in E3
 · 1: last usable value

· 4: sensor not accurate

· 5: EU exceeded

· 6: subnormal

2.7.1.14 OPCGetVendor
OPCGetVendor(Quality)

Returns the Vendor Specific information (from 0 to 255) of an OPC Quality specified by the
Quality parameter. This method is available in Links, as well as in scripts.

2.7.1.15 OPCIsBad
OPCIsBad(Quality)

Returns True if the OPC Quality is Bad, and False otherwise. This method is available in Links,
as well as in scripts.

2.7.1.16 OPCIsGood
OPCIsGood(Quality)

Returns True if the OPC Quality is Good, and False otherwise. This method is available in Links,
as well as in scripts.

2.7.1.17 OPCIsUncertain
OPCIsUncertain(Quality)

Returns True if the OPC Quality is Uncertain, and False otherwise. This method is available in
Links, as well as in scripts.

2.7.1.18 OPCMakeQuality
OPCMakeQuality(QualityFlag, SubStatus, Limit, Vendor)

Returns a new OPC Quality value, built using the values passed in the QualityFlag, SubStatus,
Limit, and Vendor parameters. This method is available in Links, as well as in scripts. Possible
values for each one of the parameters are:

· QualityFlag: Specifies the quality of the value

· 0: Bad

· 1: Uncertain

Programming in E3 37
 · 3: Good

· SubStatus: Specifies the substatus of the value (between 0 and 15, see the OPCGetSubStatus
method for possible values). If this parameter is omitted, assumes 0 (zero)

· Limit: Specifies the limit of the value. If this parameter is omitted, assumes 0 (zero)

· 0: Free

· 1: Low

· 2: High

· 3: Const

· Vendor: Specific value of the vendor (between 0 and 255). If this parameter is omitted,
assumes 0 (zero)

2.7.1.19 OPCSetLimit
OPCSetLimit(Quality, Limit)

Changes the Limit information of an OPC Quality and returns the modified value. This method
is available in Links, as well as in scripts. Possible values for the Limit parameter are:

· 0: Free

· 1: Low

· 2: High

· 3: Const

2.7.1.20 OPCSetQuality
OPCSetQuality(Quality, QualityFlag)

Changes the Quality information of an OPC Quality and returns the modified value. This
method is available in Links as well as in scripts. Possible values for the QualityFlag
parameter are:

· 0: Bad

· 1: Uncertain

· 2: Not used

· 3: Good

38 Programming in E3
2.7.1.21 OPCSetSubStatus
OPCSetSubStatus(Quality, SubStatus)

Changes the Substatus information (from 0 to 15) of an OPC Quality and returns the modified
value. This method is available in Links, as well as in scripts. The OPC Standard specifies the
following values:

· Good Quality:

· 0: non-specific

· 1: local override

· Bad Quality:

· 0: non-specific

· 1: config error

· 2: not connected

· 3: device failure

· 4: last known value

· 5: comm failure

· 6: out of service

· Uncertain Quality:

· 0: non-specific

· 1: last usable value

· 4: sensor not accurate

· 5: EU exceeded

· 6: subnormal

2.7.1.22 OPCSetVendor
OPCSetVendor(Quality, Vendor)

Changes the Vendor Specific information (from 0 to 255) of an OPC Quality and returns the
modified value. This method is available in Links, as well as in scripts.

Programming in E3 39
2.7.1.23 SetBit
SetBit(Value, BitIndex, BitValue)

Sets the value of Value (True or False) of the bit specified by BitIndex (from 0 to 31) to BitValue.
This method returns an error in case the BitIndex parameter is outside the allowed range
(between 0 and 31). This method is available in Links, as well as in scripts.

2.7.1.24 SourceTypeName
SourceTypeName(SourceType)

Returns a String with the description of the active Measurement Source (the ActiveSource
property of Analog Measurement and Discrete Measurement objects in Elipse Power). This
method is available in Links, as well as in scripts. Possible values for SourceType parameter
are the following:

· -1: Empty String

· 0: Active Source

· 1: SCADA

· 2: Operator

· 3: Control Center

· 4: Billing

· 5: Calculated

· 6: Database

· 100: Topology Processor

· 101: Power Flow

· 102: State Estimator

· 103: Load Shedding

NOTE: In case the value passed on SourceType parameter is not one of the possible values,
this method returns "???".

40 Programming in E3
2.8 General Events, Methods, and Properties of Objects
This section contains information about general events, methods, and properties of objects.

2.8.1 Events
Events are occurrences related to an object, which allow triggering scheduled actions.
Basically, there are two types of events: physical (or external) and internal. Physical events
are, for exammple, user actions. In case the user types something on the keyboard, the
relevant information can be the pressed key or, if the user points and clicks the mouse, the
relevant information can be the arrow position and button status. Internal events are, for
example, value changes in a variable (Tag) in the system. Since the tag can be associated to an
external device, it is possible to say that internal events can have physical associations, such
as temperature changes in a chamber, for example.

2.8.1.1 Event Variables

Event Variables are created when the event is started. To be used, they should be associated
to parameters in the script call of the event.

The following example is a procedure call associated to the KeyDown event of SomeObject.
Sub SomeObject_KeyDown(KeyCode, Shift)

Notice that in this call there are two variables, KeyCode and Shift. E3 will automatically assign
values to these variables at the moment when the event occurs. In this case, KeyCode will
receive the code of the pressed key and Shift will be true or false, whether the SHIFT key is
being pressed or not.

2.8.1.2 OnStartRunning
OnStartRunning()

Occurs as soon as an object is started. Example (Months is an Internal Tag and uses the
OnStartRunning event to fill an array):
Sub Months_OnStartRunning()
Value = Array("January", "February", "March", "April",_
"May", "June", "July", "August", "September", "October",_
"November", "December")
End Sub

NOTE: To access this array, it is necessary to copy the Value property to a local variable.

Programming in E3 41
2.8.1.3 OnStopRunning
OnStopRunning()

Occurs when the execution of an instance of this object finishes. Use the OnStopRunning event
to perform termination operations for the object. Example:
Sub InternalTag1_OnStopRunning()
' When InternalTag1 object finishes
' it assigns False to InternalTag2
Set tag2 = Application.GetObject("Data.InternalTag2")
tag2.Value = False
End Sub

2.8.2 Methods
This chapter lists E3 predefined methods, grouping them by types of objects, starting by
standard methods of the application objects. Each entry displays the name of the method with
its respective parameters, in the correct syntax and also an example of its use.

2.8.2.1 Calling Methods

Many predefined methods have parameters, which can (or should) be passed at method call.
For this, VBScript has a rule that must be followed. If the method is used in an assignment, its
parameters should be put inside brackets. For example, look at this GetObject method call:
obj = Application.GetObject("data.tag001")

If the method is called alone, the brackets should be taken out. For example, look at this
SetVariableValue method call:
Screen.Item("Query").SetVariableValue Value, 12

Brackets used in method citations in this manual work only as an indicator to differentiate
them from properties. In scripts, this rule must be followed.

2.8.2.2 Activate
Activate()

Activates a currently inactive object. Example:

Sub CommandButton1_Click()
Dim obj, tag
Set obj = Application.GetObject("Data")
' Create a new object and let it disabled (False).
Set tag = obj.AddObject("DemoTag", False)
' Setup the new object parameters.
tag.Name = "tag001"
tag.Type = 3
' Enable the object (start it up).
tag.Activate()
End Sub

42 Programming in E3
2.8.2.3 AddObject
AddObject(ClassName[[, Activate], ObjectName])

The AddObject method adds a new object in the application via script. This method has the
ClassName parameter, which is mandatory, and indicates the type of the object to create. For
example, in order to create a rectangle on the Screen, the ClassName parameter must be
"DrawRect". The created object is contained inside the object that called the AddObject
method and can be accessed using the Item method.

The Activate parameter is optional and indicates whether the object is enabled after creating
it or not. When the object is activated, links and scripts remain enabled. If the object is
created with Activate equal to False, it can be later activated using the Activate method.

The ObjectName parameter is also optional and indicates a name for the new object. In case of
an already existing name, the new name is automatically incremented. If this parameter is not
informed, the new object is named after the class defined in the ClassName parameter.

The object is created only if its type is compatible with the object that contains it. In order to
be sure that the object was created, the IsObject method can be used.

NOTE: Only objects which have the Insert menu option can access this method.

2.8.2.4 Context
Context(ContextName)

Returns the object implementing the context indicated by the parameter ContextName, which
must be a String surrounded by quotation marks. This method fails if no object on the upper
hierarchy of the object calling this method implements this context. The following contexts are
available:

· Container: Server and Viewer objects (objects inserted in project files, or in folders inside
projects)

· Area: Alarm Areas, or any server object whose property IsAlarmArea is set to True

NOTE: Context names are case-insensitive. To check the context to which an object belongs,
just open its Properties window, select the Item tab, and then check its valid contexts in the
Contexts frame. In case an object defines more than one context, their names are presented
in alphabetical order, separated by commas.

Programming in E3 43
2.8.2.5 Deactivate
Deactivate()

Deactivates a previously created object, or an object previously activated using the Activate
method. You can deactivate an object when it is necessary to perform a previous configuration
(property initialization, for example), or when you want to perform tests in which it is
necessary that the object is neither present nor activated. Example:
Sub CommandButton1_Click()
Dim obj, new
Set obj = Application.GetObject("Data")
Set new = obj.AddObject("DemoTag", True)
' Deactivate the object.
new.Deactivate()
End Sub

2.8.2.6 DeleteObject
DeleteObject(ChildName)

Erases from the project the specified object. ChildName parameter is a String (ignores
capitalization) and indicates the child object to be deleted. This method returns True if the
event has accomplished deleting the object, or False, if child object does not exist.

In order to delete an object from a reference to an element, parent object's DeleteObject

method is used. Example:
Sub CommandButton1_Click()
Set obj = Application.GetObject("Data")
If obj.DeleteObject("Tag001") Then
MsgBox("Tag successfully deleted!")
Else
MsgBox("Deleting failed: tag does not exist.")
End If
End Sub

NOTE: Only objects which have the Insert menu option can access this method.

2.8.2.7 GetChildObject
GetChildObject(ObjectPath)

The GetChildObject method returns a reference to the child object pointed by the ObjectPath
parameter. Then it is possible to access all properties and methods of this object, similar to
the GetObject method. This method fails if the path pointed by the ObjectPath parameter
contains a property or method at its end. The path pointed by the child object is not a path
starting from root (the .prj file) but instead a path from the object where this method is called.

NOTE: This method DOES NOT exist in the Application object of the server nor in the
Application Folders, however it exists in the Application object of the Viewer, thus it is
accessible even in a read-only Viewer.

44 Programming in E3
2.8.2.8 GetObject
GetObject(ObjectPath)

GetObject method searches for an object from the specified project path in ObjectPath, and
returns its reference. This allows accessing all object properties and methods.

This is a common practice in E3 scripts programming. It facilitates handling objects and makes
code more intelligible. Example:
Sub CommandButton1_Click()
' Assign the value 20 to the object Value property
' InternalTag1 which is in Data.
Set tag = Application.GetObject("Data.InternalTag1")
tag.Value = 20
End Sub

2.8.2.9 Item
Item(ItemId)

Returns a reference to the ItemId child object of the object that called the method. The Item
method can search for an object either by its name or by its index (integer, from 1 up to that
specified in the Count property). If the specified index or name is valid, the Item method
returns the object reference, otherwise it will return an invalid parameter error. Example:
Sub Screen1_Click()
' Assigns to obj the reference to the Screen1 Button1
' child object.
Set obj = Item("Button1")
' Set the obj BackColor property, that is,
' of Button1.
obj.BackColor = RGB(255, 0, 0)
End Sub

2.8.2.10 Save
Save()

This method saves the specified object that was modified at run time. Children objects will
also be saved, according to parent object specifications. This method is not valid for Screen
and Viewer objects. Example:
Sub CommandButton1_Click()
Set area = Application.GetObject("ConfigAlarms")._
AddObject("Area", true)
Application.GetObject("ConfigAlarms").Save()
End Sub

NOTE: Changes made at run time and saved in the object are only visible in E3 Studio after
updating the project, which can be performed by right-clicking the project name and
selecting the Refresh option.

Programming in E3 45
2.8.3 Properties
Each object has Properties, which are used to save information about its characteristics. For
example, take and object like a Rectangle. One of its properties is Name, where its name is
stored. Two other properties are Width and Height, which save its width and height,
respectively.

In this chapter, E3 object's properties will be summarized. Each entry has the name of the
property, its description, and, when possible, a practical example of its use. This topic
introduces the properties that are present in all E3 objects. The following topics bring
properties that are specific to the object or group of objects mentioned in their titles. In some
of these topics, the first item is also about common properties; in this case, properties that
are common to all the objects which group is being depicted in the topic (for example, in the
Screen Objects Properties topic, the first item is Screen Objects Common Properties, where all
properties common to these objects are grouped).

Properties are identified by an icon indicating the datatype supported on their content. They
are:

Available Datatypes

ICON DATA DESCRIPTION

Boolean Returns True or False.

Numeric Returns positive, negative,

integer, or double, to be
defined by the property.

Returns a date in Gregorian

Date
format (from 1899 on).

Text Returns a text.

Returns a variable type,

Variant which may assume several
formats.

Color Returns a color in RGB format.

Returns a Link between

Link
objects.

Returns a certain set of

Enum
values.

Some properties can propagate their values to the same property in their child objects; in this
case, they are called propagator properties. You can, however, force the property in the child
object to behave distinctively.

46 Programming in E3
NOTE: Some of the properties use the HIMETRIC unit system. In HIMETRIC system, each unit is
equivalent to a thousandth centimeter; that is, 1,000 units equals to 1 centimeter. So, this is
the measurement pattern adopted for properties in this manual, when necessary.

2.8.3.1 Application
The Application property returns the application object related to the current object
context. With this application object it is possible, for example, to search for other objects in
the application. Example:
Sub Screen1_Click()
' When clicking the screen, set a value and display a message box
set obj = Application.GetObject("Data.InternalTag1")
obj.Value = 100
MsgBox "Value of InternalTag1: " & obj.Value
End Sub

2.8.3.2 Count

Returns the number of child objects the object has. This property works together with the
Item method. If the object does not have any child objects, the value of this property is 0.
Example:
Sub Screen1_Click()
' Searches all Screen objects and sets
' ForegroundColor property to red
Dim obj
For i = 1 To Count
Set obj = Item(i) ' Gets a child object
obj.ForegroundColor = RGB(255, 0, 0)
Next
End Sub

2.8.3.3 DocString

Free text that enables the documentation of the object's functionalities or features by the
project's programmers. Example:
Sub CommandButton1_Click()
Docstring = "This button activates system condenser."
MsgBox Docstring
End Sub

2.8.3.4 Links
Returns an object that is a collection of connections (or Links) of any given object in E3. This
property is only available at run time. See items Common Methods and Common Properties for
methods and properties, respectively, applicable to this collection. The types of Links in this
collection are the following: Simple, Bidirectional, Reverse, Digital, Analog, Table, and
Multisource.

Programming in E3 47
2.8.3.4.1 Common Methods

This section contains information about common methods of Link collection objects returned
by the Links property.

2.8.3.4.1.1 CreateLink
CreateLink(Property, Source[, Type])

This method allows creating a Link with an object's property. In case of success, this method
returns the object just created. Otherwise, a script error occurs and this method returns
Nothing. This method has the following parameters:

· Property: specifies the property name to which the Link will be created

· Source: specifies the name of Link's source object

· Type (optional): specifies the Link type to create. When omitted, creates a Simple Link

NOTE: Not all existing properties in an object allow creating Links. To check which properties
allow this feature, go to the Links tab. If the property is invalid, does not exist, or it already
has a Link, a script error occurs.

Available options for Type parameter

OPTION DESCRIPTION
0 - Simple Link In a Simple Link, its source value is copied to
the property every time it is modified.

1 - Bidirectional Link A Bidirectional Link works just like a Simple

Link, but when there is a variation in the
property, its value is copied to the source,
thus generating a two-direction Link.

2 - Analog Link An Analog Link specifies a conversion scale

between the source variable and the
property.

3 - Digital Link In a Digital Link, fixed or alternating values

are set to the property, and these values are
set according to source being True or False.

4 - Table Link In a Table Link, you can specify conditions

among variables, values, and the
destination. On the table you specify
minimum and maximum values, and other
configurations.

48 Programming in E3
 OPTION DESCRIPTION
5 - Reverse Link A Reverse Link is a unidirectional Link from
property to source.

6 - Multisource Link A Multisource Link is similar to a Table Link,

except that each Link row allows retrieving
its value from a different source.

Example:
Sub CommandButton1_Click()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("Text1").Links.Item("Value")
If Bind Is Nothing Then
MsgBox "Text1 is not associated to any object."
Dim Source
Source = "Data.InternalTag1.Value"
MsgBox "Creating a link in '" & Source & "'."
Set Bind = Screen.Item("Text1").Links._
CreateLink("Value", Source, 0)
Bind.BiDirectional = Screen.Item("BiDirectional").Value
Bind.Reverse = Screen.Item("Reverse").Value
MsgBox "Type: " & TypeName(Bind)
Else
MsgBox "Text1 is already linked to '" &Bind.Source& "'."
End If
End Sub

2.8.3.4.1.2 Item
Item(Property, Index)

This method returns a Link object from a specific property of an object. If it is a text, Property
specifies the property name to access. The Link can also be numerically accessed by Index.
This index should be from 1 up to Count. In case there is no connection to the property, or the
index is invalid, a script error occurs. Like other collections, Links allow using VBScript's For
Each command. Example:
Sub Texto1_Click()
For Each Link In Links
MsgBox "Link source: " & Link.Source
Next
End Sub

2.8.3.4.1.3 RemoveLink
RemoveLink(Property)

This method removes a Link from a property specified by Property, in case it exists. If a Link to
the specified property does not exist, this method does nothing. Example:

Programming in E3 49
 Sub CommandButton2_Click()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("ScrollBar1").Links.Item("Value")
If Bind Is Nothing Then
' If link does not exist
MsgBox "ScrollBar1 is not linked."
Else
MsgBox "ScrollBar1 is linked to '" & Bind.Source & "'"
MsgBox "Removing link."
Screen.Item("ScrollBar1").Links.RemoveLink("Value")
End If
End Sub

2.8.3.4.2 Common Properties

This section contains information about common properties of Link collection objects
returned by the Links property.

2.8.3.4.2.1 Count

Returns the number of child objects (items) of a Link collection. This property works together
with the Item method. If the collection does not have children, returned value is 0 (zero).

2.8.3.4.2.2 Property

Specifies the name of the property it is linked to. When modified, moves the Link to another
property of the same object. Example:
Sub CommandButton1_Click()
Dim bind
Set bind = Screen.Item("TableBind").Links.Item(1)
bind.Property = "Caption"
End Sub

2.8.3.4.2.3 Source

Specifies Link's source, which could be the name of another application object, or a more
complex expression accessing several objects. Example:
Sub CommandButton25_Click()
Dim bind
Set bind = Screen.Item("TableBind").Links.Item(1)
bind.Source = "Data.DemoTag1.Value"
End Sub

2.8.3.4.2.4 Type

This is a read-only property, and informs the type of the Link. The available options are:

Available options for Type

OPTION DESCRIPTION
0 - bsSimple Simple Link.

1 - bsSimpleBiDir Bidirectional Link.

50 Programming in E3
 OPTION DESCRIPTION
2 - bsAnalog Analog Link.

3 - bsAnimation Digital Link.

4 - bsTable Table Link.

5 - bsReverse Reverse Link.

6 - bsMultiSource Multisource Link.

2.8.3.4.3 Simple Link

This section contains information about the properties of the Simple Link object.

2.8.3.4.3.1 Properties

The Simple Link object has no properties associated to it.

2.8.3.4.4 Bidirectional Link

This section contains information about properties of the Bidirectional Link object. This object
does not have events nor methods associated to it.

2.8.3.4.4.1 Properties

This section contains information about the properties of the Bidirectional Link object.

BiDirectional

True when a Link is Bidirectional, False when a Link is Simple or Reverse.

2.8.3.4.5 Reverse Link

This section contains information about properties of the Reverse Link object. This object does
not have events nor methods associated to it.

2.8.3.4.5.1 Properties

This section contains information about the properties of the Reverse Link object.

Reverse
True if a Link is Reverse, False if a Link is Bidirectional or Simple.

Programming in E3 51
2.8.3.4.6 Digital Link

This section contains information about properties of the Digital Link object. This object does
not have events nor methods associated to it.

2.8.3.4.6.1 Properties

This section contains information about the properties of the Digital Link object.

BlinkOff
If True, the connected property alternates periodically between values of OffValue and
BlinkOffValue properties, in case the source returns False. Example:
Sub BlinkOff_Change()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("Rectangle1")._
Links.Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to " & Bind.Source & "'"
MsgBox "Changing BlinkOff from " &_
Bind.BlinkOff & " to " & Value
Bind.BlinkOff = Value
End If
End Sub

BlinkOffValue
Specifies an alternative value the property assumes periodically when source returns
False, and BlinkOff property is set to True. Example:
Sub BlinkOffValue_Click()
On Error Resume Next
Dim Value
If Application.ShowPickColor_
(Value, ForegroundColor, 400, 300) Then
Dim Bind
Set Bind = Screen.Item("Rectangle1").Links._
Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to "& Bind.Source & "'"
MsgBox "Changing BlinkOffValue from " &_
Bind.BlinkOffValue & " to " & Value
Bind.BlinkOffValue = Value
End If
ForegroundColor = Value
End If
End Sub

BlinkOn
If True, the connected property alternates periodically between values of OnValue and
BlinkOnValue properties, in case the source returns True. Example:

52 Programming in E3
 Sub BlinkOn_Change()
On Error Resume Next
Dim Bind
Set Bind =_
Screen.Item("Rectangle1").Links.Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to " & Bind.Source & "'"
MsgBox "Changing BlinkOn from " & Bind.BlinkOn & " to "_ & Value
Bind.BlinkOn = Value
End If
End Sub

BlinkOnValue
Specifies an alternative value the property assumes periodically when source returns True,
and BlinkOn property is set to True. Example:
Sub BlinkOnValue_Click()
On Error Resume Next
Dim Value
If Application.ShowPickColor_
(Value, ForegroundColor, 400, 300) Then
Dim Bind
Set Bind = Screen.Item("Rectangle1").Links._
Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to " & Bind.Source & "'"
MsgBox "Changing BlinkOnValue from " &_
Bind.BlinkOnValue & " to " & Value
Bind.BlinkOnValue = Value
End If
ForegroundColor = Value
End If
End Sub

OffValue
Specifies the value a property assumes when source's expression returns False. Example:
Sub OffValue_Click()
On Error Resume Next
Dim Value
If Application.ShowPickColor_
(Value, ForegroundColor, 400, 300) Then
Dim Bind
Set Bind =_ Screen.Item("Rectangle1").Links._
Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to "& Bind.Source & "'"
MsgBox "Changing OffValue from " &_
Bind.OffValue & " to " & Value
Bind.OffValue = Value
End If
ForegroundColor = Value
End If
End Sub

OnValue
Specifies the value a property assumes when source's expression returns True. Example:

Programming in E3 53
 Sub OnValue_Click()
On Error Resume Next
Dim Value
If Application.ShowPickColor_
(Value, ForegroundColor, 400, 300) Then
Dim Bind
Set Bind = Screen.Item("Rectangle1").Links._
Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to "& Bind.Source & " "
MsgBox "Changing OnValue from " &_
Bind.OnValue & " to " & Value
Bind.OnValue = Value
End If
ForegroundColor = Value
End If
End Sub

2.8.3.4.7 Analog Link

This section contains information about properties of the Analog Link object. This object does
not have events nor methods associated to it.

2.8.3.4.7.1 Properties

This section contains information about the properties of the Analog Link object.

DstHiValue
Specifies the highest value reached by the property. Example:
Sub DstHiValue_ValueChange()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("ScrollBar1").Links.Item("Value")
Screen.Item("ScrollBar1").Max = Value
If Bind Is Nothing Then
MsgBox "ScrollBar1 has no link."
Else
MsgBox "ScrollBar1 is linked to " & Bind.Source & "'"
MsgBox "Changing DstHiValue from " &_
Bind.DstHiValue & " to " & Value
Bind.DstHiValue = Value
End If
End Sub

DstLoValue
Specifies the lowest value reached by the property. Example:
Sub DstLoValue_ValueChange()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("ScrollBar1").Links.Item("Value")
Screen.Item("ScrollBar1").Min = Value
If Bind Is Nothing Then
MsgBox "ScrollBar1 has no link."
Else
MsgBox "ScrollBar1 is linked to " & Bind.Source & "'"
MsgBox "Changing DstLoValue from " &_
Bind.DstLoValue & " to " & Value
Bind.DstLoValue = Value
End If
End Sub

54 Programming in E3
SrcHiValue
Specifies the highest value reached by the source. Example:
Sub SrcHiValue_ValueChange()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("ScrollBar1").Links.Item("Value")
Screen.Item("ScrollBar2").Max = Value
If Bind Is Nothing Then
MsgBox "ScrollBar1 has no link."
Else
MsgBox "ScrollBar1 is linked to " & Bind.Source & "'"
MsgBox "Changing SrcHiValue from " &_
Bind.SrcHiValue & " to " & Value
Bind.SrcHiValue = Value
End If
End Sub

SrcLoValue
Specifies the lowest value reached by the source. Example:
Sub SrcLoValue_ValueChange()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("ScrollBar1").Links.Item("Value")
Screen.Item("ScrollBar2").Min = Value
If Bind Is Nothing Then
MsgBox "ScrollBar1 has no link."
Else
MsgBox "ScrollBar1 is linked to " & Bind.Source & "'"
MsgBox "Changing SrcLoValue from " &_
Bind.SrcLoValue & " to " & Value
Bind.SrcLoValue = Value
End If
End Sub

NOTE: In case the values specified for SrcHiValue and SrcLoValue properties are the same,
there will be no scale, then Link will work as a Simple Link.

2.8.3.4.8 Table Link

This section contains information about methods and properties of the Table Link object. This
object does not have events associated to it.

2.8.3.4.8.1 Methods

This section contains information about the methods of the Table Link object.

InsertRow
InsertRow([Row])

Inserts a new row on the table. The Row parameter is optional and specifies at which table
position the row should be inserted. When omitted, it assumes the standard behavior of
inserting a row at the end of the table, which is the same as using Row equal to -1. When it is
informed and is not equal to -1, it must be a value between 1 and Count, and the new row
moves rows greater or equal to the index towards index ascending direction. A new row always
assumes the following standard values to its properties:

Programming in E3 55
· Min: 0.0

· Max: 1.0

· Blink: False

· BlinkValue: 0.0

· Value: 0.0

Example:
Sub Rectangle1_Click()
On Error Resume Next
Dim Bind
Set Bind = Screen.Item("Rectangle1").Links.Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no links."
Else
Dim row
row = Screen.Item("SetPointRow").Value
MsgBox Bind.RowCount
If (row < 1 Or row > Bind.RowCount) Then
MsgBox "Invalid row number: " & row
Else
MsgBox "Adding a row at: " & row
Bind.InsertRow(row)
If row = -1 Then
row = Bind.RowCount
Bind.Value(line) = Screen.Item("RectangleValue").ForegroundColor
Bind.BlinkValue(line) = Screen.Item("RectangleBlinkValue").ForegroundColor
Bind.Max(line) = Screen.Item("SetPointMax").Value
Bind.Min(line) = Screen.Item("SetPointMin").Value
Bind.Blink(line) = Screen.Item("CheckBoxBlink").Value
End If
End If
End If
End Sub

Item
Item(ItemId)

Returns a reference to a Table Link Row object, indicated by ItemId.

RemoveRow
RemoveRow(Row)

Removes a row at a specified index. The Row parameter determines the table row to be
removed (it must be between 1 and Count). Example:
Sub RemoveRow_Click()
On Error Resume Next
Dim Bind
Set Bind =_
Screen.Item("Rectangle1").Links.Item("ForegroundColor")
If Bind Is Nothing Then
MsgBox "Rectangle1 has no link."
Else
MsgBox "Rectangle1 is linked to '" & Bind.Source & "'"
Dim row
row = Screen.Item("Row").Value
MsgBox "Removing line " & row
Bind.RemoveRow row
End If
End Sub

56 Programming in E3
2.8.3.4.8.2 Properties

This section contains information about the properties of the Table Link object.

Count
Informs the number of rows in a table. This is a read-only property.

2.8.3.4.8.3 Table Link Row

This section contains information about properties of the Table Link Row object. This object
does not have events nor methods associated to it.

Properties
This section contains information about the properties of the Table Link Row object.

Blink
Determines that when the source is within this row's interval, the property alternates
periodically between values established in Value and BlinkValue properties. Example:
Sub CheckBox1_Click()
Screen.Item("Rectangle1").Links.Item("ForegroundColor")._
Item(1).Blink = Value
Screen.Item("Rectangle1").Links.Item("ForegroundColor")._
Item(2).Blink = Value
End Sub

BlinkValue
Specifies the alternative (blinking) value the property assumes when source is within the
specified row's interval, and Blink property is set to True. Example:
Sub CommandButton1_Click()
Dim Color
' Picks a color
Application.ShowPickColor Color, 0, 100, 100
Screen.Item("Rectangle1").Links.Item("ForegroundColor")._
Item(1).BlinkValue = Color
End Sub

Max
Specifies the highest source value for a table row.

Min
Specifies the lowest source value for a Table Row. Example (applicable for both Max and Min
properties):
Sub CommandButton1_Click()
Set Bind = _
Screen.Item("Rectangle1").Links.Item("ForegroundColor")
Set Line1 = Bind.Item(1)
Line1.Min = 0
Line1.Max = 20
Set Line2 = Bind.Item(2)
Line2.Min = 21
Line2.Max = 100
End Sub

Programming in E3 57
Value
Specifies the value the property assumes when source is within the specified row's interval.
Example:
Sub CommandButton1_Click()
Dim Color
' Picks a color
Application.ShowPickColor Color, 0, 100, 100
Screen.Item("Rectangle1").Links.Item("ForegroundColor")._
Item(1).Value = Color
End Sub

2.8.3.4.9 Multisource Link

This section contains information about methods and properties of the Multisource Link
object. This object does not have events associated to it.

2.8.3.4.9.1 Methods

This section contains information about the methods of the Multisource Link object.

InsertRow
InsertRow(InsertAtRow)

Inserts a new row in the Multisource Link table.

Item
Item(ItemId)

Returns a reference to a Multisource Link Row object, indicated by ItemId.

RemoveRow
RemoveRow(Row)

Removes the row at the index indicated by the Row parameter.

2.8.3.4.9.2 Properties

This section contains information about the properties of the Multisource Link object.

Count
This property returns the number of rows in the Multisource Link table.

58 Programming in E3
2.8.3.4.9.3 Multisource Link Row

This section contains information about the properties of the Multisource Link Row object.
This object does not have events nor methods associated to it.

Properties
This section contains information about the properties of the Multisource Link Row.

Max
Maximum interval for a Link value indicated by the Source property.

Min
Minimum interval for a Link value indicated by the Source property.

2.8.3.5 Name

Identifies each object present in the system. Modifying this property implies in modifying
all other properties or scripts that use this object. Hence, it is not advisable to change this
property at run time. Example:
Sub CommandButton9_Click()
MsgBox "Screen name is " & (Screen.Name)
End Sub

2.8.3.6 Parent
Returns the object's parent object. So, if an object is inserted in the Screen, Parent
property will return Screen. Likewise, if an Internal Tag is inserted directly below a Data
Server, InternalTag's Parent property will point to Data Server. Example:
Sub Rectangle1_Click()
' When clicking Rectangle1, changes the foreground color of Rectangle2
Parent.Item("Rectangle2").ForegroundColor = RGB(255, 0, 0)
End Sub

2.8.3.7 PathContainer

Returns a String with the path of the object containing the current object, including its
folders. This value is determined only at the moment of the request, thus it is not
recommended to create links for this property.

2.8.3.8 PathName

Identifies a path name in the system. This property is available at run time only. Example:
Sub CommandButton9_Click()
MsgBox "Screen path is " & (Screen.PathName)
End Sub

Programming in E3 59
2.8.3.9 PathVolume

Returns a String with the name of the .prj or .lib file containing the object. In E3 Studio, this
property returns the project's or library's full path (c:\folder\folder\volume.prj). At run time,
the objects running in the Viewer always return an empty String. However, objects running in
the server return the project's or library's relative path, according to the way it is stored in the
Domain (volume.prj). This value is determined only at the moment of the request, thus it is not
recommended to create links for this property.

60 Programming in E3
 CHAPTER

3
User Libraries

This section contains information about XControls and XObjects, and also ElipseX Properties.

3.1 XControls and XObjects

This section contains information about events and properties of XControls and XObjects.
These objects do not have methods associated to them.

3.1.1 Events
This section contains information about the events of XControls and XObjects.

3.1.1.1 Constructor
Constructor()

Triggered when the ElipseX is started. You may use this event to run a script that sets internal
values of an ElipseX, for example.

3.1.1.2 CustomConfig
CustomConfig()

Allows automated configurations on ElipseX instances. A configuration option appears on the

contextual menu of an ElipseX instance when there is a script associated to the CustomConfig
event of the ElipseX definition. When this option is selected on the menu, the event is
triggered. The text that appears on the menu option may be set on the CustomConfigText
property of the ElipseX definition. If this property is empty, the text displayed is "Configure".

User Libraries 61
 Contextual menu of an ElipseX instance

NOTE: The script associated to the CustomConfig event runs on E3 Studio, where objects are
not active. Therefore, its behavior is different from the usual.

3.1.2 Properties
This section contains information about the properties of XControls and XObjects.

3.1.2.1 CustomConfigText

Indicates a text that appears on the contextual menu for the configuration option of the
ElipseX instance. This option only appears if there is a script associated to the CustomConfig
event of the ElipseX definition. If the property value is empty, the text "Configure" is then
displayed in the menu option. The default value of this property is is an empty String.

62 User Libraries
3.2 ElipseX Properties
This section contains information about events and properties of the Property object of an
ElipseX. This object does not have methods associated to it.

3.2.1 Events
This section contains information about the events of the Property object of an ElipseX.

3.2.1.1 OnPropertyChanged
OnPropertyChanged()

It is triggered when an ElipseX property is modified. You may use this event to trigger scripts
that execute actions according to a certain ElipseX status.

3.2.2 Properties
This section contains information about the properties of the Property object of an ElipseX.

3.2.2.1 DefaultValue
Initial value of the object. The default value of this property is Empty.

3.2.2.2 HelpString

Text containing an object description. The default value of this property is an empty String.

3.2.2.3 Public
When an ElipseX Property is public (True), it is visible outside the Library. Otherwise, the
Property is internal and only visible to the object. The default value of this property is True. A
public Property is represented by the icon .

User Libraries 63
3.2.2.4 Retentive

This property indicates whether a property value is retentive, that is, if it must be stored
when the object is disabled (True), or if it always has its default value when the object is
activated (False).

NOTES:
· This property is only available to properties which data type is not an object (Variant,
Double, Integer, etc.)
· Using this property implies in raising E3Run memory and CPU usage, therefore it must be
used carefully

3.2.2.5 Type

Determines the type of values accepted by a Property (for example, Boolean, Double,
Integer, Variant, etc.). When specifying an object type (as for example DemoTag, IOTag,
XObject, etc.), this property has the following behavior:

· In case the ElipseX is inactive: This property works as a String, which specifies the object's
instance path of the configured type

· In case the ElipseX is active: When writing, this property works just like when the object is
inactive. However, when reading this property returns the specified object, in case it exists.
If the path does not point to an existing object at the time, this property returns Nothing

64 User Libraries
 CHAPTER

View
4
This section contains information about events, methods, and properties of E3's view objects:

· Viewer

· Frames and Splitters

· Screen and Screen Objects

· E3Alarm

· E3Browser

· E3Chart

· E3Playback

· Reports

4.1 Viewer
This section contains information about events, methods, and properties of the Viewer object.

4.1.1 Events
This section contains information about the events of the Viewer object.

4.1.1.1 OnInactive
OnInactive()

This event occurs while the Viewer is inactive, if the EnableInactivity property is set to True. It
is triggered when it is checked that the user is not using the Viewer for a period of time equal
or greater than the value of the InactivityTime property.

In a script for this event, the user may program what to do when the Viewer is inactive for a
certain period of time. For example, it is possible to determine that after 20 minutes, a logout
will be performed. Example:
Sub Viewer_OnInactive()
Logout(false)

V iew 65
 If MsgBox("This Viewer section was closed due to inactivity.") = 0 Then
Application.GetFrame("").OpenScreen "InitialScreen", 0
End Sub

4.1.1.2 User Events

This section contains information about the user events of the Viewer object.

4.1.1.2.1 OnLogin
OnLogin()

Occurs when a user performs a sucessfully system login (user authentication). The system
login can be performed using the Login method or when an object which can only be accessed
by users with a certain authorization level requests authentication. Example:
Sub Viewer_OnLogin()
MsgBox "Authorized user. Welcome to the system!"
End Sub

4.1.1.2.2 OnLogout
OnLogout()

Occurs when a logout is performed, that is, the user quits the system. The logout is performed
by calling the Logout method. Example:
Sub Viewer_OnLogout()
MsgBox "User quit the system."
End Sub

4.1.2 Methods
This section contains information about the methods of the Viewer object.

4.1.2.1 CaptureScreen
CaptureScreen(Filename)

The CaptureScreen method captures the current Screen and saves it in a file. This methods has
the same effect of the PRINT SCREEN key in Windows. The Filename parameter determines the
filename in which the Screen will be saved.

NOTE: The final format of the file is a Bitmap (.bmp), even if in the Filename parameter
another file extension is informed (.gif, .jpg, etc.).

Example:
Sub CommandButton1_Click()
Screen.Frame.CaptureScreen "c:\temp\screen.bmp"
End Sub

66 V iew
4.1.2.2 ChangePassword
ChangePassword()

This method opens a dialog box to change current user's password. This method returns True if
the current user has permission to change their password. Otherwise, it returns False,
indicating an operation failure, or that it is not possible to change the password, because the
user is not authorized.

NOTE: This method is only available if the logged-in user belongs to an E3 Domain.

4.1.2.3 DoModal
DoModal(Screen, Title, Left, Top, Width, Height, Arg, Flags)

Opens a modal Screen, which is a window that do not allow clicking other Screens while it is
not closed. The title parameter passed in this method will only be used if the Caption property
is empty. Otherwise, the parameter will be ignored.

This method has the following parameters:

· Screen: determines the name of the Screen

· Title: determines the title of the modal window

· Left, Top: XY position of the modal window in pixels

· Width: width of the modal window in pixels or HIMETRIC

· Height: height of the modal window in pixels or HIMETRIC

· Arg: determine variable to be used in the OnPreShow event of the Screen

· Flags: determines a combination used on the modal window. Such combination is done by
summing values of the next table that corresponds to the user options. When the specified
value is equal to -1, the Viewer configurations are set to the modal window. When this
value is different from -1, you may use the combinations described on the next table

Possible combinations for Flags parameter

VALUE DESCRIPTION
1 Enables a title bar on the window.

2 Enables the Close button on the window.

4 Enables the Minimize button on the window.

8 Enables the Maximize button on the window.

V iew 67
 VALUE DESCRIPTION
16 Enables a window border.

32 Specifies that the window may be resized.

64 Specifies that the window may be moved.

256 Specifies that the window will stay on the top

of the Screen.

512 Specifies that the window will be configured

with a Tool Bar style.

1024 Disables object buttons.

2048 Centralizes the modal Screen in the Frame

horizontally as well as vertically.

Example:
Sub Button1_Click()
' When clicking the Button1 opens another modal Screen
Application.DoModal "Screen1", "Title", 0, 0, 400, 200, 0, 3
End Sub

NOTE: Size values on this method may be informed as numbers or strings. of numbers, they
are interpreted as pixels. In case of strings, and followed by unit "hm", they are interpreted
as HIMETRIC. Any other case is considered as pixels.

68 V iew
4.1.2.4 ESign
ESign(ObjName[, Description[, Action[, From[, To[, User[, Comment]]]]]])

The ESign method is used to validate a field change, using an electronic signature. When this
method is used, the following dialog box is displayed:

Digital Signature dialog box

Parameters of the ESign method

PARAMETER DESCRIPTION
ObjName Text that contains a Tag name or another
application object.

Description Text that contains the description of

ObjName. This parameter is optional and if it
is omitted, the dialog box will try to retrieve
data from ObjName's DocString property.

Action Text that contains an action to be executed

(for example, "Value change"). This
parameter is optional and its default value is
an empty String.

From Variant which contains the original value, or

the state to be altered. This parameter is
optional.

V iew 69
 PARAMETER DESCRIPTION
To Variant which contains the new Tag value, or
the value to be applied in Action. This
parameter is optional.

User Return text. Receives the login name

selected on the dialog box. This parameter is
optional.

Comment Return text. Receives a comment typed on

the dialog box. This parameter is optional.

When clicking , a window then opens to authenticate the user. If option Windows is
selected, fields User name and Password are automatically disabled. Click Other user to select
a user belonging to the network domain. In case option E3 is selected, type information about
a user belonging to an E3 Domain in fields User name and Password.

Integrated login

This method returns True if the user clicks OK, and if the User and Password fields are valid.
Otherwise, if the dialog box is dismissed or if the login or the password are wrong after three
attempts, this method returns False. In case of failure, User and Comment are configured to an
empty String.

Pre-defined comments are stored on Windows Registry. Only the last 26 comments are saved.
Every time the window is created, the last comments are retrieved from Registry, and then
used to fill in a list box. If users provide a new comment, it will be saved and the oldest one will
be discarded, in case there is no free position. If it is an already existing comment, then it
moves to the top of the recent comments list. Example:

70 V iew
 Sub Button1_Click()
Dim Tag, User, Comment
Set Tag = Application.GetObject("IO.Inputs.IO01")
If Application.ESign(Tag.PathName, , "Value Change", _
Tag.Value, 1, User, Comment) Then
If Tag.WriteEx = 1 Then
Application.TrackEvent _
"Tag IO.Inputs.IO01 changed to 1 " &_
"by the user" & User, Comment
End If
End If
End Sub

4.1.2.5 ExecuteExternalApp
ExecuteExternalApp(AppPath, Arguments, InitialDir, CmdShow[, ProcessId])

This method executes an external application with AppPath name and path, and with
Arguments, starting at the iniciando no diretório de trabalho InitialDir working directory.
When a document is specified at AppPath, the application associated to this document is
executed, and the document is passed as one of the application parameters. ProcessID
receives a number that identifies the process (this number is used on IsAppRunning method
and is the same value which appears on Windows Task Manager, on PID column). The
CmdShow parameter specifies the application window opening mode, as described on the
next table:

Available options for CmdShow parameter

OPTION DESCRIPTION
0 Hides the window and activates another
window.

1 Activates and displays the window. If the

window is maximized or minimized, it will be
restored to the original size and position. An
application must specify this value when it is
displaying a window for the first time.

2 Activates the window and displays it

minimized.

3 Activates the window and displays it

maximized.

4 Displays the window with its most recent size

and position. The active window remains
active.

5 Activates the window and display it with its

current size and position.

6 Minimizes the window and activates the next

higher level window.

7 Displays the window minimized. The active

window remains active.

V iew 71
 OPTION DESCRIPTION
8 Displays the window in its current state. The
active window remains active.

9 Activates and displays the window. If the

window is maximized or minimized, it will be
restored to its original size and position. An
application must specify this value when
restoring a window which was minimized.

Example:
Sub CommandButton1_Click()
Dim ret
Application.ExecuteExternalApp "calc.exe", "", "", 1, ret
Application.GetObject("Data.InternalTag1").Value = ret
End Sub

NOTE: The parameter returned by ProcessID may be 0, in case any process has been started.
For example, if an open document is an URL and an Internet Explorer instance is already
running, it will display the document. No new process is started, thus ProcessID is 0.

4.1.2.6 Exit
Exit()

This method closes the window in Viewer. Example:

Sub_Button1.Click()
Application.Exit()
EndSub

4.1.2.7 GetFormulaUnitDataObj
GetFormulaUnitDataObj(FormulaName)

This method gets the settings of the existing units on a certain Formula. The units are the
destination of saved data in the Formula (values). This method has the FormulaName
parameter, which informs Formula name.

Use the GetFormulaUnitDataObj method to get a collection of units of a Formula. This method
returns True if the operation is successful, or False otherwise. Example:
Sub Button1_Click()
Dim val
' When clicking the button, displays a
' message box with the number of Units and the name
' of the First Unit
Set obj = Application.GetFormulaUnitDataObj("Formula1")
MsgBox CStr(obj.Count)
MsgBox CStr(obj.Name(1))
End Sub

72 V iew
4.1.2.8 GetFormulaValueDataObj
GetFormulaValueDataObj(FormulaName)

This method gets the settings of the existing values of a certain Formula. Values are a data set
saved in the Formula. This method has the FormulaName parameter, which informs Formula
name.

Use the GetFormulaValueDataObj method to get a collection of values in the Formula. This
method returns True if the operation is successful, or False otherwise. Example:
Sub Button1_Click()
Dim val
' When clicking the button, displays a message box
' with the number of Sets
' and the name of the First Set.
Set obj = Application.GetFormulaValueDataObj("Formula1")
MsgBox CStr(Obj.Count)
MsgBox CStr(obj.Name(1))
End Sub

4.1.2.9 GetFrame
GetFrame([FrameName])

The GetFrame method searches for a splitter object which is already open in the current
Viewer. This method has the FrameName parameter, which is optional and determines the
frame name to be searched. In case the specified value at FrameName is empty, it will return a
frame which contains all splitters or the active Screen. With the return value, use splitter
methods, for example, the OpenScreen method to open another Screen. Example:
Sub Button1_Click()
' When clicking the button, gets the Menu frame
' and replaces the current Screen of this frame by the Options screen
Set frame = Application.GetFrame("Menu")
' frame has an object of type Splitter
frame.OpenScreen "Options", 0
End Sub

4.1.2.10 GetFullUserName
GetFullUserName()

The GetFullUserName method returns the complete name of the user logged in E3. In case
there is no logged-in user, an empty String is then returned.

4.1.2.11 GetKeyPad
GetKeyPad()

Returns a reference to an Elipse KeyPad object, it allows manipulating a floating virtual

keyboard on applications developed using E3. See the User's Manual for more information on
this object. The methods and properties of the Elipse KeyPad are described on chapter ActiveX
- Elipse KeyPad.

V iew 73
4.1.2.12 GetMouseX
GetMouseX()

Returns the X coordinate of the mouse, in pixels, relative to the whole area of the computer
screen.

NOTE: This method fails in a script if the current mouse position cannot be retrieved. One of
the situations where this failure can be verified is when the Windows Logon window is open
(when pressing the CTRL + ALT + DEL key combination). This behavior of preventing access to
the current mouse position is default on Windows and cannot be overridden. As a
suggestion, use the On Error Resume Next command before using this method to
prevent script errors.

4.1.2.13 GetMouseY
GetMouseY()

Returns the Y coordinate of the mouse, in pixels, relative to the whole area of the computer
screen.

NOTE: This method fails in a script if the current mouse position cannot be retrieved. One of
the situations where this failure can be verified is when the Windows Logon window is open
(when pressing the CTRL + ALT + DEL key combination). This behavior of preventing access to
the current mouse position is default on Windows and cannot be overridden. As a
suggestion, use the On Error Resume Next command before using this method to
prevent script errors.

4.1.2.14 GetValue
GetValue(TagName)

This method searches for an object value specified on TagName parameter. If TagName points
to a property, this method returns the value of the property. However, if the TagName
parameter specifies an object, this method returns the value of the Value property of the
object. Example:
Sub Button1_Click()
' When clicking the button gets a tag value
' executed on a DataServer
X = Application.GetValue("DataServer1.InternalTag1")
End Sub

4.1.2.15 IsAppRunning
IsAppRunning(ProcessId)

Indicates if an application started by the ExecuteExternalApp method is being executed.

Returns True if the application identified on the operating system by ProcessId is running.
Otherwise returns False. Example:

74 V iew
 Sub CommandButton1_Click()
Application.ExecuteExternalApp _
"www.elipse.com.br", "", "", 1, processID
While Application.IsAppRunning(processID)
' Waits for the application end
Wend
MsgBox "The application ended!"
End Sub

NOTE: The ProcessId parameter is the same value appearing in Windows Task Manager, in the
PID column.

4.1.2.16 IsUserMemberOfGroup
IsUserMemberOfGroup(GroupName)

This method checks if the user currently logged in Viewer belongs to a certain group. This
method has the GroupName parameter, which determines the name of the group to check.
This method returns True if the user belongs to the GroupName group, or False otherwise.

4.1.2.17 IsWebViewer
IsWebViewer()

Checks if the application is viewed by E3 WebViewer. This method returns True if the
application is being executed on E3 WebViewer. Otherwise, returns False.

4.1.2.18 LoadFormulaDlg
LoadFormulaDlg(FormulaName[, UnitName[, ValueName]])

This method presents a dialog box which allows the user choosing a value set and the
destination unit, loading a Formula. This method has the FormulaName parameter, which
determines the name of the formula object to be processed.

Use the LoadFormulaDlg method to call a dialog box for loading data of the Formula object
specified by FormulaName. In this dialog box it is possible to specify which value set (UnitName
) will be sent to which tag set (ValueName). In this message box the user has all value and unit
sets available in the Formula object, and can freely set one to each other. When the user
clicks OK, the value set is loaded on the specified unit. Example:
Sub Button1_Click()
' Calls the dialog box to operate
Dim val
Application.LoadFormulaDlg("Formula1")
End Sub

4.1.2.19 LoadFormulaValues
LoadFormulaValues(FormulaName, UnitName, ValueName)

This method automatically loads a value set to a destination unit, displaying a dialog box
which allows the user informing different values from the ones defined on the Formula. This
method has the following parameters: FormulaName determines the name of the formula and
UnitName determines the name of the unit. The name of the value set is configured in the
ValueName parameter.

V iew 75
NOTE: This method returns a logical value, that is, returns True if successful, and False on
failure, which does not mean a script error.

Example:
Sub Button1_Click()
Application.LoadFormulaValues "Formula1", "Unit1", "Value1"
End Sub

4.1.2.20 LoadFormulaValuesQuiet
LoadFormulaValuesQuiet(FormulaName, UnitName, ValueName)

Loads a value set to a destination unit, without any message. This method has he following
parameters: FormulaName determines the name of the Formula, and UnitName which
determines the unit name. The name of the value set is configured in the ValueName
parameter. Example:
Sub Button1_Click()
Application.LoadFormulaValuesQuiet "Formula1", "Unit3", "Value1"
End Sub

NOTE: This method is also accessible through the Formula object.

4.1.2.21 LoadReport
LoadReport(ReportName)

Loads a Report template. The ReportName parameter is the name of the Report to be loaded.
Example:
Sub Rect_Click()
' Loading a pre-defined report
Set strRep = Application.LoadReport("[Report3]")
strRep.PrintPreview ' Previewing print
End Sub

4.1.2.22 Login
Login([Mode])

Opens a dialog box for login (user authentication) in the application. The logged-in user
remains in memory until another login or logout (when a user quits the application) are
performed. This method has the Mode parameter, which is a Boolean determining whether a
confirmation or failure message must be displayed (the default is False). When a Screen is
about to be opened (using the OpenScreen method), a check on security settings is then
performed. If True, the Screen is only opened if the logged-in user has permission. Otherwise,
a login dialog box is opened.

76 V iew
4.1.2.23 LoginUser
LoginUser(Username, UserPassword)

Executes a login for a specific user, without displaying any message. The Username parameter
is the name of the user, and the UserPassword parameter is the password of this user. This
method returns True if the user login was successful, and False otherwise. If the user passed
on Username parameter is configured to change the password on next login, this method
returns False.

NOTE: This method is only available if the logged-in user belongs to an E3 Domain.

4.1.2.24 Logout
Logout([Mode])

Executes a logout (when the current user quits the application) from Viewer. In case there is
no logged-in user, this method has no effect. From this moment on, it is considered that an
"Anonymous" user is using the application. (You can use the OnLogout event to perform a
script to go to the initial Screen or end the application). This method has the optional Mode
parameter, which is a Boolean determining whether a confirmation or failure message must
be displayed (the default is False).

4.1.2.25 PasswordConfirm
PasswordConfirm(Mode)

This method opens a dialog box asking the currently logged-in user to retype the password. It
returns True if the password is confirmed, or False otherwise. The Boolean Mode parameter
determines whether a logout must be performed in case of failure.

Password confirm

If the dialog box is closed by clicking Cancel, this method returns False. In case there is no
logged-in user, this method returns False, but without opening a dialog box. In case the typed
password is wrong, it is then asked three more times. If users type it incorrectly these three
times, the dialog box is then closed and the method returns False.

V iew 77
NOTE: This method is only available if the logged-in user belongs to an E3 Domain.

4.1.2.26 Playsound
Playsound(Filename)

Plays a sound file which path and name are indicated in the Filename parameter. The file must
follow these specifications:

· It must be Windows sound format (.wav extension)

· If the file is in the project (added using the Insert resource) command, the filename must be
enclosed in brackets

If a folder was created on the project and the file was added using the Insert resource
command, the path must be enclosed in quotation marks (for example, "c:\sound\ding.wav"). If
the file is in the local directory, the name does not need to be enclosed in quotation marks, it
is enough to type the path (for example, c:\sound\ding.wav). Example:
Sub InitialScreen_OnAlarm()
' If there is an active alarm, an alert sound will be played.
' When the alarm is recognized, the sound stops.
Set Alarm = Application._
GetObject("AlarmConfig1.Area1.AlarmSource1")
If Alarm.ActiveNACKAlarms = True Then
Application.PlaySound("[ringin.wav]")
End If
End Sub

4.1.2.27 SelectMenu
SelectMenu(Menu[, Left[, Top]])

This method displays a pop-up menu as specified by the Menu parameter. This parameter is a
text with several options delimited by a vertical bar, each one of these strings is a menu
option. In case there is a set of two consecutive delimiters, a separator will be inserted. Use
opening and closing braces to create a submenu. An asterisk in front of a string indicates an
already marked option. An exclamation point disables the option.

The dialog box position can be set through the Left and Top parameters, which indicate the
distance from left margin and top of Screen in pixels, respectively. In case these parameters
are not informed, the menu is positioned acording to the location where the mouse was
clicked.

This method returns 0 if no option is selected, or the option number, 1 for the first option, 2 for
the second, and so on. Example:

78 V iew
 Sub Button1_Click()
op = _
Application.SelectMenu("Option1||Option2{*Option2|Option3}|Option4|!Opption5")
If op = 1 Then
MsgBox "Option 1 was chosen"
ElseIf op = 2 Then
MsgBox "Option 2 was chosen"
ElseIf op = 3 Then
MsgBox "Option 3 was chosen"
ElseIf op = 4 Then
MsgBox "Option 4 was chosen"
ElseIf op = 0 Then
MsgBox "No option was chosen"
End If
End Sub

4.1.2.28 SetValue
SetValue(TagName, NewVal)

This method sets the value of an object inside server. The SetValue method searches for an
object or property executed on the server and sets the value specified in the TagName
parameter. The type and value of the NewVal parameters must be supported by the object
specified in TagName. Example:
Sub Button1_Click()
' When clicking Button1 sets value 20
' to Value property of the tag
Application.SetValue "DataServer1.InternalTag1", 20
End Sub

4.1.2.29 ShowDatePicker
ShowDatePicker(DateValue, Left, Top[, DefaultDate])

Opens a dialog box to change date and time. This method returns True if the user confirms the
date, or False if the user cancels editing. The new date is returned in the DateValue
parameter. The position of the dialog box can be configured using the Left and Top parameters,
which indicate the distance from left margin and top of the Screen in pixels, respectively. In
case these parameters are not informed, the dialog box is centralized on the screen. The value
of the DefaultDate parameter is the initial date and time when the dialog box was opened. If
no date is informed, the system assumes current date. If no time is informed, it will start as
00:00:00. If no date nor time are informed, it will start with the current date and time.
Example:
Sub Text2_Click()
Dim newTime
Application.ShowDatePicker newTime, 300, 300
MsgBox "The time is : " & newTime
End Sub

4.1.2.30 ShowFilePicker
ShowFilePicker(Open, FileName[, Extension[, Flags[, Filter]]])

Displays the Save and Open File dialog boxes from Windows. The Open parameter indicates
the dialog box to be opened. If True, opens the Open File dialog box. If False, opens the Save
dialog box. The FileName parameter indicates the variable where the filename to be saved or
loaded will be stored in case the method returns True. This parameter must be a variable. The
Extension parameter is optional and informs the default file extension to be attached to the
file name on the dialog box, when no extension is informed. In case it is empty, no extension
will be attached at the end of the file name. Multiple extensions can be specified using a
semicolon as the delimiter. The string must end with double vertical bars.

V iew 79
The Flags parameter is optional and defines the dialog box behavior. It is an integer, the sum of
values from the next table. The Filter parameter is optional and defines a set of string pairs
which specify filters that can be applied to the files. The first string describes the filter, and the
second one indicates the type of extension to be used.

Possible combinations for Flags parameter

VALUE DESCRIPTION
1 CREATEPROMPT: If the user specifies a non-
existing file, this flag asks if the file must be
created. If yes, the dialog box is closed and
the file name is returned in the Filename
parameter. Otherwise, the dialog box
remains open.

2 FILEMUSTEXIST: Specifies tha the user can

only type existing file names. Otherwise, the
dialog box displays a warning on the message
dialog.

4 NOCHANGEDIR: Recovers the current

directory to the original value in case the
user have changed the directory while
searching for the file. It has no effect for Open
File in Windows XP.

8 NODEREFERENCELINKS: Sets the dialog box to

return the selected shortcut file (.lnk). If this
flag is not specified, the dialog box return the
path and file name referenced by the
shortcut.

16 NOREADONLYRETURN: Determines that the

returned file is not read-only, and the
directory is not record protected.

32 PATHMUSTEXIST: Specifies that the user can

only inform valid files and directories,
otherwise a message box is displayed to
warn the user.

64 READONLY: Makes the option button Read

Only to be initially selected when the dialog
box is created.

128 OVERWRITEPROMPT: Makes the Save As

dialog box generates a message informing
that the file exists, and asks for confirmation
to overwrite the file.

80 V iew
Filter example:
"Chart Files (*.xlc)|*.xlc|Excel spreadsheets (*.xls)|*.xls|Data Files (*.xlc;*.xls)|
*.xlc; *.xls|All files (*.*)|*.*||"

4.1.2.31 ShowPickColor
ShowPickColor(ColorValue, Color, Left, Top)

Opens the Windows Colors dialog box to choose a color. The decimal value of the chosen color
is returned in the ColorValue parameter. The Color parameter indicates a previously selected
color on the color palette. If this parameter is not informed, assumes black (0). The position of
the dialog box can be set using the Left and Top parameters, which indicate the distance from
the left margin and from the top of the screen, respectively, in pixels. In case these
parameters are not informed, the dialog box is centralized on the screen. Example:
Sub CommandButton_Click()
Dim newColor
Dim defaultColor
defaultColor = 65280 ' Light green
If Application.ShowPickColor(newColor, defaultColor, 90, 90) Then
Screen.Item("Rectangle1").ForegroundColor = newColor
Screen.Item("Text1").Value = newColor
End If
End Sub

4.1.2.32 Stopsound
Stopsound()

Stops a playing sound. Example:

Sub CommandButton2_Click()
Application.StopSound()
End Sub

4.1.2.33 ToggleValue
ToggleValue(TagName, ValA, ValB)

The ToggleValue method searches for an object value or property executed on the server and
compare them to the ValA and ValB parameters. If the searched value is equal to ValB, the
object or property specified in TagName will receive the value of ValA. Otherwise, it will
receive the value of ValB. In case the value of TagName is not ValA nor ValB, the ToggleValue
method will set the value specified in ValA. Example:
Sub Button1_Click()
' When clicking the button, sets the value
' to a tag executed on a DataServer.
' Sets a value of 20 to the tag.
Application.SetValue "DataServer1.InternalTag1", 20
' As the value of InternalTag1 already is 20,
' the ToggleValue method alternates the value to 30.
Application.ToggleValue "DataServer1.InternalTag1", 30, 20
End Sub

V iew 81
4.1.2.34 TrackEvent
TrackEvent(EventMessage, Comment, TimeStamp)

The TrackEvent method allows generating events via script manually. These events can be
generated on the Viewer as well as on the Server, and are registered on a database table of
the application.

Parameters of the TrackEvent method

NAME DESCRIPTION
EventMessage Contains the event message (200
characters).

Comment (Optional) Contains additional comments

about the event (200 characters).

TimeStamp (Optional) Indicates the date/time the event

occurred. If it is not specified, E3 assumes
current date and time.

The TrackEvent method will only record events in case the Event Recording option in the
Domain Options is enabled. Events are recorded on a database table which is also defined on
the Event Recording settings.

For more information on Event Recording of the Domain, check the User's Manual. Example:
Sub Button1_Click()
Dim Tag, User, Comment
Set Tag = Application.GetObject("IO.Inputs.IO01")
If Application.ESign(Tag.PathName, , "Value Change", _
Tag.Value, 1, User, Comment) Then
If Tag.WriteEx 1 Then
Application.TrackEvent _
"Tag IO.Inputs.IO01 changed to 1 " &_
"by the user" & User, Comment
End If
End If
End Sub

4.1.2.35 UserAdministration
UserAdministration()

This method opens a dialog box allowing to edit a list of E3 Server's users. The available
functions are:

· Display a list of all users

· Delete users (it is not possible to delete the current user)

· Add and edit users

82 V iew
· Edit user settings

· Change the user's password

· Change other user's data (login, name, etc.)

IMPORTANT: Only the Administrator has access to the UserAdministration method. The dialog
box for user configuration is only accessible to a user enabled as Administrator.

4.1.3 Properties
This section contains information about the properties of the Viewer object.

4.1.3.1 BlinkTime

Defines the time, in milliseconds, between each state change when an object must blink
(that is, each time some object has a link and the Blink option is checked). The default value of
this property is 200 ms.

NOTE: The minimum time of screen refreshing is 55 ms; therefore, if this property is set with a
time less than 55 ms, this configuration has no effect at all.

4.1.3.2 CacheEnable
Keeps in memory the Screens already opened instantiated on the Viewer, allowing a quick
switching among them. If this property is enabled, then the Screen cache is also enabled.

4.1.3.3 Caption

Determines the name of the application which is using Viewer. The default value of this
property is empty.

4.1.3.4 CenterWindow
When enabled, determines that the viewing window of the Viewer must start centered.
Otherwise, the default setting will be used. The default value of this property is True.

4.1.3.5 CloseButton

If this option is enabled, the Close button is enabled on the Viewer, and it can be used.
Otherwise, this button does not display on the window. The default value of this property is
True.

V iew 83
4.1.3.6 CommErrorBkColor

This property is used for defining the background color of the Setpoint when a Link or
Connection fails. The default value of this property is red (RGB(255, 0, 0)). Also check the
EnableCommError property.

4.1.3.7 CommErrorText

This property is used for defining the alert message when a Link or Connection fails. The
default value of this property is "???". Also check the EnableCommError property.

4.1.3.8 CommErrorTextColor

This property is used for defining the text color of the Setpoint when a Link or Connection
fails. The default value of this property is yellow (RGB(255, 255, 0)). Also check the
EnableCommError property.

4.1.3.9 DisableTaskSwitching

If it is set to True, disables window switching on the Viewer. Otherwise, window switching is
enabled. The default value of this property is False. This property can be changed at run time
by calling the SetDisableTaskSwitching method.

4.1.3.10 EnableCommError
Enables or disables viewing communication errors. For example, if there is a Setpoint on the
Screen which is linked to an I/O Tag, and the communication between E3 and this Tag fails, the
text configured in the CommErrorText property is displayed in the Setpoint, with the color
configured in the CommErrorTextColor property, and the background color of the Setpoint
defined on the CommErrorBkColor property. The default value of this property is True.

4.1.3.11 EnableHeartbeat
Enables or disables sending a heartbeat (message sent on fixed intervals, indicating that E3
Server is active) between Viewer and server. In case the Viewer stops receiving heartbeat
messages, this means that some problem occurred, therefore connection must be aborted.
The default value of this property is False.

4.1.3.12 EnableInactivity
Enables or disables checking the user inactivity period. For more information, see the
OnInactive event of the Viewer object. The default value of this property is False.

84 V iew
4.1.3.13 EnableZoomMenu

If it is set to True, enables displaying a screen zoom configuration menu using the right
mouse button at run time, except when some script is configured with a different information
on the MouseDown or MouseUp events. Otherwise, the menu will not be displayed. The
default value of this property is True.

4.1.3.14 HeartbeatPeriodMs

Indicates the interval (in milliseconds) between heartbeat messages sent by E3 Server. The
heartbeat message is always sent when the server remains the period indicated by this
property without sending messages for the Viewer. The default value of this property is 2000
(two seconds).

4.1.3.15 HeartbeatTimeoutMs

Indicates the time, in milliseconds, that the Viewer waits without receiving messages from
E3 Server. If this time passes, and no message is received, the Viewer assumes that the
connection was lost, and starts the reconnection process. This time must be greater than the
time set in the HeartbeatPeriodMs property, preferrably greater than the double. The default
value of this property is 5000 (five seconds).

4.1.3.16 InactivityTime

Defines the maximum waiting time for a mouse or keyboard event before the inactivity
period, in minutes. For more information, see the OnInactive event of the Viewer object. The
default value of this property is 5 (five) minutes. Example:
Sub CommandButton3_Click()
MsgBox "The application will remain inactive for " & _
Application.InactivityTime & " minute(s)."
End Sub

4.1.3.17 InitialScreen

Indicates the initial Screen or Frame which is displayed when the Viewer is called. Using
the WindowStyle property, it is possible to determine if the window must start maximized,
windowed, or minimized. The default value of this property is "InitialScreen".

4.1.3.18 IsPlaybackMode
If True, indicates that the Viewer is running inside an E3Playback object, in playback mode.
This is a read-only property and it is only available at run time.

V iew 85
4.1.3.19 IsReadOnly

If set to True, indicates that the Viewer is in Read-Only mode (restricted access).

4.1.3.20 LoginRetries

Specifies the number of login retries of the Viewer, that is, how many times the login dialog
box will be displayed besides the first time. The default value of this property is 2.

4.1.3.21 MaximizeButton
If this option is enabled (True), the Maximize button is enabled on the Viewer, and this
button can be used. Otherwise, this button does not display on the window. The default value
of this property is True.

4.1.3.22 MinimizeButton
If this options is enabled (True), the Minimize button is enabled on the Viewer, and this
button can be used. Otherwise, this button does not display on the window. The default value
of this property is True.

4.1.3.23 Params

This property is a vector of key-value pairs, which returns parameters passed to the Viewer
through the command line option -params. All values are returned as Strings. For example, if
the Viewer command line contains the following parameters:
Viewer -params Language=ENU

You may use the following code to check what is Viewer's startup language.
Sub InitialScreen_OnStartRunning()
Select Case Application.Params("Language")
Case "ENU"
Item("Text1").Value = "English"
Case Else
Item("Text1").Value = "Unrecognized language"
End Select
End Sub

NOTE: The key is not case sensitive (you may use "Language" or "language"), but returned
values, specially if used with a Select command, are case sensitive.

86 V iew
4.1.3.24 ReconnectDialogDelaySec

Indicates the number of seconds the Viewer will wait during a possible reconnection to the
server before displaying a message warning the user about this action (this property does not
affect the first connection). If it is equal to 0, the reconnection message is always displayed. To
avoid displaying this message, it is advisable to put a very large number (1 billion, for
example).

NOTE: When reconnection occurs silently, all windows from the active Viewer are disabled
and an hourglass is displayed indicating that the application is unavailable. During
reconnection time, the user is not allowed to cancel the process.

4.1.3.25 RenderQuality

Controls the drawing quality of all Screens, only if the value of RenderQuality property of
the Screens is equal to 0 - rqDefault. Possible values for this property are the following:

· 0 - rqDefault: Uses a normal quality mode, known as GDI (Graphics Device Interface).
Corresponds to item Use Default from Viewer's contextual menu Quality (all screens), at run
time. This is the default value for applications created on versions prior to 4.0

· 1 - rqNormal: Forces a normal quality mode (GDI) for drawing all Screens. Corresponds to
item Force Normal Quality from Viewer's contextual menu Quality (all screens), at run time

· 2 - rqHighQuality: Forces a high quality mode (GDI+) for drawing all Screens. Corresponds to
item Force High Quality from Viewer's contextual menu Quality (all screens), at run time. This
is the default value for applications starting at version 4.0

The following figure displays the Viewer's contextual menu at run time, with the respective
configuration options for this property:

V iew 87
 Viewer's contextual menu at run time

4.1.3.26 ShowKeyPadOnEdit
This property automatically enables displaying the Elipse KeyPad when a Screen object,
which allows editing, gets the focus.

4.1.3.27 TargetDPIX

Defines the dots per inch value, horizontally, of the destination computer's monitor. The
default value of this property is -1, which means that the current's computer value is assumed.

4.1.3.28 TargetDPIY

Defines the dots per inch value, vertically, of the destination computer's monitor. The
default value of this property is -1, which means that the current's computer value is assumed.

4.1.3.29 TargetMarginX

Defines the number of pixels that must be discounted of the screen horizontal resolution
(the Viewer working area). The default value of this property is -1, which assumes the Viewer
window configuration (with or without a title bar, with or without border) together with the
current computer configuration (border width and title bar defined by Windows).

88 V iew
4.1.3.30 TargetMarginY

Defines the number of pixels that must be discounted of the screen vertical resolution (the
Viewer working area). The default value of this property is -1, which assumes the Viewer
window configuration (with or without a title bar, with or without border) together with the
current computer configuration (border width and title bar defined by Windows)

4.1.3.31 TargetResolutionX

Defines the horizontal resolution of the screen which this application is meant to (in pixels).
The default value of this property is -1, which assumes the current computer resolution.

4.1.3.32 TargetResolutionY

Defines the vertical resolution of the screen which this application is meant to (in pixels).
The default value of this property is -1, which assumes the current computer resolution.

4.1.3.33 TitleBar

If this option is enabled (True), the Viewer title bar is displayed, according to the
specifications of the Caption property. Otherwise, it is hidden. The default value of this
property is True.

4.1.3.34 User

Contains the name of the user using the Viewer. This is a read-only property.

4.1.3.35 ViewerLanguageId

Returns the language code of the Viewer or E3 Viewer running. The available values of this
property are described on the next table. This is a read-only property and it is only available at
run time.

Available options for ViewerLanguageId

DECIMAL HEXADECIMAL LANGUAGE

4 0x0004 Chinese Simplified

1031 0x0407 German

1033 0x0409 English (US)

1034 0x040A Spanish

1046 0x0416 Brazilian Portuguese

V iew 89
NOTE: This property DOES NOT correspond to the Windows installation language neither the
language configured in the Windows Regional and Language Options (Clock, Language and
Region in Windows 7) control panel.

4.1.3.36 WindowBorder

Enables or disables a border around the Viewer window. The default value of this property
is true. This is a read-write property, but changing its value at run time does not change the
settings of an already opened Viewer, only for windows opened using the Viewer settings.

4.1.3.37 WindowHeight

Determines the height of the Viewer window, in pixels. The default value of this property is
300.

4.1.3.38 WindowMovable

Indicates whether the window can be moved. The default value of this property is true. This
is a read-write property, but changing its value at run time does not change the settings of an
already opened Viewer, only for windows opened using the Viewer settings.

4.1.3.39 WindowResizable
Indicates whether the window can be resized. This property is effective only if the
WindowBorder property is true. The default value of this property is true. This is a read-write
property, but changing its value at run time does not change the settings of an already opened
Viewer, only for windows opened using the Viewer settings.

4.1.3.40 WindowSmallTitle
Indicates whether the Viewer window should have a small titlebar. This property is
effective only if the TitleBar property is true. The default value of this property is false. This is a
read-write property, but changing its value at run time does not change the settings of an
already opened Viewer, only for windows opened using the Viewer settings.

4.1.3.41 WindowStayOnTop
Indicates whether the Viewer window must always be on top of other windows. The default
value of this property is false. This is a read-write property, but changing its value at run time
does not change the settings of an already opened Viewer, only for windows opened using the
Viewer settings.

90 V iew
4.1.3.42 WindowStyle

Defines the initial style of the Viewer window. The available options are:

· 0 - Maximized: starts Viewer maximized

· 1 - Windowed: starts Viewer windowed

· 2 - Minimized: starts Viewer minimized

4.1.3.43 WindowWidth

Determines the width of the Viewer window, in pixels. The default value of this property is
400.

4.2 Frames and Splitters

This section contains information about methods and properties of Frames and Splitters. The
Splitter object does not have events associated to it and the Frame object does not have
events nor methods associated to it.

4.2.1 Splitter Methods

This section contains information about the methods of the Splitter object.

4.2.1.1 BringToFront
BringToFront()

Brings to front a Splitter which is hidden or under another one. Example:

Sub Button1_Click()
Application.GetFrame("Test").BringToFront()
End Sub

4.2.1.2 CaptureScreen
CaptureScreen(Filename)

Captures the content of a Splitter, saving it on the file pointed by Filename, in BMP format.
Example:
Sub CommandButton1_Click()
' When clicking the button, copies the content
' of the splitter to Frame.bmp file.
Screen.Frame.CaptureScreen ("c:\temp\frame.bmp")
End Sub

V iew 91
4.2.1.3 Close
Close(Code)

Use the Close method to close the Frame window. The Code parameter has the return value for
the DoModal method, if this window has been called by this method. Example:
Sub CloseButton_Click()
' When clicking the button, closes the window.
Screen.Close(0)
End Sub

4.2.1.4 FlashWindow
FlashWindow(Number, Time)

This method makes the Viewer icon on the Windows Task Bar start flashing. The Number
parameter determines the number of times the Task Bar should flash and Time determines the
time (in milliseconds) between flashes. Example:
Sub Text1_Click()
Set frame = Application.GetFrame("_top")
frame.FlashWindow 50, 500
End Sub

4.2.1.5 MaximizeFrame
MaximizeFrame()

Maximizes a Frame or modal Screen. Example:

Sub CommandButton4_Click()
Application.GetFrame("Other").MaximizeFrame()
End Sub

4.2.1.6 MinimizeFrame
MinimizeFrame()

Minimizes a Frame or modal Screen. Example:

Sub CommandButton4_Click()
Application.GetFrame("Other").MinimizeFrame()
End Sub

4.2.1.7 MoveFrame
MoveFrame([PosX], [PosY], [SizeX], [SizeY])

Moves and resizes a Frame to a specific coordinate and size. The PosX and PosY parameters
inform the new position, in pixels, relative to the left and top, respectively. The SizeX and SizeY
parameters inform new size and height,respectively, in pixels or HIMETRIC. All parameters are
optional. Example:
Sub screen2_OnPreShow(vArg)
' When the Screen is opened on Test frame, changes the position
' and the frame size
Application.GetFrame("Test").MoveFrame 100, 100, 200, 200
End Sub

92 V iew
NOTE: The size values of this method can be informed as numbers or Strings. In case of
numbers, they are considered pixels. In case of Strings, if they are followed by the "hm" unit,
they will be interpreted as HIMETRIC. Any other case is considered in pixels.

4.2.1.8 OpenScreen
OpenScreen(ScreenName, Arg)

The OpenScreen method opens a Screen inside the Splitter. The ScreenName parameter
determines the name of the Screen to be opened. It is also possible to specify a zoom
percentage of the Screen and to enable the scrollbar using the "?" key like the following
template:
<screen-name>?<zoom>?<enable-scroll>

Where <screen-name> is the name of the Screen to be opened; <zoom> is the zoom
percentage and <enable-scroll> enables or disables scrolling.

The zoom percentage of the Screen may have the following values:

· 1: the whole page

· 2: the Screen width occupies 100% of the Splitter width, with proportional height

· 3: the Screen height occupies 100% of the Splitter height, with proportional width

· 4: The Screen completely fills the splitter

· 5 to 100: it is the equivalent of the zoom percentage of the Screen itself

Enabling scroll may have the following values:

· 0: disables scrolling

· 1: enables scrolling

The Arg parameter allows passing the specified value to the Screen by using the OnPreShow
event. Example:
Sub Button1_Click()
' When clicking the button opens Screen2 on Test frame
' and passes 1 to be used in the OnPreShow event
Application.GetFrame("Test")._
OpenScreen "Screen2?100?0", "This is a test."
End Sub
Sub Screen2_OnPreShow(vArg)
' The message box will display the sentence
' "This is a test."
MsgBox vArg
End Sub

V iew 93
4.2.1.9 Refresh
Refresh(Force)

The Refresh method allows forcing redrawn of a Screen or Splitter content. It should be used in
Viewer scripts with massive processing (loops, for example), or in method calls which demand
a long time and also demand visual indication of the progress of the process to the user.

Due to the general redrawn being a heavy operation, the default version of the Refresh
method (without parameters) is optimized in order to ignore redrawn request from E3. This
standard behavior is ideal for loop progress indication, where a lot of redrawns are made. The
Force parameter disables this optimization, making sure that for each call to Refresh method,
a redrawn is made. However, when using this option, the Refresh method cannot be called
repeatedly, as inside a loop, for example. Example:
Sub CommandButton1_Click()
' Draws a progress bar of an operation
Screen.Item("Rectangle2")_
.HorizontalPercentFill = (i / 30) * 100
Frame.Refresh True
' <-- some lengthy operation -->
i = i + 1
Wend
End Sub

4.2.1.10 RestoreFrame
RestoreFrame()

Allows restoring the Frame window to its original size. Example:

Sub CommandButton1_Click()
Application.GetFrame("Other").RestoreFrame()
End Sub

4.2.1.11 SetDisableTaskSwitching
SetDisableTaskSwitching(Disable)

Enables or disables window switching. The Disable parameter is a boolean value that
indicates whether the window switching is enabled or not. This method updates the
DisableTaskSwitching property of the Viewer object.

NOTES:
· If more than one Viewer instance is running, and at least one of these instances use the
SetDisableTaskSwitching method, that change affects all windows
· In case it is necessary to change the window title or style, the SetFrameOptions method
must be used after calling the SetDisableTaskSwitching method

94 V iew
4.2.1.12 SetForegroundWnd
SetForegroundWnd()

The SetForegroundWnd method activates and focus the Viewer window. This method is useful
for grabbing the operator attention about some event, when the Viewer window is hidden or
minimized. Example:
Sub CommandButton1_Click()
Application.GetFrame("Other").SetForegroundWnd()
End Sub

4.2.1.13 SetFrameOptions
SetFrameOptions(Title, Flags)

Used to configure the Frame title on the window and the window style. The Title parameter is
a String which contains the window title. This text is displayed if the Caption property of the
Screen is empty.

The Flags parameters specifies the window style. If this parameter is omitted, the default
value is -1. This value is used to keep the previous configuration of the window. When this
value is not -1, you can change the window style by specifying a sum of values of the following
combinations:

Possible combinations for Flags parameter

VALUE DESCRIPTION
1 Enables the window title bar.

2 Enables the Close button on the window.

4 Enables the Minimize button on the window.

8 Enables the Maximize button on the window.

16 Enables the window border.

32 Specifies that the window can be resized. For

this, the window must have a border.

64 Specifies that the window can be moved.

256 Specifies that the window will stay on top of

the Screen.

512 Specifies that the window will be configured

as a Tool Bar style.

1024 Disables object buttons.

2048 Centers the window.

V iew 95
Example:
Sub Screen_OnPreShow()
Frame.SetFrameOptions("Alarm Screen", 114)
End Sub

In the previous example, the 114 (2 + 16 + 32 + 64) value indicates that the window has a Close
button enabled (2), a border (16), can be resized (32), and can be moved (64). The window title
is "Alarm Screen".

In the Open Screen and Open Modal Screen picks it is also possible to configure the window
style during editing, using the Window Style dialog box. For more information see the topic
Picks.

NOTE: the SetFrameOptions method must be used after calling the SetDisableTaskSwitching
method in case there is a need to change the window title or style.

4.2.2 Splitter Properties

This section contains information about the properties of the Splitter object.

4.2.2.1 IsHTML
The IsHTML property returns True if the Splitter contains HTML code inserted into the
Frame. Otherwise, returns False.

4.2.2.2 SplitBorder
Enables or disables the Splitter border, and determines if the border between main and
remaining Splitters must be displayed at run time. This property has no effect on the
remaining Splitter. The default value of this property is True.

4.2.2.3 SplitDockPosition

Indicates the Splitter position on the Screen. The available options are:

Available options for SplitDockPosition

OPTION DESCRIPTION
0 - dockRemaining Places the Splitter as remaining, that is, it
occupies the remaining space in the
horizontal or vertical Splitter.

96 V iew
 OPTION DESCRIPTION
1 - dockTop Places the Splitter as main, above the
remaining.

2 - dockBottom Places the Splitter as main, below the

remaining.

3 - dockLeft Places the Splitter as main, on the left of the

remaining.

4 - dockRight Places the Splitter as main, on the right of the

remaining.

4.2.2.4 SplitLink

The SplitLink property contains a link that should be displayed in the Splitter. It is possible
to specify a project Screen, an executable or an Internet link. In case of Screens, it is possible
to specify a zoom percentage and enabling scroll bars using a "?" key, as in the template
<screen-name>?<zoom>?<scroll-bar>, where <screen-name> is the name of
the Screen to be opened; <zoom> is the zoom percentage and <scroll-bar> is 1 to
enable or 0 to disable. The <zoom> and <scroll-bar> properties are valid only if the
indicated link is a Screen. Otherwise, they will be ignored. If the <zoom> parameter is not
informed, assumes 100%. If the <scroll-bar> parameter is not informed, assumes 1, that
is, enabled. Example:
Sub CommandButton1_Click()
Application.GetFrame("Splitter1").SplitLink = "Screen1?10?1"
End Sub

4.2.2.5 SplitResizable
Determines if the main Splitter can be resized at run time. This property has no effect on the
remaining Splitter. The default value of this property is True.

4.2.2.6 SplitValue

The SplitValue property determines the value to be set to the Frame Splitter, which might
be % (percentage), hm (HIMETRIC), or px (pixels). If the unit is omitted, it will be considered
HIMETRIC. Exemplo:
Sub Splitter1_Click()
SplitValue = 10
End Sub

4.2.3 Frame Properties

This section contains information about the properties of the Frame object.

V iew 97
4.2.3.1 Caption

The Caption property defines the Frame title to be displayed on the Viewer title bar.

4.3 Screens and Screen Objects

This section contains information about events, methods, and properties of Screens and
Screen Objects.

4.3.1 Screen
This section contains information about events, methods, and properties of the Screen object.

4.3.1.1 Events
This section contains information about the events of the Screen object.

4.3.1.1.1 Click
Click()

It occurs when the left mouse button is pressed over the screen. This event will not occur if the
screen is not visible or its Enabled property is set to False. The screen visibility depends on
three factors: Visible property set to True; parent object visible and Layer property of the
object on the Screen layer. Example:
Sub Screen_Click()
' Displays a message box when
' the user clicks the screen
MsgBox "You clicked the screen."
End Sub

4.3.1.1.2 DbClick
DbClick()

Occurs when there is a left mouse button double-click over the screen. This event will not
occur if the object is not visible or its Enabled property is set to False. The object's visibility
depends on three factors: Visible property set to True; parent object visible and object's Layer
property on the Screen layer. Example:
Sub Screen_DbClick()
' Displays a message box when
' the user double-clicks the screen
MsgBox "You double-clicked the screen."
End Sub

98 V iew
4.3.1.1.3 KeyDown
KeyDown(KeyCode, Shift)

It occurs when a key is pressed, regardless of the Screen focus.

Variables of the KeyDown event

NAME DESCRIPTION
KeyCode Integer identifying the ASCII character of the
pressed key.

Shift Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

Example:
Sub Screen1_KeyDown(KeyCode, Shift)
' Displays a message box when
' the user presses a key
MsgBox "Key code: " & KeyCode
End Sub

4.3.1.1.4 KeyUp
KeyUp(KeyCode, Shift)

It occurs when a key is released, regardless of the Screen focus.

Variables of the KeyUp event

NAME DESCRIPTION
KeyCode Integer identifying the ASCII character of the
pressed key.

V iew 99
 NAME DESCRIPTION
Shift Displays the pressed key along with the
mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

Example:
Sub Screen1_KeyUp(KeyCode, Shift)
' Displays a message box when the user
' releases a key
MsgBox "Key code: " & KeyCode
End Sub

4.3.1.1.5 MouseDown
MouseDown(Button, ShiftState, MouseX, MouseY)

It occurs when any mouse button is pressed over the Screen. Use the MouseDown event to
determine specific actions when the user clicks the Screen.

Variables of the MouseDown event

NAME DESCRIPTION
Button Displays the pressed mouse button:

· 1: Left mouse button pressed

· 2: Right mouse button pressed

ShiftState Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

MouseX Displays the X coordinate where the mouse

was clicked on the Screen.

MouseY Displays the Y coordinate where the mouse

was clicked on the Screen.

100 V iew
Example:
Sub InitialScreen_MouseDown(Button, ShiftState, MouseX, MouseY)
' Quits the application when a mouse click occurs
' on the InitialScreen object.
Application.Exit()
End Sub

4.3.1.1.6 MouseUp
MouseUp(Button, ShiftState, MouseX, MouseY)

It occurs when a previously clicked mouse button is released. Use the MouseUp event to
determine specific action to be triggered only when a mouse button is released.

Variables of the MouseUp event

NAME DESCRIPTION
Button Displays the pressed mouse button:

· 1: Left mouse button pressed

· 2: Right mouse button pressed

ShiftState Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

MouseX Displays the X coordinate where the mouse

was clicked on the Screen.

MouseY Displays the Y coordinate where the mouse

was clicked on the Screen.

Example:
Sub InitialScreen_MouseUp(Button, ShiftState, MouseX, MouseY)
' Quits the application only when the user releases the mouse button.
Application.Exit()
End Sub

V iew 101
4.3.1.1.7 OnHide
OnHide()

It occurs when the Screen is about to be closed Use the OnHide event when you need to
perform any operations before the Screen object to be closed. This event may occur on several
situations:

· When the Screen is replaced by another one using the OpenScreen method

· When the user closes the window where the Screen is

· When the Close is called from the Screen object

· When the Viewer is closed or quit

Example:
Sub InitialScreen_OnHide()
Application.Exit()
End Sub

4.3.1.1.8 OnPreShow
OnPreShow(Arg)

It occurs before the Screen is displayed. The Arg variable receives the content of the Arg
parameter of the OpenScreen method, which generates this event. After that, the OnShow
event is generated. Example:
Sub Screen1_OnPreShow(Arg)
' The title of Screen1 to be displayed
' was passed as a parameter when calling the OpenScreen
' method that generated the event.
Caption = Arg
End Sub

4.3.1.1.9 OnShow
OnShow()

It occurs in the very moment when a Screen is displayed. Use the OnPreShow event to perform
any operation before this Screen is displayed. Example:
Sub MainScreen_OnShow()
MsgBox "Welcome to the system!"
End Sub

4.3.1.2 Methods
This section contains information about the methods of the Screen object.

102 V iew
4.3.1.2.1 Close
Close(Code)

Use the Close method to close the Screen. This method generates the OnHide event before
being performed. The Code parameter will contain the return value for the DoModal method, if
the Screen is called by this method. Example:
Sub CloseButton_Click()
' When CloseButton is clicked, closes the window
Screen.Close(0)
End Sub

4.3.1.2.2 FromPixelX
FromPixelX(XPixel)

Converts the X coordinate of the Screen, indicated by the XPixel parameter, from pixels to
Himetric. This method is complementary to the ToPixelX method.

4.3.1.2.3 FromPixelY
FromPixelY(YPixel)

Converts the Y coordinate of the Screen, indicated by the YPixel parameter, from pixels to
Himetric. This method is complementary to the ToPixelY method.

4.3.1.2.4 ToPixelX
ToPixelX(XHimetric)
Converts the X coordinate of the Screen, indicated by the XHimetric parameter, from Himetric
to pixels. This method is complementary to the FromPixelX method.

4.3.1.2.5 ToPixelY
ToPixelY(YHimetric)
Converts the Y coordinate of the Screen, indicated by the YHimetric parameter, from Himetric
to pixels. This method is complementary to the FromPixelY method.

4.3.1.3 Properties
This section contains information about the properties of the Screen object.

NOTE: E3 uses the HIMETRIC system to define coordinates and widths. In this system, each
logical unit is the equivalent of a thousandth of a centimeter, that is, every 1,000 units
correspond to one centimeter. Thus, this is the standard adopted in the description of E3
properties, when applicable.

V iew 103
4.3.1.3.1 BackgroundColor

Specifies the filling color of the Screen background. In scripts, use the VBScript RGB method
to gather the color to be associated to this property. The default value of this property is gray (
RGB(192, 192, 192)).

4.3.1.3.2 Caption

The Caption property defines the title of the Screen to be displayed on the title bar of the
Viewer.

4.3.1.3.3 FillStyle

This property specifies the filling style of the Screen and Screen objects. The next table
contains valid values for this property.

Available options for FillStyle

OPTION DESCRIPTION
0 - Solid Filling is solid (default).

1 - Hollow No filling. This value is not available for the

Screen object.

2 - Horizontal Filling has horizontal stripes.

3 - Vertical Filling has vertical stripes.

4 - Downward Filling has down stripes from left to right in a

45 degrees angle.

5 - Upward Filling has up stripes from left to right in a 45

degrees angle.

6 - Cross Filling has horizontal and vertical stripes.

7 - DiagonalCross Filling has diagonal stripes from left to right

in a 45 degrees angle.

8 - Gradient Filling has a gradient using ForegroundColor

as well as BackgroundColor. The effect will be
defined by the GradientStyleproperty.

9 - SemiTransparent Leaves the object translucent. This value is

not available for the Screen object.

104 V iew
 OPTION DESCRIPTION
10 - MouseArea Filling is empty, but the object still responds
to events (default). This value is not available
for the Screen object.

11 - Background Fills the Screen with background color.

12 - Picture Fills the Screen with the picture selected on

PictureFile property. This value is only
available for the Screen object.

NOTE: The FillStyle property is not available for the Picture object.

4.3.1.3.4 ForegroundColor

Specifies the foreground color of the Screen. In scripts, use the RGB method to gather the
color to be associated to this property. The default value of this property is black (RGB(0, 0, 0)).
Applications previous to the introduction of this property will have both ForegroundColor and
BackgroundColor properties set to the color stored on the BackgroundColor property and the
filling style set to 11 - Background, which paints the whole Screen with the background color
(old behavior, before creating styles). Example:
Sub Screen1_Click()
' Changes the foreground color to blue
ForegroundColor = RGB(0, 0, 255)
End Sub

4.3.1.3.5 GradientStyle

This property specifies the gradient filling style of the Screen. This property will only be
used when the value of the FillStyle property is set to 8 (Gradient). The gradients consider the
color changing as starting at ForegroundColor and ending at BackgroundColor.

Available options for GradientStyle

OPTION DESCRIPTION
0 - LeftToRight Vertical gradient, from left to right.

1 - RightToLeft Vertical gradient, from right to left.

2 - VerFromCenter Vertical gradient from center to border.

3 - VerToCenter Vertical gradient from border to center.

4 - BottomUp Horizontal gradient from bottom to top.

5 - TopDown Horizontal gradient from top to bottom.

V iew 105
 OPTION DESCRIPTION
6 - HorzFromCenter Horizontal gradient from center to border.

7 - HorzToCenter Horizontal gradient from border to center.

8 - DiagUpRight Diagonal gradient to the top with foreground

color on the right (default).

9 - DiagUpLeft Diagonal gradient to the top with foreground

color on the left.

10 - DiagUpFromCenter Diagonal gradient to the top from center to

border.

11 - DiagUpToCenter Diagonal gradient to the top from border to

center.

12 - DiagDownLeft Diagonal gradient to the bottom with

foreground color on the left.

13 - DiagDownRight Diagonal gradient to the bottom with

foregound color on the right.

14 - DiagDownFromCenter Diagonal gradient to the bottom from center

to border.

15 - DiagDownToCenter Diagonal gradient to the bottom from border

to center.

16 - SpotSouthEast Gradient with foreground color from right

lower corner.

17 - SpotSouthWest Gradient with foreground color from left

lower corner.

18 - SpotNorthWest Gradient with foreground color from left

upper corner.

19 - SpotNorthEast Gradient with foreground color from right

upper corner.

20 - SpotFromCenter Gradient with background color from center

to border.

21 - SpotToCenter Gradient with background color from border

to center.

106 V iew
4.3.1.3.6 Layer

This property defines in which layers the object should appear. Its value represents a 32 bit
mask, one bit for each layer. Therefore, up to 32 layers can defined. Thus, objects may be
logically grouped and displayed or hidden only by modifying the Layer property mask..

Available option in the Properties List

Example:
Sub Screen1_Click()
Layer = 1
End Sub

NOTE: The visibility of the object depends on three factors: the Visible property must be set to
True; the parent object must be visible and the Layer property of the object must be enabled
for the Screen.

4.3.1.3.7 PictureFile

Contains the picture filename which will be used as the Screen background. It can be any
format supported by E3 on DrawPicture object (*.bmp, *.gif, *.jpg, *.cur, *.ico, *.emf, *.wmf).
The default value of this property is an empty String. This property is only valid if the FillStyle
property is set to 12 - Picture.

V iew 107
4.3.1.3.8 PicturePosition

Indicates the position of the selected picture on the PictureFile property of the Screen.
This property is only valid if the FillStyle property is set to 12 - Picture. The valid options are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - Center Picture with original size, centered on
Screen.

1 - Tile Picture with original size, repeated as many

times as needed to fill the Screen.

2 - Stretch Picture resized to fill the Screen.

3 - TopLeft Picture with original size, on the left upper

corner of the Screen.

4 - BottomLeft Picture with original size, on the left lower

corner of the Screen.

5 - BottomRight Picture with original size, on the right lower

corner of the Screen.

6 - TopRight Picture with original size, on the right upper

corner of the Screen.

4.3.1.3.9 RenderQuality

Controls the drawing quality of a Screen. Possible values for this property are the
following:

· 0 - rqDefault: This Screen's drawing quality uses the value defined on Viewer's
RenderQuality property. This is the default values of this property, even in application
created on versions prior to 4.0

· 1 - rqNormal: Forces a normal quality mode (GDI) when drawing this Screen

· 2 - rqHighQuality: Forces a high quality mode (GDI+) when drawing this Screen

The following figure displays a Screen's contextual menu at run time, with the respective
configuration options for this property:

108 V iew
 Screen's contextual menu at run time

4.3.2 Screen Objects

This section contains information about events, methods, and properties of Screen Objects.

4.3.2.1 Common Events

This section contains information about common events of all Screen Objects.

4.3.2.1.1 Click
Click()

It occurs when the left mouse button is pressed over an object. This event will not occur if the
object is not visible or if its Enabled is set to False. The visibility of an object depends on three
factors: Visible property set to True; parent object visible and the Layer property of the object
present on the Screen layer. Example:
Sub Button_Click()
' Displays a message box when
' the user clicks an object
MsgBox "You clicked an object."
End Sub

V iew 109
4.3.2.1.2 DbClick
DbClick()

It occurs when there is a double click, that is, the left mouse button is quickly pressed twice
over an object. This event will not occur if the object is not visible or if its Enabled property is
set to False. The visibility of the object depends on three factors: Visible property set to True;
parent object visible and Layer property of the object present on Screen layer. Example:
Sub Button_DbClick()
' Displays a message box when
' the user performs a double-click over the object
MsgBox "You clicked twice over the object."
End Sub

4.3.2.1.3 KeyDown
KeyDown(KeyCode, Shift)

It occurs when a key is pressed and the object has the focus of the keyboard. Notice that this
event will not be generated if the object is not enabled (Enabled property set to False) or if this
object does not have keyboard focus.

Variables of the KeyDown event

NAME DESCRIPTION
KeyCode Integer identifying the ASCII character of the
pressed key.

Shift Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

Example:
Sub Button_KeyDown(KeyCode, Shift)
' Displays a message box when
' the user presses a key
MsgBox "Key code: " & KeyCode
End Sub

110 V iew
4.3.2.1.4 KeyUp
KeyUp(KeyCode, Shift)

It occurs when a key is released and the object has keyboard focus. Notice that this event will
not be generated if the object is not enabled (Enabled property set to False) or if this object
does not have keyboard focus.

Variables of the KeyUp event

NAME DESCRIPTION
KeyCode Integer identifying the ASCII character of the
pressed key.

Shift Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

Example:
Sub Button_KeyUp(KeyCode, Shift)
' Displays a message box when the user
' releases a key
MsgBox "Key code: " & KeyCode
End Sub

4.3.2.1.5 MouseDown
MouseDown(Button, ShiftState, MouseX, MouseY)

It occurs when any mouse button is pressed over the object.

Variables of the MouseDown event

NAME DESCRIPTION
Button Displays the pressed mouse button:

· 1: Left mouse button pressed

· 2: Right mouse button pressed

V iew 111
 NAME DESCRIPTION
ShiftState Displays the key pressed along with the
mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

MouseX Displays the X coordinate where the mouse

was clicked on the Screen.

MouseY Displays the Y coordinate where the mouse

was clicked on the Screen.

Example:
' Quits the application when there is a
' mouse click on the InitialScreen object.
Sub InitialScreen_MouseDown(Button, ShiftState, MouseX, MouseY)
Application.Exit()
End Sub

4.3.2.1.6 MouseUp
MouseUp(Button, ShiftState, MouseX, MouseY)

It occurs when any previously clicked mouse button is released over the object. Use the
MouseUp event to specify actions to be performed only when the mouse button is released.

Variables of the MouseUp event

NAME DESCRIPTION
Button Displays the pressed mouse button:

· 1: Left mouse button pressed

· 2: Right mouse button pressed

ShiftState Displays the pressed key along with the

mouse:

· 4: SHIFT key

· 8: CTRL key

· 12: CTRL + SHIFT keys

112 V iew
 NAME DESCRIPTION
MouseX Displays the X coordinate where the mouse
was clicked on the Screen.

MouseY Displays the Y coordinate where the mouse

was clicked on the Screen.

Example:
' Quits the application only when the user releases the mouse button
' after clicking Rectangle1 object.
Sub Rectangle1_MouseUp(Button, ShiftState, MouseX, MouseY)
Application.Exit()
End Sub

4.3.2.2 Common Methods

This section contains information about common methods of all Screen Objects.

4.3.2.2.1 BringToFront
BringToFront()

Brings the object to the uppermost layer on the Screen, in front of all other objects. Example:
Sub Button1_Click()
' When clicking Button1, the system
' brings Rectangle1 to the front
Screen.Item("Rectangle1").BringToFront()
End Sub

4.3.2.2.2 SendToBack
SendToBack()

Sends the object to the lowermost layer on the Screen, at the back of all other objects.
Example:
Sub Button2_Click()
' When clicking Button2, the system
' sends Rectangle1 to the back
Screen.Item("Rectangle1").SendToBack()
End Sub

4.3.2.2.3 SetFocus
SetFocus()

Use the SetFocus method to move mouse or keyboard focus to a specific object. Example:
Sub Screen1_OnShow()
' When opening the window, moves focus to Button1
Item("Button1").SetFocus()
End Sub

V iew 113
4.3.2.3 Common Properties
On this section there are all common properties of all Screen Objects. The next properties do
not apply to the following objects: ActiveX (MSForms), E3Chart, E3Browser, and E3Alarm. These
objects are treated later, on specific chapters.

NOTE 1: E3 uses the HIMETRIC system to define coordinates and widths. In this system, each
logical unit is the equivalent of a thousandth of a centimeter, that is, every 1,000 units
correspond to one centimeter. Thus, this is the standard adopted in the description of E3
properties, when applicable.

NOTE 2: The following properties are common to all previously cited objects, including Groups
of objects and Sliders.

4.3.2.3.1 Enabled

Enables or disables access via keyboard or mouse. This property only affects objects which
allows input via keyboard or mouse.

4.3.2.3.2 Frame

Returns the parent frame of the object. This property is only accessible at run time.

4.3.2.3.3 HasFocus

This property determines that the selected object has focus. This property is only
accessible at run time.

4.3.2.3.4 Height

Determines the height of the object.

4.3.2.3.5 MouseOver

Tells whether mouse pointer is on Screen. If True, MouseOver is enabled. Otherwise, it is

not. This property is only available at run time. Default value is False.

114 V iew
4.3.2.3.6 MouseOverChild

Tells whether mouse pointer is over one of the objects inserted on the Screen. If True,
MouseOverChild is enabled. Otherwise, it is not. This property is only available at run time.
Default value is False.

4.3.2.3.7 Screen

Returns the parent Screen of the object. This property is only accessible at run time.

4.3.2.3.8 TabStop

This property determines how TAB key is used on the system. If it is True, the key can be
used, otherwise it cannot be used.

4.3.2.3.9 Tip

The Tip property displays a popup text when mouse is over an object at run time. Example:
Sub RoundRect1_MouseUp(nButton, nShiftState, x, y)
Tip = "This is a test!"
End Sub

4.3.2.3.10 Visible

Defines the object visibility. If True, the object is visible, as long as the following factors are
also present: the parent object of this object must be visible, and the Layer property of this
object must also be available on the Screen layervisible object's parent-object, and object's
Layer property present on Screen layer.

4.3.2.3.11 Width

Determines the width of the object, in Himetric units.

4.3.2.3.12 X

The X property defines the left horizontal coordinate, in Himetric units, of the object.

4.3.2.3.13 Y

The Y property defines the upper vertical coordinate, in Himetric units, of the object.

V iew 115
4.3.2.3.14 Angle

The Angle property defines the rotation angle in degrees, counter clockwise, that the object
should be rotated. This property also applies to children objects of this one, respecting
rotation limitations of each child object. The object rotates according to its center, which can
be edited during the rotation operation. The default value of this property is 0 (no rotation).

4.3.2.3.15 BackgroundColor

This property specifies the background color of the object. This color is used when the
BackgroundStyle property is configured to 1 (opaque) and one of the VerticalPercentFill or
HorizontalPercentFill properties has a value different from 100. Another use of this color is
when the FillStyle property is configured with values between 2 and 8. This makes the
remaining area use the background color for filling. In scripts, use the RGB function of VBScript
to create the color associated to this property. The default value of this property is gray (RGB
(192, 192, 192)).

4.3.2.3.16 BackgroundStyle

This property specifies the filling mode of the object background. This property enables
using the VerticalPercentFill and HorizontalPercentFill properties with values different from
100 and also set the FillStyle property with values between 2 and 8. This makes the remaining
area use the background color configured in the BackgroundColor property for filling. The
following table contains valid values for the BackgroundStyle property.

Available options for BackgroundStyle

OPTION DESCRIPTION
0 - Transparent No background is drawn.

1 - Opaque If visible, the background is drawn.

4.3.2.3.17 BorderColor

Specifies the border or line color of this object. This property is only used when the
BorderStyle is not configured to 5 (null), where the object is borderless. In scripts, use the RGB
function of VBScript to create the color to be associated to this property. The default value of
this property is white (RGB(255, 255, 255)), except for the Display and SetPoint objects, which
default value is dark gray (RGB(128,128,128)).

116 V iew
4.3.2.3.18 BorderStyle

The BorderStyle property determines the border style to be applied to the object.

Available options for BorderStyle

OPTION DESCRIPTION
0 - Normal Applies a solid border to the object (default).

1 - Dash Applies a dashed border to the object.

2 - Dot Applies a dotted border to the object.

3 - Dashdot Applies a dash-dot border to the object.

4 - Dashdotdot Applies a dash-dot-dot border to the object.

5 - Null The object has no border.

4.3.2.3.19 BorderWidth

Defines the width, in Himetric units, of the object border or line. It is only used if the
BorderStyle property is not configured to 5 (null). The default value of this property is 0. This is
an exception in the measuring system of E3, because when its value is 0, the line or border
width is not defined in Himetric units, but in pixels. The BorderWidth property with a value
equal to 0 indicates a 1 pixel width.

4.3.2.3.20 Effect3D

Determines the application of a 3D effect in the selected object. The available options for
this property are described in the following table.

Available options for Effect3D

OPTION DESCRIPTION
0 - No3D Transparent (default).

1 - Raised Applies a raised 3D effect.

2 - Sunken Applies a sunken 3D effect.

V iew 117
4.3.2.3.21 Effect3D_X

Specifies the 3D effect dimension in the horizontal axis of the object (X axis). The default
value of this property is 30.

4.3.2.3.22 Effect3D_Y

Specifies a 3D effect dimension in the vertical axis of the object (Y axis). The default value of
this property is 30.

4.3.2.3.23 Effect3DColorBase

Determines the color of the 3D effect base in the object. The default value of this property
is black (RGB(0, 0, 0)).

4.3.2.3.24 Effect3DColorTop

Determines the color of the 3D effect top in the object. The default value of this property is
white (RGB(255, 255, 255)).

4.3.2.3.25 FillStyle

This property specifies the filling style of the object. The following table contains valid
values for the FillStyle property.

Available options for FillStyle

OPTION DESCRIPTION
0 - Solid Filling is solid (default).

1 - Hollow No filling.

2 - Horizontal Filling has horizontal stripes.

3 - Vertical Filling has vertical stripes.

4 - Downward Filling has stripes down from left to right in 45

degrees.

5 - Upward Filling has stripes up from left to right in 45

degrees.

6 - Cross Filling has horizontal and vertical stripes.

7 - DiagonalCross Filling has stripes up and down from left to

right in 45 degrees.

118 V iew
 8 - Gradient Filling has a gradient using both the
ForegroundColor and the BackgroundColor
property. The effect is determined by the
GradientStyle property.

9 - SemiTransparent The object remains semi transparent.

10 - MouseArea No filling, but the object remains event

responsive.

4.3.2.3.26 ForegroundColor

This property specifies the foreground color of the object. This color is used when the
FillStyle property is set to 0 (solid) or between 2 and 9. In scripts, use the RGB function of
VBScript to create the color to be associated to this property. The default value of this
property is blue (RGB(0, 0, 255)), except for the Display and SetPoint objects, which default
value is white (RGB(255, 255, 255)).

4.3.2.3.27 GradientStyle

This property specifies the gradient filling style of the object. This property is only used
when the value of the FillStyle property is set to 8 (Gradient). The gradients consider the
changing as setting off from the color configured in the ForegroundColor property and moving
towards the color configured in the BackgroundColor property.

Available options for GradientStyle

OPTION DESCRIPTION
0 - LeftToRight Vertical gradient from left to right.

1 - RightToLeft Vertical gradient from right to left.

2 - VerFromCenter Vertical gradient from center to border.

3 - VerToCenter Vertical gradient from border to center.

4 - BottomUp Horizontal gradient from bottom to top.

5 - TopDown Horizontal gradient from top to bottom.

6 - HorzFromCenter Gradient from center to border.

7 - HorzToCenter Gradient from border to center.

8 - DiagUpRight Diagonal gradient to top with foreground

color on the right (default).

V iew 119
9 - DiagUpLeft Diagonal gradient to top with foreground
color on the left.

10 - DiagUpFromCenter Diagonal gradient to top from center to

border.

11 - DiagUpToCenter Diagonal gradient to top from border to

center.

12 - DiagDownLeft Diagonal gradient to bottom with foreground

color on the left.

13 - DiagDownRight Diagonal gradient to bottom with foreground

color on the right.

14 - DiagDownFromCenter Diagonal gradient to bottom from center to

border.

15 - DiagDownToCenter Diagonal gradient to bottom from border to

center.

16 - SpotSouthEast Gradient with foreground color from lower

right corner.

17 - SpotSouthWest Gradient with foreground color from lower

left corner.

18 - SpotNorthWest Gradient with foreground color from upper

left corner.

19 - SpotNorthEast Gradient with foreground color from upper

right corner.

20 - SpotFromCenter Gradient with background color from center

to border.

21 - SpotToCenter Gradient with background color from border

to center.

IMPORTANT: A large amount of objects simultaneously displayed with a gradient may lead to
a poor performance when updating the screen. Using figures may solve this problem.

120 V iew
4.3.2.3.28 HorizontalFillStyle

Defines the horizontal filling of the object. This property works along with the
HorizontalPercentFill property, which informs the percentage of the object to be filled. These
two properties allows a simulation of a level filling in an object, as in a tank, for example.

Available options for HorizontalFillStyle

OPTION DESCRIPTION
0 - FillLeftToRight The filling percentage is from left to right
(default).

1 - FillRightToLeft The filling percentage is from right to left.

2 - FillCenterToEdgesH The filling percentage is from center to

border.

4.3.2.3.29 HorizontalPercentFill

Use the HorizontalPercentFill property to specify which is the percentage of the horizontal
area of the object to be filled. The acceptable values for this property vary from 0 to 100. This
property works along with the HorizontalFillStyle property, which informs how the filling is
going to be performed. The default value of this property is 100.

4.3.2.3.30 Layer

This property defines in which layers the object should appear. The value represents a 32 bit
mask, one bit for each layer. Therefore, up to 32 individual layers can de defined. Thus, objects
can be logically grouped and displayed or hidden only by changing the Layer mask property.

4.3.2.3.31 Shadow

Indicates a shadow effect on the object. If True, the object has a shadow, which coordinates
are established by the ShadowX and ShadowY properties. Otherwise, the object does not have
a shadow. The default value of this property is False.

4.3.2.3.32 ShadowColor

Specifies the filling color of the object shadow. This color is used when the Shadow property
is set to True. In scripts, use the RGB function of VBScript to create the color to be associated
to this property. The default value of this property is dark gray (RGB(128, 128, 128)).

V iew 121
4.3.2.3.33 ShadowX

Defines the left vertical coordinate of the object shadow, in Himetric units. This shadow is
always relative to the X property of the object. Positive values indicate a shadow on the right
side of the object, and negative ones on the left side. The default value of this property is 200.

4.3.2.3.34 ShadowY

Defines the upper horizontal coordinate of the object shadow, in Himetric units. This
shadow is always relative to the Y property of the object. Positive values indicate a shadow
below the object, and negative ones above. The default value of this property is 200.

4.3.2.3.35 VerticalFillStyle

Defines the vertical filling of the object. This property works along with the
VerticalPercentFill property, which informs the percentage of the object to be filled. These two
properties allow a simulation of a level filling in an object.

Available options for VerticalFillStyle

OPTION DESCRIPTION
0 - FillBottomToTop The filling percentage is from bottom to top.

1 - FillTopToBottom The filling percentage is from top to bottom.

2 - FillCenterToEdgesV The filling percentage is from center to

border.

4.3.2.3.36 VerticalPercentFill

Use the VerticalPercentFill property to specify which percentage of the vertical area of the
object to be filled. The acceptable values for this property vary from 0 to 100. This property
works along with the VerticalFillStyle property, which indicates how this filling occurs. The
default value of this property is 100.

4.3.2.4 Group
This section contains information about properties of the Group of objects. This object does
not have events nor methods associated to it.

122 V iew
4.3.2.4.1 Properties

This section contains information about the properties of the Group of objects.

4.3.2.4.1.1 EnableOverrideLineColor

This property enables or disables the Group object to override the original colors of the
lines of the objects contained in the Group. If the EnableOverrideLineColor is enabled, the
original colors of the lines of the objects in the Group are replaced by the color set in the
OverrideLineColor property. Otherwise, each object in the Group displays its original color.
The default value of this property is False.

4.3.2.4.1.2 OverrideFillColor

When the OverrideFillMode property is set to 2 or 3, the OverrideFillColor property is used

to define the filling color of the adjacent objects in the Group, instead of their original colors.
In scripts, use the RGB function of VBScript to create the color to be associated to this
property. The default value of this property is red (RGB(255, 0, 0)).

4.3.2.4.1.3 OverrideFillMode

The OverrideFillMode property specifies the filling mode of the objects in the Group. It
changes the original filling mode of the image without changing the original filling settings of
the object.

Available options for OverrideFillMode

OPTION DESCRIPTION
0 - NoOverride Original filling of the object.

1 - WireFrame The objects are not filled, they only draw

their borders.

2 - SolidFill The filling of the objects in the Group is solid

with the color specified in the
OverrideFillColor property.

3 - ByBrightness The filling of the objects in the Group is solid

with the color specified in the
OverrideFillColor property, however, the
brightness of the original color of each object
is preserved.

V iew 123
4.3.2.4.1.4 OverrideLineColor

When the EnableOverrideLineColor property is set to True, the OverrideLineColor property

is used to define the color of the line of the objects in the Group, instead of their original color.
In scripts, use the RGB function of VBScript to create the color to be associated to this
property. The default value of this property is red (RGB(255, 0, 0)).

4.3.2.5 Round Rectangle

This section contains information about the properties of the Rounded Rectangle object. This
object does not have events nor methods associated to it.

4.3.2.5.1 Properties

This section contains information about the properties of the Round Rectangle object.

4.3.2.5.1.1 RoundAspectX

The RoundAspectX property defines the dimension of rectangle sizes on X axis. Thus,
according to the value defined on this property, the corners of the rectangle will change their
shape, from a rectangle to an ellipse. This property may vary its value from 0,1 to 1. Example:
Sub RoundRect_Click()
RoundAspectX = 0.5
End Sub

4.3.2.5.1.2 RoundAspectY

The RoundAspectY property defines the size of the height dimension of the rectangle on Y
axis. Thus, according to the value defined on this property, the rectangle corners will change
their shape, from a rectangle to an ellipse. This property may vary its value from 0,1 to 1.
Example:
Sub RoundRect_Click()
RoundAspectY = 0.5
End Sub

4.3.2.6 Arc of Ellipse

This section contains information about the properties of the Arc of Ellipse object. This object
does not have events nor methods associated to it.

4.3.2.6.1 Properties

This section contains information about the properties of the Arc of Ellipse object.

124 V iew
4.3.2.6.1.1 ArcBeginAngle

This property configures the initial angle of the object arc, in degrees. The accepted interval
of this property ranges from 0 to 359. The arc style and shape also depend on the ArcEndAngle
and ArcStyle properties. The default value of this property is 0. Example:
Sub CommandButton9_Click()
Screen.Item("Arc1").ArcBeginAngle = 12
End Sub

4.3.2.6.1.2 ArcEndAngle

This property configures the final angle of the object arc, in degrees. The accepted interval of
this property ranges from 0 to 359. The arc style and shape also depend on the ArcBeginAngle
and ArcStyle properties. The default value of this property is 270. Example:
Sub CommandButton9_Click()
Screen.Item("Arc1").ArcEndAngle = 12
End Sub

4.3.2.6.1.3 ArcStyle

This property specifies the style of the object border or line. The object border will be
drawn according to the defined style, using the color specified in BorderColor with the
BorderWidth width. The next table contains valid values for the ArcStyle property:

Available options for ArcStyle

OPTION DESCRIPTION
0 - arc Drawing style is an arc.

1 - chord Drawing style is a chord, connecting a

starting and an ending point.

2 - pie Drawing style is of pie type (default).

Example:
Sub CommandButton9_Click()
Screen.Item("Arc1").ArcStyle = 1
End Sub

4.3.2.7 Picture
This section contains information about the properties of the Picture object. This object does
not have events nor methods associated to it.

V iew 125
4.3.2.7.1 Properties

This section contains information about the properties of the Picture object.

4.3.2.7.1.1 BackgroundColor

This property specifies the filling background color of the object. This color is used when
the BackgroundStyle property is set to 1 (opaque) and one of the VerticalPercentFill or
HorizontalPercentFill properties is different from 100. Another use of this color is when the
FillStyle property is set to a value between 2 and 8. This makes the remaining area uses the
background color as the filling color. In scripts, use the VBScript RGB method to build the
associated color of this property. The default value of this property is gray (RGB(192, 192, 192)
).

4.3.2.7.1.2 BackgroundStyle

This property specifies the filling mode of the object background. This property enables
using the VerticalPercentFill and HorizontalPercentFill properties with values different from
100 and also sets the FillStyle property with values between 2 and 8. This makes the
remaining area to use the BackgroundColor property as the filling. The next table contains
valid values for BackgroundStyle property.

Available options for BackgroundStyle

OPTION DESCRIPTION
0 - Transparent No object background will be drawn.

1 - Opaque In case it is visible, the background will be

drawn.

4.3.2.7.1.3 Convert

This property allows converting a picture. If the value is set to 0 it is possible to preview the
conversion. Otherwise, it is not possible to preview the conversion. This property only accepts
0 and 1. The default value of this property is 0.

4.3.2.7.1.4 EnableOverrideLineColor

This property enables or disables the object to overwrite the original color of the image line
by the color defined in the OverrideLineColor property. If the EnableOverrideLineColor
property is enabled, makes the original color of the object line to be modified by the color of
the OverrideLineColor property. Otherwise, the Picture object displays the original color.

126 V iew
4.3.2.7.1.5 Filename

Defines the name of the image file associated to this object. The file path may be the
complete disk file path as well as the path relative to the application (when the image file is
inserted as an application resource). The default value of this property is empty. The following
image file types are supported:

PROPERTY FILTER DESCRIPTION FILTER

Bitmap file BMP No Yes

Graphics Interchange GIF No Yes

Format
Joint Picture Expert JPG No Yes
Group
Icon File ICO No Yes

4.3.2.7.1.6 HorizontalFillStyle

Defines how the horizontal filling of the object will be done. This property works with the
HorizontalPercentFill, property, which informs what object percentage should be filled. These
two properties allow simulating a level filling in an object, the same way as a tank level, for
example.

Available options for HorizontalFillStyle

OPTION DESCRIPTION
0 - FillLeftToRight The filling percentage will be from left to right
(default).

1 - FillRightToLeft The filling percentage will be from right to

left.

2 - FillCenterToEdgesH The filling percentage will be from center to

border.

Example:
Sub Circle1_OnStartRunning()
HorizontalFillStyle = 2
End Sub

V iew 127
4.3.2.7.1.7 HorizontalPercentFill

Use the HorizontalPercentFill property to specify the percentage of the object horizontal
area to be filled. The accepted values of this property range from 0 to 100. This property works
with HorizontalFillStyle property, which informs how this filling will be performed. The default
value of this property is 100. Example:
Sub Circle1_OnStartRunning()
HorizontalPercentFill = 200
End Sub

4.3.2.7.1.8 OverrideFillColor

When the OverrideFillMode property is set to 2 or 3, the OverrideFillColor property will be

used to set the color of the image filling, instead of the original color. In scripts, use the
VBScript RGB method to build a color to be linked to this property. The default value of this
property is red (RGB(255, 0, 0)). Example:
Sub DrawPicture1_Click()
' When clicking the object sets the Override
' mode to solid and changes the image filling
' color to blue
OverrideFillMode = 2
OverrideFillColor = RGB(0, 0, 255)
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.9 OverrideFillMode

The OverrideFillMode property specifies the filling mode of the object image, when it is
displaying a Windows Metafile file. It changes the original filling mode of the image without
changing the file defined on the Filename property. The next table contains valid values for the
OverrideFillMode property.

Available options for OverrideFillMode

OPTION DESCRIPTION
0 - NoOverride The image will keep its original filling
(default).

1 - WideFrame The image will not be filled.

2 - SolidFill The image will be filled with the color

specified on the OverrideFillColor property.

3 - ByBrightness The image will be filled with the color

specified by the OverrideFillColor property,
however it will take into account what was
the intensity of the original color of the
image.

128 V iew
Example:
Sub DrawPicture1_Click()
' When clicking the object sets the
' Override mode to solid and changes the image filling
' color to blue
OverrideFillMode = 2
OverrideFillColor = RGB(0, 0, 255)
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.10 OverrideLineColor

When the EnableOverrideLineColor property is set to True, the OverrideLineColor property

will be used to define the color to be used as the color line of the picture, instead of the
original color. In scripts, use the VBScript RGB method to build the color to be linked to this
property. The default value of this property is red (RGB(255, 0, 0)). Example:
Sub DrawPicture1_Click()
OverrideLineColor = RGB(0, 0, 255)
End Sub

NOTE: This property only works when the Picture objects is working with metafiles (WMF or
EMF).

4.3.2.7.1.11 Shadow

Indicates the presence of a shadow effect in the object. If set to True, the object has a
shadow, which coordinates are established by the ShadowX and ShadowY properties.
Otherwise, the object does not have a shadow effect. The default value of this property is
False.

4.3.2.7.1.12 ShadowColor

Specifies the filling color of the object. This color is used when the Shadow property is set to
True. In scripts, use the VBScript RGB method to build the color associated to this property.
The default value of this property is light gray (RGB(128, 128, 128)). Example:
Sub Button1_Click()
' Changes the background color of the button
' to light gray when clicking the object
ShadowColor = RGB(192, 192, 192)
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

V iew 129
4.3.2.7.1.13 ShadowX

Defines the vertical coordinate left to the shadow of the object, in Himetric units. This
shadow is always relative to the X property of the object. Positive values indicate the shadow
will be on the right side of the object, and negative values on the left side of the object. The
default value of this property is 200.

4.3.2.7.1.14 ShadowY

Defines the upper horizontal coordinate right to the shadow of the object, in Himetric units.
This shadow is always relative to the Y property of the object. Positive values indicate the
shadow will be below the object, and negative values, above the object. The default value of
this property is 200. Example:
Sub Button1_Click()
ShadowY = 250
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.15 TransparentColor

When the TransparentMode is set to 1, this property defines which image color will not be
drawn, and the image will remain transparent in these points. In scripts, use the VBScript RGB
method to build the color to be associated to this property. The defualt value of this property
is white (RGB(255, 255, 255)). Example:
Sub DrawPicture1_Click()
' Leaves the blue color transparent
' when clicking the object
TransparentMode = 1 ' ByColor
TransparentColor = RGB(0, 0, 255)
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.16 TransparentMode

The TransparentMode property specifies the way the image will handle the transparency
effect.

Available options for TransparentMode

OPTION DESCRIPTION
0 - Disabled No transparency will be performed.

130 V iew
 OPTION DESCRIPTION
1 - ByColor Transparency will use the color set in the
TransparentColor property.

2 - ByPercent The image will be transparent with its

transparency percentage specified in the
TransparentPercent property.

Example:
Sub DrawPicture1_Click()
' Leaves the blue color transparent
' when clicking the Picture object
TransparentMode = 1 ' ByColor
TransparentColor = RGB(0, 0, 255)
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.17 TransparentPercent

When the TransparentMode is set to 2, this property defines how transparent the color will
be, varying from 0 (fully transparent) to 100 (fully opaque or solid). Example:
Sub DrawPicture1_Click()
' Leaves the image transparent when clicking the object
TransparentMode = 1 ' ByPercent
TransparentPercent = 50 ' 50% transparent
End Sub

NOTE: This property only works when the Picture object is working with metafiles (WMF or
EMF).

4.3.2.7.1.18 VerticalFillStyle

Defines the vertical filling of the object. This property works with the VerticalPercentFill
property, which informs what is the percentage of the object will be filled. These two
properties allow simulating a level filling in the object.

Available options for VerticalFillStyle

OPTION DESCRIPTION
0 - FillBottomToTop Filling percentage will be from bottom to top.

1 - FillTopToBottom Filling percentage will be from top to bottom.

V iew 131
 OPTION DESCRIPTION
2 - FillCenterToEdgesV Filling percentage will be from center to
border.

Example:
Sub Circle1_OnStartRunning()
VerticalFillStyle = 2
End Sub

4.3.2.7.1.19 VerticalPercentFill

Use the VerticalPercentFill property to specify what is the percentage of the vertical area of
the object will be filled. The acceptable values for this property vary from 0 to 100. This
property works with the VerticalFillStyle property, which informs how this filling will occur. The
default value of this property is 100. Example:
Sub Circle1_OnStartRunning()
VerticalPercentFill = 254
End Sub

4.3.2.8 Text, Display, and SetPoint

This section contains information about events and properties of Text, Display, and SetPoint
objects. These objects do not have methods associated to them.

4.3.2.8.1 Events

This section contains information about the events of Text, Display, and SetPoint objects.

4.3.2.8.1.1 Validate
Validate(Cancel, NewValue)

Occurs after testing the SetPoint limits (see MinLimit, MaxLimit, and EnableLimits properties)
and before SetPoint value is sent to the tag. This event allows the user to validate SetPoint
value.

If Cancel is True, the attribution operation must be cancelled. Otherwise, the value will be
sent to the tag. NewValue is the value to be validated. The old value can be accessed through
the Value property of the SetPoint. Example:
Sub Text1_Validate(Cancel, NewValue)
' Displays a MessageBox which asks the user
' if the new SetPoint value should be used
message = "Current value: " & value & vbnewline & _
"New value: " & NewValue & vbnewline & vbnewline & _
"Do you accept the new value?"
If MsgBox (message, vbQuestion + vbYesNo, _
"Validate Event") = vbNo Then
Cancel = True
End If
End Sub

132 V iew
4.3.2.8.2 Properties

This section contains information about the properties of Text, Display, and SetPoint objects.

4.3.2.8.2.1 EnableLimits

Checks for limits in the text. If True, and the user inserts a non-number value, or a value
outside the limits defined by MinLimit and MaxLimit properties, an error message is displayed
(IsSetPoint property must be True). Example:
Sub CommandButton1_Click()
Screen.Item("Text1").EnableLimits = _
Not(Screen.Item("Text1").EnableLimits)
End Sub

4.3.2.8.2.2 Format

Specifies the type of format to be attributed to the object. It allows changing the way data is
presented without changing the value itself. You can edit this property manually, or set it
through the formatting window. Its use is similar to format codes on spreadsheets, following
the same basic syntax. The following datatype are supported:

Datatypes supported by Format

DATATYPE DESCRIPTION
Number Decimal, scientific, hexadecimal, binary, and
octal output.

Text General text.

Boolean Boolean values.

Date/Time Gregorian calendar.

4.3.2.8.2.3 IsSetPoint

Determines whether the object allows editing the Value property. The Value property is a
Variant (it can assume any and every type of value) exhibited by Text object. If True, editing is
allowed; otherwise, it is not. It can be viewed when Viewer object is running. Default value is
False.

V iew 133
4.3.2.8.2.4 KeepFormatWhenEditing

Allows you to edit object's value with or without keeping its format. The available options
are:

· 0 - kfNever: in this case, the value is always edited with no formatting (default)

· 1 - kfAutomatic: allows the value to be edited in the formatted value, in case E3 detects it is
possible for the formatted text to be interpreted as a value

In case the value is considered incompatible, the value is edited without formatting.

4.3.2.8.2.5 MaxLimit

Contains the maximum value allowed for the object (the EnableLimits property must be
True). Example:
Sub CommandButton3_Click()
Screen.Item("Text1").MaxLimit = Screen.Item("Text6").Value
End Sub

4.3.2.8.2.6 MinLimit

Contains the minimum value allowed for the object (the EnableLimits property must be
True). Example:
Sub CommandButton2_Click()
Screen.Item("Text1").MinLimit = Screen.Item("Text5").Value
End Sub

4.3.2.8.2.7 Multiline

This property indicates whether the text will have multiple lines (True) or will be a simple
text box (False). This can be viewed when Viewer is running. Default value is False. Example:
Sub Screen1_OnStartRunning()
Screen.Item("TextBox1").Multiline = True
End Sub

4.3.2.8.2.8 SetPointDataType

Determines the value type sent from the SetPoint to the tag.

Available options for SetPointDataType

OPTION DESCRIPTION
0 - stCurrentType Maintains current type (see next).

1 - stChar 8 bit signed integer value.

134 V iew
 OPTION DESCRIPTION
2 - stByte 8 bit unsigned integer value.

3 - stWord 16 bit unsigned integer value.

4 - stInteger 16 bit signed integer value.

5 - stLong 32 bit signed integer value.

6 - stDWord 16 bit unsigned integer value.

7 - stSingle 32 bit floating point value.

8 - stDouble 64 bit floating point value.

9 - stDateTime Date/time value.

10 - stString Text.

When the typed text is sent by the SetPoint, it will first try to convert the value to the set type (
Word, String, Double, etc.). If conversion is not possible, that is, the typed value is not valid for
the chosen type, no value is sent (for example, if the user types "-1", and the type is Byte). But
when property value is 0 - stCurrentType, the datatype sent by the SetPoint comes from the
previous value present in the object. In case it is Empty, or Null, no conversion will be
performed, and the typed value will be sent as text. Example:
Sub Combobox1_Change()
Screen.Item("Text1").SetPointDataType = CInt(Left(Value, 2))
End Sub

4.3.2.8.2.9 StretchText

Resizes the object type. When enabled, the object automatically resizes text font size so
that the area occupied by the object always remains the same. Otherwise, if the property is
set to False, no resizing will be performed.

4.3.2.8.2.10 TextAlignment

This property specifies the horizontal alignment of the text displayed in the object.

Available options for TextAlignment

OPTION DESCRIPTION
0 - LeftAlignment Text horizontal alignment on the left.

1 - CenterAlignment Text horizontal alignment centered.

V iew 135
 OPTION DESCRIPTION
2 - RightAlignment Text horizontal alignment on the right.

4.3.2.8.2.11 TextColor

Specifies font color in the text. Use the VBScript RGB method to compose the color to be
associated to this property. Default value is black (RGB(0, 0, 0)).

4.3.2.8.2.12 TextFont

Defines the type of font to be used in the object. This property cannot be used in Links, and
contains the following subproperties, which can be changed via scripts:

TextFont subproperties

NAME TYPE DESCRIPTION

Name String Font name.

Size Floating Point Font size, in points.

Bold Boolean Indicates whether text has a

bold style.

Italic Boolean Indicates whether text has an

italic style.

Underline Boolean Indicates whether text has an

underline style.

Strikethrough Boolean Indicates whether text has a

strikethrough style.

Weight Integer Indicates a variation on font's

bold effect (the Bold
subproperty). Values for this
subproperty may range from
0 (does not interfere with
bold effect) to 1000.

Charset Integer Font character set. See the

table of character sets below,
for a list of all available
values for this subproperty.

136 V iew
 Available values for Charset subproperty

VALUE DESCRIPTION
0 ANSI (American National Standards Institute)

1 Default (displays the available character set

in the font)

2 Symbol

128 Japanese (Shift-JIS)

129 Korean

134 Chinese Simplified (GBK)

136 Chinese Traditional (Big5)

161 Greek

162 Turkish

177 Hebrew

178 Arabic

186 Baltic

204 Russian

222 Thai

238 Central Europe

255 OEM (Original Equipment Manufacturer)

4.3.2.8.2.13 Value

The Value property is a Variant (it can assume any and every type of value) displayed by the
object. Usually this property contains a text, because it is automatically filled in when creating
a new Text object. The IsSetPoint property determines whether the object allows editing the
Value property. Example:
Sub DrawString1_OnStartRunning()
' Reads a tag value and displays the Text
Dim obj
Set obj = Application.GetObject("DataServer1.DemoTag1")
Value = "DemoTag1 value = " & obj.Value
End Sub

V iew 137
4.3.2.8.2.14 VertTextAlignment

Determines the vertical alignment of the object text.

Available options for VertTextAlignment

OPTION DESCRIPTION
0 - TopAlignment Text vertical alignment on top of the object.

1 - MidAlignment Text vertical alignment centered in the

object.

2 - BottomAlignment Text vertical alignment at the bottom of the

object.

4.3.2.8.2.15 WordWrap

Enables or disables a line break in the text, in case the available area for the text overrides
the limits defined by the object. For this property to work, the Multiline property must be set
to a True.

4.3.2.9 Scale
This section contains information about properties of the Scale object. This object does not
have events nor methods associated to it.

4.3.2.9.1 Properties

This section contains information about the properties of the Scale object.

4.3.2.9.1.1 BackgroundColor

This property specifies the filling color of the object background. This color is used when
the BackgroundStyle property is set to 1 (opaque) and one of the VerticalPercentFill or
HorizontalPercentFill properties has a value different from 100. Another use of this color is
when the FillStyle property is set to values between 2 and 8. This makes the remaining area to
use the background color for filling. In scripts, use the VBScript RGB method to build the color
to be associated to this property. The default value of this property is gray (RGB(192, 192, 192)
).

138 V iew
4.3.2.9.1.2 BorderColor

This property determines the border color which will be applied on the Scale object. With
this property, it is possible to apply a default color or personalize it by editing the color. The
default value of this property is white (RGB(255, 255, 255)). Example:
Sub Scale1_Click()
BorderColor = RGB (255, 0, 0)
End Sub

4.3.2.9.1.3 BorderStyle

The BorderStyle property determines the style of the border which will be applied to the
Scale object.

Available options for para BorderStyle

OPTION DESCRIPTION
0 - Normal Applies a solid border on the vertical grid of
the scale (default).

1 - Dash Applies a dash-line border on the scale.

2 - Dot Applies a dotted border on the scale.

3 - Dashdot Applies a dash-dot border on the scale.

4 - Dashdotdot Applies a dash-dot-dot border on the scale.

5 - Null The object will have no border.

Example:
Sub Scale1_Click()
BorderStyle = 1
End Sub

4.3.2.9.1.4 BorderWidth

This property determines the width (in pixels) of the Scale border. By using this property it is
possible to set the border width, without changing its structure. The default value of this
property is 0. Example:
Sub CommandButton1_Click()
Screen.Item("Scale1").BorderWidth = 120
End Sub

V iew 139
4.3.2.9.1.5 ForegroundColor

This property specifies the filling color of the object's foreground. This color is used when
the FillStyle property is set to 0 (solid) or between 2 and 9. In scripts, use the VBScript RGB
method to build the color to be associated to this property. The default value of this property
is blue (RGB(0, 0, 255)). Example:
Sub Button1_Click()
' Changes the background color of the button
' to green when clicking the object
ForegroundColor = RGB(0, 255, 0)
End Sub

4.3.2.9.1.6 Format

Specifies the type of format to be attributed to the object. It allows changing the way data is
presented without changing their value. You can edit this property manually, or set it through
the formatting window. Its use is similar to formatting codes on spreadsheets, following the
same basic syntax. The following datatype are supported.

Datatypes supported by Format

DATATYPE DESCRIPTION
Number Decimal, scientific, hexadecimal, binary, and
octal output.

Text Text in general.

Boolean Boolean values

Date/Time Gregorian calendar.

4.3.2.9.1.7 GradientStyle

Specifies the object's gradient fill style. Used only when the FillStyle property is set to 8
(Gradient). Gradients range from ForegroundColor to BackgroundColor properties.

Available options for GradientStyle

OPTION DESCRIPTION
0 - LeftToRight Vertical gradient from left to right.

1 - RightToLeft Vertical gradient from right to left.

2 - VerFromCenter Vertical gradient from center to border.

3 - VerToCenter Vertical gradient from border to center.

4 - BottomUp Horizontal gradient from bottom to top.

140 V iew
 OPTION DESCRIPTION
5 - TopDown Horizontal gradient from top to bottom.

6 - HorzFromCenter Gradient from center to border.

7 - HorzToCenter Gradient from border to center.

8 - DiagUpRight Diagonal top gradient with foreground color

on the right (default).

9 - DiagUpLeft Diagonal top gradient with foreground color

on the left.

10 - DiagUpFromCenter Diagonal top gradient from center to border.

11 - DiagUpToCenter Diagonal top gradient from border to center.

12 - DiagDownLeft Diagonal bottom gradient with foreground

color on the left.

13 - DiagDownRight Diagonal bottom gradient with foreground

color on the right.

14 - DiagDownFromCenter Diagonal bottom gradient from center to

border.

15 - DiagDownToCenter Diagonal bottom gradient from border to

center.

16 - SpotSouthEast Gradient with foreground color from right

lower corner.

17 - SpotSouthWest Gradient with foreground color from left

lower corner.

18 - SpotNorthWest Gradient with foreground color from left

upper corner.

19 - SpotNorthEast Gradient with foreground color from right

upper corner.

20 - SpotFromCenter Gradient with background color from center

to border.

21 - SpotToCenter Gradient with background color from border

to center.

V iew 141
IMPORTANT: Too many objects being displayed simultaneously with gradients leads to poor
performance when updating the Screen. Using pictures may solve the problem.

Example:
Sub Button1_Click()
' Objeto gets a gradient
FillStyle = 8 ' GradientFill
GradientStyle = 0 ' LeftToRight
End Sub

4.3.2.9.1.8 LineColor

Determines the color of the line with the scale's ticks and minor ticks. To determine the
color of the legend with object numbers, use the TextColor property. Default value is black (
RGB(0, 0, 0)).

4.3.2.9.1.9 MaximumValue

This property determines the maximum value reached by the scale. The default value of this
property is 100. Example:
Sub CommandButton_Click()
' When clicking the button, opens a MessageBox
' indicating the maximum value of the property
MsgBox CSTr(Screen.Item("Scale1").MaximumValue)
End Sub

4.3.2.9.1.10 MinimumValue

This property determines the minimum value reached by the scale. The default value of this
property is 0. Example:
Sub CommandButton1_Click()
' When clicking the button, opens a MessageBox
' indicating the minimum value of the property
MsgBox _
CSTr(Application.GetObject("Data.Scale1").MinimumValue)
End Sub

4.3.2.9.1.11 MinorTicks

Determines the number of minor ticks on the scale. Default value is 3. Example:
Sub CommandButton1_Click()
' Displays the total amount of minor ticks on the scale
MsgBox CStr(Screen.Item("Scale1").MinorTicks)
End Sub

142 V iew
4.3.2.9.1.12 MinorTicksPercentSize

This property determines the size of the marks which subdivide each measure of the Scale
object. The default value of this property is 10. Example:
Sub CommandButton1_Click()
MsgBox CStr(Screen.Item("Scale1").MinorTicksPercentSize)
End Sub

4.3.2.9.1.13 ScaleAlignment

This property determines the type of alignment which will be attributed to the scale:

· 0 - RightSide: to the right (default value)

· 1 - LeftSide: to the left

Example:
Sub CommandButton1_Click()
Screen.Item("Scale1").ScaleAlignment = 1
End Sub

4.3.2.9.1.14 ShowText

Determines whether text is displayed in the Scale legend. If True, text is displayed.
Otherwise, the object displays only scale lines and minor ticks. Default value is True.

4.3.2.9.1.15 StretchText

Applies stretching to the text in the object (whenever height or width vary, the text box
follows the change). If True, the text stretches to accommodate to the object's new
dimensions. Otherwise, text maintains its original settings. Default value is False.

4.3.2.9.1.16 TextAlignment

The TextAlignment property determines the alignment of the text on the object.

Available option for TextAlignment

OPTION DESCRIPTION
0 - leftAlignment Left text alignment (default).

1 - centerAlignment Centered text alignment.

2 - rightAlignment Right text alignment.

V iew 143
4.3.2.9.1.17 TextColor

Determines the font color applied to the legend numbers on the Scale. To determine the
line color with ticks and minor ticks, use the LineColor property. Default value is black (RGB(0,
0, 0)).

4.3.2.9.1.18 TextFont

Determines the font to be applied to the Scale. This property cannot be used in Links. See
property TextFont of Text, Display, and SetPoint objects for more information about
subproperties that can be modified via scripts.

4.3.2.9.1.19 Ticks

Determines the number of ticks on the scale. Default value is 5.

4.3.2.9.1.20 TicksPercentSize

Determines the size of the lines which divide the Scale object. The size of the default divider
line of the Scale will be smaller or bigger according to this value. The default value of this
property is 20.

4.3.2.10 Dynamic Move

This section contains information about the properties of the Dynamic Move object. This
object does not have events nor methods associated to it.

4.3.2.10.1 Properties

This section contains information about the properties of the Dynamic Move object.

4.3.2.10.1.1 Detents

The Detents property determines the number of steps of the object movement. Example:
Sub CommandButton1_Click()
MsgBox Screen.Item("DynamicRotate1").Detents
End Sub

4.3.2.10.1.2 EnableOverrideLineColor

Enables or disables the object to override the original line color of the object by the color
defined by OverrideLineColor property. Otherwise, each object in the group will present its
original line color. Default value is False.

144 V iew
4.3.2.10.1.3 EnableSlider

This property enables object movement slider. If True, enables movement. Otherwise,
movement is disabled.

4.3.2.10.1.4 OverrideFillColor

When OverrideFillMode property is set to 2 or 3, the OverrideFillColor property is used to

define the color to fill the object, instead of its original color. Use the VBScript RGB method to
compose the color to be associated to this property. Default value is red (RGB(255, 0, 0)).
Example:
Sub DrawGroup1_Click()
' When clicking the object sets the
' Override mode to solid and changes the
' filling color to blue
OverrideFillMode = 2
OverrideFillColor = RGB(0, 0, 255)
End Sub

4.3.2.10.1.5 OverrideFillMode

The OverrideFillMode property specifies the filling mode of the objects which are moving.
It changes the image's original filling mode without changing the original filling settings of the
objects.

Available options for OverrideFillMode

OPTION DESCRIPTION
0 - NoOverride Original filling of the object.

1 - WireFrame Objects will not be filled, only their borders

will be drawn.

2 - SolidFill Filling of the objects contained in a group will

be solid with the color specified in the
OverrideFillColor property.

3 - ByBrightness Filling of the objects contained in a group will

be solid with the color specified in the
OverrideFillColor property, however it will
take into account the brightness of the
original filling color of every object.

Example:

V iew 145
 Sub DrawGroup1_Click()
' When clicking the object sets the
' Override mode to solid and changes the
' filling color of the image to blue
OverrideFillMode = 2
OverrideFillColor = RGB(0, 0, 255)
End Sub

4.3.2.10.1.6 OverrideLineColor

When EnableOverrideLineColor property is set to True, OverrideLineColor property is used

to define the color to be used on object lines, instead of their original color. Use the VBScript
RGB method to compose the color to be associated to this property. Default value is red (RGB
(255, 0, 0)). Example:
Sub Group1_Click()
OverrideLineColor = RGB(255, 0, 0)
End Sub

4.3.2.10.1.7 RangeMax

Determines maximum range of the object's linear sliding.

4.3.2.10.1.8 RangeMin

Determines minimum range of the object's linear sliding.

4.3.2.10.1.9 Value

This is the initial value of the Slider. It must be a value between RangeMax and RangeMin
properties.

4.3.2.11 Dynamic Rotate

This section contains information about the properties of the Dynamic Rotate object. This
object doe not have events nor methods associated to it.

4.3.2.11.1 Properties

This section contains information about the properties of the Dynamic Rotate object.

4.3.2.11.1.1 Detents

This property determines the number of steps of the object movement.

146 V iew
4.3.2.11.1.2 EnableOverrideLineColor

This property enables or disables the object to overwrite the original color of the image line
by the color defined in the OverrideLineColor property. If the EnableOverrideLineColor
property is enabled, the original color of the object line is changed by the color set in the
OverrideLineColor property. Otherwise, the object displays the original color. The default
value of this property is False.

4.3.2.11.1.3 EnableSlider

The EnableSlider property enables or disables the slider in the object movement.

4.3.2.11.1.4 OverrideFillColor

When the OverrideFillMode property is set to 2 or 3, the OverrideFillColor property is used

to define the color to be used in the filling of the moving object, instead of the original color. In
scripts, use the RGB function of VBScript to create the color to be associated to this property.
The default value of this property is red (RGB(255, 0, 0)).

4.3.2.11.1.5 OverrideFillMode

The OverrideFillMode property specifies the filling mode of the moving objects. It changes
the original filling mode of the image without changing the original filling settings of the
objects.

Available options for OverrideFillMode

OPTION DESCRIPTION
0 - NoOverride Original filling of the object.

1 - WireFrame Objects are not filled, they only draw their

borders.

2 - SolidFill The filling of the objects is solid with the color

specified in the OverrideFillColor property.

3 - ByBrightness The filling of the objects is solid with the color

specified in the OverrideFillColor property,
however, the brightness of the original color
of each object is preserved.

V iew 147
4.3.2.11.1.6 OverrideLineColor

When the EnableOverrideLineColor property is set to True, the OverrideLineColor property

is used to define the color to be used in the line of the moving object, instead of the original
color. In scripts, use the RGB function of VBScript to create the color to be associated to this
property. The default value of this property is red (RGB(255, 0, 0)).

4.3.2.11.1.7 RangeMax

This property determines the maximum range reached by the rotational movement of the
object.

4.3.2.11.1.8 RangeMin

This property determines the minimum range reached by the rotational movement of the
object.

4.3.2.11.1.9 RotationAngle

This property determines the rotation angle of the object movement. Example:
Sub CommandButton1_DbClick()
Screen.Item("DynamicMove1").RotationAngle = 180
End Sub

4.3.2.11.1.10 RotationDirection

The RotationDirection property determines the orientation rotation of the object

movement.

Available options for RotationDirection

OPTION DESCRIPTION
0 - Clockwise Directs the rotation angle to the right of the
object.

1 - CounterClockWise Directs the rotation angle to the left of the

object.

Example:
Sub CommandButton1_Click()
' Directs the rotation angle to the right of the object
Screen.Item("DynamicRotate1").RotationDirection = 1
End Sub

148 V iew
4.3.2.11.1.11 Value

This is the initial value of the movement. It must be a value between the RangeMax and
RangeMin properties.

4.3.2.12 Microsoft Forms

This section contains information about common events and properties of Microsoft Forms
objects. These objects do not have common methods associated to them.

4.3.2.12.1 Common Events

This section contains information about common events of Microsoft Forms objects.

4.3.2.12.1.1 BeforeDragOver
BeforeDragOver(Index, Cancel, Data, X, Y, DragState, Effect, Shift)

It occurs when there is a drag-and-drop action on the object. Use this event in order to monitor
if the mouse entered, left or stood over a target-object. The event is triggered when user
moves the mouse or presses and releases any button. Mouse pointer position will indicate
which object will generate the event. You can specify the mouse pointer status by verifying
DragState variable.

Many controls (objects) do not support drag-and-drop operations while Cancel variable is
False, which is default. This means that the control rejects any attempt of dragging-and-
dropping something on itself and therefore, it does not trigger BeforeDropOrPaste event. The
TextBox and the ComboBox are exceptions, they accept drag-and-drop operations even when
Cancel is False.

Variables of BeforeDragOver event

NAME DESCRIPTION
Index Indicates, in a multi-pages object, the index
of the page which will be affected by the
operation that generated the event. For
other objects, it is ignored.

Cancel Event status. By default it is False and

indicates that the target-object will address
the event and not the main application.

Data Data being dragged to the target object.

X, Y Mouse position in points within the target

object. X is measured from the left side of the
object; Y is measured from the top.

V iew 149
 NAME DESCRIPTION
DragState Indicates mouse condition when the event is
generated:

· 0 - fmDragStateEnter: mouse is within the

object range

· 1 - fmDragStateLeave: mouse is out of the

object range

· 2 - fmDragStateOver: mouse is at a new

position, but still within the object range

Effect Indicates the actions supported by the target

object, that is, the drag effect on the
mentioned object:

· 0 - fmDropEffectNone: target object does

not accept copying or moving from any
origin

· 1 - fmDropEffectCopy: target object allows

copying from any origin to itself

· 2 - fmDropEffectMove: target object allows

moving from any origin to itself

· 3 - fmDropEffectCopyOrMove: target
object allows copying or moving from any
origin to itself

Shift Integer which sum indicates SHIFT, CTRL, and

ALT keys status:

· 1: SHIFT key pressed

· 2: CTRL key pressed

· 4: ALT key pressed

For example, a value of 5 indicates that SHIFT

and ALT keys were pressed (1 + 4 = 5).

150 V iew
4.3.2.12.1.2 BeforeDropOrPaste
BeforeDropOrPaste(Index, Cancel, Ctrl, Action, Data, X, Y, Effect, Shift)

Triggered immediately before a drag-and-drop operation. Normally, it occurs right after

BeforeDragOver event.

Variables of BeforeDropOrPaste event

NAME DESCRIPTION
Index Indicates, in a multi-pages object, the index
of the page which will be affected by the
operation that generated the event. For
other objects, it is ignored.

Cancel Event status. By default it is False and

indicates that the target object will address
the event and not the main application.

Ctrl Target object.

Data Data being dragged to the target object.

Action Indicates the result, based on keyboard

settings, of a pending drag-and-drop
operation:

· 2 - fmActionPaste: pastes selected object

on target object

· 3 - fmActionDragDrop: indicates that users

dragged selected object from its origin
and dropped it onto target object

X, Y Mouse position in points within the target

object. X is measured from the left side of the
object; Y is measured from the top.

DragState Indicates mouse condition when the event is

generated:

· 0 - fmDragStateEnter: mouse is within

object range

· 1 - fmDragStateLeave: mouse is outside

object range

· 2 - fmDragStateOver: mouse is at a new

position, but still within the object range

V iew 151
 NAME DESCRIPTION
Effect Indicates the actions supported by the target
object, that is, the drag effect on the
mentioned object:

· 0 - fmDropEffectNone: target object does

not accept copying or moving from any
origin

· 1 - fmDropEffectCopy: target object allows

copying from any origin to itself

· 2 - fmDropEffectMove: target object allows

moving from any origin to itself

· 3 - fmDropEffectCopyOrMove: target
object allows copying or moving from any
origin to itself

Shift Integer which sum indicates SHIFT, CTRL, and

ALT keys status:

· 1: SHIFT key pressed

· 2: CTRL key pressed

· 4: ALT key pressed

For example, a value of 5 indicates that SHIFT

and ALT keys were pressed (1 + 4 = 5).

4.3.2.12.1.3 Change
Change()

It occurs when the value of the Value property of the object is modified. Here are some
examples of actions, which trigger the Change event:

· Clicking a check box, an option button or an increase-decrease button

· Clicking or selecting words in a selection list or a text editor

· Selecting different tabs in a Dialog Box

· Moving the scrolling bar in a scrolling bar object

· Clicking the arrows of an increase-decrease button

· Selecting different pages in a multi-pages object

152 V iew
4.3.2.12.1.4 OnError
OnError(Number, Description, SCode, Source, HelpFile, HelpContext, CancelDisplay)

Generated by an object internal error. If this event is not handled, E3 will display a generic
error message.

Variables of the OnError event

NAME DESCRIPTION
Number Integer identifying the error.

Description String with error description.

SCode Integer with the error code of the OLE

subsystem (not used).

Source String with the object that generated the

error.

HelpFile String with name and path of the help file.

HelpContext Context number of the help topic referring to

the error (Integer).

CancelDisplay Boolean indicating whether the error should

be displayed on a message box.

4.3.2.12.1.5 KeyPress
KeyPress(KeyAscii)

This event occurs when the object has keyboard focus and user presses a key corresponding to
a character that can be displayed on Screen (an ANSI key, with its code indicated in the
KeyAscii variable). That is, the event occurs when any of the following keys are pressed:

· Any keyboard character that can be printed

· CTRL key combined with any standard alphabet character

· CTRL key combined with any special character

· BACKSPACE key

· ESC key

This event does not occur in the following conditions:

V iew 153
· When pressing TAB key

· When pressing ENTER key

· When pressing DEL key (this is not an ANSI key)

· When pressing keyboard arrow keys

· When a key changes focus from one object to another

While a user is pressing a key that produces an ANSI code, the object repeatedly receives the
KeyDown and the KeyPress events. When the user releases the key, the KeyUp event occurs. In
order to monitor keyboard physical status or handle keys which are not recognized by the
KeyPress event (such as function keys, browsing keys, etc.), use the KeyDown and KeyUp
events.

4.3.2.12.2 Common Properties

This section contains information about common properties of Microsoft Forms objects.

NOTE: E3 uses the HIMETRIC system to define coordinates and widths. In this system, each
logical unit is the equivalent of a thousandth of a centimeter, that is every 1,000 units
correspond to one centimeter. Thus, this is the standard adopted in the description of E3
properties, when applicable.

4.3.2.12.2.1 BackColor

Specifies the object's background color. In scripts, use the VBScript RGB method to compose
the color to be associated to this property. Default value for Combo, List, and Text is white (
RGB(255, 255, 255)). For all other objects, it is beige (RGB(236, 233, 216)).

4.3.2.12.2.2 ForeColor

Specifies the object's foreground color. In scripts, use the VBScript RGB method to compose
the color to be associated to this property. The default value of this property for all MS Forms
objects is black (RGB(0, 0, 0)).

4.3.2.12.2.3 MouseIcon

This property sets an image to the mouse pointer, whenever the pointer moves over an
object. This property is valid only when MousePointer property is set to 99 -
fmMousePointerCustom.

An image file can be selected to be used as mouse pointer in two different ways. Via Property
Window (.cur or .ico extensions), or via scripts, by using the LoadPicture method to specify the

154 V iew
name and the path of the file with the personalized icon (.cur extension only). Example:
Sub CommandButton1_Click()
' Setting the 99 - fmMousePointerCustom item to the property
' so that it accepts mouse icon customization
Screen.Item("CheckBox1").MousePointer = 99
Screen.Item("CheckBox1").MouseIcon = LoadPicture("C:\a.cur")
End Sub

4.3.2.12.2.4 MousePointer

Specifies the type of the mouse pointer displayed when the user moves it over an object.
The available options are:

Available options for MousePointer

OPÇÃO DESCRIÇÃO
0 - fmMousePointerDefault Default pointer. The image is determined by
the object.

1 - fmMousePointerArrow Arrow.

2 - fmMousePointerCross Arrow shaped pointer.

3 - fmMousePointerBeam I-beam shaped pointer.

6 - fmMousePointerSizeNesw North-East, South-West double arrow

shaped pointer.

7 - fmMousePointerSizeNS North-South doublearrow shaped pointer.

8 - fmMousePointerNWse North-West, South-East double arrow

shaped pointer.

9 - fmMousePointerWE West-East double arrow shaped pointer.

10 - fmMousePointerUpArrow Upper arrow.

11 - MousePointerStarHourGlassring Hourglass.

12 - fmMousePointerHelpNoDrop Not symbol (a circle with a diagonal line) on

the upper side of the dragged object.
Indicates and invalid drop destiny.

13 - fmMousePointerAppStarting Hourglass shaped pointer.

14 - fmMousePointerHelp Question mark pointer.

15 - fmMousePointerSizeAll Resizes the whole cursor (arrows pointing to

North, South, East, and West).

V iew 155
 OPÇÃO DESCRIÇÃO
99 - fmMousePointerCustom Uses the icon specified in the MouseIcon
property.

Use this property to indicate functionality changes as the mouse pointer slides over the
objects on the Screen. For example, an hourglass shaped pointer (option 11) is useful to
indicate that the user should wait for the process or operation to be finished. Some icons may
vary, depending on the system configuration, like icons associated to working area themes.
The default value of this property is 0 - fmMousePointerDefault.

4.3.2.12.3 Checkbox

This section contains information about properties of the Checkbox object. This object does
not have events nor methods associated to it.

4.3.2.12.3.1 Properties

This section contains information about the properties of the Checkbox.

Accelerator
Defines or gets the object accelerator key. This accelerator key is a shortcut key which,
when used together with ALT key, gives focus to the object. Default value is Empty.

Alignment
Specifies the object alignment on the Screen relative to its legend. The available options
are:

· 0 - fmAlignmentLeft: aligns the legend to the left of the object

· 1 - fmAligmentRight: aligns the legend to the right of the object

AutoSize
Adjusts text width, in case its available area is larger than the object size. For Checkbox and
Option Button objects, if the property is True, the text will be resized to fit the object current
size.

BackStyle
Defines the object background style. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no background will be

drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

156 V iew
NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

Caption
Defines the text to be displayed on the object.

Font
Determines the object font. This property cannot be used in scripts or links, and it is
configured exclusively via E3 Studio.

GroupName
Creates a mutually exclusive group of objects.

NOTE: This property is not used in E3 and it is kept for compatibility reasons with Microsoft
Forms standard specification.

Locked
Enables or disables editing the object. If True, editing is not allowed; otherwise, it is. The
value configured for the Enabled property influences the Locked property behavior. For further
details, see the Enabled property. Default value is False.

Picture

Specifies the picture (bitmap) set to the object. An image file can be selected in two ways,
via Properties List; or via scripts, by using the LoadPicture method to specify the path and the
name of the file containing the picture. To remove the picture, click the value of the Picture
property and press the DEL key. The BACKSPACE key does not delete the picture. Example:
Sub CommandButton1_Click()
Screen.Item("CheckBox1").Picture = LoadPicture("C:\tab.gif")
End Sub

PicturePosition
Specifies the picture position set to the object relative to its legend. The available options
for this property are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - fmPicturePositionLeftTop Picture appears on the left of its legend. The
legend is aligned to the upper side of the
picture.

1 - fmPicturePositionLeftCenter Picture appears on the left of its legend. The

legend is centered relative to the picture.

V iew 157
 OPTION DESCRIPTION
2 - fmPicturePositionLeftBottom Picture appears on the left of its legend. The
legend is aligned to the lower part of the
picture.

3 - fmPicturePositionRightTop Picture appears on the right of its legend. The

legend is aligned to the upper side of the
picture.

4 - fmPicturePositionRightCenter Picture appears on the right of its legend. The

legend is centered relative to the picture.

5 - fmPicturePositionRightBottom Picture appears on the right of its legend. The

legend is aligned to the lower part of the
picture.

6 - fmPicturePositionAboveLeft Picture appears above the legend. The

legend is aligned to the left side of the
picture.

7 - fmPicturePositionAboveCenter Picture appears above the legend. The

legend is centered below the picture
(default).

8 - fmPicturePositionAboveRight Picture appears above the legend. The

legend is aligned to the right side of the
picture.

9 - fmPicturePositionBelowLeft Picture appears below the legend. The

legend is aligned to the left side of the
picture.

10 - fmPicturePositionBelowCenter Picture appears below the legend. The

legend is centered above the picture.

11 - fmPicturePositionBelowRight Picture appears below the legend. The

legend is aligned to the right side of the
picture.

SpecialEffect
Specifies the object appearance. The available options are the following:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmButtonEffectFlat The object appears to be flat and has a raised
border, a color change or both.

158 V iew
 OPTION DESCRIPTION
2 - fmButtonlEffectSunken The object has a shadow on the upper left
side and is raised on the lower right side, as if
it is sunked on the Screen.

TextAlign
Specifies how text is aligned in the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left side of the object

· 2 - fmTextAlignCenter: centralizes text to the right side of the object

· 3 - fmTextAlignRight: aligns the text to the right side of the object

TripleState
Determines up to three value status for the object. If True, the user can choose from three
status options, False, True, or Null. The Null state is displayed as a shaded button. Otherwise,
the user can only choose from True or False values. Default value is False.

Value
Indicates the initial value of the object. Its behavior is Boolean. If True, its initial status is
checked, otherwise it will start unchecked. Default value is False.

WordWrap
Enables or disables line breaks in the text, in case the available area for the text overrides
the boundaries determined in the object.

4.3.2.12.4 Option Button

This section contains information about properties of the Option Button object. This object
does not have events nor methods associated to it.

4.3.2.12.4.1 Properties

This section contains information about the properties of the Option Button.

Accelerator
Defines or gets the object accelerator key. This accelerator key is a shortcut key which,
when used together with ALT key, gives focus to the object. Default value is Empty.

Alignment
Specifies the object alignment on the Screen relative to its legend. The available options
are:

· 0 - fmAlignmentLeft: aligns the legend to the left of the object

V iew 159
· 1 - fmAligmentRight: aligns the legend to the right of the object

AutoSize
Adjusts text width, in case its available area is larger than the object size. For Checkbox and
Option Button objects, if the property is True, the text will be resized to fit the object current
size.

BackStyle
Defines the object background style. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no background will be

drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

Caption
Defines the text to be displayed on the object.

Font
Determines the object font. This property cannot be used in scripts or links, and it is
configured exclusively via E3 Studio.

GroupName
Creates a mutually exclusive group of objects.

NOTE: This property is not used in E3 and it is kept for compatibility reasons with Microsoft
Forms standard specification.

Locked
Enables or disables editing the object. If True, editing is not allowed; otherwise, it is. The
value configured for the Enabled property influences the Locked property behavior. For further
details, see the Enabled property. Default value is False.

Picture

Specifies the picture (bitmap) set to the object. An image file can be selected in two ways,
via Properties List; or via scripts, by using the LoadPicture method to specify the path and the
name of the file containing the picture. To remove the picture, click the value of the Picture
property and press the DEL key. The BACKSPACE key does not delete the picture. Example:

160 V iew
 Sub CommandButton1_Click()
Screen.Item("OptionButton1").Picture = LoadPicture("C:\tab.gif")
End Sub

PicturePosition
Specifies the picture position set to the object relative to its legend. The available options
for this property are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - fmPicturePositionLeftTop Picture appears on the left of its legend. The
legend is aligned to the upper side of the
picture.

1 - fmPicturePositionLeftCenter Picture appears on the left of its legend. The

legend is centered relative to the picture.

2 - fmPicturePositionLeftBottom Picture appears on the left of its legend. The

legend is aligned to the lower part of the
picture.

3 - fmPicturePositionRightTop Picture appears on the right of its legend. The

legend is aligned to the upper side of the
picture.

4 - fmPicturePositionRightCenter Picture appears on the right of its legend. The

legend is centered relative to the picture.

5 - fmPicturePositionRightBottom Picture appears on the right of its legend. The

legend is aligned to the lower part of the
picture.

6 - fmPicturePositionAboveLeft Picture appears above the legend. The

legend is aligned to the left side of the
picture.

7 - fmPicturePositionAboveCenter Picture appears above the legend. The

legend is centered below the picture
(default).

8 - fmPicturePositionAboveRight Picture appears above the legend. The

legend is aligned to the right side of the
picture.

9 - fmPicturePositionBelowLeft Picture appears below the legend. The

legend is aligned to the left side of the
picture.

10 - fmPicturePositionBelowCenter Picture appears below the legend. The

legend is centered above the picture.

V iew 161
 OPTION DESCRIPTION
11 - fmPicturePositionBelowRight Picture appears below the legend. The
legend is aligned to the right side of the
picture.

SpecialEffect
Specifies the object appearance. The available options are the following:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmButtonEffectFlat The object appears to be flat and has a raised
border, a color change or both.

2 - fmButtonlEffectSunken The object has a shadow on the upper left

side and is raised on the lower right side, as if
it is sunked on the Screen.

TextAlign
Specifies how text is aligned in the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left side of the object

· 2 - fmTextAlignCenter: centralizes text to the right side of the object

· 3 - fmTextAlignRight: aligns the text to the right side of the object

TripleState
Determines up to three value status for the object. If True, the user can choose from three
status options, False, True, or Null. The Null state is displayed as a shaded button. Otherwise,
the user can only choose from True or False values. Default value is False.

Value
Indicates the initial value of the object. Its behavior is Boolean. If True, its initial status is
checked, otherwise it will start unchecked. Default value is False.

WordWrap
Enables or disables line breaks in the text, in case the available area for the text overrides
the boundaries determined in the object.

162 V iew
4.3.2.12.5 Combo

This section contains information about events, methods, and properties of the Combo object.

4.3.2.12.5.1 Events

This section contains information about the events of the Combo object.

DropButtonClick
DropButtonClick()

It occurs when a Combo is displayed or hidden when clicking the object.

4.3.2.12.5.2 Methods

This section contains information about the methods of the Combo object.

AddItem
AddItem([pvargItem, ][pvargIndex])

Adds items to a Combo. pvargItem is a String containing the text to be added to the box. If
omitted, an empty String will be added. pvargIndex is the index of the Combo text. If omitted,
pvargItem is added as the last item on the Combo. Example:
Sub CommandButton1_Click()
EntryCount = EntryCount + 1
ComboBox1.AddItem(EntryCount & " - Selection")
End Sub

Clear
Clear()

Clears the text of the object. Example:

Sub ClearTextButton_Click()
ComboBox1.Clear()
End Sub

Copy
Copy()

Copies the previously selected text content to the Clipboard. Use the Paste method to paste
the content into the indicated place. Example:
Sub CommandButton1_Click()
Screen.Item("ComboBox1").Copy()
End Sub

Cut
Cut()

Cuts the previously selected text content to the Clipboard. Use the Paste method to paste the
content into the indicated place. Example:

V iew 163
 Sub CommandButton1_Click()
Screen.Item("ComboBox1").Cut()
End Sub

DropDown
DropDown()

This method opens the item list of a Combo. This is the same as clicking at run time in the right
side button of the object. Example:
Sub CommandButton1_Click()
Dim ComboBox1
ComboBox1.AddItem "Pineapple"
ComboBox1.AddItem "Strawberry"
ComboBox1.AddItem "Grape"
ComboBox1.AddItem "Orange"
ComboBox1.DropDown()
End Sub

Paste
Paste()

Inserts the content of the Clipboard into the object. Example:

Sub CommandButton1_Click()
Screen.Item("ComboBox1").Paste()
End Sub

RemoveItem
RemoveItem(pvargIndex)

Removes items from a Combo. This method has the pvargIndex parameter specifying the item
to be excluded. The first item number is 0, the second item number is 1, and so on. Example:
Sub CommandButton2_Click()
ComboBox1.SetFocus
' Check if the list contains the selected data
If ComboBox1.ListCount >= 1 Then
' If there is no selection, choose the last item.
If ComboBox1.ListIndex = -1 Then
ComboBox1.ListIndex = ComboBox1.ListCount – 1
End If
ComboBox1.RemoveItem(ComboBox1.ListIndex)
End If
End Sub

4.3.2.12.5.3 Properties

This section contains information about the properties of the Combo object.

AutoSize
Adjusts text width, in case its available area is larger than the object size. For the Combo
Box object, if the property is True, the text will be resized to fit the object's current size.

AutoTab
Enables or disables the object's automatic tabbing. If True, tabbing is automatic.
Otherwise, it is not. After users have typed the maximum number of characters in an object
(using the MaxLength property), focus moves automatically to the next object in the tabbing
order, whenever these characters are reached. For example, for a Combo Box to always
display stored data with five characters, you can use the MaxLength property to specify the
maximum number of characters to be typed in the object and the AutoTab property to

164 V iew
automatically move to the next object after users have typed five characters.

AutoWordSelect
Enables or disables the object's automatic word selection. If True, the whole word is
selected, plus the next white space. Otherwise, just the indicated character is selected.

BackStyle
Defines the object's background style. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no background will be

drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

BorderColor
Defines the border color applied to the object. Thus, it is possible to use the default color,
or personalize it while editing. To apply this property, the BorderStyle property must be set to
1 - fmBorderStyleSingle. Default value is black (RGB(0, 0, 0)).

BorderStyle
Defines the style of the border applied to the object. The available options are:

· 0 - fmBorderStyleNone: no border

· 1 - fmBorderStyleSingle: single border

BoundColumn
Establishes the column where data is stored on the list. For example, if each row has eight
items, and the BoundColumn property is 3, the system stores information on the third column
of the row currently selected. If value is 0, it is passed to the object's ListIndex property. If
value is 1 or higher, the indicated data is attributed to the column referring to the value
specified in the property. Columns start at 1.

NOTE: This property has no effect on E3 and it is kept for compatibility reasons with Microsoft
Forms standard specification.

CanPaste
Specifies whether Clipboard area contains data supported by the object. If True, the object
can receive information pasted from Clipboard area. However, if the data in this area is in a
format the object does not support, this property is False. This property is only available at run

V iew 165
time.

Column
Specifies the object's row and column. If only the column value is specified, the Column
property reads or writes the column specified on the object's current row. For example,
MyComboBox.Column(3) reads or writes the third column of the object. This property is
only available at run time.

ColumnCount
Specifies the number of columns of the object. If it is set to 0, no columns will be displayed. If
set to -1, all available columns will appear. Default value is 1.

ColumnHeads
Enables or disables displaying column titles in the object. If True, the title is displayed.
Otherwise, it is not. Default value is False.

ColumnWidths
Specifies the object's column width, in points. If value is -1 or blank, width is calculated on
the column (minimum width in a calculated column is 72 points, or 1 inch). If value is 0, column
is hidden. To produce narrower columns, you should specify width in the property, or use one
of the values on the next table.

Available options for ColumnWidths

OPTION DESCRIPTION
90;72;90 First column is 90 points (1.25 inches);
second column is 72 points (1 inch); third
column is 90 points.

6 cm;0;6 cm First column is 6 centimeters; second column

is hidden; third column is 6 centimeters. As
part of the third column is visible, an
horizontal scrollbar is visible.

1.5 in;0;2.5 in First column is 1.5 inches, second column is

hidden, and the third column is 2.5 inches.

2 in;;2 in First column is 2 inches, second column is 1

inch (default), and the third column is 2
inches. As only half of the third column is
visible, an horizontal scrollbar is visible.

(Empty) All three columns are the same width (1.33

inches). The default value of this property is
empty (E3 will use the system's default value.

166 V iew
CurTargetX
Returns the horizontal insertion position of a text in the object. This position is measured in
HIMETRIC units. You can use either CurTargetX or CurX properties to move the insertion point
in a text as users pass over the object content. When users move the insertion point to
another row in the text, the CurTargetX property specifies the most appropriate position for
the text's insertion point. CurX property is defined in this value, if the text row is bigger than
the value of CurTargetX. Otherwise, CurX property is defined as the text row ending. This
property is available at run time only.

NOTE: This property has no effect in E3 and is kept for compatibility reasons with the
Microsoft Forms standard specification.

CurX
Specifies current horizontal text insertion position in the object. This property is applied to
an object with many rows, that is, whenever Multiline property is enabled. The return value is
valid when the object has focus. You can use either Multiline or CurX properties to place the
text insertion point as users pass over the object's content. When users move the insertion
point to another row in the text, CurTargetX property specifies the most appropriate position
for the text's insertion point. CurX property is defined in this value, if the text row is bigger than
the value of CurTargetX. Otherwise, CurX property is defined as the text row ending. This
property is available at run time only.

DragBehavior
Enables or disables the drag-and-drop resource of a text in the object content. The
available options for this property are:

· 0 - fmDragBehaviorDisabled: does not allow dragging and dropping a text in the object
content

· 1 - fmDragBehaviorEnabled: allows dragging and dropping a text in the object content

The default value of this property is 0 - fmDragBehaviorDisabled.

NOTE: The DragBehavior property has no effect if the Style property is set to 2 -
fmStyleDropDownList.

DropButtonStyle
Specifies the symbol displayed in the Combo button. The available options for this
property are:

Available options for DropButtonStyle

OPTION DESCRIPTION
0 - fmDropButtonStylePlain Displays a plain button, without a symbol.

V iew 167
 OPTION DESCRIPTION
1 - fmDropButtonStyleArrow Displays a down arrow (default).

2 - fmDropButtonStyleEllipsis Displays an ellipsis.

3 - fmDropButtonStyleReduce Displays an horizontal line with an

underscore character.

The default value of this property is 1 - fmDropButtonStyleArrow.

EnterFieldBehavior
Controls how text content is selected in the editing area when TAB key is pressed on the
object, and not when the object receives focus as the result of a SetFocus method. The
available options are:

· 0 - fmEnterFieldBehaviorSelectAll: selects the whole text content when the TAB key is
pressed in the object

· 1 - fmEnterFieldBehaviorRecallSelection: selection remains unaltered

The default value of this property is 0 - fmEnterFieldBehaviorSelectAll.

Font
Determines the object font. It cannot be used in scripts or Links, and it is configured
exclusively via E3 Studio.

HideSelection
Specifies whether the selected text is still highlighted when the object does not have focus
anymore. If True, the selected text only remains highlighted in case the object has focus.
Otherwise, the object will always appear highlighted, no matter if it has the focus. Default
value is True.

IMEMode
The IMEMode property specifies the IME (Input Method Editor) mode of an object.

NOTE: This property only applies to applications written in Eastern languages (Chinese
Simplified and Traditional, Korean, and Japanese) and it is ignored in other applications. It
was kept for compatibility reasons with Microsoft Forms standard specification.

The available options are the following:

168 V iew
 Available options for IMEMode

OPTION DESCRIPTION
0 - fmIMEModeNoControl No IME control (default).

1 - fmIMEModeOn IME mode on.

2 - fmIMEModeOff IME mode off. English mode.

3 - fmIMEModeDisable IME mode off. Users cannot activate IME

mode via keyboard.

4 - fmIMEModeHiragana IME mode on with Hiragana mode (Full

Width).

5 - fmIMEModeKatakanaFull IME mode on with Katakana mode (Full

Width).

6 - fmIMEModeKatakana IME mode on with Katakana mode (Half

Width).

7 - fmIMEModeAlphaFull IME mode on with Alphanumeric mode (Full

Width).

8 - fmIMEModeAlpha IME mode on with Alphanumeric mode (Half

Width).

9 - fmIMEModeHangulFull IME mode on with Hangul mode (Full Width).

10 - fmIMEModeHangul IME mode on with Hangul mode (Half Width).

11 - fmIMEModeHanziFull IME mode on with Hanzi mode (Full Width).

12 - fmIMEModeHanzi IME mode on with Hanzi mode (Half Width).

LineCount
Returns the row number of the object. This property is only available at run time.

List
Returns or defines column and row entries on the object list. Column and row numbering
starts at zero; it means that the number of the first column and of the first row on the list are
zero, the second column and row are 1, and so on. This property is only available at run time.

ListCount
Returns the number of items in the object list. This property is only available at run time.

V iew 169
ListIndex
Identifies the item currently selected on the list (index). Values for this property go from -1 to
the total amount of rows in a list minus one (that is, ListCount - 1). When no row is selected,
ListIndex returns -1. When the user selects a row in a Combo, the system defines the value of
ListIndex property. The list's first row value of this property is 0, the second row value is 1, and
so on. This property is only available at run time.

ListRows
Determines the maximum amount of rows on the object list. Default value is 8.

ListStyle
Determines the object list style. The available options for this property are:

· 0 - fmListStylePlain: list with background items in plain style

· 1 - fmListStyleOption: displays option buttons or combo boxes for a list with several options.
When the user selects one item of the group, the option button associated to this item is
selected and the option buttons of the other group items are unchecked

The default value of this property is 0 - fmListStylePlain.

ListWidth
Determines the width of the object list. Default value is 0.

Locked
Enables or disables object editing. If True, editing is not allowed; otherwise, it is. The value
configured for the Enabled property influences the behavior of the Locked property. For further
details, see the Enabled property. Default value is False.

MatchEntry
Searches for a text entry that matches the data in the object. When a text instance is
found, the row with the text is highlighted, and column content is displayed. The available
options are the following:

· 0 - fmMatchEntryFirstLetter: search for a text entry that matches the first character typed in
the object. If the same character is repeatedly typed, moves to the next entry type which
starts with that character, and so on

· 1 - fmMatchEntryComplete: as every character is typed, the object searches for a text entry
that matches the typed characters

· 2 - fmMatchEntryNone: does not perform a search in the object

The default value of this property is 1 - fmMatchEntryComplete.

170 V iew
MatchFound
Indicates whether the text users have typed in the object matches any entry in the list. If
True, the Value property content matches one of the records on the list. Otherwise, the Value
property content does not match any of the records on the list (default). This property is
available only at run time, and does not apply if the MatchEntry property is set to 2. Default
value is False.

MatchRequired
Specifies whether the typed text should match or not the items in Combo. If True, users
cannot leave the box until the text inserted matches an item on the object. Otherwise, the
inserted text on the Combo can be different from all existing data on it.

MaxLength
Determines the maximum number of characters in the object. If set to 0, there will be no
character limit in the object.

SelectionMargin
Enables or disables the object's selection margin. If True, the text will be selected when
clicking the object's margin. Otherwise, the text will not be selected when clicking the margin.

NOTE: If the SelectionMargin property is set to True when the object is being printed,the
selection margin will also be printed.

SelLength
Returns the number of selected characters in the object. This property is only available at
run time.

SelStart
Indicates the starting point of the selected text, or the insertion point if no text is selected.
This property is only available at run time.

SelText
Returns the text selected in the object. This property is only available at run time.

ShowDropButtonWhen
Specifies when the drop button (object browsing key) is displayed. The available options
are:

· 0 - fmShowDropButtonWhenNever: does not display a drop button

· 1 - fmShowDropButtonWhenFocus: only display the drop button when the object has focus

· 2 - fmShowDropButtonWhenAlways: always displays a drop button

V iew 171
SpecialEffect
Specifies the object appearance. The available options are:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmSpecialEffectFlat Object looks flat and has a raised border, a
color change, or both.

1 - fmSpecialEffectRaised Object is raised on the upper left side, and a

shadow on the right lower side, as a relief.

2 - fmSpecialEffectSunken Object has a shadow on the left upper side,

and is raised on the right lower side. The
object and its border looks sunken on the
Screen.

3 - fmSpecialEffectEtched Border looks etched around the edges of the

object.

6 - fmSpecialEffectBump Object has a ledge on the right lower side,

and looks flat on the left upper side.

Style
Determines the object style. The available options are:

· 0 - fmStyleDropDownCombo: the object behaves as a drop down combo. Users may type a
value on the editing area or select a value from the drop down list (default)

· 2 - fmStyleDropDownList: the object behaves as a list. Users must choose a value from a list

Text
Returns the text of the selected option. This property is only available at run time.

TextAlign
Specifies how text is aligned inside the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left of the object

· 2 - fmTextAlignCenter: aligns the text to the center of the object

· 3 - fmTextAlignRight: aligns the text to the right of the object

172 V iew
TextColumn
Identifies the column in the object. The values for this property range from -1 to the number
of columns in the list. TextColumn property value for the first column is 1, for the second
column is 2, and so on. When the TextColumn property is set to 0, values of the ListIndex
property will be displayed. When the TextColumn property is set to -1, the first column with
ColumnWidths property value greater than 0 will be displayed.

TextLength
Returns the number of characters typed in the object. This property is only available at run
time.

TopIndex
Defines or returns the item in the combo which is on the top of the list. This property returns
-1 if the list is empty or hidden.

Value
This is the value in the BoundColumn property of currently selected rows. For a Combo Box,
changing the contents of the Value property does not change the value of BoundColumn
property. To add or delete entries in a ComboBox, you can use either AddItem or RemoveItem
methods.

4.3.2.12.6 Command Button

This section contains information about events and properties of the Command Button object.
This object does not have methods associated to it.

4.3.2.12.6.1 Events

This section contains information about the events of the Command Button object.

MouseMove
MouseMove()

This event occurs when mouse pointer is moved over a Command Button.

4.3.2.12.6.2 Properties

This section contains information about the properties of the Command Button object.

Accelerator
Defines or gets the accelerator key of the object. This accelerator key is a shortcut key
which, used with the ALT key, gives focus to the object. The default value of this property is
empty.

V iew 173
AutoSize
Adjusts text width, in case its available area is larger than the object size. For the Command
Button object, if the property is True, the text will be resized to fit the current size of the object.
The text content is cut when it exceeds the object area.

BackStyle
Defines the background style of the object. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no object background

will be drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

Caption
Defines the text to be displayed in the object.

Font
This property is used to determine the object font. This property cannot be used on scripts
or Links, it must be configured only in Studio.

Locked
Enables or disables object editing. If True, editing is not allowed; otherwise, it is. The value
configured for the Enabled property influences the Locked property behavior. For further
details, see the Enabled property. Default value is False.

Picture

Specifies the picture (bitmap) attributed to the object. An image file can be selected in two
ways. Via Properties List; or via scripts, by using the LoadPicture function to specify the path
and the name of the file containing the picture. To remove the picture, click the value of
Picture property and press the DEL key. The BACKSPACE key does not delete the picture.

174 V iew
PicturePosition
Specifies the position of the picture attributed to the object relative to its legend. The
available options for this property are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - fmPicturePositionLeftTop Picture appears on the left of its legend. The
legend is aligned to the upper side of the
picture.

1 - fmPicturePositionLeftCenter Picture appears on the left of its legend. The

legend is centered relative to the picture.

2 - fmPicturePositionLeftBottom Picture appears on the left of its legend. The

legend is aligned to the lower part of the
picture.

3 - fmPicturePositionRightTop Picture appears on the right of its legend. The

legend is aligned to the upper side of the
picture.

4 - fmPicturePositionRightCenter Picture appears on the right of its legend. The

legend is centered relative to the picture.

5 - fmPicturePositionRightBottom Picture appears on the right of its legend. The

legend is aligned to the lower part of the
picture.

6 - fmPicturePositionAboveLeft Picture appears above the legend. The

legend is aligned to the left side of the
picture.

7 - fmPicturePositionAboveCenter Picture appears above the legend. The

legend is centered below the picture
(default).

8 - fmPicturePositionAboveRight Picture appears above the legend. The

legend is aligned to the right side of the
picture.

9 - fmPicturePositionBelowLeft Picture appears below the legend. The

legend is aligned to the left side of the
picture.

10 - fmPicturePositionBelowCenter Picture appears below the legend. The

legend is centered above the picture.

V iew 175
 OPTION DESCRIPTION
11 - fmPicturePositionBelowRight Picture appears below the legend. The
legend is aligned to the right side of the
picture.

TakeFocusOnClick
Specifies whether the object takes focus when clicked. If True, it does. Otherwise, the
object does not take focus when clicked.

WordWrap
Enables or disables line breaks in text, in case the available area for the text overrides the
limits determined in the object.

4.3.2.12.7 Label

This section contains information about properties of the Label object. This object does not
have events nor methods associated to it.

4.3.2.12.7.1 Properties

This section contains information about the properties of the Label object.

Accelerator
Defines or get the accelerator key of the object. This accelerator key is a shortcut key which,
used with the ALT key, gives focus to the object. The default value of this property is empty.

AutoSize
Adjusts text width, in case its available area is larger than the object size. For the Label
object, when this property is set to True, text is resized to match the current size of the object.

BackStyle
Defines the background style of the object. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no object background

will be drawn

· 1 - fmBackStyleOpaque (valor padrão): defines the object as opaque, that is, the background
will be drawn (default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

176 V iew
BorderColor
Defines the color of the border applied to the object. Thus, it is possible to use the default
color, or personalize it while editing. To apply this property, the BorderStyle property must be
set to 1 - fmBorderStyleSingle. Default value is black (RGB(0, 0, 0)).

BorderStyle
Defines the style of the border applied to the object. The available options are:

· 0 - fmBorderStyleNone: no border

· 1 - fmBorderStyleSingle: single border

Caption
Defines the text to be displayed in the object.

Font
This property is used to determine the object font. This property cannot be used on scripts
or Links, it must be configured only in Studio.

Picture

Specifies the picture (bitmap) attributed to the object. An image file can be selected in two
ways. Via Properties List; or via scripts, by using the LoadPicture function to specify the path
and the name of the file containing the picture. To remove the picture, click the value of
Picture property and press DEL key. The BACKSPACE key does not delete the picture.

PicturePosition
Specifies the position of the picture attributed to the object relative to its legend. The
available options for this property are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - fmPicturePositionLeftTop Picture appears on the left of its legend. The
legend is aligned to the upper side of the
picture.

1 - fmPicturePositionLeftCenter Picture appears on the left of its legend. The

legend is centered relative to the picture.

2 - fmPicturePositionLeftBottom Picture appears on the left of its legend. The

legend is aligned to the lower part of the
picture.

3 - fmPicturePositionRightTop Picture appears on the right of its legend. The

legend is aligned to the upper side of the
picture.

V iew 177
 OPTION DESCRIPTION
4 - fmPicturePositionRightCenter Picture appears on the right of its legend. The
legend is centered relative to the picture.

5 - fmPicturePositionRightBottom Picture appears on the right of its legend. The

legend is aligned to the lower part of the
picture.

6 - fmPicturePositionAboveLeft Picture appears above the legend. The

legend is aligned to the left side of the
picture.

7 - fmPicturePositionAboveCenter Picture appears above the legend. The

legend is centered below the picture
(default).

8 - fmPicturePositionAboveRight Picture appears above the legend. The

legend is aligned to the right side of the
picture.

9 - fmPicturePositionBelowLeft Picture appears below the legend. The

legend is aligned to the left side of the
picture.

10 - fmPicturePositionBelowCenter Picture appears below the legend. The

legend is centered above the picture.

11 - fmPicturePositionBelowRight Picture appears below the legend. The

legend is aligned to the right side of the
picture.

SpecialEffect
Specifies the object appearance. The available options are:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmSpecialEffectFlat Object looks flat and has a raised border, a
color change, or both.

1 - fmSpecialEffectRaised Object is raised on the upper left side, and a

shadow on the right lower side, as a relief.

2 - fmSpecialEffectSunken Object has a shadow on the left upper side,

and is raised on the right lower side. The
object and its border looks sunken on the
Screen.

178 V iew
 OPTION DESCRIPTION
3 - fmSpecialEffectEtched Border looks etched around the edges of the
object.

6 - fmSpecialEffectBump Object has a ledge on the right lower side,

and looks flat on the left upper side.

TextAlign
Specifies how text is aligned inside the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left of the object

· 2 - fmTextAlignCenter: aligns the text to the center of the object

· 3 - fmTextAlignRight: aligns the texto to the right of the object

WordWrap
Enables or disables line breaks in text, in case the available area for the text overrides the
limits determined in the object. For this property to work, Multiline property must be True.

4.3.2.12.8 List

This section contains information about events and properties of the List object. This object
does not have events associated to it.

4.3.2.12.8.1 Methods

This section contains information about the methods of the List object.

AddItem
AddItem([pvargItem, ][pvargIndex])

Adds items to a List. pvargItem is a String containing the text to be added to the List. If omitted,
an empty String will be added. pvargIndex is the index of the List text. If omitted, pvargItem is
added as the last item on the List. Example:
Sub CommandButton1_Click()
EntryCount = EntryCount + 1
ListBox1.AddItem(EntryCount & " - Selection")
End Sub

Clear
Clear()

Clears the text of the object. Example:

Sub ClearTextButton_Click()
ListBox1.Clear()
End Sub

V iew 179
RemoveItem
RemoveItem(pvargIndex)

Removes items from a List. This method has the pvargIndex parameter specifying the item to
be excluded. The first item number is 0, the second item number is 1, and so on. Example:
Sub CommandButton2_Click()
List1.SetFocus
' Checks if the list has selected items
If List1.ListCount >= 1 Then
' If there is no selection, chooses the last item of the list.
If List1.ListIndex = -1 Then
List1.ListIndex = List1.ListCount – 1
End If
List1.RemoveItem(List1.ListIndex)
End If
End Sub

4.3.2.12.8.2 Properties

This section contains information about the properties of the List object.

BorderColor
Defines the border color applied to the object. Thus, it is possible to use the default color,
or personalize it while editing. To apply this property, the BorderStyle property must be set to
1 - fmBorderStyleSingle. Default value is black (RGB(0, 0, 0)).

BorderStyle
Defines the style of the border applied to the object. The available options are:

· 0 - fmBorderStyleNone: no border

· 1 - fmBorderStyleSingle: single border

BoundColumn
Establishes the column where data is stored on the List. For example, if each row has eight
items, and the BoundColumn property is 3, the system stores information on the third column
of the currently selected row. If value is 0, it is passed to the object's ListIndex property. If
value is 1 or higher, the indicated data is attributed to the column referring to the value
specified in the property. Columns start at 1.

NOTE: This property has no effect on E3 and it is kept for compatibility reasons with Microsoft
Forms standard specification.

Column
Specifies the object's row and column. If only the column value is specified, the Column
property reads or writes the column specified on the object's current row. For example,
MyListBox.Column(3) reads or writes the third column of the object. This property is
only available at run time.

180 V iew
ColumnCount
Specifies the number of columns of the object. If it is set to 0, no columns will be displayed. If
set to -1, all available columns will appear. Default value is 1.

ColumnHeads
Enables or disables displaying column titles in the object. If True, the title is displayed.
Otherwise, it is not. Default value is False.

ColumnWidths
Specifies the object's column width, in points. If value is -1 or blank, width is calculated on
the column (minimum width in a calculated column is 72 points, or 1 inch). If value is 0, column
is hidden. To produce narrower columns, you should specify a width in the property, or use one
of the values on the next table.

Available options for ColumnWidths

OPTION DESCRIPTION
90;72;90 First column is 90 points (1.25 inches);
second column is 72 points (1 inch); third
column is 90 points.

6 cm;0;6 cm First column is 6 centimeters; second column

is hidden; third column is 6 centimeters. As
part of the third column is visible, an
horizontal scrollbar is visible.

1.5 in;0;2.5 in First column is 1.5 inches, second column is

hidden, and the third column is 2.5 inches.

2 in;;2 in First column is 2 inches, second column is 1

inch (default), and the third column is 2
inches. As only half of the third column is
visible, an horizontal scrollbar is visible.

(Empty) All three columns are the same width (1.33

inches). The default value of this property is
empty (E3 will use the system's default
value).

Font
Determines the object font. It cannot be used in scripts or Links, and it is configured
exclusively via E3 Studio.

V iew 181
IMEMode
The IMEMode property specifies the IME (Input Method Editor) mode of an object.

NOTE: This property only applies to applications written in Eastern languages (Chinese
Simplified and Traditional, Korean, and Japanese) and it is ignored in other applications. It
was kept for compatibility reasons with Microsoft Forms standard specification.

The available options are the following:

Available options for IMEMode

OPTION DESCRIPTION
0 - fmIMEModeNoControl No IME control (default).

1 - fmIMEModeOn IME mode on.

2 - fmIMEModeOff IME mode off. English mode.

3 - fmIMEModeDisable IME mode off. Users cannot activate IME

mode via keyboard.

4 - fmIMEModeHiragana IME mode on with Hiragana mode (Full

Width).

5 - fmIMEModeKatakanaFull IME mode on with Katakana mode (Full

Width).

6 - fmIMEModeKatakana IME mode on with Katakana mode (Half

Width).

7 - fmIMEModeAlphaFull IME mode on with Alphanumeric mode (Full

Width).

8 - fmIMEModeAlpha IME mode on with Alphanumeric mode (Half

Width).

9 - fmIMEModeHangulFull IME mode on with Hangul mode (Full Width).

10 - fmIMEModeHangul IME mode on with Hangul mode (Half Width).

11 - fmIMEModeHanziFull IME mode on with Hanzi mode (Full Width).

12 - fmIMEModeHanzi IME mode on with Hanzi mode (Half Width).

182 V iew
IntegralHeight
Adjusts height in text editing area, in case its available area exceeds the object size. If True,
its height is adjusted to fit the object's current size, thus displaying the whole text. Otherwise,
the size of text editing area remains the same. If a text is larger than the available space, it will
not be displayed in the object.

List
Returns or defines column and row entries on the object list. Column and row numbering
starts at zero; it means that the number of the first column and of the first row on the list are
zero, the second column and row are 1, and so on. This property is only available at run time.

ListCount
Returns the number of items in the object list. This property is only available at run time.

ListIndex
Identifies the item currently selected on the list (index). The values of this property go from -
1 to the total amount of rows in a list minus one (that is, ListCount - 1). When no row is
selected, ListIndex returns -1. When users select a row in a List, the system defines the value
of ListIndex property. The List's first row value of this property is 0, the second row value is 1,
and so on. This property is only available at run time.

ListStyle
Determines the object list style. The available options for this property are:

· 0 - fmListStylePlain: list with background items in plain style

· 1 - fmListStyleOption: displays option buttons or combo boxes for a list with several options.
When users select one item of the group, the option button associated to this item is
selected and the option buttons of the other group items are unchecked

The default value of this property is 0 - fmListStylePlain.

NOTE: The option 1 - fmListStyleOption can only be enabled if the MultiSelect property is set
to 1 - fmMultiselectMulti.

Locked
Enables or disables object editing. If True, editing is not allowed; otherwise, it is. The value
configured for the Enabled property influences the behavior of the Locked property. For further
details, see the Enabled property. Default value is False

MatchEntry
Searches for a text entry that matches data in the object. When a text instance is found,
the row with the text is highlighted, and column content is displayed. The available options
are the following:

V iew 183
· 0 - fmMatchEntryFirstLetter: search for a text entry that matches the first character typed in
the object. If the same character is repeatedly typed, moves to the next entry type which
starts with that character, and so on

· 1 - fmMatchEntryComplete: as every character is typed, the object searches for a text entry
that matches the typed characters

· 2 - fmMatchEntryNone: does not perform a search in the object

The default value of this property is 1 - fmMatchEntryComplete.

MultiSelect
Indicates whether the object allows multiple selections. The available options for this
property are:

· 0 - fmMultiSelectSingle: only one item can be selected

· 1 - fmMultiSelectMulti: allows selecting one item by pressing the space bar or by clicking
the mouse, thus checking or unchecking an item in the list

· 2 - fmMultiSelectExtended: allows selecting one item by pressing the SHIFT key, by clicking
the mouse, or by pressing the SHIFT key and one of the arrow keys, extending the selection
to the current item. Pressing the CTRL key and clicking the mouse, checks or unchecks the
item

The default value of this property is 0 - fmMultiSelectSingle.

Selected
Selects or deselects an item, and checks whether an item is selected, when Multiline
property is True. To check whether the item is selected or not, the item index must be passed,
and the property returns its selection status. So, it is possible to see which items are selected
when users select more than one. This property is only available at run time. When multiple
selections are not used, it is recommended using the Value or the ListIndex properties.

SpecialEffect
Specifies the object appearance. The available options are:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmSpecialEffectFlat Object looks flat and has a raised border, a
color change, or both.

1 - fmSpecialEffectRaised Object is raised on the upper left side, and a

shadow on the right lower side, as a relief.

184 V iew
 OPTION DESCRIPTION
2 - fmSpecialEffectSunken Object has a shadow on the left upper side,
and is raised on the right lower side. The
object and its border looks sunken on the
Screen.

3 - fmSpecialEffectEtched Border looks etched around the edges of the

object.

6 - fmSpecialEffectBump Object has a ledge on the right lower side,

and looks flat on the left upper side.

Text
Returns the text of the selected option. This property is only available at run time.

TextAlign
Specifies how text is aligned inside the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left of the object

· 2 - fmTextAlignCenter: aligns the text to the center of the object

· 3 - fmTextAlignRight: aligns the text to the right of the object

TextColumn
Identifies the column in the object. The values for this property range from -1 to the number
of columns in the list. TextColumn property value for the first column is 1, for the second
column is 2, and so on. When the TextColumn property is set to 0, values of the ListIndex
property will be displayed. When the TextColumn property is set to -1, the first column with
ColumnWidths property value greater than 0 will be displayed.

TopIndex
Defines or returns the item in the List which is on top of the list. This property returns -1 if
the list is empty or hidden.

Value
This is the value of the BoundColumn property of the currently selected rows. This property
has no effect in E3 and is kept for compatibility reasons with Microsoft Forms standard
specification.

4.3.2.12.9 Toggle Button

This section contains information about events and properties of the Toggle Button. This
object does not have methods associated to it.

V iew 185
4.3.2.12.9.1 Events

This section contains information about the events of the Toggle Button object.

MouseMove
MouseMove()

This event occurs when mouse pointer is moved over the Toggle Button object.

4.3.2.12.9.2 Properties

This section contains information about the properties of the Toggle Button object.

Accelerator
Defines or gets the accelerator key of the object. This accelerator key is a shortcut key
which, used with the ALT key, gives focus to the object. The default value of this property is
empty.

Alignment
Specifies the object alignment on the Screen, relative to its legend. The available options
are:

· 0 - fmAlignmentLeft: aligns the legend to the left of the object

· 1 - fmAligmentRight: aligns the legend to the right of the object

AutoSize
Adjusts text width, in case its available area is larger than the object size. For the Toggle
Button object, when this property is set to True, the text is resized to match the current size of
the object.

BackStyle
Defines the background style of the object. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no object background

will be drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

186 V iew
Caption
Defines the text to be displayed in the object.

Font
This property is used to determine the object font. This property cannot be used on scripts
or Links, it must be configured only in Studio.

GroupName
Creates a mutually exclusive group of objects. This property is only available at run time.

NOTE: This property is not used in E3 and it is kept for compatibility reasons with Microsoft
Forms standard specification.

Locked
Enables or disables object editing. If True, editing is not allowed; otherwise, it is. The value
configured for the Enabled property influences the Locked property behavior. For further
details, see the Enabled property. Default value is False.

Picture

Specifies the picture (bitmap) attributed to the object. An image file can be selected in two
ways. Via Properties List; or via scripts, by using the LoadPicture function to specify the path
and the name of the file containing the picture. To remove the picture, click the value of
Picture property and press the DEL key. The BACKSPACE key does not delete the picture.

PicturePosition
Specifies the position of the picture attributed to the object relative to its legend. The
available options for this property are:

Available options for PicturePosition

OPTION DESCRIPTION
0 - fmPicturePositionLeftTop Picture appears on the left of its legend. The
legend is aligned to the upper side of the
picture.

1 - fmPicturePositionLeftCenter Picture appears on the left of its legend. The

legend is centered relative to the picture.

2 - fmPicturePositionLeftBottom Picture appears on the left of its legend. The

legend is aligned to the lower part of the
picture.

3 - fmPicturePositionRightTop Picture appears on the right of its legend. The

legend is aligned to the upper side of the
picture.

V iew 187
 OPTION DESCRIPTION
4 - fmPicturePositionRightCenter Picture appears on the right of its legend. The
legend is centered relative to the picture.

5 - fmPicturePositionRightBottom Picture appears on the right of its legend. The

legend is aligned to the lower part of the
picture.

6 - fmPicturePositionAboveLeft Picture appears above the legend. The

legend is aligned to the left side of the
picture.

7 - fmPicturePositionAboveCenter Picture appears above the legend. The

legend is centered below the picture
(default).

8 - fmPicturePositionAboveRight Picture appears above the legend. The

legend is aligned to the right side of the
picture.

9 - fmPicturePositionBelowLeft Picture appears below the legend. The

legend is aligned to the left side of the
picture.

10 - fmPicturePositionBelowCenter Picture appears below the legend. The

legend is centered above the picture.

11 - fmPicturePositionBelowRight Picture appears below the legend. The

legend is aligned to the right side of the
picture.

SpecialEffect
Specifies the object appearance. The available options are:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmSpecialEffectFlat Object looks flat and has a raised border, a
color change, or both.

1 - fmSpecialEffectRaised Object is raised on the upper left side, and a

shadow on the right lower side, as a relief.

2 - fmSpecialEffectSunken Object has a shadow on the left upper side,

and is raised on the right lower side. The
object and its border looks sunken on the
Screen.

188 V iew
 OPTION DESCRIPTION
3 - fmSpecialEffectEtched Border looks etched around the edges of the
object.

6 - fmSpecialEffectBump Object has a ledge on the right lower side,

and looks flat on the left upper side.

TextAlign
Specifies how text is aligned inside the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left of the object

· 2 - fmTextAlignCenter: aligns the text to the center of the object

· 3 - fmTextAlignRight: aligns the text to the right of the object

TripleState
Determines up to three value status for the object. If True, users can choose from three
status options: False, True, or Null. The Null state is displayed as a shaded button. Otherwise,
users can only choose from True or False values. Default value is False.

Value
Indicates the initial value of the object. It has a Boolean behavior. If True, the object starts
checked; otherwise, its initial state is unchecked. The default value of this property is False.

WordWrap
Enables or disables line breaks in text, in case the available area for the text overrides the
limits determined in the object. For this property to work, Multiline property must be True.

4.3.2.12.10 Text

This section contains information about events, methods, and properties of the Text object.

4.3.2.12.10.1 Events

This section contains information about the events of the Text object.

DropButtonClick
DropButtonClick()

This event occurs whether the options list appears or disappears when clicking the object.

V iew 189
4.3.2.12.10.2 Methods

This section contains information about the methods of the Text object.

Copy
Copy()

Copies to the Clipboard Area a text previously selected. Use the Paste method to paste the text
in another place. Example:
Sub CommandButton1_Click()
Screen.Item("TextBox1").Copy()
End Sub

Cut
Cut()

Cuts to the Clipboard Area a text previously selected. Use the Paste method to paste the text in
another place. Example:
Sub CommandButton1_Click()
Screen.Item("TextBox1").Cut()
End Sub

Paste
Paste()

Inserts into the Text the content of the Clipboard Area. Example:
Sub CommandButton1_Click()
Screen.Item("TextBox1").Paste()
End Sub

4.3.2.12.10.3 Properties

This section contains information about the properties of the Text object.

AutoSize
The AutoSize property adjusts text width, in case its available area exceeds the size of the
object. For the Text object, when this property is set to True, the text width is readjusted to the
same width of the object. The default value of this property is False.

NOTE: It is advisable to avoid using the AutoSize property with a Text which also uses the
Multiline and WordWrap properties. When users type into a Text with these properties set to
True, it will automatically resize itself as a long and narrow text box, with a width of one
character and a size of one text row.

AutoTab
Enables or disables the object's automatic tabbing. If True, tabbing is automatic.
Otherwise, it is not. After users have typed the maximum number of characters in an object
(using the MaxLength property), focus moves automatically to the next object in the tabbing
order, whenever these characters are reached. For example, for a Text object to always

190 V iew
display stored data with five characters, you can use the MaxLength property to specify the
maximum number of characters to be typed in the object and the AutoTab property to
automatically move to the next object after users have typed five characters.

AutoWordSelect
Enables or disables the object's automatic word selection. If True, the whole word is
selected, plus the next white space. Otherwise, just the indicated character is selected.

BackStyle
Defines the object's background style. The available options are:

· 0 - fmBackStyleTransparent: defines the object as transparent, that is, no background will be

drawn

· 1 - fmBackStyleOpaque: defines the object as opaque, that is, the background will be drawn
(default value)

NOTE: This property does no affect bitmap transparency. You should use an image editor like
Paintbrush, for example, to save a bitmap as transparent. Not all ActiveX objects support
transparent bitmaps.

BorderColor
Defines the border color applied to the object. Thus, it is possible to use the default color,
or personalize it while editing. To apply this property, the BorderStyle property must be set to
1 - fmBorderStyleSingle. Default value is black (RGB(0, 0, 0)).

BorderStyle
Defines the style of the border applied to the object. The available options are:

· 0 - fmBorderStyleNone: no border

· 1 - fmBorderStyleSingle: single border

CanPaste
Specifies whether Clipboard Area contains data supported by the object. If True, the object
can receive information pasted from Clipboard Area. However, if data in this Area is in a
format the object does not support, this property is False. This property is only available at run
time.

CurLine
Specifies the current object's row, that is, the row that contains the text insertion point. The
number of the first row is 0. The default value of this property is 0.

V iew 191
CurTargetX
Returns the horizontal insertion position of a text in the object. This position is measured in
Himetric units (0.0001 meters). You can use CurTargetX and CurX to move the insertion point of
a text while moving through the object content. When moving the insertion point to another
row of text, the CurTargetX property specifies the most indicated position for the desired text
insertion point. The CurX property is defined with this value, if the text row is greater than the
value of CurTargetX. Otherwise, the CurX property is defined as the ending of the text row. This
property is only accessible at run time.

CurX
Specifies current horizontal text insertion position in the object. This property is applied to
an object with many rows, that is, whenever Multiline property is enabled. The return value is
valid when the object has focus. You can use either Multiline or CurX properties to place the
text insertion point as users pass over the object's content. When users move the insertion
point to another row in the text, CurTargetX property specifies the most appropriate position
for the text's insertion point. CurX property is defined in this value, if the text row is greater
than the value of CurTargetX. Otherwise, CurX property is defined as the text row ending. This
property is only available at run time.

DragBehavior
Enables or disables the drag-and-drop resource of a text in the object content. The available
options for this property are:

· 0 - fmDragBehaviorDisabled: does not allow dragging and dropping a text in the object
content

· 1 - fmDragBehaviorEnabled: allows dragging and dropping a text in the object content

The default value of this property is 0 - fmDragBehaviorDisabled

NOTE: The DragBehavior property has no effect if the Style property is set to 2 -
fmStyleDropDownList.

EnterFieldBehavior
Controls how text content is selected in the edition area when TAB key is pressed on the
object, and not when the object receives focus as the result of the SetFocus method. The
available options are:

· 0 - fmEnterFieldBehaviorSelectAll (default): selects all the content of the text when TAB key
is pressed on the object

· 1 - fmEnterFieldBehaviorRecallSelection: the selection remains untouched

192 V iew
EnterKeyBehavior
Defines ENTER key behavior in the object. If True, whenever you press ENTER, a new line is
created in the object's text editing area. Otherwise, whenever you press ENTER, focus goes to
the next object in tab order. This also happens if Multiline property is set to False, regardless
of EnterKeyBehavior property value.

The combination CTRL+ENTER also depends on the value of Multiline property. If this property
is set to True, whenever these two keys are pressed together a new line is created in the
object's text editing area, regardless of EnterKeyBehavior property value. If the property is
False, the keys will have no effect on the text.

Font
Determines object's font. It cannot be used in scripts or Links, and it is configured
exclusively via Studio.

HideSelection
Specifies whether the selected text is still highlighted when the object does not have focus
anymore. If True, the selected text only remains highlighted in case the object has focus.
Otherwise, the object will always appear highlighted, regardless of the presence of focus in
the object. Default value is True.

IMEMode
The IMEMode property specifies the IME (Input Method Editor) mode of an object.

NOTE: This property only applies to applications written in Eastern languages (Chinese
Simplified and Traditional, Korean, and Japanese) and it is ignored in other applications. It
was kept for compatibility reasons with Microsoft Forms standard specification.

The available options are the following:

Available options for IMEMode

OPTION DESCRIPTION
0 - fmIMEModeNoControl No IME control (default).

1 - fmIMEModeOn IME mode on.

2 - fmIMEModeOff IME mode off. English mode.

3 - fmIMEModeDisable IME mode off. Users cannot activate IME

mode via keyboard.

4 - fmIMEModeHiragana IME mode on with Hiragana mode (Full

Width).

V iew 193
 OPTION DESCRIPTION
5 - fmIMEModeKatakanaFull IME mode on with Katakana mode (Full
Width).

6 - fmIMEModeKatakana IME mode on with Katakana mode (Half

Width).

7 - fmIMEModeAlphaFull IME mode on with Alphanumeric mode (Full

Width).

8 - fmIMEModeAlpha IME mode on with Alphanumeric mode (Half

Width).

9 - fmIMEModeHangulFull IME mode on with Hangul mode (Full Width).

10 - fmIMEModeHangul IME mode on with Hangul mode (Half Width).

11 - fmIMEModeHanziFull IME mode on with Hanzi mode (Full Width).

12 - fmIMEModeHanzi IME mode on with Hanzi mode (Half Width).

IntegralHeight
Property IntegralHeight adjusts height in text editing area, in case its available area
exceeds object size. If True, its height is adjusted to fit the object's current size, thus displaying
the whole text. Otherwise, the size of text editing area remains the same. If a text is larger than
the available space, it will not be displayed in the object.

LineCount
The LineCount property returns object's number of lines. This property is only available at
run time.

Locked
Enables or disables object editing. If True, editing is not allowed; otherwise, it is. The value
configured for the Enabled property influences the behavior of the Locked property. For further
details, see the Enabled property. Default value is False.

MaxLength
Determines the maximum number of characters in the object. If set to 0, there will be no
character limit in the object.

Multiline
This property indicates whether the text will have multiple lines (True) or be a simple text
box (False). It can be viewed when Viewer is running. Default value is False.

194 V iew
PasswordChar
Converts the object's text to a special character configured in the property. Use this
property to protect confidential information, such as passwords or security codes.
PasswordChar property's value is a character (usually an asterisk) that appears in the object
instead of the current characters the user types. If the character is not specified, the control
will display the characters actually typed.

ScrollBars
Specifies whether the object has vertical or horizontal scrollbars, or even both. The
available options are:

· 0 - fmScrollBarNone: no scroll bars are displayed

· 1 - fmScrollBarHorizontal: a horizontal scroll bar is displayed

· 2 - fmScrollBarVertical: a vertical scroll bar is displayed

Default value is 0 - fmScrollBarNone.

SelectionMargin
Enables or disables the object's selection margin. If True, the text will be selected when you
click the object's margin. Otherwise, the text will not be selected when you click the margin.

NOTE: If the SelectionMargin property is set to True when the object is being printed,the
selection margin will also be printed.

SelLength
Returns the number of selected characters in the object. This property is only available at
run time.

SelStart
Indicates the starting point of the selected text, or the insertion point if no text is selected.
This property is only available at run time.

SelText
Returns the text selected in the object. This property is only available at run time.

V iew 195
SpecialEffect
Specifies the object appearance. The available options are:

Available options for SpecialEffect

OPTION DESCRIPTION
0 - fmSpecialEffectFlat Object looks flat and has a raised border, a
color change, or both.

1 - fmSpecialEffectRaised Object is raised on the upper left side, and a

shadow on the right lower side, as a relief.

2 - fmSpecialEffectSunken Object has a shadow on the left upper side,

and is raised on the right lower side. The
object and its border looks sunken on the
Screen.

3 - fmSpecialEffectEtched Border looks etched around the edges of the

object.

6 - fmSpecialEffectBump Object has a ledge on the right lower side,

and looks flat on the left upper side.

TabKeyBehavior
Determines whether tab order is allowed at editing area. If True, whenever TAB key is
pressed, a space character is inserted at editing area. Otherwise, when TAB is pressed, focus
goes to the next object on the tab order.

Text
Returns the text being typed. This property is available only at run time.

TextAlign
Specifies how text is aligned inside the object. The available options are:

· 1 - fmTextAlignLeft: aligns the text to the left of the object

· 2 - fmTextAlignCenter: aligns the text to the center of the object

· 3 - fmTextAlignRight: aligns the text to the right of the object

TextLength
Returns the number of characters typed in the object. This property is only available at run
time.

196 V iew
Value
It is the text in the editing region.

WordWrap
Enables or disables line breaks in the text, in case the available area of the text overrides
the limits determined by the object. For this property to work, Multiline property must be
True.

4.3.2.12.11 Spin Button

This section contains information about events, methods, and properties of the Spin Button
object.

4.3.2.12.11.1 Events

This section contains information about the events of the Spin Button object.

SpinDown
SpinDown()

It occurs whenever users press the down arrow key. This event decreases the object Value
property.

SpinUp
SpinUp()

It occurs whenever users press the up arrow key. This event increases the object Value
property.

4.3.2.12.11.2 Properties

This section contains information about the properties of the Spin Button object.

Delay
Specifies the object's delay. Delay property affects the duration of time between
consecutive SpinUp, SpinDown and Change events, generated when users click the spin button
and keep it pressed. The first event occurs immediately. Delay until the second occurrence of
the event is five times the value specified for this property. After this initial occurrence, the
interval between events is the one specified at Delay property. Default value is 50 ms. This
means that the object starts the first event after 250 ms (five times the specified value), and
start the following events after every 50 ms.

Max
Determines the object's maximum limit.

V iew 197
Min
Determines the object's minimum limit.

Orientation
Determines object orientation on Screen. The options available for this property are:

· -1 - fmOrientationAuto: determines orientation automatically, based on the object's

dimensions, that is, how it was created

· 0 - fmOrientationVertical: the object is placed vertically

· 1 - fmOrientationHorizontal: the object is placed horizontally

Default value is -1 - fmOrientationAuto.

SmallChange
Specifies the amount of movement that happens when users click one of the object's scroll
arrows. Default value is 1.

Value
Integer between the values defined for Min and Max properties. It indicates spin's initial
value. It does not accept values lower than Min or higher than Max.

4.3.2.12.12 Scrollbar

This section contains information about events, methods, and properties of the Scrollbar
object.

4.3.2.12.12.1 Events

This section contains information about the events of the Scrollbar object.

Scroll
Scroll()

The Scroll event is generated when the scrolling bar pointer is moved to any direction.

4.3.2.12.12.2 Properties

This section contains information about the properties of the Scrollbar object.

198 V iew
Delay
Specifies the object's delay. Delay property affects the duration of time between
consecutive SpinUp, SpinDown and Change events, generated when users click the scrollbar
and keep it pressed. The first event occurs immediately. Delay until the second occurrence of
the event is five times the value specified for this property. After this initial occurrence, the
interval between events is the one specified at Delay property. Default value is 50 ms. This
means that the object starts the first event after 250 ms (five times the specified value), and
start the following events after every 50 ms.

LargeChange
Specifies the scroll bar cursor's number of steps. LargeChange property's value is the
quantity that alters Value property when users click the area between scroll box and scroll bar
cursor. Any integer will fit at LargeChange property, but the recommended interval is from -
32.767 to 32.767. Also, this value should be between the values of Max and Min properties.

Max
Determines the object's maximum limit.

Min
Determines the object's minimum limit.

Orientation
Determines object orientation on Screen. The options available for this property are:

· -1 - fmOrientationAuto: determines orientation automatically, based on the object's

dimensions, that is, how it was created

· 0 - fmOrientationVertical: the object is placed vertically

· 1 - fmOrientationHorizontal: the object is placed horizontally

Default value is -1 - fmOrientationAuto.

ProportionalThumb
The ProportionalThumb property specifies whether the scroll bar size is equal to the object
dimension. If this property is set to True, the scroll bar box has the same dimensions of the
object. Otherwise, if the object is resized, the scroll box remains with its original size. The
default value of this property is True.

SmallChange
Specifies the amount of movement that happens when users click one of the object's scroll
arrows. Default value is 1.

V iew 199
Value
Integer between the values defined for Min and Max properties. It indicates spin's initial
value. It does not accept values lower than Min or higher than Max.

4.3.2.13 E2Controls
This section contains information about events, methods, and properties of E2Control objects.

4.3.2.13.1 Common Properties

This section contains information about the common properties of the E2Control objects.

4.3.2.13.1.1 Frame_BorderColor

Defines a color for the Frame border.

4.3.2.13.1.2 Frame_BorderEnabled

Enables or disables a Frame border.

4.3.2.13.1.3 Frame_BorderThickness

Defines the thickness of the Frame border, in pixels.

4.3.2.13.1.4 Frame_Color

Defines the background color of the title area of the object. The default value of this
property is gray (RGB(192, 192, 192)).

4.3.2.13.1.5 Frame_Enable

Enables or disables the display of the Frame object. The default value of this property is
True, except for the E2Button object.

4.3.2.13.1.6 Frame_Enable3D

Enables or disables a 3D effect of the Frame object.

200 V iew
4.3.2.13.1.7 Frame_Separator

Enables or disables the display of a separator line between the title and the object.

4.3.2.13.1.8 Frame_Set3DInset

If this property is set to True, the object border appears as lowered. If it is False (default),
the object border appears as raised.

4.3.2.13.1.9 Frame_Thickness3D

Defines the thickness of the 3D border of the Frame object, in pixels.

4.3.2.13.1.10 Frame_Title

This property defines the title of the Frame object.

4.3.2.13.1.11 Frame_TitleColor

Defines the font color of the Frame title. The default value of this property is black (RGB(0, 0,
0)).

4.3.2.13.1.12 Frame_TitleEnabled

Enables or disables the display of the Frame title. The default value of this property is True.

4.3.2.13.1.13 Frame_TitleFont

The Frame_TitleFont property is used to determine the font of the Frame title. This property
cannot be used in scripts or Links, being set only via Studio.

4.3.2.13.2 E2Animation

This section contains information about properties of the E2Animation object. This object
does not have events nor methods associated to it.

4.3.2.13.2.1 Properties

This section contains information about the properties of the E2Animation object.

V iew 201
BackgroundColor
This property defines the background color of the E2Animation object. The default value of
this property is white (RGB(255, 255, 255)).

BlinkTime
Defines the time interval, in milliseconds, of the object's blinking effect.

Border
Enables or disables the display of a border around the object.

DefaultZone
Defines the default Zone, which is displayed when the associated Tag is out of the limits of
other Zones defined for the object.

IsTransparent
If the value of this property is True, defines that the object background is transparent,
allowing the screen background to appear. Otherwise, the background color is solid, as
defined in BackgroundColor.

Value
This property defines a value that determines what is the active Zone. The default value of
this property is 0.

Zones
Collection of Zones of the E2Animation object.

4.3.2.13.2.2 Zone Collection

This section contains information about methods of the Zone Collection object. This object
does not have events nor methods associated to it.

Methods
This section contains information about the methods of the Zone Collection object.

Add
Add([AxisName])

Adds a new Zone into the Zone Collection. The AxisName parameter is optional, being kept for
compatibility reasons.

Remove
Remove(Index)

Removes a Zone. The Index parameter indicates the index of the Zone to be removed.

202 V iew
4.3.2.13.2.3 Zones

Defines a set of bitmap images used to create an animation effect in the object. The Zones can
be configured by accessing the Properties window of the object, on the E2Animation tab. The
options of this window are the following.

Available options for the E2Animation tab

OPTION DESCRIPTION
Zones List with all Zones defined in the object.

Add button Adds a new Zone.

Remove button Erases the selected Zone.

Default zone Defines the selected Zone as the default

Zone of the object.

Blink Defines if the bitmap blinks when the object

value is inside the Zone interval.

Tip Displays a help text over the Zone.

Minimum Minimum value for Zone variation.

Maximum Maximum value for Zone variation.

Image file Name of the bitmap file displayed when the

object value is inside the Zone interval.

Example Displays a preview of the bitmap file of the

selected Zone.

Properties
This section contains information about the properties of the Zones of the E2Animation object.

Blink
Indicates that this Zone is part of the blinking effect. The default value of this property is
False.

Filename
Indicates what is the image filename used in the Zone.

Maximum
Defines the maximum value for the Zone. The default value of this property is 20000.

V iew 203
Minimum
Defines the minimum value for the Zone. The default value of this property is 0.

TipEnable
Enables or disables a tip for the Zone. The default value of this property is False.

TipText
Defines a tip for the Zone. The default value of this property is an empty String.

4.3.2.13.3 E2Bitmap

This section contains information about properties of the E2Bitmap object. This object does
not have events nor methods associated to it.

4.3.2.13.3.1 Properties

This section contains information about the properties of the E2Bitmap object.

Filename

Defines the image filename linked to the E2Bitmap. The file path may be the full file path
on disk, as well as a relative application path (when the image file is inserted as an
application Resource). The default value of this property is an empty String.

IsTransparent
This property enables or disables object transparency, based on the color defined by the
TransparentColor property.

TransparentColor
Defines what is the color to be considered by the IsTransparent property as being
transparent. The default value of this property is white (RBG(255, 255, 255)).

4.3.2.13.4 E2Button

This section contains information about events and properties of the E2Button object. This
object does not have methods associated to it.

4.3.2.13.4.1 Events

This section contains information about the events of the E2Button object.

OnRelease
OnRelease()

This event is triggered when mouse button is released.

204 V iew
4.3.2.13.4.2 Properties

This section contains information about the properties of the E2Button object.

Action
This property defines the behavior of the E2Button object when clicked. The available
values for this property are:

· 0 - Momentary: Standard button behavior, appearing lowered only when mouse is pressed

· 1 - Toggle: It has two states, on and off

· 2 - Jog: Switches between two values, one when the button is pressed and another one
when the button is released

The default value of this property is 0 - Momentary.

Alignment
Determines the text alignment of the button. The available values for this property are:

· 0 - HorizontalAlignmentLeft: Aligns the text to the left

· 1 - HorizontalAlignmentCenter: Aligns the text to the center

· 2 - HorizontalAlignmentRight: Aligns the text to the right

The default value of this property is 1 - HorizontalAlignmentCenter.

BackgroundColor0
Defines the background color of the button when it is not pressed. The default value of this
property is gray (RGB(192, 192, 192)).

BackgroundColor1
Defines the background color of the button when it is pressed. The default value of this
property is gray (RGB(192, 192, 192)).

Bitmap0

Defines the button image when it is not pressed. The default value of this property is an
empty String.

Bitmap1

Defines the button image when it is pressed. The default value of this property is an empty
String.

V iew 205
Text0
Defines the button text when it is not pressed. The default value of this property is "OFF".

Text1
Defines the button text when it is pressed. The default value of this property is "ON".

TextColor0
Defines the text color of the button when it is not pressed. The default value of this property
is black (RGB(0, 0, 0)).

TextColor1
Defines the text color of the button when it is not pressed. The default value of this property
is black (RGB(0, 0, 0)).

TextFont0
The TextFont0 property is used to determine the button font when it is not pressed. This
property cannot be used in scripts or Links, being set only via Studio.

TextFont1
The TextFont1 property is used to determine the button font when it is pressed. This
property cannot be used in scripts or Links, being set only via Studio.

Type
Defines the button type. The available values for this property are the following:

· 0 - ButtonTypeKey: standard button behavior

· 1 - ButtonTypeSwitchH: the button behavior is of a horizontally divided switch

· 2 - ButtonTypeSwitchV: the button behavior is of a vertically divided switch

· 3 - ButtonTypeLeverH: the button behavior is of a lever which moves from left to right and
vice versa

· 4 - ButtonTypeLeverV: the button behavior is of a lever which moves from top to bottom and
vice versa

· 5 - ButtonTypeTransparent: the button is transparent

· 6 - ButtonTypeUserBitmap: the button display switches between the images defined in the
Bitmap0 and Bitmap1 properties

· 7 - ButtonTypeCheckbox: the button behavior is the same of a Checkbox

· 8 - ButtonTypeRadio: the button behavior is the same of a Radiobox

206 V iew
The default value of this property is 0 - ButtonTypeKey.

Value
The Value property is a Variant which assumes the value in the Value0 property if the button
is not pressed, and the value in the Value1 property if the button is pressed.

Value0
Defines the value of the Value property when the button is not pressed.

Value1
Defines the value of the Value property when the button is pressed.

4.3.2.13.5 E2Display

This section contains information about properties of the E2Display object. This object does
not have events nor methods associated to it.

4.3.2.13.5.1 Properties

This section contains information about the properties of the E2Display object.

BackgroundColor
This property defines the background color of the object. The default value of this property
is gray (RGB(192, 192, 192)).

BackgroundStyle
Defines the background style of the object. The available values of this property are the
following:

· 0 - bsTransparent: background is transparent

· 1 - bsOpaque: the color defined in the BackgroundColor property is visible

The default value of this property is 1 - bsOpaque.

Format
Contains a text which represents a mask where the object values are displayed. This mask
can represent several types of values:

· General: It has no specific formatting, automatically adapting to the specified value

· Number: Displays numbers with an integer and a fraction part. The user may opt for up to 15
decimal places, for using a thousand separator or not, and for displaying negative numbers
as signed or between parentheses. For very large or very small numbers, the Scientific
format is recommended

V iew 207
· Date: Displays date number values (when valid). To represent only time, use the equivalent
format

· Time: Displays time number values (when valid). To represent only dates, use the
equivalent format

· Percentage: Multiplies the number by 100 and adds a percentage symbol. Allows up to 15
decimal places

· Scientific: Displays the number with a mantissa and exponent notation. Ideal for numbers
with variable magnitude. Allows up to 15 decimal places

· Special: Allows formatting integers on non-decimal basis (hexadecimal, octal, or binary, for
example)

· Other: Allows directly editing the formatting code, or selecting a previously created format

HorizontalAlignment
Defines the horizontal alignment of the E2Display text. The available values of this
property are the following:

· 0 - HorizontalAlignmentLeft: aligns horizontally to the left

· 1 - HorizontalAlignmentCenter: aligns horizontally to the center

· 2 - HorizontalAlignmentRight: aligns horizontally to the right

The default value of this property is 1 - HorizontalAlignmentCenter.

MultiLine
Defines whether the object has multiple lines or not. This property is only available if the
Value property is of String-type.

TextColor
Defines the text color of the object. The default value of this property is black (RGB(0, 0, 0)).

TextFont
The TextFont property is used to determine the object font. This property cannot be used in
Links. See property TextFont of Text, Display, and SetPoint objects for more information about
subproperties that can be modified via scripts.

Value
This property contains a Variant which may assume any datatype value, and the way these
values are displayed is defined in the Format property.

208 V iew
VerticalAlignment
Defines the vertical alignment of E2Display's text. The available values for this property
are the following:

· 0 - VerticalAlignmentTop: aligns vertically with the upper side of the object

· 1 - VerticalAlignmentMiddle: aligns vertically with the center of the object

· 2 - VerticalAlignmentBottom: aligns vertically with the bottom side of the object

The default value of this property is 1 - VerticalAlignmentMiddle.

4.3.2.13.6 E2Gauge

This section contains information about properties of the E2Gauge object. This object does not
have events nor methods associated to it.

4.3.2.13.6.1 Properties

This section contains information about the properties of the E2Gauge object.

BackgroundColor
This property defines the background color of the object. The default value of this property
is gray (RGB(128, 128, 128)).

BulletsVisible
Displays or hides the scale's bullet points.

DecimalPlaces
This property defines the number of decimal places for the nominal value of the E2Gauge.

FrameColor
Defines the background color of the object.

HiColorLegend
Defines the legend color for the High limit. The default value of this property is yellow (RGB
(255, 255, 0)).

HiDiv
Marks the beginning of the scale for the High limit. The default value of this property is
13300.

V iew 209
HiHiColorLegend
Defines the legend color for the Very High limit. The default value of this property is red (
RGB(255, 0, 0)).

HiHiDiv
Marks the beginning of the scale for the Very High limit. The default value of this property is
16600.

HiHiLimitVisible
Enables or disables the display of the Very High limit.

HiLimit
The maximum value of this property is 1 and the minimum is limited by the LowLimit
property. The default value of this property is 0.7.

HiLimitVisible
Enables or disables the display of the High limit.

LegendVisible
Displays a bar along the E2Gauge object, which allows configuring different colors,
depending on a range of values. The default value of this property is True.

LimitVisible
Defines whether the mininum and maximum values of the scale appear on the chart or not.

LowColorLegend
Defines the legend color for the Low limit. The default value of this property is dark green (
RGB(0, 128, 0)).

LowDiv
Marks the beginning of the scale for the Low limit. The default value of this property is 6600.

LowLimit
The minimum value of this property is 0.1, and the maximum is limited by the HiLimit
property. The default value of this property is 0.62.

LowLimitVisible
Enables or disables the display of the Low limit.

LowLowColorLegend
Defines the legend color for the Very Low limit. The default value of this property is green (
RGB(0, 255, 0)).

210 V iew
LowLowDiv
Marks the beginning of the scale for the Very Low limit. The default value of this property is
3300.

LowLowLimitVisible
Enables or disables the display of the Very Low limit.

Maximum
Defines the maximum value of the E2Gauge scale.

Minimum
Defines the minimum value of the E2Gauge scale.

NeedleColor
Defines the needle color of the E2Gauge. The default value of this property is white (RGB
(255, 255, 255)).

NeedleThickness
Defines the thickness of the E2Gauge needle, in pixels. The default value of this property is 2,
and it only accepts 1 or 2 as a value.

NormalColor
Defines the legend color for the Normal limit. The default value of this property is olive (RGB
(128, 128, 0)).

NumberOfPoints
Defines the number of subdivisions which are visible on the object scale.

Orientation
Defines the orientation of the E2Gauge object. The available values for this property are
the following:

· 0 - Left: the lower part of the object is aligned with the left side of the frame

· 1 - Up: the lower part of the object is aligned with the upper part of the frame

· 2 - Down: the lower part of the object is aligned with the lower part of the frame

· 3 - Right: the lower part of the object is aligned with the right side of the frame

The default value of this property is 2 - Down.

V iew 211
Reverted
Enables or disables reversing the object scale.

ShowFrame
Enables or disables displaying the background all the needle's path.

StartAngle
Defines the initial displaying angle of the E2Gauge object's needle.

SubTickColor
Defines the color of the scale subdivisions. The default value of this property is black (RGB
(0, 0, 0)).

SubTicksVisible
Enables or disables displaying the scale subdivisions.

TextColor
Defines the text color of the scale. The default value of this property is black (RGB(0, 0, 0)).

TextFont
The TextFont property is used to determine the text font of the scale. This property cannot
be used in Links. See property TextFont of Text, Display, and SetPoint objects for more
information about subproperties that can be modified via scripts.

ThickTicks
Enables or disables displaying thicker scale dividers. The default value of this property is
False.

TickColor
Defines the color of the scale dividers. The default value of this property is black (RGB(0, 0,
0)).

TicksVisible
Enables or disables displaying scale dividers.

TickValues
Enables or disables displaying values of the scale dividers.

TotalNumberOfSubTicks
Defines the total amount of subdivisions displayed on the scale.

212 V iew
Value
This property defines a value between the Maximum and Minimum properties of the
object's scale.

ValueVisible
Enables or disables displaying the value of the Value property. The default value of this
property is False.

4.3.2.13.7 E2Setpoint

This section contains information about properties of the E2Setpoint object. This object does
not have events nor methods associated to it.

4.3.2.13.7.1 Properties

This section contains information about the properties of the E2Setpoint object.

AutoSend
If this property is True (default), the value defined in the Value property is updated on Links,
as soon as the object loses focus. Otherwise, Links only receive this value when the ENTER key
is pressed.

BackgroundColor
This property defines a background color for the object. The default value of this property is
gray (RGB(192, 192, 192)).

BackgroundStyle
Defines the background style of the object. The values of this property are the following:

· 0 - bsTransparent: background is transparent

· 1 - bsOpaque: color defined in the BackgroundColor property is visible

The default value of this property is 1 - bsOpaque.

EnableMaxLimit
Enables or disables the definition of a maximum limit for the E2Setpoint value.

EnableMinLimit
Enables or disables the definition of a minimum limit for the E2Setpoint value.

V iew 213
Format
Contains a text which represents a mask where the object values are displayed. This mask
can represent several types of values:

· General: It has no specific formatting, automatically adapting to the specified value

· Number: Displays numbers with an integer and a fraction part. The user may opt for up to 15
decimal places, for using a thousand separator or not, and for displaying negative numbers
as signed or between parentheses. For very large or very small numbers, the Scientific
format is recommended

· Date: Displays date number values (when valid). To represent only time, use the equivalent
format

· Time: Displays time number values (when valid). To represent only dates, use the
equivalent format

· Percentage: Multiplies the number by 100 and adds a percentage symbol. Allows up to 15
decimal places

· Scientific: Displays the number with a mantissa and exponent notation. Ideal for numbers
with variable magnitude. Allows up to 15 decimal places

· Special: Allows formatting integers on non-decimal basis (hexadecimal, octal, or binary, for
example)

· Other: Allows directly editing the formatting code, or selecting a previously created format

HorizontalAlignment
Defines the horizontal alignment of the E2Setpoint text. The available values for this
property are the following:

· 0 - HorizontalAlignmentLeft: aligns horizontally on the left

· 1 - HorizontalAlignmentCenter: aligns horizontally on the center

· 2 - HorizontalAlignmentRight: aligns horizontally on the right

The default value of this property is 1 - HorizontalAlignmentCenter.

HScroll
Enables or disables displaying a horizontal scrollbar on the text, in case the MultiLine
property is True.

MaxLimit
Maximum limit that can be reached by the Value property of the object. The default value of
this property is 200. This limit is only checked if the EnableMaxLimit property is enabled.

214 V iew
MinLimit
Minimum limit that can be reached by the Value property of the object. The default value of
this property is 0. This limit is only checked if the EnableMinLimit property is enabled.

MultiLine
Defines whether the object has multiple lines or not. This property is only available if the
Value property is of type String.

ReadOnly
Indicates whether this object can be edited or not at run time. The default value of this
property is False.

Refresh
Indicates whether the E2Setpoint value is updated or not as soon as Tag value changes. The
default value of this property is True.

SelectAllOnFocus
Enables or disables selecting all characters of the E2Setpoint when this object receives
focus. The default value of this property is True.

TextColor
Defines the text color of the object. The default value of this property is black (RGB(0, 0, 0)).

TextFont
The TextFont property is used to determine the object font. This property cannot be used in
Links. See property TextFont of Text, Display, and SetPoint objects for more information about
subproperties that can be modified via scripts.

Type
Defines the Setpoint type. The available values for this property are the following:

· 0 - setpointString: accepts any alphanumerical characters

· 1 - setpointNumeric: accepts only numerical characters and the decimal separator (dot or
comma, according to regional settings)

· 2 - setpointDateTime: accepts only date and time values, which are converted to the format
defined on regional settings)

The default value of this property is 1 - setpointNumeric.

Value
This property defines a value for the E2Setpoint. The way this value is viewed is defined in
the Format property.

V iew 215
VerticalAlignment
Defines the vertical alignment of the E2Setpoint text. The available values of this property
are the following:

· 0 - VerticalAlignmentTop: aligns vertically to the top of the object

· 1 - VerticalAlignmentMiddle: aligns vertically to the center of the object

· 2 - VerticalAlignmentBottom: aligns vertically to the bottom of the object

The default value of this property is 1 - VerticalAlignmentMiddle.

VScroll
Enables or disables displaying a vertical scrollbar on the text, in case the MultiLine
property is True.

4.3.2.13.8 E2Text

This section contains information about properties of the E2Text object. This object does not
have events nor methods associated to it.

4.3.2.13.8.1 Properties

This section contains information about the properties of the E2Text object.

BlinkTime
Defines the time interval, in milliseconds, of the object's blinking effect.

DefaultZone
Defines the default Zone of the object.

Value
This property contains a Variant which may assume any data type values (Integer, Boolean,
String, etc.).

Zones
Collection of Zones of the E2Text object.

4.3.2.13.8.2 Zone Collection

This section contains information about the methods of the Zone Collection object of the
E2Text. This object does not have events nor properties associated to it.

216 V iew
Methods
This section contains information about the methods of the Zone Collection object of the
E2Text.

Add
Add([AxisName])

Adds a new Zone in the Zone Collection. The AxisName parameter is optional and has no effect,
being kept for compatibility reasons.

Remove
Remove(Index)

Removes a Zone. The Index parameter indicates the index of the Zone to be removed.

4.3.2.13.8.3 Zones

Defines a set of Zones for the E2Text object. These Zones can be configured accessing the
property window of the object, in the Zones tab. The available options in this tab are the
following:

Available options in the Zones tab

OPTION DESCRIPTION
Zones List with all zones defined in the object.

Add button Adds a new Zone.

Remove button Removes the selected Zone.

Blinks every (ms) Defines if the text and background of the Zone
blink whe the object value is inside the Zone
interval.

Message Text of the message displayed when the

object value is inside the Zone interval.

Alignment Defines text alignment.

Font Defines text font.

Background Color Defines background color of the Zone.

Transparent Defines if the object background is

transparent when the Zone is active.

Default zone Defines the selected Zone as the default

Zone of the object.

V iew 217
 OPTION DESCRIPTION
Blink Defines if the Zone blinks when the object
value is inside the Zone interval.

Minimum Minimum value for the Zone.

Maximum Maximum value for the Zone.

Tip Displays a help text for the Zone.

Example Displays an example of the Zone behavior at

run time.

Properties
This section contains information about the properties of the E2Text object Zones.

BackgroundColor
Defines a background color for the text Zone. The default value of this property is white (RGB
(255, 255, 255)).

Blink
Indicates that this Zone participates in the blinking effect. The default value of this property
is False. If it is enabled, this zone switches with the default Zone, according to the time defined
in the BlinkTime property of the E2Text object.

HorizontalAlignment
Defines the text alignment. The available values are:

· 0 - HorizontalAlignmentLeft: aligns horizontally to the left

· 1 - HorizontalAlignmentCenter: aligns horizontally to the center

· 2 - HorizontalAlignmentRight: aligns horizontally to the right

The default value of this property is 1 - HorizontalAlignmentCenter.

Maximum
Defines the maximum value for the Zone. The default value of this property is 20000.

Message
Defines the text linked to the Zone. This message is displayed when the associated Tag is
inside the Zone limits.

218 V iew
Minimum
Defines the minimum value for the Zone. The default value of this property is 0.

TextColor
Defines the text color for the Zone. The default value of this property is black (RGB(0, 0, 0)).

TextFont
Defines style, color, and size of the font used to display the message text. This property
cannot be used in Links. See property TextFont of Text, Display, and SetPoint objects for more
information about subproperties that can be modified via scripts.

TipEnable
Enables or disables a tip for the Zone. The default value of this property is False.

TipText
Defines a tip for the Zone. The default value of this property is an empty String.

Transparent
Defines that the object background is transparent when this Zone is active.

4.3.2.14 Elipse KeyPad

This section contains information about methods and properties of the Elipse KeyPad object.
This object does not have events associated to it.

4.3.2.14.1 Methods

This section contains information about the methods of the Elipse KeyPad object.

4.3.2.14.1.1 Hide
Hide()

Hides the Elipse KeyPad. This method has no effect if the KeyPad is already invisible. Example:
' The following code hides the KeyPad
Sub CommandButton1_Click()
Application.GetKeyPad().Hide()
End Sub

4.3.2.14.1.2 Show
Show()

Displays the Elipse KeyPad. This method has no effect if the KeyPad is already visible. Example:
' The following code displays the KeyPad
Sub CommandButton1_Click()
Application.GetKeyPad().Show()
End Sub

V iew 219
4.3.2.14.2 Properties

This section contains information about the properties of the Elipse KeyPad object.

4.3.2.14.2.1 AutoHideOnEnter

Automatically hides the KeyPad when the ENTER key of the virtual keyboard is pressed.
Example:
' Changes the Keypad behavior.
' If the ENTER key of the virtual keyboard is pressed
' the KeyPad is hidden.
Sub CommandButton1_Click()
Application.GetKeyPad().AutoHideOnEnter = True
End Sub

4.3.2.14.2.2 AutoHideOnEsc

Automatically hides the KeyPad when the ESC key of the virtual keyboard is pressed.
Example:
' Changes the KeyPad behavior.
' If the ESC key of the virtual keyboard is pressed
' the KeyPad is hidden.
Sub CommandButton1_Click()
Application.GetKeyPad().AutoHideOnEsc = True
End Sub

4.3.2.14.2.3 Layout

Allows changing the presentation layout of the KeyPad. Possible values of this property are:

· br-simple: Displays an alphanumeric keyboard

Example of alphanumeric KeyPad

· num: Displays a numeric keyboard

220 V iew
 Example of numeric KeyPad

Example:
' Switches between Alphanumeric and Numeric modes
Sub ToggleButton1_Click()
If ToggleButton1.Value Then
Application.GetKeyPad().Layout = "br-simple"
Else
Application.GetKeyPad().Layout = "num"
End If
End Sub

4.3.2.14.2.4 SizeFactor

Increases or decreases the original size of the KeyPad using a multiplication factor. The
original size of the KeyPad is the following:

Default size values of the KeyPad

LAYOUT WIDTH HEIGHT

Alphanumeric 550 px 250 px

Numeric 200 px 300 px

The following example resizes the KeyPad to 75% of its original size.
Sub CommandButton1_Click()
Application.GetKeyPad().SizeFactor = 0.75
Application.GetKeyPad().Show()
End Sub

V iew 221
4.3.2.14.2.5 Sound

Allows changing the sound played when clicking a KeyPad key. The default value of this
property is an empty String, meaning that no sound plays when clicking a key. In case the value
of this property changes, the new value must be an absolute path of a WAV file or this file must
be added to the Domain as a Resource. Example:
Sub CommandButton1_Click()
Application.GetKeyPad().Sound = "c:\windows\media\ringout.wav"
End Sub

4.3.2.14.2.6 X

The X coordinate of the upper left corner of the KeyPad object. This property can be used to
move the KeyPad horizontally. Example:
Sub CommandButton1_Click()
' Moves the KeyPad 50 pixels to the right
Application.GetKeyPad().X = Application.GetKeyPad().X + 50
End Sub

4.3.2.14.2.7 Y

The Y coordinate of the upper left corner of the KeyPad object. This property can be used to
move the KeyPad vertically. Example:
Sub CommandButton1_Click()
' Moves the KeyPad 50 pixels down
Application.GetKeyPad().Y = Application.GetKeyPad().Y + 50
End Sub

4.4 E3Alarm
This section contains information about the properties, events and methods of the E3Alarm
object.

4.4.1 Events
This section contains information about the events of the E3Alarm object.

4.4.1.1 KeyPress
KeyPress(KeyAscii)

This event occurs when the object has the keyboard focus and user presses a key
corresponding to a character that can be showed on Screen (an ANSI key, of a code indicated in
the KeyAscii parameter). That is, the event occurs when some of the following keys are
pressed:

· Any keyboard character that can be printed

· CTRL key combined with any standard alphabet character

· CTRL key combined with any special character

222 V iew
· BACKSPACE key

· ESC key

This event does not occur in the following conditions:

· By pressing the TAB key

· By pressing the ENTER key

· By pressing the DEL key (this is not an ANSI key)

· By pressing keyboard arrow keys

· When a key change the focus from an object to another

While a user presses a key that produces an ANSI code, the object repeatedly receives the
KeyDown and the KeyPress events. When the user releases the key, the KeyUp event occurs.

In order to monitor keyboard physical status or handle keys which are not recognized by the
KeyPress event (such as function keys, browsing keys, etc.), use the KeyDown and KeyUp
events.

4.4.1.2 MouseMove
MouseMove()

Occurs when the mouse pointer is moved over the control.

4.4.2 Methods
This section contains information about the methods of the E3Alarm object.

4.4.2.1 AboutBox
AboutBox()

This method displays a dialog box with information about version and copyright of the E3Alarm
object.

V iew 223
4.4.2.2 AckAll
AckAll([Operator])

Allows globally acknowledging all alarms. The Operator parameter is an optional String
indicating the name of the operator that acknowledged the alarm. This value is displayed on
the Operator column of the E3Alarm. If it is omitted, the current Viewer user is used, or else
"(No User)", in case there is no user logged in. For the acknowledgement itself, the logged user
must have permission to acknowledge alarms.

4.4.2.3 AckCurrentFilter
AckCurrentFilter([Operator])

Allows acknowledging all alarms of the current filter. The Operator parameter is an optional
String indicating the name of the operator that acknowledged the alarm. This value is
displayed on the Operator column of the E3Alarm. If it is omitted, the current Viewer user is
used, or else "(No User)", in case there is no user logged in. For the acknowledgement itself,
the logged user must have permission to acknowledge alarms.

4.4.2.4 AckSelected
AckSelected([Operator])

Allows acknowledging the selected alarms. If there is no selected alarm in the E3Alarm, this
method fails. The user may acknowledge the alarm (in this case, a new record is inserted into
the Database indicating the acknowledgement), and in the E3Alarm the corresponding row
indicates that it is acknowledged. The Operator paramter is an optional String indicating the
name of the operator that acknowledged the alarm. This value is displayed on the Operator
column of the E3Alarm. If it is omitted, the current Viewer user is used, or else "(No User)", in
case there is no user logged in. For the acknowledgement itself, the logged user must have
permission to acknowledge alarms.

4.4.2.5 GetFocusedEvent
GetFocusedEvent()

This method returns an object with the properties of the selected event (the one that has
focus) on E3Alarm, in case there is a selected event. If no event is selected, this method
returns a Nothing object.

The properties of the returned object contains field values of the selected event. The object
contain a copy of the values at the time of the method call, therefore if the selected event
changes, the properties are not updated automatically, being necessary to use this method
every time you need to get updated information about the selected event. The properties of
the object returned by this method are the following:

224 V iew
 Properties of the object returned by the GetFocusedEvent method

NAME DESCRIPTION
Acked Informs if the alarm was acknowledged or
not. This field can assume values 0: not
acknowledged, and 1: acknowledged.

AckRequired Determines the automatic acknowledging of

the alarm. This field has the values 0:
automatic acknowledging, and 1: manual
acknowledging.

AckTime Records E3 date/time at the moment the

alarm is acknowledged, or zero (12/30/1899)
while the alarm has not been acknowledged.
In case of alarms that do not need
acknowledging, this field assumes E3 date/
time of the moment when the alarm
becomes active.

ActorID Name of the operator that acknowledged the

alarm. It can be:

· The Viewer logged in user, when the

acknowledging is done on E3Alarm (or "No
User", if there is no logged in user).

· System: when the acknowledging is

automatic (that is, for alarms that ask for
acknowledging).

· A name passed by Script (for example,

using AckArea, AckAllAlarms,
LogTrackingEvent from Alarm Server, or Ack
from Alarm Source).

The limit of this field when stored on a

database is 50 characters.

AlarmSourceName Records the name of the alarm source. The

limit of this field when stored on a database
is 100 characters. For example,
"AlarmSource1".

Area For alarm events, the name of the area to

which the alarm source belongs to. For other
events (for example, using the
LogTrackingEvent method from Alarm Server),
may be a user defined text. The limit of this
field when stored on a database is 100
characters.

V iew 225
 NAME DESCRIPTION
ConditionActive Indicates if the alarm source is in alarm. This
field presents the states 0: inactive condition
and 1: active condition.

ConditionName Name of the condition, if this is an alarm

event. This field can have the following
values:

· Dead Band: Dead band alarm source type

· Digital: Digital alarm source type

· Level: Analog alarm source type

· RateOfChange: Rate of change alarm

source type

If the event is not an alarm (for example,

using the LogTrackingEvent method from
Alarm Server), this value is always an empty
String. The limit of this field when stored on a
database is 100 characters.

CurrentValue Determines the value of the alarm source

(converted to Double) at the moment of the
event. For other events (for example, using
the LogTrackingEvent), this value is always 0.
The limit of this field when stored on a
database is 100 characters.

Enabled Determines if the alarm checking is enabled.

This field presents the states 0: disabled
alarm source checking and 1: enabled alarm
source checking.

226 V iew
 NAME DESCRIPTION
EventCategory Category of the event. For alarms, this field
can assume the following values:

· Dead Band: Dead band alarm source type

· Digital: Digital alarm source type

· Level: Analog alarm source type

· RateOfChange: Rate Of Change alarm

source type

For other events (for example, using the

LogTrackingEvent), this field can assume user
defined values. The limit of this field when
stored on a database is 100 characters.

EventCLSID Unique identifier of an alarm. When a new

alarm occurs on a Source, a new EventCLSID
number is generated, so it keeps the same
CLSID on the database as long as it remains
on the active and non acknowledged list of
alarms.

EventTime Date/time of the alarm source value at the

moment of the event.

EventTimeUTC Date/time of the alarm source value at the

moment of the event, relative to Greenwich
Meantime. This value is the same as
EventTime, being kept in E3 for compatibility
reasons.

EventType Type of the event. For alarm events, it is

always "Condition". For other events, it can
be a user defined text, for example, using the
LogTrackingEvent method from Alarm Server
(for example, "Tracking", "Simple", etc.). The
limit of this field when stored on a database
is 100 characters.

FormattedValue Shows the formatted value of the alarm

source that is saved on the event. The limit of
this field when stored on a database is 100
characters. NOTE: this is a read-only field.

V iew 227
 NAME DESCRIPTION
FullAlarmSourceName Records the full path of the alarm source,
including areas, alarm configuration name
and possible folders where this alarm source
might be inserted. For example, "Folder1.
AlarmConfig1.Area1.AlarmSource1".

InTime Records the date/time of the value when it

gets into an alarm condition.

Message It is the configured text on the alarm source,

or specified by another event (for example,
using the LogTrackingEvent method of the
Alarm Server). The limit of this field when
stored on a database is 200 characters.

OutTime Records the date/time of the value when it

gets out of an alarm condition, or zero
(12/30/1899) while the alarm does not get
out of the active condition.

Quality Quality of the alarm source value at the

moment of the event. This field assumes the
numerical values:

· 0 - 63: bad quality

· 64 - 127: uncertain quality

· 128 - 191: undefined value

· 192 - 255: good quality

If the event is not an alarm (for example, if it

is using the LogTrackingEvent method of the
Alarm Server), this field is equal to an empty
String. Example: "Bad (0)", "Uncertain (64)",
"?? (128)", "Good (192)".

Severity It is the configured severity value on the

alarm source. This field can assume values 0:
high; 1: medium; 2: low. It can also assume
another user defined value if it is an event, as
when it is using the LogTrackingEvent
method.

Source For alarm events, informs the expression

used to evaluate alarm conditions. The limit
of this field when stored on a database is 100
characters. For example, "Data.DemoTag1.
Value".

228 V iew
 NAME DESCRIPTION
SubConditionName Name of the subcondition, if it is an alarm
event. This field can assume the values:

· DB: Dead band alarm

· DIG: Digital alarm

· RC: Rate of change alarm

· LOLO: Very low range analog alarm

· LO: Low range analog alarm

· HI: High range analog alarm

· HIHI: Very high range analog alarm

If the event is not an alarm (for example, if it

is using the LogTrackingEvent method of the
Alarm Server), this field is equal to an empty
String. The limit of this field when stored on a
database is 100 characters.

UserField Read-only indexed property which index

varies from 1 to 4, containing user defined
fields.

Example:

V iew 229
 Dim evt
Set evt = GetFocusedEvent()
If Not(evt Is Nothing) Then
Dim str
str = str & "EventTime = " & evt.EventTime & Chr(13)
str = str & "EventTimeUTC = " & evt.EventTimeUTC & Chr(13)
str = str & "InTime = " & evt.InTime & Chr(13)
str = str & "OutTime = " & evt.OutTime & Chr(13)
str = str & "AckTime = " & evt.AckTime & Chr(13)
str = str & "CurrentValue = " & evt.CurrentValue & Chr(13)
str = str & "ActorID = " & evt.ActorID & Chr(13)
str = str & "Area = " & evt.Area & Chr(13)
str = str & "AlarmSourceName = " & evt.AlarmSourceName & Chr(13)
str = str & "FullAlarmSourceName = " & evt.FullAlarmSourceName & Chr(13)
str = str & "ConditionName = " & evt.ConditionName & Chr(13)
str = str & "EventCategory = " & evt.EventCategory & Chr(13)
str = str & "EventType = " & evt.EventType & Chr(13)
str = str & "Message = " & evt.Message & Chr(13)
str = str & "Quality = " & evt.Quality & Chr(13)
str = str & "Source = " & evt.Source & Chr(13)
str = str & "SubConditionName = " & evt.SubConditionName & Chr(13)
str = str & "FormattedValue = " & evt.FormattedValue & Chr(13)
str = str & "UserField(1) = " & evt.UserField(1) & Chr(13)
str = str & "UserField(2) = " & evt.UserField(2) & Chr(13)
str = str & "UserField(3) = " & evt.UserField(3) & Chr(13)
str = str & "UserField(4) = " & evt.UserField(4) & Chr(13)
str = str & "Severity = " & evt.Severity & Chr(13)
str = str & "Acked = " & evt.Acked & Chr(13)
str = str & "AckRequired = " & evt.AckRequired & Chr(13)
str = str & "ConditionActive = " & evt.ConditionActive & Chr(13)
str = str & "Enabled = " & evt.Enabled & Chr(13)
str = str & "EventCLSID = " & evt.EventCLSID & Chr(13)
MsgBox str
Else
MsgBox "No selected event."
End If

4.4.3 Properties
This section contains information about the properties of the E3Alarm object.

NOTE: E3 uses the HIMETRIC system for coordinate and width definitions. In this system, each
logical unit is equal to one hundreth of a centimeter. That is, each 1000 units correspond to
one centimeter. Thus, this is the standard adopted when describing E3 properties, when
applicable.

4.4.3.1 ActiveAlarms

Determines the total amount of active alarms in the object. This is a read-only property.

4.4.3.2 ActiveHighAlarms

Indicates the number of high severity active alarms. This is a read-only property.

230 V iew
4.4.3.3 ActiveHighNACKAlarms

Indicates the number of high severity unacknowledged alarms. This is a read-only property.

4.4.3.4 ActiveLowAlarms

Indicates the number of low severity active alarms. This is a read-only property.

4.4.3.5 ActiveLowNACKAlarms

Indicates the number of low severity unacknowledged alarms. This is a read-only property.

4.4.3.6 ActiveMedAlarms

Indicates the number of medium severity active alarms. This is a read-only property.

4.4.3.7 ActiveMedNACKAlarms

Indicates the number of medium severity unacknowledged alarms. This is a read-only

property.

4.4.3.8 ActiveNACKAlarms

Indicates the total amount of unacknowledged alarms in the object (active or not). This is a
read-only property.

4.4.3.9 AllowAckAll
Enables the E3Alarm pop-up menu option that allows acknowledging all alarms. The default
value of this property is True.

4.4.3.10 AllowAckCurrentFilter
Enables the E3Alarm pop-up menu option that allows acknowledging all alarms of the
current filter. If there is no visible alarms, the property has no effect. The default value of this
property is True.

4.4.3.11 AllowAckSelected

Enables the E3Alarm pop-up menu option that allows acknowledging all selected alarms. If
there is no selected alarms, the property has no effect. The default value of this property is
True.

V iew 231
4.4.3.12 AllowColumnClick

Enables or disables field selection and their sort direction by clicking E3Alarm's column
headers at run time. If True, and header is invisible (see the ColumnHeader property), when
you click the column title, data is sorted using this column as the key. When you click the same
column title again, the sort order is reversed (from ascending to descending, and vice-versa).
When you click it with the SHIFT key pressed, the field is used as a second key. As in the
primary key, a second click with SHIFT pressed reverses the sort order of the secondary field.

4.4.3.13 AlarmServer

Name of the single alarm server in the application.

4.4.3.14 ColumnHeader
When True, this property enables viewing E3Alarm header. The header also visually sorts
data in the table (see the AllowColumnClick property). Default value is True.

4.4.3.15 Domain

Specifies the domain to which E3Alarm connects. Default value is empty, that is, E3Alarm
connects to the same Domain of the Viewer where it is. For example, \\NameOfOtherServer.

4.4.3.16 Enabled
Enables the ActiveX object in the project. Default value is True.

4.4.3.17 Filter

Controls visible alarm areas at E3Alarm. If its value is not empty, the events which area
name start with the text typed in this field are presented. For example, if Filter is "Ana", only
the alarms of areas such as "Analog.Production" or "Analysis" are displayed, but not "Digital.
Analysis" or "Digital.Production". When SimpleAreaFilter property is False, the alarm area also
allows using wild cards (such as * or ?) for filtering and allowing multiple area filters,
separated by colons. Allowed wildcards are:

· "*": takes no or any amount of characters

· "?": takes any character

· "#": takes any digit

· "[ ]": allows specifying a cluster of characters. For example:

· "[ab]": takes a character if it is "a" or "b"

232 V iew
 · "[f-h]": takes a character between "f" and "h"

· "[!cz]": takes a character which is neither "c" nor "z"

· "[!m-p]": takes any character as long as it is not between "m" and "p"

Default value is empty, that is, there is no filter per area (see also the ShowHighPriority,
ShowMediumPriority, and ShowLowPriority properties).

4.4.3.18 FilterType

Performs alarm filters. The available options are:

· 1 - OnlyAlarms: displays only alarms

· 2 - Only Events: displays only events

· 3 - AlarmsAndEvents: displays both alarms and events

4.4.3.19 Font

Determines E3Alarm header and row font. This is a read-only property, and cannot be
modified at run time.

4.4.3.20 GridBkColor

Determines E3Alarm background color. Default value is the color configured in Windows for
the Window item (Control Panel - Display - Appearance - Advanced).

4.4.3.21 PopupMenu
Enables a pop-up menu on E3Alarm. Default value is True.

4.4.3.22 PrimarySortAscending
When False, primary field events sorting is descending. Otherwise, it is ascending. Default
value is False.

4.4.3.23 PrimarySortField

Determines the primary field for sorting events at E3Alarm. The field name should always
be in English (see alarm field table appended in this manual). Default value is "EventTime".
When this option is empty, SecondarySortField property does not have any effect.

V iew 233
4.4.3.24 SecondarySortAscending

When False, secondary field events sorting is descending. Otherwise, it is ascending.

Default value is False.

4.4.3.25 SecondarySortField

Determines the secondary field for sorting events at E3Alarm. Field name should always be
in English (see alarm field table appended in this manual). Default value is "EventTime". This
property does not have any effect when PrimarySortField property is empty.

4.4.3.26 ShowHighPriority
Filters the alarms to be displayed, according to severity. If True, high severity alarms are
shown. Otherwise, these are hidden. Default value is True.

4.4.3.27 ShowLowPriority

Filters the alarms to be displayed, according to severity. If True, low severity alarms are
shown. Otherwise, these are hidden. Default value is True.

4.4.3.28 ShowMediumPriority
Filters the alarms to be displayed, according to severity. If True, medium severity alarms
are shown. Otherwise, these are hidden. Default value is True.

4.4.3.29 SimpleAreaFilter
When True, filter behavior per alarm area name is based only in total coincidence of the
initial part of the name. When False, you can also use wildcards and multiple area filters
which must be separated by colons. See the Filter property, which specifies filters per area
name.

4.5 E3Browser
This section contains information about the properties, events and methods of the E3Browser
object.

4.5.1 Events
This section contains information about the events of the E3Browser object.

234 V iew
4.5.1.1 KeyPress
KeyPress (KeyAscii)

This event occurs when the object has the keyboard focus and the user presses a key
corresponding to a character that can be showed on Screen (an ANSI key, of a code indicated in
the KeyAscii variable). That is, the event occurs when some of the following keys are pressed:

· Any keyboard character that can be printed

· CTRL key combined with any standard alphabet character

· CTRL key combined with any special character

· BACKSPACE

· ESC

This event does not occur in the following conditions:

· By pressing TAB

· By pressing ENTER

· By pressing DEL (this is not an ANSI key)

· By pressing keyboard arrow keys

· When a key change the focus from an object to another

While a user presses a key that produces an ANSI code, the object repeatedly receives the
KeyDown and the KeyPress events. When the user releases the key, the KeyUp event occurs.

In order to monitor keyboard physical status or handle keys which are not recognized by the
KeyPress event (such as function keys, browsing keys, etc.), use the KeyDown and KeyUp
events.

4.5.1.2 OnDrawRow
OnDrawRow(Selected, Line, TextColor, BackColor)

This method passes four parameters. The Selected parameter indicates whether the row is
selected. The Line parameter indicates the number of the row being drawn. The TextColor
parameter indicates the row's text color, and the BackColor parameter indicates the text's
background color. If the color is modified within this event, this change is used by E3Browser
when drawing the row. Another important new feature is that if the GetColumnValue method
is called within this event, returned values are the drawn row's ones, and not the selected
row.

V iew 235
4.5.1.3 OnFormatCell
OnFormatCell(Column, FieldName, OriginalValue, FormattedValue)

This event allows customizing the format of E3Browser's cells text. Parameters of this event
are the following:

· Column: Index of E3Browser's visible column (starting at 0). It allows identifying the cell's
column being formatted

· FieldName: A text with the name of the column's field being formatted

· OriginalValue: Cell's unformatted Variant-type value

· FormattedValue: A formatted Variant-type value, according to the configuration of

E3Browser's column. If it is modified inside the event, then it allows changing the formatted
value

Example (formatting Alarm fields):

Sub E3Browser1_OnFormatCell(Column, FieldName, OriginalValue, FormattedValue)
If Column = 15 Then
If Not IsNull(OriginalValue) Then
FormattedValue = SourceTypeName(OriginalValue)
ElseIf Column = 9 Then
If OriginalValue = 0 Then
FormattedValue = "High"
ElseIf OriginalValue = 1 Then
FormattedValue = "Medium"
Else
FormattedValue = "Low"
End If
End If
End Sub

4.5.1.4 MouseMove
MouseMove()

Occurs when the mouse pointer is moved over the E3Browser.

4.5.2 Methods
This section contains information about the methods of the E3Browser object.

4.5.2.1 AboutBox
AboutBox()

This method displays a dialog box with information about version and copyright of the
E3Browser object.

236 V iew
4.5.2.2 ClearFields
ClearFields()

Clears column and row formatting at E3Browser. Example:

Sub CommandButton1_Click()
Screen.Item("E3Browser1").ClearFields()
End Sub

4.5.2.3 GetColumnValue
GetColumnValue(Index)

Returns the value of a cell, in the informed column and selected line. This method has the
Index parameter, determining the index of the desired column. Example:
Sub E3Browser1_DblClick()
Screen.Item("Text1").Value = GetColumnValue(0)
Screen.Item("Text2").Value = GetColumnValue(1)
Screen.Item("Text3").Value = GetColumnValue(2)
Screen.Item("Text4").Value = GetColumnValue(3)
End Sub

4.5.2.4 Requery
Requery()

The Requery method updates the query by using the current Query settings, returning data to
E3Browser. Example:
Sub CommandButton1_Click()
Screen.Item("E3Browser1").Requery()
End Sub

4.5.2.5 RetrieveE3QueryFields
RetrieveE3QueryFields()

The RetrieveE3QueryFields method reads Query data structure and updated E3Browser
formatting with the fields defined by the Query. If it is successful, it returns True. Otherwise, it
returns False. This method is especially useful when one must use one single E3Browser to
display data from different tables or queries. Example:
Sub CommandButton1_Click()
Screen.Item("E3Browser1").RetrieveE3QueryFields()
End Sub

4.5.3 Properties
This section contains information about the properties of the E3Browser object.

V iew 237
4.5.3.1 AllowColumnResize

Enables or disables object's grid column size configuration, at run time. If False, column size
is fixed, and cannot be modified.

4.5.3.2 AllowRowResize

Enables or disables object's grid row size configuration, at run time. If False, row size is
fixed, and cannot be modified.

4.5.3.3 ColumnWidth

Determines E3Browser's columns width, in pixels.

4.5.3.4 CurSel

Indicates E3Browser cursor's current position, that is, the row index where it is placed.

4.5.3.5 E3Query
Returns E3Browser's Query object, so that its properties can be accessed.

4.5.3.6 Fields
Returns the Collection that contains a list of all table fields, making it possible its
reference through the items of this collection. Default value is empty. Example:
Sub E3Browser1_Click()
' Changes the color of Field1
Set fields = Screen.Item("E3Browser").Fields
Set Field1 = fields.Item("Field1")
field1.BkColor = RGB(255, 0, 0) ' Red
' Shows how many fields E3Browser has
MsgBox fields.Count
' Shows E3Browser's number of fields
For Each Fields In fields
MsgBox fields.Name
Next
End Sub

4.5.3.7 FixedBkColor

Specifies E3Browser's first column background color. Default value is beige (RGB(236, 233,
216)).

238 V iew
4.5.3.8 FixedColumnWidth

Specifies E3Browser's first column width (in pixels). Default value is 30.

4.5.3.9 FixedRowFont

Determines the font to be used at E3Browser's header row. This property cannot be used in
scripts or links, and is configured only via Studio. Default value is Arial.

4.5.3.10 FixedRowHeight

Determines E3Browser's header row height (in pixels). Default value is 20.

4.5.3.11 FixedTextColor

Changes E3Browser's header color.

4.5.3.12 GridBkColor

Determines E3Browser's data area background color. Default value is white (RGB(255, 255,
255)).

4.5.3.13 GridFont

Determines the font to be used at E3Browser's data area texts. Default value is Arial. This
property cannot be used in scripts or links, being configured only via Studio.

4.5.3.14 GridLineColor

Determines E3Browser's data grid line color. Default value is gray (RGB(192, 192, 192)).

4.5.3.15 GridLinesType

Determines the type of lines to be drawn on E3Browser's data grid.

Available options for GridLinesType

OPTION DESCRIPTION
0 - GLNone No grid lines.

1 - GLHorz Only horizontal grid lines (default).

2 - GLVert Only vertical grid lines.

V iew 239
 OPTION DESCRIPTION
3 - GLBoth Horizontal and vertical grid lines.

4.5.3.16 RefreshTime

Specifies Query's refresh time relative to the specific database. Through this property it is
possible to verify data update at the related Historic referring to a specific time (in
milliseconds). When the RefreshTime property is 0, there is no data update, and data remains
unchanged.

4.5.3.17 RowHeight

Defines E3Browser's rows height, in pixels. Default value is 20.

4.5.3.18 SelectRow
Determines whether it is possible to select E3 Browser's rows. If True, these rows can be
selected. Otherwise, row selection is disabled.

4.5.3.19 SourceQuery

Contains a reference to the E3Query to which E3Browser is connected.

NOTE: To change E3Browser's Query via scripts (in case the new Query modifies the fields of
the original Query), in addition to changing the SourceQuery property, you must use the
RetrieveE3QueryFields and Requery methods.

4.5.3.20 TextBkColor

Specifies E3Browser's data cells background color. Default value is white (RGB(255, 255,
255)).

4.5.3.21 TextColor

Specifies E3Browser's text color. Default value is black (RGB(0, 0, 0)).

4.5.3.22 TitleTipBkColor

Specifies E3Browser's tip background color. Default value is black (RGB(0, 0, 0)).

240 V iew
4.5.3.23 TitleTipTextColor

Specifies E3Browser's tip text color. Default value is gray (RGB(204, 204, 204)).

4.5.3.24 ToolbarBkColor

Specifies E3Browser's toolbar background color. Default value is beige (RGB(236, 233, 216)).

4.5.3.25 ToolbarFont

Determines E3Browser's toolbar text font. This property cannot be used in scripts or links,
being configured only via Studio.

4.5.3.26 ToolbarForeColor

Specifies E3Browser's toolbar foreground color. Default value is black (RGB(0, 0, 0)).

4.5.4 E3Browser Fields

This section contains information about properties of the E3Browser Field object. This object
does not have events nor methods associated to it.

4.5.4.1 Properties
This section contains information about the properties of the E3Browser field object.

4.5.4.1.1 BkColor

Determines background color of an E3Browser Field. The default value is the color
configured on Windows for the Window item on Control Panel (Control Panel - Display -
Appearance - Advanced).

4.5.4.1.2 Color

Returns the color of the Field text. The default value of this property is black (RGB(0, 0, 0)).

4.5.4.1.3 Format

Configures the formatter used on the Field column.

V iew 241
4.5.4.1.4 Name

Returns the name of the Field.

4.5.4.1.5 Visible

Enables or disables the visibility of the selected Field on E3Browser Query. If this property is
configured to True, the Field is visible on E3Browser. Otherwise, the Field is not shown on
E3Browser at run time. The default value is True.

4.5.4.1.6 Width

Returns the width of the Field, in Himetric units.

4.6 E3Chart
This section contains information about events, properties, and methods of the E3Chart
object.

4.6.1 Events
This section contains information about the events of the E3Chart object.

4.6.1.1 OnCursorChange
OnCursorChange()

This event occurs whenever an E3Chart cursor changes its position. For example, you can
create a script for this event when you need to show cursor position values on Screen.
Sub E3Chart1_OnCursorChange()
Set Chart = Application.GetFrame("").Screen.Item("E3Chart1")
Set Pen = Chart.Pens.Item(0)
' The Text1 object must display the current position of the cursor
Set Text = Application.GetFrame("").Screen.Item("Text1")
If Pen.GetCursorPos(aa, bb) Then
Text.Value = "X Position = " & aa & "; Y Position = " & bb
End If
End Sub

4.6.1.2 OnLegendClick
OnLegendClick(Row, Col, RowData)

Occurs whenever the user clicks in one of the Legend rows. The Row and Col parameters
indicate, respectively, the clicked row and column. The RowData parameter is the Legend Pen
index where the click has occurred. Example:
Sub E3Chart1_OnLegendClick(Row, Col, RowData)
Set text = Screen.Item("Text1")
text.Value = Legend.Item(col).Name & " " & _
Pens.Item(RowData).name
End Sub

242 V iew
4.6.1.3 OnQueryFinish
OnQueryFinish()

Occurs whenever one or more Queries are finished in the object. When this event is
generated, the call for the FitAll or FitPen methods can cause problems if you are using
automatic Queries, since these methods activate other Queries until all data is read. In this
case, it is recommended that the value passed by these methods parameters be 1, which fits
Pens vertically.

4.6.2 Methods
This section contains information about the methods of the E3Chart object.

4.6.2.1 CopyConfig
CopyConfig(SourceChart[, Flags])

The CopyConfig method copies settings from an E3Chart to another one. The SourceChart
parameter indicates the origin E3Chart which properties are copied to the E3Chart calling the
CopyConfig method.

NOTE: in case of Reports, the CopyConfig method works only with Historic-type Pens.

For example, considering copy settings from an E3Chart on a Screen (in this example,
ScreenChart) to another one within a report (ReportChart). In this case, the script
must be added to the E3Report object associated to the Report.
Sub OnBeforePrint
Set Chart = _
Report.Sections("PageHeader").Controls("ReportChart")
Chart.CopyConfig(Application.GetFrame()._
Screen.Item("ScreenChart"))
Chart.LoadData()
Chart.FitAll()
End Sub

NOTE: this method also has an optional and not used parameter called Flags, kept only for
compatibility reasons.

4.6.2.2 FitAll
FitAll([FitStyle])

Fits all Pens into the E3Chart. The optional parameter FitStyle indicates how Pens fit at run
time:

· 0: fits both axes at the same time

V iew 243
· 1: fits only the vertical axis

· 2: fits only the horizontal axis

Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").FitAll()
End Sub

4.6.2.3 FitPen
FitPen(Pen[, FitStyle])

Fits a Pen into the E3Chart specified by index or name. The Pen parameter defines the Pen to
be fit into the E3Chart. The optional parameter FitStyle indicates how Pens fit at run time:

· 0: fits both axes at the same time

· 1: fits only the vertical axis

· 2: fits only the horizontal axis

Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.FitPen(1)
Chart.FitPen("Pen1", 1)
' Fits Pen1 only vertically
End Sub

4.6.2.4 LoadData
LoadData()

Loads data into an E3Chart. This method is specially used for loading data before printing,
when used in a Report object. Example:
Sub CommandButton1_Click()
MsgBox Screen.Item("E3Chart1").LoadData()
End Sub

NOTE: the LoadData method is synchronous only if the pen is not in Automatic mode.

4.6.2.5 ResetConfig
ResetConfig([Flags])

Removes all configurations set in an E3Chart, rolling them back to their initial status. Example:
Sub E3Chart1_OnStartRunning()
' When starting E3Chart1, removes all settings
ResetConfig()
End Sub

244 V iew
NOTE: this method also has an optional parameter called IntFlags, which is kept only for
compatibility reasons.

4.6.2.6 ShowCursors
ShowCursor()

Activates the Interval Search mode. At run time, this resource can be acessed by right-clicking
the object and selecting the Interval Search option on the context menu.

4.6.2.7 ZoomIn
ZoomIn()

The ZoomIn method increases zoom in the E3Chart, that is, it closes up Pen viewing. At run
time, this feature can be accessed by right clicking the object and selecting the Zoom In option
on the context menu. Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").ZoomIn()
End Sub

4.6.2.8 ZoomOut
ZoomOut()

The ZoomOut method decreases zoom in the E3Chart, that is, it opens up Pen viewing in
E3Chart. At run time, this feature can be accessed by right clicking the E3Chart and selecting
the Zoom Out option. Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").ZoomOut()
End Sub

4.6.3 Properties
This section contains information about the properties of the E3Chart object.

4.6.3.1 Axes
Returns the E3Chart Axes Collection. Then, the collection properties may be modified.

4.6.3.2 BackColor

Determines the E3Chart background color. For this color to be displayed, the
ShowBackground property must be set to True. Default value is beige (RGB(236, 233, 216)).

V iew 245
4.6.3.3 CursorBegin

Sets the initial cursor position, between 0 and 1. Either the ShowCursors method must be
executed or the Interval Search option must be enabled for the cursors to appear.

4.6.3.4 CursorColor

Determines the interval search cursor color. Default value is red (RGB(255, 0, 0)).

4.6.3.5 CursorEnd

Sets the final cursor position, between 0 and 1. Either the ShowCursors method must be
executed or the Interval Search option must be enabled for the cursors to appear.

4.6.3.6 CursorLineStyle

Establishes the line style for interval search cursor. The available options are:

Available options for CursorLineStyle

OPTION DESCRIPTION
0 - LS_Solid Applies a solid line in the interval cursor of
the E3Chart.

1 - LS_Dash Applies a dashed line in the interval cursor of

the E3Chart.

2 - LS_Dot Applies a dotted line in the interval cursor of

the E3Chart.

3 - LS_Dashdot Applies a dash-dotted line in the interval

cursor of the E3Chart.

4 - LS_Dashdotdot Applies a dash-dot-dot line in the interval

cursor of the E3Chart.

5 - LS_Null Applies an invisible line in the interval cursor

of the E3Chart.

4.6.3.7 CursorLineWidth

Establishes the cursor line width.

246 V iew
4.6.3.8 ForeColor

Determines the foreground color of the E3Chart. The default value of this property is black (
RGB(0, 0, 0)).

4.6.3.9 GridBkColor

Determines the background color of the E3Chart grid. The default value of this property is
white (RGB(255, 255, 255)). Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.GridBkColor
MsgBox "Next"
E3Chart1.GridBkColor = RGB(0, 255, 0)
MsgBox "Return"
E3Chart1.GridBkColor = Old
End Sub

4.6.3.10 HorAxisTitle

Determines the title of the main horizontal Axis. Example:

Sub CommandButton1_Click()
Set E3Chart1= Screen.Item("E3Chart1")
Old = E3Chart1.HorAxisTitle
MsgBox "Next"
E3Chart1.HorAxisTitle = "Test"
MsgBox "Return"
E3Chart1.HorAxisTitle = Old
End Sub

4.6.3.11 HorGrid

Determines the line type to be applied on the E3Chart horizontal grid.

Available options for HorGrid

OPTION DESCRIPTION
0 - Solid Applies a solid line on the E3Chart horizontal
grid.

1 - Dash Applies a dashed line on the E3Chart

horizontal grid.

2 - Dot Applies a dotted line on the E3Chart

horizontal grid (default).

3 - Dashdot Applies a dash-dot line on the E3Chart

horizontal grid.

4 - Dashdotdot Applies a dash-dot-dot line on the E3Chart

horizontal grid.

V iew 247
 OPTION DESCRIPTION
5 - Invisible Applies an invisible line on the E3Chart
horizontal grid.

Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.HorGrid
For i = 0 To 5
E3Chart1.HorGrid = i
MsgBox "E3Chart1.HorGrid =" & CStr(i)
Next
MsgBox "Return"
E3Chart1.HorGrid = Old
End Sub

4.6.3.12 HorGridColor

Determines the color of the horizontal grid of an E3Chart object. The default value of this
property is gray (RGB(192, 192, 192)). Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.HorGridColor = RGB(255, 0, 0)
MsgBox "Next"
E3Chart1.HorGridColor = RGB(255, 0, 0)
MsgBox "Next"
E3Chart1.HorGridColor = RGB(0, 0, 255)
MsgBox "Return"
E3Chart1.HorGridColor = Old
End Sub

4.6.3.13 HorMinorTicks

Determines the number of subdivisions of the grid horizontal scales. The default value of
this property is 1. Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.HorMinorTicks
For i = 0 To 5
E3Chart1.HorMinorTicks = i
MsgBox "Next value"
Next
E3Chart1.HorMinorTicks = Old
End Sub

4.6.3.14 HorScaleBegin

Determines the initial value to be applied on the grid main horizontal scale. This value can
either be numerical (for XY E3Charts) or Data (for fixed time scale E3Charts). For real time
E3Charts, this property is not applied, and you must use the TimeSpan property instead.

248 V iew
4.6.3.15 HorScaleEnd

Determines the final value to be applied on the grid main horizontal scale. This value can
either be numerical (for XY E3Charts) or Data (for fixed time scale E3Charts). For real time
E3Charts, this property is not applied, and you must use the TimeSpan property instead.
Example:
Sub ComboBox1_Change()
' Defines which query to be displayed
current_query_index = ListIndex
Set E3Chart1 = Screen.Item("E3Chart1")
i = 0
For Each query In E3Chart1.Queries
If i = current_query_index Then
query.FieldFilter(0) = "" ' Fetches everything
Set current_query = query
Else
query.FieldFilter(0) = "<0" ' Fetches anything
' to prevent slowing down the operation
End If
i = i + 1
Next
' Only displays pens which use the current query
For Each pen In E3Chart1.Pens
pen.Visible = (pen.QueryName = current_query.Name)
Next
' Updates queries
E3Chart1.Queries.UpdateData()
Screen.Item("E3Chart1").HorScaleBegin = Now - 0.001
Screen.Item("E3Chart1").HorScaleEnd = Now
End Sub

4.6.3.16 HorScaleFormat

Contains a text representing a mask which the horizontal scale values are displayed. This
mask can represent several value types:

· General: Has no specific formatting, adapting itself automatically to the specified value

· Number: Presents both integer and fractional parts of a number. The user can opt for up to
15 decimal places, for separating thousands or not, and for how to display negative
numbers. For either too small or too large numbers, use the Scientific format

· Date: Presents numerical values for date and time (when applicable). To display time only,
use the equivalent format

· Time: Presents numerical values for time and date (when applicable). To display date only,
use the equivalent format

· Percent: Multiplies the number by 100 and adds the percent symbol to it. It may have up to
15 decimal places

· Scientific: Presents a number with an exponent and a mantissa notation. Ideal for numbers
with varied magnitudes. It may have up to 15 decimal places

· Special: Allows formatting integer numbers in non-decimal bases (hexadecimal, octal, or

binary, for example)

· Other: Allows editing any formatting code directly in this field, or then selecting a previously

V iew 249
 created format

The mask of these formats, as specified in the Type field, is displayed in the Properties window
(for example, "M/d/yy", "0E-00", etc.)

4.6.3.17 HorTickUnit

Determines the number of subdivisions between grid marks. When this property is equal to
0, spacing is automatic. Example:
Sub SubCommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.HorTickUnit
For i = 0 To 30 Step 10
E3Chart1.HorTickUnit = i
MsgBox "E3Chart1.HorTickUnit = " & CStr(i)
Next
MsgBox "Return"
E3Chart1.HorTickUnit = Old
End Sub

4.6.3.18 Legend
Returns the Legend object of the E3Chart. Then, the Legend properties can be changed.

4.6.3.19 MouseMode

Selects one of the runtime options of the E3Chart menu. The available options for this
property are:

· 0 - MouseModeZoom: Puts mouse in Zoom mode by selected area. This option is available
in numerical scale charts in XY and fixed scale. This is the equivalent of selecting the Zoom
Box option of the E3Chart runtime menu

· 1 - MouseModePan: Puts mouse in Scale moving mode. This is the equivalent of selecting
the Move option of the E3Chart runtime menu

· 2 - MouseModePanH: Puts mouse in Scale moving mode only in the horizontal direction. This
is the equivalent of selecting the Move horizontally option of the E3Chart runtime menu

· 3 - MouseModeSearch: Puts mouse in Pen data values search mode. This is the equivalent of
selecting the Search option of the E3Chart runtime menu

· 4 - MouseModeCursors: Enables the Time interval search option. This is the equivalent of
selecting the Search Intervals option of the E3Chart runtime menu

250 V iew
4.6.3.20 Padding

This property determines the distance, in pixels, between the chart and the border of the
E3Chart, as seen on the next figures through the red arrows. The default value of this property
is 10. Example:

Padding property equal to 10

Padding property equal to 30

V iew 251
4.6.3.21 Pens
Returns the Pen Collection object of the E3Chart. The Pen Collection object is used to
insert, remove, or access the available Pens of an E3Chart. This is a read-only property.
Example:
Sub CommandButton1_Click()
For Each pen In Screen.Item("E3Chart1").Pens
pen.Visible = True
Next
End Sub

4.6.3.22 Queries
Returns the Query Collection object of the E3Chart. The Query Collection object is used to
insert, remove, or access the available Queries of an E3Chart. This is a read-only property.

4.6.3.23 RefreshTime

This property determines the update time of the E3Chart. Example:

Sub E3Chart1_OnStartRunning()
MsgBox RefreshTime
End Sub

4.6.3.24 ScaleFont

Determines the text font used on the grid. Example:

Sub CommandButton1_Click()
Screen.Item("E3Chart1").ScaleFont = "Times New Roman"
Screen.Item("E3Chart1").ScaleFont.Size = 12
Screen.Item("E3Chart1").ScaleFont.Italic = True
End Sub

4.6.3.25 ShowBackground
Enables or disables viewing the chart background. If this property is True, the chart
background is displayed. Otherwise, the chart has a transparent background. The color chosen
in the BackColor property does not appear if this property is False (default). Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
E3Chart1.ShowBackground = Not E3Chart1.ShowBackground
End Sub

4.6.3.26 ShowBottomScale
If this property is set to True, the main horizontal Axis is displayed on the bottom of the grid.
Otherwise, it is not displayed. The default value is True. Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
oldBottomScale = E3Chart1.ShowBottomScale
MsgBox "Display axis"
E3Chart1.ShowBottomScale = True
MsgBox "Hide axis"
E3Chart1.ShowBottomScale = False
MsgBox "Return..."
E3Chart1.ShowBottomScale = oldBottomScale
End Sub
252 V iew
4.6.3.27 ShowGridBackground

Enables or disables viewing the grid background. If this property is True (default), the grid
background is displayed. Otherwise, the grid has a transparent background. The chosen color
in the GridBkColor property does not appear if this property is set to False. Example:
Sub CommandButton1_Click()
Set Chart1 = Screen.Item("E3Chart1")
Chart1.ShowGridBackground = Not Chart1.ShowGridBackground
End Sub

4.6.3.28 ShowLeftScale
If this property is set to True, the main vertical Axis is displayed on the left side of the grid.
Otherwise, it is invisible. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.ShowLeftScale = Not Chart.ShowLeftScale
End Sub

4.6.3.29 ShowRightScale
If this property is set to True, the main vertical Axis is displayed on the right size of the grid.
Otherwise, it is invisible. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.ShowRightScale = Not Chart.ShowRightScale
End Sub

4.6.3.30 ShowPopupMenu
Enables or disables the option of displaying the E3Chart runtime menu. If the value is equal
to True, this menu is displayed when the user right-clicks the E3Chart chart. If the value is
False, this menu is not displayed. The default value of this property is True.

4.6.3.31 ShowTitle
If this property is set to True, the main title of the E3Chart is visible. Otherwise, it is
invisible. The Title property contains the title to be displayed in the E3Chart. Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
oldTitle = E3Chart1.Title
oldShowTitle = E3Chart1.ShowTitle
E3Chart1.Title = "Test!"
MsgBox "Display"
E3Chart1.ShowTitle = True
MsgBox "Hide"
E3Chart1.ShowTitle = False
MsgBox "Return"
E3Chart1.Title = oldTitle
E3Chart1.ShowTitle = oldShowTitle
End Sub

V iew 253
4.6.3.32 ShowTopScale

If this property is set to True, the main horizontal Axis on the top of the grid. Otherwise, it is
not displayed. The default value is False. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.ShowTopScale = Not Chart.ShowTopScale
End Sub

4.6.3.33 TimeSpan

Indicates the time scale on E3Chart main horizontal Axis when it is configured to show real
time scale. The value of this property is always in seconds. The default value is 60. Example:
Sub RoundRect1_Click()
MsgBox Screen.Item("E3Chart1").TimeSpan
End Sub

4.6.3.34 Title

Determines the main title of the E3Chart. For this title to appear on the E3Chart, the
ShowTitle property must be set to True.

4.6.3.35 TitleFont

Determines the font of the E3Chart main title. Example:

Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
E3Chart1.Title = "Test"
E3Chart1.ShowTitle = True
MsgBox "Change font"
E3Chart1.TitleFont = "Times New Roman"
MsgBox "Change size"
E3Chart1.TitleFont.Size = 20
End Sub

4.6.3.36 VerAxisTitle

Determines the title of the main vertical Axis. Example:

Sub ComboBox1_Change()
Screen.Item("E3Chart1").VerAxisTitle = "Title1"
End Sub

4.6.3.37 VerGrid

Determines the line type applied on the vertical grid of an E3Chart.

Available options for VerGrid

OPTION DESCRIPTION
0 - Solid Applies a solid line on the vertical grid of the
E3Chart.

254 V iew
 OPTION DESCRIPTION
1 - Dash Applies a dashed line on the vertical grid of
the E3Chart.

2 - Dot Applies a dotted line on the vertical grid of

the E3Chart (default).

3 - Dashdot Applies a dash-dot line on the vertical grid of

the E3Chart.

4 - Dashdotdot Applies a dash-dot-dot line on the vertical

grid of the E3Chart.

5 - Invisible Applies an invisible line on the vertical grid of

the E3Chart.

Example:
Sub E3Chart1_OnStartRunning()
VerGrid = 2
End Sub

4.6.3.38 VerGridColor

Determines the line color of the main vertical Axis of the grid. The default value of this
property is gray (RGB(192, 192, 192)). Example:
Sub RoundRect1_Click()
Screen.Item("E3Chart1").VerGridColor = RGB(255, 0, 0)
End Sub

4.6.3.39 VerMinorTicks

Determines the number of subdivisions between marks of the main vertical Axis of the grid.
The default value of this property is 1. Example:
Sub RoundRect1_Click()
Screen.Item("E3Chart1").VerMinorTicks = 3
End Sub

4.6.3.40 VerScaleBegin

Determines the value on top of the main vertical Axis of the E3Chart grid. The default value of
this property is 100. Example:
Sub RoundRect1_Click()
MsgBox Screen.Item("E3Chart1").VerScaleBegin
End Sub

V iew 255
4.6.3.41 VerScaleEnd

Determines the value on bottom of the main vertical Axis of the grid. The default value of this
property is -100. Example:
Sub RoundRect1_Click()
MsgBox Screen.Item("E3Chart1").VerScaleEnd
End Sub

4.6.3.42 VerScaleFormat

Contains a text representing a mask in which the vertical scale values are displayed. This
mask can represent several value types:

· General: Has no specific formatting, adapting itself automatically to the specified value

· Number: Presents both integer and fractional parts of a number. The user can opt for up to
15 decimal places, for separating thousands or not, and for how to display negative
numbers. For either too small or too large numbers, use the Scientific format

· Date: Presents numerical values for date and time (when applicable). To display time only,
use the equivalent format

· Time: Presents numerical values for time and date (when applicable). To display date only,
use the equivalent format

· Percent: Multiplies the number by 100 and adds the percent symbol to it. It may have up to
15 decimal places

· Scientific: Presents a number with an exponent and a mantissa notation. Ideal for numbers
with varied magnitudes. It may have up to 15 decimal places

· Special: Allows formatting integer numbers in non-decimal bases (hexadecimal, octal, or

binary, for example)

· Other: Allows editing any formatting code directly in this field, or then selecting a previously
created format

The mask of these formats, as specified in the Type field, is displayed in the Properties window
(for example, "M/d/yy", "0E-00", etc.)

4.6.3.43 VerTickUnit

Determines the number of subdivisions between grid marks. When this property is set to 0,
spacing is automatic. Example:

256 V iew
 Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
Old = E3Chart1.VerTickUnit
For i = 0 To 30 Step 10
E3Chart1.VerTickUnit = i
MsgBox "E3Chart1.VerTickUnit = " & CStr(i)
Next
MsgBox "Return"
E3Chart1.VerTickUnit = Old
End Sub

4.6.4 Pen Collection

This section contains information about methods and properties of the Pen Collection object.
This object does not have events associated to it.

4.6.4.1 Methods
This section contains information about the methods of the Pen Collection object.

NOTE: The E3Chart pen collection must be accessed via Pens property.

4.6.4.1.1 AddPen
AddPen(PenName)

The AddPen method adds a new Pen to the E3Chart, returning the Pen created. Example:
Sub CommandButton1_Click()
' Creates an untitled pen.
Set Pen = Screen.Item("E3Chart1").Pens.AddPen("")
MsgBox Pen.Name
End Sub
SubCommandButton1_DbClick()
' Creates a pen named "Pen1".
' If the name already exists, increments it.
Set Pen = Screen.Item("E3Chart1").Pens.AddPen("Pen1")
MsgBox Pen.Name
End Sub

Sub CommandButton2_Click()
' Creates a pen and links it to DemoTag1.
Set Chart = Screen.Item("E3Chart1")
Set Pen = Chart.Pens.AddPen("")
MsgBox Pen.Name
Pen.UsetimeStamp = True
Pen.YLink = "Data.DemoTag1"
Pen.Connect()
End Sub

4.6.4.1.2 ChangePenPos
ChangePenPos(Source, Dest)

Modify the drawing position of the Pens in an E3Chart. This method is especially useful when a
Pen has a line shape and another one has an area shape. If the area pen is drawn after the line
pen, it may hide the last one. One solution could be to invert the drawing order of these Pens.

· Source: determines the index of the Pen to be moved (starting at 1)

V iew 257
· Dest: determines the Pen destination (starting at 1)

Example:
Sub CommandButton1_Click()
' Moves pen 1 to position 2.
Screen.Item("E3Chart1").Pens.ChangePenPos(1, 2)
End Sub

4.6.4.1.3 Item
Item(Index)

The Item method turns a Pen object back to the Pen Collection, specified by an index. This
method has the Index parameter that can be a numeric type if corresponding to the Pen index,
or a text if it corresponds to the Pen name. Example:
Sub CommandButton1_Click()
' Gets the first pen.
Set Pen1 = Screen.Item("E3Chart1").Pens.Item(0)
End Sub

4.6.4.1.4 Remove
Remove(Name)

The Remove method removes a Pen using the specified name. This method has a Name
parameter determining the name of the Pen to be removed. Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Pens.Remove(1)
End Sub

4.6.4.1.5 SetCursorPos
SetCursorPos(X, Range)

Positions the cursor of every E3Chart Pen. It is the same behavior as the SetCursorPos method
of each Pen.

4.6.4.2 Properties
This section contains information about the properties of the Pen Collection object.

4.6.4.2.1 Count

Contains the total amount of Pens inserted on the E3Chart. This is a read-only property.

258 V iew
4.6.4.3 Pens
This section contains information about methods and properties of the Pen object. This object
does not have events associated to it.

4.6.4.3.1 Methods

This section contains information about methods and properties of the Pen object. This object
does not have events associated to it.

4.6.4.3.1.1 AddPoint
AddPoint(ValueX, ValueY[, Quality])

Adds a point at the end of the real time buffer. The size of the buffer is only valid after
connecting the Pen. If the Pen is created in Studio, connection is automatic, but if it is created
via script it is necessary to call the Connect method after creating it. This method must be
used with real time Pens, and with the UseTimeStamp property set to False. The optional
parameter Quality indicates the quality of the point to be inserted. If this parameter is not
informed, the quality of the point is considered as Good (192). The number of points that can
be inserted into a Pen depends on the size of the buffer (the BufferSize property of the Pen).

4.6.4.3.1.2 Clear
Clear()

Erases data from real time buffers, without decreasing its size. This method does not
disconnect Links, nor removes historical data.

4.6.4.3.1.3 Connect
Connect()

The Connect method connects the Pen to the server in order to receive data in real time,
associating the XLink and YLink properties. If the Pen is already connected, this method
remains inactive. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.Disconnect()
Pen1.Connect()
End Sub

4.6.4.3.1.4 Disconnect
Disconnect()

The Disconnect method cleans up the current data and prevent a Pen from receiving more real
time data from its associated tag. If the Pen is already disconnected, this method does
nothing. It can be used to change a tag at run time. When the Disconnect method is used with
a mixed pen (DataSourceType property equal to 2), this method removes the real time part,
and keeps the historic part. At run time, the Connect method must be called to show real time

V iew 259
data again. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.Disconnect()
Pen1.Connect()
End Sub

4.6.4.3.1.5 GetCursorPos
GetCursorPos(X, Y)

Returns to the position where the cursor intercepted the Pen in the E3Chart. This method has
the X and Y parameters, corresponding to x and y cursor positions. If this method is successful,
it returns True, otherwise it returns False. Example:
Sub CommandButton1_Click()
For Each pen In Chart.Pens
If pen.GetCursorPos(aa, bb) Then
strResult = strResult & pen.name & " := " & CSTr(CDate(aa)) + _
"y " + CStr(bb) + vbNewLine
End If
Next
MsgBox strResult
End Sub

4.6.4.3.1.6 GetPoint
GetPoint(ValueX, ValueY)

Returns the X and Y coordinates of the nearest point of the input value in the ValueX
parameter. The ValueX parameter informs the reference value to search for the point, and
then gets the effective value of the X coordinate of the nearest point found. The ValueY
parameter returns the effective value of the Y coordinate of the nearest point found. This
method returns True if a point is found, and False otherwise.

4.6.4.3.1.7 SetCursorPos
SetCursorPos(X, Range)

Positions the cursor of the E3Chart Pen. The X parameter indicates what is the position where
the cursor must be positioned, similar to the behavior of moving the cursor in a mouse search.
The cursor is moved to the nearest position indicated by the X parameter. The Range
parameter is optional and used as a validation. The cursor is only moved if the valid point is
inside the interval. Any negative value indicates that the passed interval must not be used.
Example:
' If there is a valid point in (x = 1, y = 10) and another one in (x = 4, y = 20)
SetCursorPos(2) ' moves the cursor to the point (1, 10)
SetCursorPos(4) ' moves the cursor to the point (4, 20)
' When range is used, the cursor is only moved if the point is inside the range.
' Does not move the cursor, because 2 is more than 0.5 units
' away from the nearest point, which is 1
SetCursorPos (2, 0.5)
' sends the cursor to the point (1, 10)
SetCursorPos (2, 4)

This method returns True if the cursor is moved, otherwise returns False.

260 V iew
4.6.4.3.2 Properties

This section contains information about the properties of the Pen object.

4.6.4.3.2.1 AutoQuery

When AutoQuery property is set to True, one says that this is an AutoQuery-type Pen, or
simply an Automatic Pen. The goal of an Automatic Pen is to save memory consumption and
query time. To do so, it applies filters on E3Timestamp field to bring only needed data into
E3Chart's area. Every time an E3Chart's visible period changes, an Automatic Pen retrieves
missing data to complete the drawing of that period. In addition, an AutoQuery also completes
historical missing data to connect Pen's historical and real time parts. If, by any reason,
historical data is not retrieved after thirty seconds, an AutoQuery is cancelled on that part.
See also the MaxGapTime property for more details.

Due to the way an AutoQuery applies filters to an E3TimeStamp field, it is not available for
user-defined Storage queries or SQL code. That is, even when AutoQuery property is set to
True, it has no effect on Storage-type Queries. One way to recognize an AutoQuery is a hatched
drawing on the E3Chart screen. Every time hatches appear on that drawing, this means that on
this period an AutoQuery is being performed. When hatch borders are in red, this means that
AutoQuery on that part is on failure. In this case, E3Chart reruns problematic Queries on that
part.

NOTE: Different from a real time part, where each Pen has its own data buffer, Pen's historical
part is stored on the Query, and it is shared among Pens. For example, when a Query has
three fields, E3Timestamp, Field1, and Field2, this data is stored on the Query and it is
available for Pens sharing that Query. Thus, the common part, usually the E3Timestamp field,
can be used by two different Pens, without duplicating data. In case of Automatic Pens, two
different Pens can use the same table and, due to different scales, they can load different
Query periods. In this situation, each Pen automatically inherits the part loaded by the other
Pen.
The Query object cannot work simultaneously in Automatic and Non-Automatic mode. This
also means that if different Pens, one Automatic and another one Non-Automatic, want to
share the same Query, that Query is going to adapt to the first Pen using it. That is, the
AutoQuery property does not ensure that a Query is in Automatic mode, this depends on
other factors.

4.6.4.3.2.2 AverageY

Informs the average of the Pen in the interval, in case the EnableCalc property is enabled. In
case the E3Chart is in Interval Search mode, displays the average of this interval. Otherwise,
displays the interval between the beginning and the end on the horizontal Axis. Values with
bad quality are not considered in case the ShowBadPoints is disabled. This is a read-only
property.

V iew 261
4.6.4.3.2.3 BkColor

Determines the background color used on a Pen of Area type. The default value of this
property is empty. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.BkColor = RGB(255, 0, 0)
End Sub

4.6.4.3.2.4 BufferSize

Determines the number of points kept on the Pen in real time. After this value, older data is
discarded. On historic Pens, this property has no effect. This property is only considered after
connecting to the Pen. For more information, see the Connect method. The default value of
this property is 1000, and it must be always greater than 0. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.Disconnect()
Pen1.BufferSize = 5000
Pen1.Connect()
End Sub

4.6.4.3.2.5 Color

Determines the line color of the Pen in the E3Chart. The default value of this property is
empty. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.Color= RGB(212, 208, 20)
End Sub

4.6.4.3.2.6 DataSourceType

Determines Pen data source. The available options for this property are the following:

Available options for DataSourceType

OPTION DESCRIPTION
0 - Real Time Indicates connection of the Pen to a tag
updated in real time.

1 - Historic Indicates connection of the Pen to data from

a Query.

2 - Real Time & Historic Indicates connection of the Pen to real time
and historic tags data simultaneously.

When the DataSourceType property is equal to 0 (Real Time), the XLink and YLink properties
inform the Links used, or else the UseTimeStamp property informs that the XLink property is

262 V iew
not used, being replaced by the timestamp of the YLink property. When the DataSourceType
property is equal to 1 (Historic), the XField and YField properties informs field tables to be
used. The QueryName property indicates the name of the table used. When the
DataSourceType property is equal to 2 (Real Time & Historic), the 0 and 1 options work
simultaneously for the Pen.

NOTE: At run time, when this property changes and the Pen stops displaying real time data,
you must call the Connect method to display data again.

Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
MsgBox "Click OK to create a pen."
Set Pen = E3Chart1.Pens.AddPen("Pen1")
Pen.DataSourceType = 0 ' Real time
Pen.YLink = "Data.DemoTag1"
Pen.UseTimeStamp = True ' In X uses timestamp
Pen.Color = RGB(255, 0, 0)
Pen.Docstring = "Test"
MsgBox "Clique OK to connect."
Pen.Connect() ' Starts receiving data
MsgBox "Click OK to fit."
E3Chart1.FitPen(0)
MsgBox "Click OK to remove this pen."
E3Chart1.Pens.Remove(Pen.Name)
End Sub

4.6.4.3.2.7 DigitalData

Determines the digital plot style. If this property is set to True, the digital plot style
assumes that data changing is in digital form, that is, its value relative to the last one changed
instantly. Otherwise, the changing is considered linear and the points are bounded by a line.
The default value of this property is True. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.DigitalData = True
End Sub

4.6.4.3.2.8 EnableCalc

Enables or disables calculating average, minimum, and maximum inside the interval.

4.6.4.3.2.9 EnableHighLimit

Enables or disables checking the high limit.

4.6.4.3.2.10 EnableLowLimit

Enables or disables checking low limit.

V iew 263
4.6.4.3.2.11 EU

This property is used to identify the engineering unit represented by the value. For example,
degrees, meters, KW/h, etc.

4.6.4.3.2.12 HighlightMaxGapTime

Specifies if the line of the visual connection between the historic and real time part of a
mixed Pen (defined in MaxGapTime) must have a different color (defined in MaxGapTimeColor)
and style (defined in MaxGapTimeStyle). The default value of this property is False.

4.6.4.3.2.13 HighLimit

Determines the high limit alarm.

4.6.4.3.2.14 InterpolatedBeginY

Informs the value of the interpolated point where the initial cursor crosses the Pen. This is a
read-only property.

4.6.4.3.2.15 InterpolatedEndY

Informs the value of the interpolated point where the final cursor crosses the Pen. This is a
read-only property.

4.6.4.3.2.16 LimitPenBkColor

Determines the background color of the Pen when in alarm.

4.6.4.3.2.17 LimitPenColor

Determines the Pen color when in alarm.

4.6.4.3.2.18 LowLimit

Determines the low limit alarm.

264 V iew
4.6.4.3.2.19 MaxGapTime

Allows specifying a limit time to be considered for a visual connection between the historic
and real time part of a mixed Pen. The default value of this property is 0. The value of this
property can be modified at run time.

NOTE: This property is available from version 3.5 on. For applications created in prior
versions and opened in version 3.5, the value of the property is always 0.

4.6.4.3.2.20 MaxGapTimeColor

Allows configuring the color of the visual connection between the historic and real time
part of a mixed Pen, defined in the MaxGapTime property. The default value of this property is
red (RGB(255, 0, 0)).

4.6.4.3.2.21 MaxGapTimeStyle

Specifies the line style of the visual connection between the historic and real time part of
a mixed Pen, configured in the MaxGapTime property. Possible values for this property are the
following:

· 0: Solid

· 1: Dashed

· 2: Dotted

· 3: Dash - Dot

· 4: Dash - Dot - Dot

· 5: Invisible

NOTE: the option 5 (Invisible) of this property can only be selected via scripts.

4.6.4.3.2.22 MaxY

Informs the maximum value of the Pen in the interval, in case the EnableCalc property is
enabled. In case the E3Chart is in Interval Search mode, displays the average in this interval.
Otherwise, displays the average in the interval between the beginning and the end in the
horizontal Axis. Values with bad quality are not considered in case the ShowBadPoints
property is disabled. This is a read-only property.

V iew 265
4.6.4.3.2.23 MinY

Informs the minimum value of the Pen in the interval, in case the EnableCalc property is
enabled. In case the E3Chart is in Interval Search mode, displays the average in this interval.
Otherwise, display the average in the interval between the beginning and the end on the
horizontal Axis. Values with bad quality are not considered if the ShowBadPoints property is
disabled. This is a read-only property.

4.6.4.3.2.24 Name

Determines the name of the Pen. Example:

Sub CommandButton1_Click
Screen.Item("E3Chart1").Pens.Name = "Pen1"
End Sub

4.6.4.3.2.25 PenStyle

Determines the Pen line style. The default value of this property is 0 (zero). The available
options are the following:

Available options for PenLineStyle

OPTION DESCRIPTION
0 - LsSolid Solid line.

1 - LsDash Dashed line.

2 - LsDot Dotted line.

3 - LsDashDot Dash-dot line.

4 - LsDashDotDot Dash-dot-dot line.

5 - LsNull No line.

NOTE: Using a value different from 0 (LsSolid) in this property, together with the Width
property greater than 1 (one), may degrade the drawing performance of the Pen.

4.6.4.3.2.26 PenType

Determines the drawing type of the Pen in the E3Chart:

· 0: Line

· 1: Point

266 V iew
· 2: Point-line

· 3: Area

Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.PenType = 1
End Sub

4.6.4.3.2.27 QueryName

Determines the name of the Query the Pen is using. This property is used if the
DataSourceType property is set to 1 (Historic). Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.QueryName = Query12
End Sub

4.6.4.3.2.28 ScaleX

The ScaleX property indicates to which X scale of the E3Chart this Pen is linked. The
configured scale for ScaleX has a horizontal orientation, that is, it may be positioned on top or
on the bottom of the E3Chart. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Set Pen = Chart.Pens.AddPen("DemoTagPen2")
Pen.XLink = "Data.DemoTag2"
Pen.UseTimeStamp = True
' The scale must exist.
Pen.ScaleX = "ScaleForDemoTag2"
Pen.Connect
End Sub

4.6.4.3.2.29 ScaleY

The ScaleY property indicates to which Y scale of the E3Chart this Pen is linked. The
configured scale for ScaleY has a vertical orientation, positioned on the left or on the right of
the object. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Set Pen = Chart.Pens.AddPen("DemoTagPen2")
Pen.YLink = "Data.DemoTag2"
Pen.UseTimeStamp = True
' The scale must exist.
Pen.ScaleY = "ScaleForDemoTag2"
Pen.Connect
End Sub

4.6.4.3.2.30 ScanValue

Defines the scan time waiting time for the real time Pen tag. This value is taken into account
on analog drawing mode. When this value overrides the value determined by ScanValue, it is
considered that the tag value has not been changed on the interval. Otherwise, when
ScanValue is equal to zero, Pen data is always connected with a straight line bounding these
two points as if the value is varying in linear mode. The unit of this property is milliseconds.

V iew 267
Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.ScanValue = 1000
End Sub

4.6.4.3.2.31 ShowAverage

Enables displaying Pen average on the E3Chart. This property is only effective if the
EnableCalc property is enabled.

4.6.4.3.2.32 ShowBadPoints

When disabled, bad quality points are not plotted. If the Pen is drawing lines, the lines
crossing bad quality points are not connected. For the point quality to be considered in the
historic part of the Pen, the fieldname_quality must be selected on the E3Chart Query. When
enabled, all points are plotted normally.

4.6.4.3.2.33 ShowMinMax

Enables displaying minimum and maximum points of the Pen on the E3Chart. This property
is only effective if the EnableCalc property is enabled.

4.6.4.3.2.34 UseTimeStamp

Determines that it is used, for the horizontal Axis, the value of the timestamp associated to
the vertical Axis. See an example in the description of the DataSourceType property.

4.6.4.3.2.35 Visible

Determines if the Pen is visible on the E3Chart. If this option is set to True, the Pen is visible
at run time. Otherwise, the Pen is hidden. Example:
Sub CommandButton1_Click()
Set Pen1 = Screen.Item("E3Chart1").Pens.Item("Pen1")
Pen1.Visible = Not Pen1.Visible
End Sub

4.6.4.3.2.36 Width

Determines the width of the Pen line on the E3Chart. The default value of this property is 0
(zero).

NOTE: Using values greater than 1 (one) in this property, together with the PenStyle property
different from 0 (LsSolid), may degrade the drawing performance of the Pen.

268 V iew
4.6.4.3.2.37 XField

Name of the Query Field used to plot data on a horizontal scale. It is used for historic Pens.

4.6.4.3.2.38 XLink

Name of the link used to plot data on a horizontal scale. When the value of this property is
changed, the Pen is automatically disconnected. After configuring it, the Connect method
must be called so that the Pen starts receiving data relative to this link. This is only used for
real time Pens.

4.6.4.3.2.39 XMaxY

Informs the X value relative to the MaxY point. This is a read-only property.

4.6.4.3.2.40 XMinY

Informs the X value relative to the MinY point. This is a read-only property.

4.6.4.3.2.41 YField

Name of the Query Field used to plot data on a vertical scale. It is used for historic Pens.

4.6.4.3.2.42 YLink

Name of the link used to plot data on a vertical scale. When the value of this property is
changed, the Pen is automatically disconnected. After configuring it, the Connect method
must be called so that the Pen starts receiving data relative to this link. This is used only for
real time Pens.

4.6.5 Axis Collection

This section contains information about methods and properties of the Axis Collection object.
This object does not have events associated to it.

4.6.5.1 Methods
This section contains information about the methods of the Axis Collection object.

V iew 269
4.6.5.1.1 AddAxis
AddAxis(AxisName)

Adds a new Axis with the name specified in the AxisName parameter and returns it. In case of
trying to create an Axis with an already existing name, an error message is displayed. To
generate a name automatically, simply pass a blank name in the AxisName parameter.
Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Set newAxis = Chart.Axes.AddAxis("")
newAxis.Color = RGB(255, 0, 0)
End Sub

4.6.5.1.2 Remove
Remove(Index)

Removes the Axis by its name or index, as specified in the Index parameter. Main Axes 0 and 1
cannot be removed. In case of trying to remove them, an error message is displayed. Example:
Sub CommandButton1_Click()
' This example removes all additional axes
Set Chart = Screen.Item("E3Chart")
While (Chart.Axes.Count > 2)
Chart.Axes.Remove(2)
Wend
End Sub
Sub CommandButton1_Click()
' Removes an additional axis, if available
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Remove(2)
End Sub

4.6.5.2 Properties
This section contains information about the properties of the Axis Collection object.

4.6.5.2.1 Count

Returns the total amount of E3Chart Axes, including the main Axes (Horizontal and Vertical).
Example:
CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
MsgBox Chart.axes.Count
End Sub

4.6.5.2.2 HorAxis

Returns the main horizontal Axis. This Axis also appears on the Axes list. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
MsgBox Chart.axes.Item(0).Name & ", " & Chart.axes.Item(1).Name
MsgBox Chart.axes.HorAxis.Name & ", " & _
Chart.axes.Item("AxisName").Name
End Sub

270 V iew
4.6.5.2.3 Item

Returns the Axis using its name or index. The index 0 is always the main horizontal Axis and
the index 1 is always the main vertical Axis. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart")
MsgBox Chart.axes.Item(0).Name & ", " & Chart.axes.Item(1).Name
MsgBox Chart.axes.HorAxis.Name & ", " & Chart.axes.Item("AxisName").Name
End Sub

4.6.5.2.4 VerAxis

Returns the main vertical Axis. This Axis also appears on the list of Axes. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
MsgBox Chart.axes.Item(0).Name & ", " & Chart.axes.Item(1).Name
MsgBox Chart.axes.Item("AxisName").Name & ", " & _
Chart.axes.VerAxis.Name
End Sub

4.6.5.3 Axes
This section contains information about methods and properties of the Axis object. This object
does not have events associated to it.

4.6.5.3.1 Methods

This section contains information about the methods of the Axis object.

NOTE: The HorAxis and VerAxis are Axes Collection properties which access default vertical
and horizontal Axes, respectively. For example, instead of using Chart.Axes.Item
("HorizontalAxis"), you may use Chart.Axes.HorAxis. Other user-created Axes
have their own names.

4.6.5.3.1.1 GetHistoricPeriod
GetHistoricPeriod(Begin, End)

Returns the time interval shown in the historic scale. The Begin parameter indicates the
historic scale initial date, and the End parameter indicates the final date. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart")
Chart.Axes.Item("AxisName").GetHistoricPeriod min, max
Value = CStr(dmin) & " " & CStr(dmax)
MsgBox "Start Date = " & CStr(min) & _
vbNewLine & " Ending Date = " & CStr(max)
End Sub

V iew 271
4.6.5.3.1.2 GetMinMax
GetMinMax(Min, Max)

Returns the minimum and maximum numeric scale values in the Min and Max parameters.
Example:
Sub CommandButton1_DBClick()
Set Chart = Screen.Item("E3Chart")
Chart.Axes.Item("AxisName").GetMinMax dmin, dmax
MsgBox CStr(dmin) & " " & CStr(max)
End Sub

4.6.5.3.1.3 GetRealTimePeriod
GetRealTimePeriod(Period)

Returns the time unit configured in the real time scale. The Period parameter receives the
time scale value. Example:
Dim Unit, Value
Unit = Screen.Item("E3Chart1").Axes.Item_
("HorizontalAxis").GetRealTimePeriod(Value)
MsgBox "Value: " & CStr(Value) & " Unit: " & CStr(Unit)

4.6.5.3.1.4 GetTickSpacing
GetTickSpacing(TickSpacing, TimeUnit)

Returns the spacing between ticks and the configured unit. The TickSpacing parameter
determines the spacing between the ticks (scale subdivisions) and the TimeUnit parameter
determines the unit. When this parameter is zero, it means it is automatic. The unit is not
used when scale is numeric. The available options in the TimeUnit parameter are the same
displayed in the GetRealTimePeriod method table. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Unitvalue_
= Chart.Axes.Item("AxisName").GetTickSpacing(TickSpacing)
MsgBox "Value " = " & CStr(TickSpacing) & _
" unit " & CStr(Unitvalue)
End Sub

4.6.5.3.1.5 SetHistoricPeriod
SetHistoricPeriod(Begin, End)

Sets up the time period for the historic scale. The Begin parameter determines the initial
period of the scale and the End parameter determines the scale final period of the scale.
Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart2")
Chart.Axes.Item("AxisName").ScaleType = 2
' Displays the last period of time
Chart.Axes.Item("AxisName").SetHistoricPeriod now - 1, now
End Sub

272 V iew
4.6.5.3.1.6 SetMinMax
SetMinMax(Min, Max)

Sets up the minimum and maximum values of the numeric scale. The minimum value is
determined by the Min parameter and the maximum value by the Max parameter. Example:
Sub Circle1_Click()
Set Chart = Screen.Item("E3Chart2")
Chart.Axes.Item("AxisName").SetMinMax -10, 500
End Sub

4.6.5.3.1.7 SetRealTimePeriod
SetRealTimePeriod(Times, TimeUnit)

Sets up the time period in the unit defined by the TimeUnit parameter. The available options in
this TimeUnit parameter are the same displayed in the GetRealTimePeriod method. The Times
parameter determines the time period and the scale unit is specified by the TimeUnit
parameter. In this mode (real time) the Axis is always updated. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart5")
' tuSeconds = 0, tuMinutes =1, tuHours = 2, tuDays = 3,
' tuWeeks = 4, tuMonths = 5, tuYears = 6
' 2 minutes
Chart.Axes.Item("AxisName").SetRealTimePeriod 2, 1
Chart.Axes.Item("AxisName").SetTickSpacing 30, 0
End Sub

4.6.5.3.1.8 SetTickSpacing
SetTickSpacing(TickSpacing, TimeUnit)

Sets up the spacing between ticks (scale subdivisions) by using the configured unit. The
spacing between ticks is determined by the TickSpacing parameter. The TimeUnit parameter
determines the unit. In case of numeric scale, the unit is not considered. Available options in
the TimeUnit parameter are the same displayed in the GetRealTimePeriod method table.
Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
' 10 (in case of numeric scale,
' the value of the unit is not considered)
Chart.Axes.Item("AxisName").SetTickSpacing 10, 0
Chart.Axes.Item("AxisName").SetTickSpacing 20, 0
End Sub

4.6.5.3.2 Properties

This section contains information about the methods of the Axis object.

NOTE: The HorAxis and VerAxis are Axes Collection properties which access default vertical
and horizontal Axes, respectively. For example, instead of using Chart.Axes.Item
("HorizontalAxis"), you may use Chart.Axes.HorAxis. Other user-created Axes
have their own names.

V iew 273
4.6.5.3.2.1 Color

Determines the main color of the Axis. Example:

Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.HorAxis.Color = RGB(0, 255, 0)
End Sub

4.6.5.3.2.2 EnableTextColor

This property, when enabled, specifies that the Axis text has the same color of the scale,
configured in the Color property. The default value of this property is False.

4.6.5.3.2.3 Format

Determines formatting of the Axis values. Example:

Sub CommandButton1_Click()
' Changes formatting
Set Chart = Screen.Item("E3Chart1")
strOldFormat = Chart.Axes.Item("AxisName").Format
MsgBox "Click to set automatic formatting."
Chart.Axes.Item("AxisName").Format = "" ' Automatic
MsgBox "Click to use another formatting."
Chart.Axes.Item("AxisName").Format = "0.0"
MsgBox "Click to use another formatting."
Chart.Axes.Item("AxisName").Format = "dd/MM/yy hh:mm:ss"
MsgBox "Click again to change back to the original formatting."
Chart.Axes.Item("AxisName").Format = strOldFormat
End Sub

4.6.5.3.2.4 GridColor

Determines the color of the grid lines. Example:

Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").ShowGrid = False
MsgBox "Click to change the color of the grid lines."
Chart.Axes.Item("AxisName").GridColor = RGB(0, 0, 255)
Chart.Axes.Item("AxisName").ShowGrid = True
End Sub

4.6.5.3.2.5 GridStyle

Determines the style of the grid line. The available options are the following:

Available options for GridStyle

OPTION DESCRIPTION
0 - solid The grid line style is solid.

1 - dash The grid line style is dashed.

2 - dot The grid line style is dotted.

274 V iew
 OPTION DESCRIPTION
3 - dashdot The grid line style is dash-dot.

4 - dashdotdot The grid line style is dash-dot-dot.

5 - invisible There is no visible lines on the grid.

Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
' Solid 0, dash 1, dot 2, dashdot 3, dashdotdot 4, invisible 5
For i = 0 To 5
MsgBox "Click to change the line style of the grid."
Chart.Axes.Item("AxisName").GridStyle = i
Next
End Sub

4.6.5.3.2.6 Inverse

Inverts the order of the minimum and maximum values on the numerical scale. Normally, in
vertical scales, the minimum value appears at the bottom, and the maximum at the top. On
horizontal scales, the minimum value appears on the left, and the maximum value on the
right. When the Inverse property is set to True, however, this order is inverted, maximum
values at the bottom or on the left, minimum values at the top or on the right. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").Inverse = Not _
Chart.Axes.Item("AxisName").Inverse
End Sub

4.6.5.3.2.7 MinorTicks

Determines the total amount of subdivisions between scales. Example:

Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").MinorTicks = _
Chart.Axes.Item("AxisName").MinorTicks + 1
End Sub

4.6.5.3.2.8 Mirror

Indicates the Axis mirroring. If this property is set to True, the Axis is mirrored on the
opposite side of the original Axis. Otherwise, the Axis remains on the same position. Example:
Sub CommandButton1_DBClick()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").Mirror = Not _
Chart.Axes.Item("AxisName").Mirror
End Sub

V iew 275
4.6.5.3.2.9 Name

Determines the name of the Axis. Example:

Sub CommandButton1_DBClick()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").Title = Chart.Axes.Item("AxisName").Name
End Sub

4.6.5.3.2.10 Position

Determines the position of the Axis relative to the E3Chart grid. The available options are
the following:

Available options for Position

OPTION DESCRIPTION
0 - axpLeft The Axis is positioned on the left of the scale.

1 - axpRight The Axis is positioned on the right of the

scale.

2 - axpTop The Axis is positioned at the top of the scale.

3 - axpBottom The Axis is positioned at the bottom of the

scale.

Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Set newAxis = Chart.Axes.AddAxis("")
For i = 0 To 3
MsgBox "Click OK to change the axis position."
newAxis.Position = i
Next
MsgBox "Remove the axis."
Chart.Axes.Remove(newAxis.Name)
End Sub

4.6.5.3.2.11 ScaleType

Determines the scale type displayed by the Axis. The available options for this item are the
following:

Available options for ScaleType

OPTION DESCRIÇÃO
0 - atNumberScale Numerical scale.

1 - atLastPeriod Displays the last period (Real Time).

276 V iew
 OPTION DESCRIÇÃO
2 - atPeriod Time interval (Historic).

Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Set newAxis = Chart.Axes.AddAxis("")
For i = 0 To 2
MsgBox "Click OK to change the scale type."
newAxis.ScaleType = i
Next
MsgBox "Remove the axis."
Chart.Axes.Remove(newAxis.Name)
End Sub

4.6.5.3.2.12 ShowGrid

Determines grid lines viewing. If this property is set to True, the grid lines are displayed.
Otherwise, the lines are hidden. Example:
Sub CommandButton_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").ShowGrid = Not _
Chart.Axes.Item("AxisName").ShowGrid
End Sub

4.6.5.3.2.13 Title

Determines the title of the Axis. Example:

Sub CommandButton1_Click()
Set Chart = Screen.Item("E3Chart1")
Chart.Axes.Item("AxisName").Title = _
Chart.Axes.Item("AxisName").Name
MsgBox "Click to remove the title."
' Removes the title
Chart.Axes.Item("AxisName").Title = ""
End Sub

4.6.5.3.2.14 Visible

Determines the visibility of the Axis on the grid. If this property is set to True, the Axis is
visible on the grid. Otherwise, the Axis is hidden. Example:
Sub CommandButton1_Click()
Set Chart = Screen.Item(E3Chart1)
Chart.Axes.Item("AxisName").Visible = Not _
Chart.Axes.Item("AxisName").Visible
End Sub

4.6.6 Query Collection

This section contains information about methods and properties of the Query Collection
object. This object does not have events associated to it.

V iew 277
4.6.6.1 Methods
This section contains information about the methods of the Query Collection object.

4.6.6.1.1 AddQuery
AddQuery(QueryName, IsInternal)

Adds a Query to E3Chart Queries Collection. The QueryName parameter determines the the
name of the added Query. The IsInternal parameter is optional, deprecated, and must not be
informed. Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Queries.AddQuery("Query1")
End Sub

4.6.6.1.2 Item
Item(Index)

Sets up or returns a Query Collection by name or index. This method has an Index parameter
that is mandatory and assumes the following behavior: if it is a number, it corresponds to the
Query index in the Queries Collection. If it is a text, it corresponds to the Query name. Example:
Sub CommandButton1_Click()
Set query = Screen.Item("E3Chart1").Queries.Item(0)
End Sub

4.6.6.1.3 Remove
Remove(Index)

Removes the Query object specified by name or index. This method has an Index parameter
corresponding to the Query name to be removed. Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Queries.Remove(0)
End Sub

4.6.6.1.4 UpdateData
UpdateData()

Updates data from all Queries. Example:

Sub Text1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
E3Chart1.Queries.UpdateData()
End Sub

4.6.6.2 Properties
This section contains information about the properties of the Query Collection object.

278 V iew
4.6.6.2.1 Count

Contains the total amount of E3Chart Queries. This is a read-only property.

4.6.7 Legend
This section contains information about methods and properties of the Legend object. This
object does not have events associated to it.

4.6.7.1 Methods
In the Legend, many columns can be selected. Each column shows an information type and has
a corresponding name and value. Next, there is a description table of possible columns in a
Legend.

Available options for column identification

OPTION DESCRIPTION
Pen color Displays the Pen color.

Description Displays the DocString property of the Pen.

DifX Displays the difference between initial and

final cursors.

DifY Displays the difference between initial and

final interpolated points of the Y axis.

XScale Displays the name of the scale linked to the X

tag.

YScale Displays the name of the scale linked to the Y

tag.

Status Displays the status of the Pen.

XEnd Displays the ending position of the cursor.

YEnd Displays the interpolated point where the

ending cursor crosses the Pen.

XBegin Displays the beginning position of the cursor.

YBegin Displays the interpolated point where the

beginning cursor crosses the Pen.

MaximumY Displays the maximum Pen value in the

interval.

V iew 279
 OPTION DESCRIPTION
AverageY Displays the average Pen value in the
interval.

MinimumY Displays the minimum Pen value in the

interval.

Pen name Displays the name of the Pen.

X tag name Displays the X tag name linked to the Pen.

Y tag name Displays the Y tag name linked to the Pen.

Unit Displays the unit linked to the Pen.

X tag value Displays the value of the X tag linked to the

Pen. This value is displayed when the chart is
in Search mode.

Y tag value Displays the value of the Y tag linked to the

Pen. This value is displayed when the chart is
in Search mode.

4.6.7.1.1 ChangeColumnPos
ChangeColumnPos(Source, Dest)

Swaps the position between two columns. This method has the following parameters:

· Source: is the index of the column to be swapped to Dest

· Dest: is the index of the column to be swapped to Source

Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Legend.ChangeColumnPos 1, 2
End Sub

4.6.7.1.2 Count
Count()

Returns the number of columns of the Legend. Example:

Sub CommandButton1_Click()
MsgBox Screen.Item("E3Chart1").Legend.Count()
End Sub

280 V iew
4.6.7.1.3 InsertColumn
InsertColumn(Col, Index)

Inserts a new column in the Legend. This method has the following parameters:

· Col: identifies the column to be inserted (see Available options for column identification
table in the Legend Methods topic)

· Index: determines the position where the column is inserted

Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Legend.InsertColumn 1, 2
End Sub
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Legend.InsertColumn "Color", 2
End Sub

4.6.7.1.4 Item
Item(Col)

Returns a Legend column by name or index. The Col parameter determines the column index or
name (see the Available options for column identification table in the Legend Methods topic).
Example:
Sub CommandButton1_Click()
MsgBox Screen.Item("E3Chart1").Legend.Item(1)
End Sub

4.6.7.1.5 RemoveColumn
RemoveColumn(Col)

Removes a column. This method has a Col parameter determining the column to be removed
(see the Available options for column identification table in the Legend Methods topic).
Example:
Sub CommandButton1_Click()
Screen.Item("E3Chart1").Legend.RemoveColumn(1)
End Sub

4.6.7.2 Properties
This section contains information about the properties of the Legend object.

4.6.7.2.1 BackColor

Configures or returns the background color of the Legend. The default value of this property
is white (RGB(255, 255, 255)).

V iew 281
4.6.7.2.2 EnableTextColor

This property, when enabled, specifies that the Legend text has the same color of the Pen,
configured in the Color property. The default value of this property is False.

4.6.7.2.3 LegendPos

Indicates the position of the Legend on the E3Chart.

Available options for LegendPos

OPTION DESCRIPTION
0 - lgTop Displays the Legend on top.

1 - lgLeft Displays the Legend on the left.

2 - lgBottom Displays the Legend at the bottom.

3 - lgRight Displays the Legend on the right.

Example:
Sub CommandButton10_Click()
Screen.Item("E3Chart1").Legend.LegendPos = 3
End Sub

4.6.7.2.4 ShowAllPens

When this property is set to True, all EChart Pens are displayed on the Legend. The Visible
property of the Pen is ignored. When set to False, only Pens with the Visible property set to
True are displayed. Example:
Sub CommandButton1_Click()
Set E3Chart1 = Screen.Item("E3Chart1")
E3Chart1.Legend.ShowAllPens = Not _
E3Chart1.Legend.ShowAllPens
End Sub

4.6.7.2.5 ShowHeader

Determines the visibility of the Legend title (header). If this option is set to True, the Legend
title is displayed. Otherwise, the title is hidden. Example:
Sub CommandButton2_Click()
Screen.Item("E3Chart1").Legend.ShowHeader = False
End Sub

282 V iew
4.6.7.2.6 Size

Determines the size of the Legend. This size may be the height or width, depending on the
position of the Legend. Example:
Sub CommandButton13_Click()
MsgBox Screen.Item("E3Chart1").Legend.Size
End Sub

4.6.7.2.7 Visible

Determines the visibility of the Legend. If this property is set to True, the Legend is visible
on the E3Chart. Otherwise, it is hidden. Example:
Sub CommandButton13_Click()
Screen.Item("E3Chart1").Legend.Visible = False
End Sub

4.6.7.3 Legend Columns

This section contains information about properties of the Legend Column object. This object
does not have events nor methods associated to it.

4.6.7.3.1 Properties

This section contains information about the properties of the Legend Column object.

4.6.7.3.1.1 Caption

Allows defining a title for the column.

4.6.7.3.1.2 Column

Returns a column identifier. See the Available options for Columns table. Example:
Sub CommandButton15_Click()
Set col= Screen.Item("E3Chart1").Legend.Item(1)
MsgBox col.Column
End Sub

4.6.7.3.1.3 Format

Configures the formatter used on the column. Example:

Sub CommandButton15_Click()
Set col= Screen.Item("E3Chart1").Legend.Item(1)
MsgBox col.Format = "0.0"
End Sub

V iew 283
4.6.7.3.1.4 Index

Returns the column position on the Legend. Example:

Sub CommandButton15_Click()
Set col = Screen.Item("E3Chart1").Legend.Item(1)
MsgBox col.Index
End Sub

4.6.7.3.1.5 Name

Determines the name of the column. The column names can be seen on the Available
options for columns table. Example:
Sub CommandButton1_Click()
set Chart = screen.item("E3Chart1")
set query = Chart.Queries.Item(0)
MsgBox query.Name
MsgBox query.TableName
End Sub

4.6.7.3.1.6 TextAlign

Returns the text alignment of the column. The available options for this property are the
following:

Available options for TextAlign

OPTION DESCRIPTION
0 - taLeft Left alignment.

1 - taRight Right alignment.

2 - taCenter Centered alignment.

Example:
Sub CommandButton1_Click()
Set col = Screen.Item("E3Chart1").Legend.Item(1)
col.TextAlign = 2
End Sub

4.6.7.3.1.7 Width

Returns the column width. Example:

Sub CommandButton1_Click()
Set col = Screen.Item("E3Chart1").Legend.Item(1)
col.width = 50
End Sub

284 V iew
4.7 E3Playback
This section contains information about methods and properties of the E3Playback object.
This object does not have events associated to it.

4.7.1 Methods
This section contains information about the methods of the E3Playback object.

4.7.1.1 Pause
Pause()

Pauses the playback clock at the current time. Example:

Sub CommandButton1_Click()
Screen.Item("E3Playback1").Pause()
End Sub

4.7.1.2 Play
Play()

Starts playing data at the current playback time, moving the clock forward according to the
current playing speed. Example:
Sub CommandButton1_Click()
Screen.Item("E3Playback1").Play()
End Sub

4.7.1.3 Stop
Stop()

Interrupts playback, tag data and alarms are removed from the screen and no new query is
performed on the database. Example:
Sub CommandButton1_Click()
Screen.Item("E3Playback1").Stop()
End Sub

4.7.2 Properties
This section contains information about the properties of the E3Playback object.

4.7.2.1 CurrentTime

Displays the current date and time of the E3Playback object. This property is only available
at run time.

V iew 285
4.7.2.2 DBServer

Indicates the name of the Database which contains the application historical data.

4.7.2.3 InitialScreen

Indicates the Screen which will be initially displayed on the E3Playback. If this property is
left blank, the initial screen of the Viewer object is used.

4.7.2.4 PlaybackState

Informs the current state of the E3Playback object. This property is only available at run
time and the options are the following:

Options for PlaybackState property

OPTION DESCRIPTION
0 - Stopped The playback clock is stopped.

1 - Playing The playback clock is moving.

2 - Paused The playback clock is paused.

4.8 Reports
This section contains information about events, methods, and properties of the Report object.

4.8.1 Events
This section contains information about the events of the Report object.

4.8.1.1 OnAfterPrint
OnAfterPrint()

Started after a section has been assembled in the Report. You may use this event to update
any necessary counter after completing the Report.

4.8.1.2 OnBeforePrint
OnBeforePrint()

Started before the section has been assembled in the Report. You may use this event to
modify an object value in the Report before printing it. It is recommended that the Query fields
of the Report do not be accessed while this event is being used.

286 V iew
4.8.1.3 OnDataInitialize
OnDataInitialize()

Occurs before the OnReportStart event. This event allows adding and configuring fields to the
Fields collection of a Report, before generating them. Example:
Sub OnDataInitialize()
Fields.Add "Name"
Fields.Add "Sector"
Fields.Add "Code"
End Sub

4.8.1.4 OnError
OnError(Number, Description, SCode, Source, HelpFile, HelpContext, CancelDisplay)

Generated by an internal error in the Report. If this event is not handled, E3 displays a generic
error message.

Variables of the OnError event

NAME DESCRIPTION
Number Integer identifying the error.

Description String with the error description.

SCode Integer with the error code of the OLE

subsystem (not used).

Source String with the object that generated the

error.

HelpFile String with the name and path of the help file.

HelpContext Number of the help topic context referring to

the error (integer).

CancelDisplay Boolean which indicates if the error should

be displayed on a MessageBox.

4.8.1.5 OnFetchData
OnFetchData(eof)

Triggered every time a new record is processed. This event is used to run a script that modifies
field values added to the Report in a script associated to the OnDataInitialize event. The
default value of the variable eof is True and indicates that after the script, the processing of
the current record of the Report is finished.

V iew 287
4.8.1.6 OnFormat
OnFormat()

Started before data is read and loaded in the Report, but before the section is prepared for
printing. This event may be used to modify the layout of the Report section or any other object.

4.8.1.7 OnHyperlink
OnHyperlink(Button, Link)

Occurs when clicking a link on a Report. you may use this event to run a script which redirects a
link or to configure a link on the Report. The Button variable indicates which button was
clicked (normally, 1) and the Link variable determines what is the address to follow.

4.8.1.8 OnNoData
OnNoData()

Occures when there is no data to be printed in the Report. You may use this event to run a
script which displays an error message on the screen warning that there is no data to print
and cancel the Report.

4.8.1.9 OnPageEnd
OnPageEnd()

Occurs at the end of each Report page printing.

4.8.1.10 OnPageStart
OnPageStart()

Occurs at the beginning of each Report page printing.

4.8.1.11 OnPrintProgress
OnPrintProgress(PageNumber)

Occurs while a Report page is being printed. The PageNumber variable indicates the current
page number.

4.8.1.12 OnReportEnd
OnReportEnd()

Triggered at the end of the Report generation, after printing is finished.

288 V iew
4.8.1.13 OnReportStart
OnReportStart()

Triggered at the beginning of the Report generation, before start printing.

4.8.2 Methods
This section contains information about the methods of the Report object.

4.8.2.1 Export
Export([ExportFilter, ][ExportFileName])

Prints a Report according to the format specified in the file. This method has a strExportFilter
parameter, which determines the Report filter, indicating the export format. It may assume
the following options:

· PDF: Exports data to Adobe PDF format

· Excel: Exports data to Excel spreadsheet format

· HTML: Exports data to HTML format

· TEXT: Exports data to a text file

· RTF: Exports data to Rich Text Format

· TIFF: Exports data to Tag Image File Format

When simply informing a filter name, as previously exposed, data is exported using common
properties of each filter. You may modify the common properties of export filters by using the
GetExportFilter method before exporting data. The name of the file must be informed in the
strExportFileName parameter. Example:

V iew 289
 Sub Button1_Click()
Set report = Application.LoadReport("[Report3]")
Select case Application._
SelectMenu("PDF|Excel|HTML|RTF|Text|TIFF|Text(CSV)")
Case 1
Report.Export "PDF", "C:\mail\reports\report.pdf"
MsgBox "Exported to PDF!"
Case 2
Report.Export "EXCEL", "C:\mail\reports\report.XLS"
MsgBox "Exported to XLS!"
Case 3
Report.Export "HTML", "C:\mail\reports\report.html"
MsgBox "Exported to HTML!"
Case 4
Report.Export "RTF", "C:\mail\reports\report.rtf"
MsgBox "Exported to RTF!"
Case 5
Report.Export "TEXT", "C:\mail\reports\report.txt"
MsgBox "Exported to TXT!"
Case 6
Report.Export "TIFF", "C:\mail\reports\report.tiff"
MsgBox "Exported to TIFF!"
Case 7
Set reportFilter = report.GetExportFilter("TEXT")
reportFilter.FileName = "C:\mail\reports\report2.txt"
reportFilter.TextDelimiter = ","
report.Export reportFilter
MsgBox "Exported to TXT using a filter!"
End Select
End Sub

4.8.2.2 GetExportFilter
GetExportFilter(FilterName)

Returns an object that specifies exporting custom parameters. This method has the
FilterName parameter, which determines the Report filter, indicating the format type for
exporting. It may assume the following options:

· PDF: Exports data to Adobe PDF format

· Excel: Exports data to Excel spreadsheet format

· HTML: Exports data to HTML format

· TEXT: Exports data to a text file

· RTF: Exports data to Rich Text Format

· TIFF: Exports data to Tag Image File Format

After getting the filter, the following properties can be modified:

290 V iew
 Properties which can be changed

PROPERTY FILTER DESCRIPTION

AutoRowHeight Excel In True (default),
automatically configures the
row height. In False,
configures the size to the
largest element on the row.

BorderSpace Excel Minimum spacing between

cells. The default value is 59
twips.

CreateCSSFile HTML If true, generates a CSS file in

the TMLOutputPath directory.

DoubleBoundaries Excel In True, indicates that the

elements aligned to the right
must replace the ones
aligned to the left on the
same column. Otherwise,
leave it in false to make more
room.

ExportRange HTML Indicates a page range for

exporting. For example, "1, 2,
3-9, 14".

FaxExport TIFF Object which allows exporting

data in RFC 1314 TIFF format.

FileName All Informs the filename to which

data is exported.

GenPageBreaks HTML In True, places page breaks

under the lowest element in
each Report page.

HTMLOutputPath HTML Default HTML file output

path.

JPGQuality PDF Indicates the quality level of

the exported images (from 0
to 100).

MinColumnWidth Excel Minimum size of the column.

The default value is 1011
twips.

MinRowHeight Excel Minimum size of the row.

V iew 291
 PROPERTY FILTER DESCRIPTION
MultiSheet Excel In True, each Report page
goes to a separate
spreadsheet.

PageDelimiter TEXT Configures or returns the

delimiter character between
pages.

SuppressEmptyLines TEXT Removes or inserts empty

lines, for layout purposes.

TextDelimiter HTML Configures or returns the

delimiter character among
texts.

TrimEmptySpace Excel In True, the vertical space

among elements is removed.
The default is False.

Unicode TEXT Determines if the text is

saved in Unicode format (16
bits).

WebCacheOutput HTML In True, the Report is

exported to the WebCache
service. Otherwise (default),
it is not exported.

4.8.2.3 Print
Print()

Prints a Report. Example:

Sub Rect_Click()
Application.LoadReport("[Report3]").Print()
End Sub

4.8.2.4 PrintPreview
PrintPreview()

Performs a printing preview of the Report on the screen. If the Report is correctly displayed on
screen, returns True. In case the user presses the Cancel button or some error happens,
returns False. Example:
Sub CommandButton1_Click()
Set report = Application.LoadReport("[Report1]")
Start = Application.GetObject("Data.Chart.datas").Value
End = Application.GetObject("Data.Chart.datae").Value
report.Item("Query1").SetVariableValue "Begin", Start
report.Item("Query1").SetVariableValue "End", End
report.PrintPreview()
End Sub

292 V iew
NOTE: This method is not available for reports loaded using the LoadReport method of the
Server.

4.8.2.5 Query
Query()

Returns the Query object currently selected on the Report. For more information about this
object, see the Query chapter. Example:
Sub Rect_Click()
Set Query = Application.LoadReport("[Report3]").Query()
Query.SetVariableValue("Key1", "XYZ")
End Sub

4.8.3 Properties
To create a script in the Report, use the Report Script Editor, accessed through the Scripts
Editor button and to view the Report, use the Generate Report button, both located on the
Report toolbar.

The report scripts use some procedures, depending on the object or the section which the
code should be inserted. For example:
Report.Sections("PageHeader").Controls("E3Chart1")._
GridBkColor= RGB(255, 0, 255).

Where:

· PageHeader: is the name of the section where the object is inserted in the Report

· E3Chart1: is the name of the object which is inside the specified section, in this case it is
PageHeader

· GridBkColor: is the property name of the object, in this case it is E3Chart

· RGB (255, 0, 255): it is the parameter or action of the property. In this case, changing the
background color of the chart to pink

So, to make a script in the Report, use the following concept:

Report.Sections("SectionName").Controls("ObjectName")._
PropertyName = property_parameters

NOTE: The Report object encapsulates an ActiveReports object (or AR), which is the Report
itself.

V iew 293
4.8.3.1 Caption

Contains the Report title which appears in the title bar of the preview window. The default
value of this property is empty.

4.8.4 Layout
This section contains information about properties of the Report Layout object. This object
does not have events nor methods associated to it.

4.8.4.1 Properties
This section contains information about the properties of the Layout object of the Report.

NOTE: The properties described here are part of the ActiveReport (AR) object, which is
encapsulated in the Report object. These properties are only valid inside the AR scope and
cannot be accessed from outside this object.

4.8.4.1.1 _PageBottomMargin

Determines the bottom margin of the report, in twips (1 twip = 1/440 inches). The default
value of this property is 1440 (1 inch or 2.54 cm).

4.8.4.1.2 _PageLeftMargin

Determines the left margin of the Report, in twips (1 twip = 1/440 inches). The default value
of this property is 1440 (1 inch or 2.54 cm).

4.8.4.1.3 _PageRightMargin

Determines the rigth margin of the Report, in twips (1 twip = 1/440 inches). The default value
of this property is 1440 (1 inch or 2.54 cm).

4.8.4.1.4 _PageTopMargin

Determines the top margin of the Report, in twips (1 twip = 1/440 inches). The default value
of this property is 1440 (1 inch or 2.54 cm).

294 V iew
4.8.4.1.5 AllowSplitters

Allows the viewing screen of the Report to be splitted into two parts. This property is only
available at run time. If this property is set to False (default value), the splitting bar does not
appear on the screen.

4.8.4.1.6 documentName

Determines the name of the document for the Report. This name appears on the printing
manager and may be used to easily identify the Report. The default value of this property is
"ActiveReports Document".

4.8.4.1.7 MaxPages

Establishes the maximum amount of pages for the Report. When this number is reached, E3
stops processing the document. The default value of this property is 10.

4.8.4.1.8 ParentReport

This property is an internal system variable and contains a reference to the Report object.
This is a read-only property, and valid only for the OnDataInitialize and OnReportEnd events.

4.8.4.1.9 PrintWidth

Determines the width of the printing area of the Report, in twips. If the size of the Report is
changed at run time, the printing width must also be changed, to ensure that the Report uses
the whole printing area. The size of the printing area must also include the margin width, so
that the Report do not oversizes the paper size. If this happens, the error appears as a red
dotted line printed on every page of the Report.

4.8.4.1.10 RulerVisible

When set to True, indicates that one vertical and one horizontal ruler are displayed on the
preview window of the Report. Otherwise, these rulers are invisible.

4.8.4.1.11 ScriptDebuggerEnabled

Enables or disables the ActiveReports debugger (JIT), to debug scripts associated to the
Report. This debugger is not available in E3, only in Reports.

V iew 295
4.8.4.1.12 ScriptLanguage

Indicates the language used to interpret the scripts associated to a Report. The default
language is VBScript, but JScript may also be used.

4.8.4.1.13 ShowParameterUI

Enables or disables the dialog box parameters of the Query which appears when the report
is being executed. If this property is set to True, the query dialog box parameters are
displayed. Otherwise, these parameters are be displayed.

4.8.4.1.14 Status

Returns the Report status. The available options for this property are the following:

Available options for Status

OPTION DESCRIPTION
0 - DDStatIdle Indicates that the Report is closed.

1 - DDStartRunning Indicates that the Report is being executed.

2 - DDStartCompleted Indicates that the Report is complete.

3 - DDStartCanceled Indicates that the Report has been

cancelled.

4.8.4.1.15 TOCEnabled

Enables or disables the table of contents of the Report. If this property is set to True, the
table of contents of the Report is enabled. Otherwise, the Report has no table of contents. The
default value of this property is True.

4.8.4.1.16 TOCVisible

If this property is set to True, the Report index is displayed. Otherwise, the index remains
invisible. The default value of this property is True.

4.8.4.1.17 ToolbarVisible

Enables or disables the toolbar of the printing preview window of the Report. If this
property is set to True, the toolbar is enabled. Otherwise, this window has no toolbar.

296 V iew
4.8.4.1.18 UserData

Configures or returns specific user information. This property is similar to the Tag property
of Visual Basic, but it is exported and saved in an .rpx file. It may be used to save and load any
customized information needed to draw the Report.

4.8.4.1.19 Version

Returns the product version number.

4.8.4.1.20 WaterMark

Adds a background image to the Report (a watermark). Watermarks are texts or pictures
which appear under the text of the document. Normally, they make the document visually
more interesting.

Example of watermark

The default value of this property is empty (no image or text).

4.8.4.1.21 WaterMarkAlignment

Determines the watermark alignment in the Report. The available options for this
property are the following:

Available options for WaterMarkAlignment

OPTION DESCRIPTION
0 - ddPATopLeft Aligns the image to the top and left.

1 - ddPATopRight Aligns the image to the top and right.

2 - ddPACenter Aligns the image to the center (default).

3 - ddPABottomLeft Aligns the image to the bottom and left.

4 - ddPABottomRight Aligns the image to the bottom and right.

V iew 297
4.8.4.1.22 WaterMarkPrintOnPages

Indicates the number of Report pages which receive the watermark. The used syntax may
include a single page, a page range, or even a combination of both. For example: 1, 5-8, 9, 10-
15.

4.8.4.1.23 WaterMarkSizeMode

Configures the watermark size effect in the Report page. The available options are the
following:

Available options for WaterMarkSizeMode

OPTION DESCRIPTION
0 - ddSMClicp The watermark is displayed in its original size
in the Report.

1 - ddSMStretch The watermark fills in the whole Report page.

2 - ddSMZoom The watermark is resized up to the page size

of the Report.

4.8.5 Section
This section contains information about common properties of the Report Section object. This
object does not have events nor methods associated to it.

4.8.5.1 Common Properties

This section contains information about the common properties of the Section object of the
Report.

4.8.5.1.1 BackColor

Specifies the background color of the Report section. The effect of this property is only
visible if the BackStyle property is enabled for the 1 - ddBKNormal option. The default value is
white (RGB(255, 255, 255)).

298 V iew
4.8.5.1.2 BackStyle

Specifies the background style of the Report section. The available options for this
property are the following:

· 0 - ddBKTransparent: transparent background

· 1 - ddBKNormal: normal background

4.8.5.1.3 CanGrow

Determines the application of a stretch effect to the text of the Report page. In case the
page width or height are enlarged, the text accompanies this variation. If this property is set to
True, the text accompanies height and width variations of the object. Otherwise, this one gets
the initial settings. The default value of this property is True.

4.8.5.1.4 CanShrink

Determines the application of a shrink effect to the page text of a Report. In case the page
width or height are diminished, the text accompanies this variation. If this property is set to
True, the text accompanies the height and width variations of the object. Otherwise, this one
gets the initial settings. The default value of this property is True.

4.8.5.1.5 height

Determines the height of the page section of the Report. The default value of this property is
360.

4.8.5.1.6 IsRepeating

Determines a section repetition on the last page of the Report. If this property is set to
True, the section is repeated on the last page. Otherwise, there is no repetition.

4.8.5.1.7 Name

Indicates the section name of the Report.

V iew 299
4.8.5.1.8 Type

Returns the section type. The available options are:

Available options for Type

OPTION DESCRIPTION
0 - ReportHeader ReportHeader section type.

1 - ReportFooter ReportFooter section type.

2 - PageHeader PageHeader section type.

3 - PageFooter PageFooter section type.

4 - GroupHeader GroupHeader section type.

5 - GroupFooter GroupFooter section type.

6 - Detail Detail section type.

4.8.5.1.9 Visible

Enables or disables section visibility in the Report. If this property is set to True, the section
is visible in the Report. Otherwise, it is hidden. The default value of this property is True.

4.8.5.2 Group Header

This section contains information about properties of the Group Header object or the Report.
This object does not have events nor methods associated to it.

4.8.5.2.1 Properties

This section contains information about the properties of the Group Header object of the
Report.

4.8.5.2.1.1 ColumnLayout

Determines if the GroupHeader is using the same layout of the columns configured on the
Detail section. If this property is set to True, the number of columns in the Detail section is the
same as the associated GroupHeader or GroupFooter. Otherwise, it remains with standard
configuration.

300 V iew
4.8.5.2.1.2 DataField

Returns data from the fields of the Report. Defines a mandatory field for a group inside the
content of the Detail section. This value is set to the name of all fields in the data source of the
Report or to the name of a custom field which is inserted in the fields collection. When this
property is set, the Report creates a new group every time the field value changes in the data
recording of the detail.

4.8.5.2.1.3 GrpKeepTogether

Determines if the GroupHeader section is printed as a single block on the same page of the
Report. The available options are the following:

Available options for GrpKeepTogether

OPTION DESCRIPTION
0 - GrpNone The page can be broken immediately after a
GroupHeader.

1 - GrpFirstDetails The GroupHeader is printed with the first

Detail section of the same Report page or
column.

2 - GrpAll The GroupHeader, Detail, and Footer of a

group are printed together on the same
Report page.

The default value of this property is 0 - GrpNone.

4.8.5.2.1.4 KeepTogether

Determines if the Report sections are printed as a single block, on the same page. The
available options for this property are the following:

Available options for KeepTogether

OPTION DESCRIPTION
0 - ddGrpNone There is a page break after the Report.

1 - ddGrpFirstDetail TheRreport prints the Detail section on the

same page or column.

V iew 301
4.8.5.2.1.5 NewColumn

Inserts a new column break before or after printing the section in the Report. The available
options for this property are the following:

Available options for NewColumn

OPTION DESCRIPTION
0 - ddNPNone There is no page break on the section.

1 - ddNBefore Starts printing the section on a new page.

2 - ddNPAfter Starts a new page after printing the section.

3 - ddNPBeforeAfter Starts printing on a new page and a new page

after printing the section.

4.8.5.2.1.6 NewPage

Inserts a page break in the Report. The available options for this property are the
following:

Available options for NewPage

OPTION DESCRIPTION
0 - ddNPNone There is no page break in the section
(default).

1 - ddNBefore Starts printing on a new page.

2 - ddNPAfter Starts printing a new page after printing the

section.

3 - ddNPBeforeAfter Starts printing on a new page and starts a

new page after printing the section.

302 V iew
4.8.5.2.1.7 Repeat

Determines if the GroupHeader is printed again after being associated to the Detail
section when there are multiple pages, columns, or page breaks in the Report. The available
options are the following:

Available options for Repeat

OPTION DESCRIPTION
0 - ddRepeatNone There is no re-printing of the Group Header
(default).

1 - ddRepeatOnPage Prints the header groups on top of the page

according to the specifications of the Detail
section.

2 - ddRepeatOnColumn Prints the header groups on top of the page

column of the Report according to the
specifications of the Detail section.

3 - ddRepeatAll Prints the header groups and the other

objects on top of the Report page according
to the specifications of the Detail section.

4.8.5.2.1.8 UnderlayNext

Determines if the section must print one section after another, consecutively. If this
property is set to True, the next section starts printing from the upper coordinate of the
section on the Report page. Otherwise, this resource is not used. The default value of this
property is False.

4.8.5.3 Detail
This section contains information about properties of the Report Detail object. This object
does not have events nor methods associated to it.

4.8.5.3.1 Properties

This section contains information about the properties of the Detail object of the Report.

4.8.5.3.1.1 ColumnCount

Determines the number of columns of the Detail section of the Report. The width of each
column must be equal to the printable area of the Report, divided by the number of columns.
The default value of this property is 1.

V iew 303
4.8.5.3.1.2 ColumnDirection

The ColumnDirection property determines the printing direction of the Detail section
columns. The available options are the following:

Available options for ColumnDirection

OPTION DESCRIPTION
0 - ddCDDownAcross Prints each column of the Detail section from
top to bottom and then moves to the next
column on the right.

1 - ddCDAcrossDown Prints each column of the Detail section from

right to left and so on.

The layout is determined according to the configured option:

ddCDDownAccross

304 V iew
 ddCDAccrossDown

4.8.5.3.1.3 ColumnSpacing

Determines the column spacing in the Detail section. The default value of this property is 0.

4.8.5.3.1.4 KeepTogether

Determines if the Report sections are printed as a single block, on the same page. The
available options for this property are the following:

Available options for KeepTogether

OPTION DESCRIPTION
0 - ddGrpNone There is a page break after the Report.

1 - ddGrpFirstDetail The Report prints the Detail section on the

same page or column.

V iew 305
4.8.5.3.1.5 NewColumn

Inserts a new column break before or after printing the section in the Report. The available
options for this property are the following:

Available options for NewColumn

OPTION DESCRIPTION
0 - ddNPNone There is no page break in the section.

1 - ddNBefore Starts printing the section on a new page.

2 - ddNPAfter Starts a new page after printing the section.

3 - ddNPBeforeAfter Starts printing on a new page and a new page

after printing the section.

4.8.5.3.1.6 NewPage

Inserts a page break in the Report. The available options for this property are the
following:

Available options for NewPage

OPTION DESCRIPTION
0 - ddNPNone There is no page break in the section.

1 - ddNBefore Starts printing on a new page.

2 - ddNPAfter Starts a new page after printing the section.

3 - ddNPBeforeAfter Starts printing on a new page and starts a

new page after printing the section.

4.8.5.4 Group Footer

This section contains information about properties of the Group Footer object of the Report.
This object does not have events nor methods associated to it.

4.8.5.4.1 Properties

This section contains information about the properties of the Group Footer object of the
Report.

306 V iew
4.8.5.4.1.1 ColumnLayout

Determines if the GroupFooter uses the same layout of the columns configured on the
Detail section. If this property is set to True, the number of columns of the Detail section
reflects in the associated GroupHeader or GroupFooter. Otherwise, the default configurations
remains. The default value of this property is True.

4.8.5.4.1.2 KeepTogether

Determines if the Report sections are printed as a single block, on the same page. The
available options for this property are the following:

Available options for KeepTogether

OPTION DESCRIPTION
0 - ddGrpNone There is a page break after the Report.

1 - ddGrpFirstDetail The Report prints the Detail section on the

same page or column.

4.8.5.4.1.3 NewColumn

Inserts a new column break before or after printing the section in the Report. The available
options for this property are the following:

Available options for NewColumn

OPTION DESCRIPTION
0 - ddNPNone There is no page break on the section.

1 - ddNBefore Starts printing the section on a new page.

2 - ddNPAfter Starts a new page after printing the section.

3 - ddNPBeforeAfter Starts printing on a new page and a new page

after printing the section.

V iew 307
4.8.5.4.1.4 NewPage

Inserts a page break in the Report. The available options for this property are the
following:

Available options for NewPage

OPTION DESCRIPTION
0 - ddNPNone There is no page break in the section
(default).

1 - ddNBefore Starts printing on a new page.

2 - ddNPAfter Starts printing a new page after printing the

section.

3 - ddNPBeforeAfter Starts printing a new page and starts a new

page after printing the section.

4.8.5.4.1.5 PrintAtBottom

Determines if the GroupFooter or the Report footer are printed at the page bottom. If this
property is set to True and the Report has a page footer, the GroupFooter and the Report
footer are printed above the Page Footer section. Configuring more than one section to print
the Report footer makes the following sections to print on separate pages.

4.8.6 Objects
This section contains information about properties of Report objects. These objects do not
have events nor methods associated to them.

4.8.6.1 Common Properties

This section contains information about common properties of the Report objects.

4.8.6.1.1 BackColor

Specifies a background color of the Report object. The effect of this property is only visible if
the BackStyle property is enabled for the 1 - ddBKNormal option. The default value of this
property is white (RGB(255, 255, 255)).

NOTE: this property is only valid for the Line and Page Break objects.

308 V iew
4.8.6.1.2 BackStyle

Specifies the background style of the Report objects. The available options for this
property are the following:

· 0 - ddBKTransparent: transparent (displays the color defined by the BackColor property of

the section)

· 1 - ddBKNormal: normal (displays the color defined by the BackColor property of the object)

The default value is 0 - ddBKTransparent.

NOTE: this property is not valid for Line, Barcode, Page Break, and Frame objects.

4.8.6.1.3 height

This property determines the object height in the Report.

NOTE: this property is not valid for Line and Page Break objects.

4.8.6.1.4 left

Returns the left positioning value of the object in the Report.

NOTE: this property is not valid for Line and Page Break objects.

4.8.6.1.5 Name

Determines the name of the object. The default value of this property is empty.

4.8.6.1.6 Tag

Returns the tag type associated to the object, that is, Boolean, String, Integer, etc.

4.8.6.1.7 Top

Returns the top value of the object.

V iew 309
NOTE: this property is not valid for the Line object.

4.8.6.1.8 Visible

Determines the object visibility in the Report. If this option is set to True, the object is
visible in the Report. Otherwise, the object is hidden. The default value of this property is True.

NOTE: this property is not valid for Page Break object.

4.8.6.1.9 Width

This property determines the object width in the Report.

NOTE: this property is not valid for Line and Page Break objects.

4.8.6.2 Barcode
This section contains information about properties of the Report Barcode object. This object
does not have events nor methods associated to it.

4.8.6.2.1 Properties

This section contains information about the properties of the Report Barcode object.

4.8.6.2.1.1 Alignment

Determines the text alignment of the object in the Report. The available optios are the
following:

· 0 - ddtxLeft: aligns the text to the left of the object

· 1 - ddtxRight: aligns the text to the right of the object

· 2 - ddtxCenter: aligns the text to the center of the object

4.8.6.2.1.2 BarWidth

Determines the bar width of the Barcode. Configuring the width to 1, the object bar is
expanded in 15 points, and so on. The higher the number configured on the property, the
bigger the bar width of the Barcode. The default value of this property is 1.

310 V iew
4.8.6.2.1.3 Caption

Contains the object text itself. The default value of this property is empty.

4.8.6.2.1.4 CaptionPosition

Specifies the text position of the Caption property in the object. The available options for
this property are the following:

· 0 - ddbcCaptionNone: the text of the Caption property does not appear on the Barcode

· 1 - ddbcCaptionAbove: the text of the Caption property appears above the Barcode

· 2 - ddbcCaptionBelow: the text of the Caption property appears below the Barcode

The default value of this property is 0 - ddbcCaptionNone.

4.8.6.2.1.5 DataField

Configures or returns data associated to the object. This associated data may be a
Database table field provided by the Query object, a mathematical expression with Query
fields and VBScript functions (in this case, the field must be preceded by an equal symbol), or
an E3 tag or property. In this case the current variable value is displayed when the printing is
performed. The default value of this property is empty.

NOTE: The server must be running in order to capture variable value.

4.8.6.2.1.6 Direction

Determines the spatial orientation of the barcode. The available options for this property
are the following:

Available options for Direction

OPTION DESCRIPTION
0 - ddbcLeftToRight The barcode is oriented from left to right.

1 - ddbcRightToLeft The barcode is oriented from right to left.

2 - ddbcTopToBottom The barcode is oriented from top to bottom.

3 - ddbcBottomToTop The barcode is oriented from bottom to top.

V iew 311
The default value of this property is 0 - ddbcLeftToRight.

4.8.6.2.1.7 EnableCheckSum

Enables or disables reading a checksum value (character from the barcode object). If this
property is set to False, only codes with a checksum are affected.

4.8.6.2.1.8 Font

Determines the object font on the text established by the Caption property. The default
value of this property is Arial.

NOTE: This property is not used on scripts or links, being edited only via E3 Studio.

4.8.6.2.1.9 Forecolor

Specifies the filling color of the object foreground. In scripts, use the VBScript RGB method
to build the color to be associated to this property. The default value of this property is black (
RGB(0, 0, 0)).

4.8.6.2.1.10 Style

Determines the Barcode style. The available options are the following:

Available options for Style

OPTION DESCRIPTION
0 - ddbcNone Default Barcode style.

1 - ddbcAnsi39 Barcode style ANSI 3 of 9 (Code 39). Uses

letters, numbers, -,*, $, /, +, %, etc.

2 - ddbcAnsi39x Barcode style extended ANSI 3 of 9 (Extended

Code 39). Uses full ASCII characters.

3 - ddbcCode_2_of_5 Barcode style 2 of 5. Uses only numbers.

4 - ddbcCode25intlv Barcode style Interleaved 2 of 5. Uses only

numbers.

5 - ddbcCode25mat Barcode style Matrix 25.

312 V iew
 OPTION DESCRIPTION
6 - ddbcCode39 Barcode style Code, uses letters, numbers, -,
*, $, /, +, %, etc.

7 - ddbcCode39x Barcode style Extended Code 39. Uses full

ASCII characters.

8 - ddbcCode_128_a Barcode style 128 A. Uses numbers,

punctuation, or letters.

9 - ddbcCode_128_b Barcode style 128 B. Uses strings, numbers,

punctuation, or letters.

10 - ddbcCode_128_c Barcode style 128 C. Uses only numbers.

11 - ddbcCode_128auto Barcode style 128 Automatic. Uses full ASCII

characters. Automatically selects codes
among 128 A, B, and C to set the smallest
value in the Barcode.

12 - ddbcCode_93 Barcode style Code 93. Uses letters,

numbers, -, *, $, /, +, %, etc.

13 - ddbcCode_93x Barcode style Extended Code 93. Uses full

ASCII characters.

14 - ddbcMSI Barcode style MSI Code. Uses only numbers.

15 - ddbcPostNet Barcode style PostNet. Uses only numbers

with a digital verification.

16 - ddbcCodabar Barcode style Codabar. Uses A, B, C, D, +,

-, :, /, or numbers.

17 - ddbcEAN_8 Barcode style EAN-8. Uses only numbers

(seven numbers and digital verification).

18 - ddbcEAN_13 Barcode style EAN-13. Uses only numbers (12

numbers and digital verification).

19 - ddbcUPC_A Barcode style UPC-A. Uses only numbers (11

numbers and digital verification).

20 - ddbcUPC_EO Barcode style UPC-E1. Uses only numbers.

Used for UPC zero-compression symbols. In
the Caption property, you may enter six digits
of the UPC-E code or 11 digits. If an 11 digits
code is inserted, the Barcode converts it to
UPC-E six digits, if possible. Otherwise,
converts from 11 to six UPC-E digits and
nothing is displayed.

V iew 313
 OPTION DESCRIPTION
21 - ddbcUPC_E1 Barcode style UPC-E1. Uses only numbers.
The width of the input data of UPC E1 is six
number characters.

22 - ddbcRM4SCC Barcode style Royal Mail RM4SCC. Uses only

letters and numbers (with digital
verification). This Barcode is used in United
Kingdom.

23 - ddbcUCCEAN128 Barcode style UCC/EAN_128. Uses full ASCII

characters. The special version of the Code
128 is used on the HIBC application.

4.8.6.3 Ellipse, Rectangle, and Round Rectangle

This section contains information about properties of the Report Ellipse, Rectange, and Round
Rectangle objects. These objects do not have events nor methods associated to them.

4.8.6.3.1 Properties

This section contains information about the properties of the Report Ellipse, Rectangle and
Round Rectangle objects.

4.8.6.3.1.1 LineColor

Specifies the line color of the object. The default value of this property is black (RGB(0, 0, 0)).

4.8.6.3.1.2 LineStyle

Determines the line style of the object. The available options for this property are the
following:

Available options for LineStyle

OPTION DESCRIPTION
0 - ddLSTransparent The object line becomes transparent.

1 - ddLSSolid The object line appears as solid.

2 - ddLSDash The object line becomes dashed.

3 - ddLSDot The object line becomes dotted.

4 - ddLSDashDot The object line has dashes and dots.

314 V iew
 OPTION DESCRIPTION
5 - ddLSDashDotDot The object line becomes dotted, dashed, and
dotted.

The default value of this property is 1 - ddLSSolid.

4.8.6.3.1.3 LineWeight

Specifies the width of the line object. Setting the width to 1, the object line is expanded in 15
points, if set to 2, the object line is expanded in 30 points, and so on. The higher the number
set in this property, the bigger the width of the object. The default value of this property is 1.

4.8.6.3.1.4 Shape

Allows changing the object shape. The available options are the following:

Available options for Shape

OPTION DESCRIPTION
0 - ddSHRectangle Rectangular format.

1 - ddSHEllipse Elliptical or circular format.

2 - ddSHRoundRect Round rectangle format.

4.8.6.4 Picture
This section contains information about properties of the Report Picture object. This object
does not have events nor methods associated to it.

4.8.6.4.1 Properties

This section contains information about the properties of the Report Picture object.

4.8.6.4.1.1 DataField

Configures or returns an associated data to the object. This associated data may be a
Database table field provided by the Query object, a mathematical expression with Query
fields and VBScript functions (in this case, the field must be preceded by the equal symbol), or
an E3 tag or property. In this case the current variable value is displayed when printing is
performed. The default value of this property is empty.

V iew 315
NOTE: The server must be running in order to the variable value can be captured.

4.8.6.4.1.2 Forecolor

Specifies the foreground color of the object. In scripts, use the VBScript RGB function to
build the color to be associated to this property. The default value of this property is black (
RGB(0, 0, 0)).

4.8.6.4.1.3 hyperLink

Specifies the link attributed to the text. To use this resource use the OnHyperLink event. The
default value of this property is empty.

4.8.6.4.1.4 LineColor

Specifies the line color of the object. The default value of this property is black (RGB(0, 0, 0)).

4.8.6.4.1.5 LineStyle

Determines the object line style. The available options for this property are the following:

Available options for LineStyle

OPTION DESCRIPTION
0 - ddLSTransparent The line becomes transparent on the object.

1 - ddLSSolid The line appears solid on the object.

2 - ddLSDash The line becomes dashed on the object.

3 - ddLSDot The line becomes dotted on the object.

4 - ddLSDashDot The line becomes dashed and dotted on the

object.

5 - ddLSDashDotDot The line becomes dashed, dotted, and dotted

on the object.

The default value of this property is 1 - ddLSSolid.

316 V iew
4.8.6.4.1.6 LineWeight

Specifies the line width of the object. Configuring width to 1, the object line is expanded in
15 points, and so on. The higher the number configured in this property, the larger the width of
the object. The default value of this property is 1.

4.8.6.4.1.7 Picture

Specifies the picture file for the object. The allowed extensions are .bmp, .gif, .jpg, .cur, .
ico, .emf, and .wmf. The default value of this property is empty.

4.8.6.4.1.8 PictureAlignment

Determines the picture alignment in the object. The available options are the following:

Available options for PictureAlignment

OPTION DESCRIPTION
0 - ddPATopLeft Aligns the picture on top left of the object.

1 - ddPATopRight Aligns the picture on top right of the object.

2 - ddPACenter Aligns the picture on center of the object.

3 - ddPABottomLeft Aligns the picture at the bottom left of the

object.

4 - ddPABottomRight Aligns the picture at the bottom right of the

object.

The default value of this property is 2 - ddPACenter.

4.8.6.4.1.9 SizeMode

Specifies the size of the object. The available options are the following:

Available options for SizeMode

OPTIONS DESCRIPTION
0 - ddsMClip Displays the object in its current size.

1 - ddsMStretch Adjusts the object according to its area.

V iew 317
 OPTIONS DESCRIPTION
2 - ddsMZoom Adjusts the height or width of the object
image inside the specified area, without
distorting it.

4.8.6.5 SetPoint
This section contains information about properties of the Report SetPoint object. This object
does not have events nor methods associated to it.

4.8.6.5.1 Properties

This section contains information about the properties of the SetPoint object of the Report.

4.8.6.5.1.1 Alignment

Determines the text alignment of the object. The available options for this property are:

· 0 - Left: left alignment (default)

· 1 - Right: right alignment

· 2 - Center: centered alignment

4.8.6.5.1.2 CanGrow

Determines the application of a stretch effect to the object text. In case the width or height
of the object are enlarged, the text accompanies this variation. If this property is set to True,
the text accompanies height and width variations of the object. Otherwise, this one gets its
initial settings. The default value of this property is True.

4.8.6.5.1.3 CanShrink

Determines the application of a shrinking effect to the object text. In case of object width or
height are diminished, the text accompanies this variation. If this property is set to True, text
accompanies height and width variations of the object. Otherwise, this one gets its initial
settings. The default value of this property is True.

4.8.6.5.1.4 ClassName

Returns the class of the object. This is a read-only property.

318 V iew
4.8.6.5.1.5 DataField

Configures or returns data associated to an object. This associated data may be a Database
table field provided by the Query object, a mathematical expression with Query fields and
VBScript functions (in this case, the field must be preceded by an equal symbol), or an E3 tag or
property. In this case the current variable value is displayed when printing is performed. The
default value of this property is empty.

NOTE: The server must be running in order to capture variable value.

4.8.6.5.1.6 Font

This property determines text font of the object. The default value of this property is empty.
This property cannot be used in scripts or links and it is configured only via Studio.

4.8.6.5.1.7 ForeColor

The ForeColor specifies the background color of the object. In scripts, use the VBScript RGB
function to build the color to be associated to this property. The default value of this property
is black (RGB(0, 0, 0)).

4.8.6.5.1.8 hyperLink

The hyperLink property determines the link to be set to the text. To use this resource, use
the OnHyperLink event.

4.8.6.5.1.9 Multiline

The Multiline property indicates whether the text has multiple lines (True) or is a simple
Text Box (False). This can be viewed when the Viewer object is running. The default value of this
property is False.

4.8.6.5.1.10 OutputFormat

Configures or returns text formatting of the Text property, used on one of the formatting
functions (FormatCurrency, FormatDateTime, FormatNumber, and FormatPercent) in Visual
Basic.

4.8.6.5.1.11 Style

Returns the text style set on the object. This is a read-only property.

V iew 319
4.8.6.5.1.12 SummaryDistinctField

Determines the field name to be used by the selected function in the SummaryFunc
property. This property is only valid if the function defined in the SummaryFunc property is
from the Distinct Summary function group, which encompasses functions from 9 to 15, and
when the SummaryType property value is different from 0.

4.8.6.5.1.13 SummaryFunc

Determines the function type to be used for processing values of the field specified in the
DataField property, as described on the next table. This property is only valid when the
SummaryType property value is different from 0.

Available options for SummaryFunc

OPTION DESCRIPTION
0 - Sum Calculates the sum of all values inside the
specified total intervals (group, page, or
Report).

1 - Avg Calculates the average of all values inside

the specified total intervals (group, page, or
Report).

2 - Count Counts the number of all values inside the

specified total intervals (group, page, or
Report).

3 - Min Displays the lowest value (minimum value) of

all values inside the specified total intervals
(group, page, or Report).

4 - Max Displays the highest values (maximum value)

of all values inside the specified total
intervals (group, page, or Report).

5 - Var Calculates the variance of the values inside

the specidied total intervals (group, page or
Report).

6 - VarP Calculates the populational variance of the

values inside the specified total intervals
(group, page or Report).

7 - Dev Calculates the deviation of the values inside

the specified total intervals (group, page or
Report).

320 V iew
 OPTION DESCRIPTION
8 - DevP Calculates the populational deviance of the
values inside the specified total intervals
(group, page or Report).

9 - DSum Calculates the sum of all distinct values

inside the specified total intervals (group,
page or Report).

10 - DAvg Calculates the average based on distinct

values inside the specified total intervals
(group, page or Report).

11 - DCount Counts the number of distinct values inside

the specified total intervals (group, page or
Report).

12 - DVar Calculates the variance of the distinct values

inside the specified total intervals (group,
page or Report).

13 - DVarP Calculates the populational variance of the

distinct values inside the specified total
intervals (group, page or Report).

14 - DDev Calculates the deviance of the distinct values

inside the specified total intervals (group,
page or Report).

15 - DDevP Calculates the populational deviance of the

distinct values inside the specified total
intervals (group, page or Report).

4.8.6.5.1.14 SummaryGroup

This property is only valid when the SummaryType property is equal to 3 - SubTotal. The
SummaryGroup property indicates what is the GroupHeader section name used to control
subtotals, that is, at each changing in the GroupHeader value, summation is restarted.

NOTE: When this property is used, the CanShrink and CanGrow properties are disabled.

4.8.6.5.1.15 SummaryRunning

Determines if a summary running total is performed, according to the following options:

· 0 - None: does not perform the summary

V iew 321
· 1 - Group: calculates the summary running for each total interval specified

· 2 - All: calculates the summary running of all values in the Report, despite of grouping

This property is only valid when the SummaryType property is different from 0.

4.8.6.5.1.16 SummaryType

Determines the summary type or level to be generated. The available options are the
following:

Available options for SummaryType

OPTION DESCRIPTION
0 - None No summary generation.

1 - GrandTotal Specifies that the whole content of the

Report is summarized.

2 - PageTotal Specifies that a subtotal by page is

generated.

3 - SubTotal Specifies that a subtotal for each group is

generated, defined in the SummaryGroup
property.

4 - PageCount Specifies a page counter.

4.8.6.5.1.17 Text

Determines the text to be set to the object.

4.8.6.5.1.18 VerticalAlignment

Determines the vertical alignment of the object, as follows:

· 0 - Top: top alignment

· 1 - Middle: middle alignment

· 2 - Bottom: bottom alignment

322 V iew
4.8.6.5.1.19 WordWrap

Enables or disables a line break in the text, in case the available text area overrides the
limits determined in the object. For this property to work, the Multiline must be equal to True.
If it is True, the white-space:nowrap setting is displayed in the Style property.

4.8.6.6 Text
This section contains information about properties of the Report Text object. This object does
not have events nor methods associated to it.

4.8.6.6.1 Properties

This section contains information about the Text object of the Report.

4.8.6.6.1.1 Alignment

The Alignment property determines the text alignment, as follows:

· 0 - ddtxLeft: left alignment

· 1 - ddtxRight: right alignment

· 2 - ddtxCenter: centered alignment (default value)

4.8.6.6.1.2 Angle

The Angle property indicates the text angle. The property value must be specified in decimal
degrees, that is, for the text to be displayed in a 45 degrees angle, the value must be equal to
450. The default value of this property is 0 (horizontal positioning).

4.8.6.6.1.3 Caption

The Caption property contains the object text itself. The default value of this property is
empty.

4.8.6.6.1.4 ClassName

The ClassName property allows specifying a global CSS class (indicated by an external
cascade style sheet) to be applied to the text. A CSS class is a formatting pattern which
determines the letter type and size or paragraph alignment and spacing, among other
features. Using CSS, you can apply a pre-defined formatting pattern to a text, unifying and
making text presentation faster. To apply a specific style you may use the Style property. The
default value of this property is the Normal style.

V iew 323
4.8.6.6.1.5 Font

This property indicates the font name (letter type) of the text. The default value of this
property is empty (E3 uses the system default font).

NOTE: This property cannot be used in scripts or links, it is only configured via Studio and can
only be changed at run time.

4.8.6.6.1.6 ForeColor

The Forecolor property specifies the filling color of the object background. In scripts, use
the VBScript RGB function to build the color to be associated to this property. The default value
of this property is black (RGB(0, 0, 0)).

4.8.6.6.1.7 hyperLink

The hyperLink property determines a link to be set to the object. To use this resource, use
the OnHyperLink event. The default value of this property is empty.

4.8.6.6.1.8 Multiline

The Multiline property indicates whether the text has multiple lines (True) or is a simple
Text Box (False). This can be viewed when the Viewer object is running. The default value of this
property is False.

4.8.6.6.1.9 Style

The Style property allows specifying a CSS style for the text, replacing the global style. The
property value must be a valid CSS String, otherwise this property is ignored. The default value
of this property is empty (E3 uses the system default style). Example:
Sub Report1_OnBeforePrint
Label1.Style = "font-family: Times; font-weight: bold;_
text-align: center; color: RGB(255, 255, 0)"
End Sub

4.8.6.6.1.10 VerticalAlignment

The VerticalAlignment property determines the text vertical alignment, as follows.

· 0 - ddTxTop: top alignment (default)

· 1 - ddTxMiddle: centered alignment

· 2 - ddTxBottom: bottom alignment

324 V iew
4.8.6.6.1.11 WordWrap

Enables or disables a line break on the text, in case the available text area overrides the
limits determined by the object. For this property to work, the Multiline property must be
True.

4.8.6.7 Line
This section contains information about properties of the Report Line object. This object does
not hae events nor methods associated to it.

4.8.6.7.1 Properties

This section contains information about the properties of the Line object of the Report.

4.8.6.7.1.1 LineColor

The LineColor property specifies the line color of the object. The default value of this
property is black (RGB(0, 0, 0)).

4.8.6.7.1.2 LineStyle

This property determines the line style of the object. The default value of this property is 1
- ddLSSolid. The other available options for this property are the following:

Available options for LineStyle

OPTION DESCRIPTION
0 - ddLSTransparent The line becomes transparent in the object.

1 - ddLSSolid The line appears solid in the object.

2 - ddLSDash The line becomes dashed in the object.

3 - ddLSDot The line becomes dotted in the object.

4 - ddLSDashDot The line becomes dashed and dotted in the

object.

5 - ddLSDashDotDot The line becomes dashed, dotted, and dotted

in the object.

V iew 325
4.8.6.7.1.3 LineWeight

The LineWeight property specifies the line width of the object. Configuring the width to 1,
the object line is expanded in 15 points, if the width is 2, the object line is expanded in 30
points, and so on. The higher the number configured in this property, the larger the width of
the object. The default value of this property is 1.

4.8.6.7.1.4 X1

The X1 property enables or disables the position of the initial point of the line in the X axis.

4.8.6.7.1.5 X2

The X2 property determines the position of the final point of the line in the X axis. The
default value of this property is empty.

4.8.6.7.1.6 Y1

The Y1 property determines the position of the starting point of the line in the Y axis. The
default value of this property is empty.

4.8.6.7.1.7 Y2

The Y2 property determines the position of the ending point of the line on the Y axis. The
default value of this property is empty.

4.8.6.8 Page Break

This section contains information about the properties of the Page Break object of the Report.
This object does not have events nor methods associated to it.

4.8.6.8.1 Properties

This section contains information about the properties of the Page Break object of the Report.
This object does not have events nor methods associated to it.

4.8.6.8.1.1 Enabled

The Enabled property enables or disables the object in the Report. If this option is set to
True, the object is enabled in the Report. Otherwise, the object is disabled. The default value
of this property is True.

326 V iew
4.8.6.9 Frame
This section contais information about properties of the Report Frame object. This object does
not have events nor methods associated to it.

4.8.6.9.1 Properties

This section contains information about the properties of the Frame object of the Report.

4.8.6.9.1.1 CanGrow

Determines the application of a stretch effect to the object text. In case the width or height
of the object are enlarged, the text accompanies this variation. If this property is set to True,
the text accompanies height and width variations of the object. Otherwise, this one gets the
initial settings. The default value of this property is True.

4.8.6.9.1.2 CanShrink

Determines the application of a shrinking effect to the object text. In case the width or
height of the object are diminished, the text accompanies this variation. If this property is set
to True, the text accompanies the height and width variations of the object. Otherwise, this
one gets the initial settings. The default value of this property is True.

4.8.6.9.1.3 CloseBorder

This property enables or disables viewing the border line of the Frame base, in case it
overrides more than one page in the Report.

4.8.6.9.1.4 left

The left property returns the left positioning value of the object in the Report. The default
value of this property is empty.

4.8.6.10 E3Chart
This section contains information about the properties of the Report E3Chart object.

4.8.6.10.1 Properties
Example of using E3Chart properties in a Report

The following script must be created on the PageHeader section of the Report, using the
OnBeforePrint event. Example:

V iew 327
 Sub OnBeforePrint
Set chart = _
Report.Sections("PageHeader").Controls("E3Chart1")
chart.LoadData()
chart.FitAll
End Sub
Sub OnBeforePrint
' This script copies the configuration from the
' E3Chart object to the E3Chart chart
' which is used in the report.
Set chartfrom = _
Application.GetFrame().Screen.Item("E3Chart1")
Set chart = _
Report.Sections("PageHeader").Controls("E3Chart2")
chart.CopyConfig(chartfrom)
chart.LoadData()
chart.FitAll
End Sub

NOTE: Descriptions for E3Chart properties in a Report are the same explained E3Chart's
Properties topic.

328 V iew
 CHAPTER

5
Server Objects

This section contains information about common properties of Server objects. These objects
do not have common events nor methods. Objects sharing Server properties are the following:

· Server's Runtime Objects

· Configuration-Only Objects

· Drivers

· Data Server

· Database

· Historic

· Storage

· Formulas

· Alarms

5.1 General Properties

This section contains information about general properties of Server objects.

5.1.1 ActiveAlarms
Determines the number of active alarms inside an object. If this property is set to 0 (zero),
inactive alarms are listed via property ActiveNACKAlarms. This is a read-only property. Default
value is 0 (zero).

5.1.2 ActiveHighAlarms
Indicates the number of active alarms with high severity. This is a read-only property.

Server Objec ts 329

5.1.3 ActiveHighNACKAlarms
Indicates the number of non-acknowledged alarms with high severity. This is a read-only
property.

5.1.4 ActiveLowAlarms
Indicates the number of active alarms with low severity. This is a read-only property.

5.1.5 ActiveLowNACKAlarms
Indicates the number of non-acknowledged alarms with low severity. This is a read-only
property.

5.1.6 ActiveMedAlarms
Indicates the number of active alarms with medium severity. This is a read-only property.

5.1.7 ActiveMedNACKAlarms
Indicates the number of non-acknowledged alarms with medium severity. This is a read-only
property.

5.1.8 ActiveNACKAlarms
Indicates the number of non-acknowledged alarms inside an object. This is a read-only
property.

5.1.9 Alarm
Indicates that there are active alarms inside the object. If this option is set to True, there is
at least one active alarm inside the object, and the property ActiveAlarms performs a reading
from server, then indicating the amount of active alarms. Otherwise, property
ActiveNACKAlarms performs a reading of non-acknowledged alarms. This is a read-only
property.

5.1.10 AlarmVerify
Enables a check on all alarms inside the object. After enabling that check (True), if the value
of property ActiveAlarms is greater than 0 (zero), server then checks active alarms, as well as
non-acknowledged ones, listing these last ones in the property ActiveNACKAlarms. This
property is useful to avoid a cascade effect on some systems, where the occurrence of an
event triggers a large amount of related alarms.

330 Server Objec ts

5.1.11 IsAlarmArea
Enables or disables the Alarm Area functionality for Server objects. This property is not
available for the following objects: Alarm Area, Alarm Source, and Alarm Server. The default
value of this property is False. When enabling this property, the object then has the same
properties of an Alarm Area.

5.2 Server's Runtime Objects

This section contains information about object available only at run time, the Server
(Application) and the Application Folders.

5.2.1 Server
This section contains information about specific methods of the Server (Application) object.
This object has the Item and Save general methods, besides the Name and Count properties,
which are described in the General Events, Methods, and Properties of Objects. This object
does not have events associated to it.

5.2.1.1 Methods
This section contains information about specific methods of the Server object.

NOTE: Methods described here can only be used at run time, they are not available in Studio.

5.2.1.1.1 ClearFailure
ClearFailure(FailureName)

This method is called to indicate that a failure reported by ReportFailure becomes inactive.
The FailureName parameter specifies a failure name (user-defined) and must be passed to the
ReportFailure method when that method is called.

5.2.1.1.2 E3GetActor
E3GetActor()

This method returns the logon name of the user who started the current request in E3Run. If
E3Run is not currently handling an operation generated by another process, returns "System".
If there is no user logged on the process which generated the current request, returns
"Anonymous".

Server Objec ts 331

5.2.1.1.3 LoadReport
LoadReport(ReportName)

Loads a Report model. See Viewer's LoadReport method for an example of this method's usage.

NOTE: The Report's PrintPreview method is not available in Reports loaded using this
method.

5.2.1.1.4 ReportFailure
ReportFailure(FailureName, FailureDescription, FailureWeight)

Allows the application to report failures to E3 Server. The reported failures are usually
conditions that keep the application from working partially, such as errors or malfunctions,
and normally cannot be detected by E3 Server. Thus, this method can be used in these
situations:

· To advise the system operator about problems in the server

· To help Hot-Standby manager to elect the best server to take control of the application

NOTE: The ReportFailure method is only available in E3 Server.

The ReportFailure method has the following parameters:

ReportFailure method parameters

NAME DESCRIPTION
FailureName Failure name (user-defined). This parameter
must be passed to ClearFailure method
whenever the failure becomes inactive. For
example, "FaultCOM1".

FailureDescription Failure description (user-defined). For

example, "Communication failure at COM1".

FailureWeight Defines failure's severity (or importance). A

zero value indicates no gravity. Higher values
indicate more severe faults.

Example:

332 Server Objec ts

 Sub TagSerialStatus_OnValueChanged()
If Value Then
' The tag value is True, application is on error
Application.ReportFailure "FAULT_COM1", _
"Communication fault at COM1", 100
Else
' The tag value is False, clears the failure
Application.ClearFailure "FAULT_COM1"
End If
End Sub

5.2.1.1.5 Trace
Trace(MessageText[, LogTimeStamp[, BreakLine]])

Allows recording messages in a text file. Messages will be recorded in a file with the same
name and path as the Domain file, but as a .txt file. Each new message is always inserted at
the end of the file. In case there is some failure in file recording (like access denied, for
example), there will be a script error.

This method can be used, for example, to record script debugging messages not executed at
Viewer (because in this case it is not possible to use MsgBox method).

Trace method parameters

NAME DESCRIPTION
MessageText User-defined text message.

LogTimeStamp (Optional) a Boolean indicating whether each

record must have date and time (timestamp).
If omitted, assumes True.

BreakLine (Optional) a Boolean indicating whether

there is a line break at the end of each
message. If False, all records in the file are in
a single line. If omitted, assumes True.

5.2.1.1.6 TrackEvent
TrackEvent(EventMessage, Comment, TimeStamp)

This method allows manually generating events via script. See Viewer's TrackEvent event for
more information.

5.2.2 Application Folder

The Application Folder object is similar to Data Folder object, from Data Server, allowing to
group Server objects inside folders. However, there are important differences:

· The Application Folder object is only available at run time

· This object has Application, Count, Name, Parent, and PathName general properties, and
also Item and Save general methods

Server Objec ts 333

· This object allows using For Each VBScript command to enumerate its child objects, but that
kind of access only takes into account Server objects, not listing, for example, screens and
resources inside folders

· The root folder from where it is possible to enumerate objects is always the Server object

5.3 Configuration-Only Objects

This section contains information about objects which can be only used at configuration time.

5.3.1 E3 Studio
This section contains information about specific methods of the E3StudioApplication object.
This object does not have specific events nor properties.

5.3.1.1 Methods
This section contains information about specific methods of the E3Studio object.

NOTE: Methods described here can be only used in Studio, they are not available at run time.

5.3.1.1.1 CreateFile
CreateFile(ProjectName, ClassName[, FileName, FolderName, RunWizard, OpenView])

Creates a new object on a project file (.prj). Parameters for this method are the following:

· ProjectName: the name of the project file where the object will be inserted. This parameter
cannot be empty, and the project file must be loaded on Studio. It can be project file's full
path, or a Domain file's relative path. There is no need to add the .prj extension

· ClassName: The name of the object's class to be created. See the table below for possible
values for this parameter

· FileName: The name of the inserted object. If this parameter is omitted, then it will be used
a default name to create an object of the type indicated by ClassName. The maximum
allowed size for this parameter is 32 characters, and if it already exists, it is automatically
incremented

· FolderName: The name of the Folder where the object will be created. If this parameter is
omitted, the object is then created at project file's root. The Folder name must obey the
same rules of Note's section of the RenameFolder method

· RunWizard: A Boolean indicating whether the configuration wizard of the class indicated by
ClassName will be opened after executing this method. The default value of this parameter
is True

334 Server Objec ts

· OpenView: A Boolean indicating whether the editor of the inserted object will be opened
after executing this method. The default value of this parameter is True

Possible values for ClassName parameter

OBJECT TO CREATE PARAMETER VALUE

Alarm Configuration DB.AlarmConfig

Alarm Server DB.AlarmServer

Database DB.DBServer

Data Server Panel.DataServer

Formula DB.Formula

FrameSet Panel.FrameSet

Historic DB.Hist

I/O Driver IODrv.IODriver

OPC Driver IODrv.OPCDriver

Report Panel.Report

Screen Panel.Screen

Storage DB.Historian

Viewer Panel.Viewer

5.3.1.1.2 CreateFolder
CreateFolder(ProjectName, FolderName[, ParentFolder])

Creates a new Folder with the name defined by FolderName, inside project file (.prj)
ProjectName, which parent object is indicated by ParentFolder. The following restrictions
apply to this method:

· The project file indicated in parameter ProjectName must exist, and it must be opened on
Studio

· If parameter FolderName is empty, then a default name will be used to create the Folder.
For example, Folder1

· The maximum allowed size for parameter FolderName is 32 characters

Server Objec ts 335

· If the name indicated in parameter FolderName already exists, then it will be automatically
incremented

· The name of the Folder in FolderName must obey the same rules of Note's section of the
RenameFolder method

· The Folder indicated in parameter ParentFolder must exist. If this parameter is omitted, the
new Folder is then created at project file's root

5.3.1.1.3 CreatePRJ
CreatePRJ(Filename)

Creates a new project file (.prj) named Filename, and then adds it to the current Domain, if it
exists. If the parameter Filename is not an absolute path, then it will use a path relative to the
Domain, or the default path for project files (saved on Windows Registry). The .prj extension is
added automatically, if needed.

5.3.1.1.4 RenameFolder
RenameFolder(OldName, NewName)

Allows renaming a Folder in an open project file in E3 Studio, whether it belongs to the Domain
or not. The OldName parameter is the full path to the Folder to rename, and the NewName
parameter is the new name, without a path.

NOTES:
· If Folder's full path in the parameter OldName, or the new name in the parameter
NewName starts with a character that is not a letter (with no diacritical marks or "ç"), or if
it has any character that is not a letter (with no diacritical marks or "ç"), a number (0-9), or
an underscore, you must surround that name with brackets.
· If the parameter NewName is invalid, or if the parameter OldName has a syntax error, or
else the path indicated by OldName is not found on any open project file, a script error will
occur
· Password-protected project files must be unlocked before using this method

5.4 Drivers
This section contains information about events, methods and properties of the following
objects: I/O Driver, I/O Tag, I/O Block, I/O Block Element, OPC Driver, OPC Tag, OPC Block, and
OPC Block Element.

336 Server Objec ts

5.4.1 I/O Driver
This section contains information about events, methods and properties of the I/O Driver
object.

5.4.1.1 Events
This section contains information about the events of the I/O Driver object.

5.4.1.1.1 AfterStart
AfterStart()

Occurs after the I/O driver has started to communicate. It is common to make a script for this
event using the Write method to perform equipment setup. Example:
Sub Driver1_AfterStart()
' After started, communication writes values
' to the equipment or device
Write 0, 2, 55, 2, 33.4
Write 0, 3, 55, 20, "Metal"
End Sub

5.4.1.1.2 AfterStop
AfterStop()

Occurs after the driver has finished the communication. Use the AfterStop event to perform
any necessary actions after driver communication has finished.

5.4.1.1.3 BeforeStart
BeforeStart()

Occurs when the driver is about to start the communication. Use the BeforeStart event to
perform any necessary actions before starting communication, such as setting up driver
parameters. Example:
Sub Driver1_BeforeStart()
' It performs the startup of driver parameters before
' starting the communication
P1 = 0
P2 = 20
P3 = 80
P4 = 0
End Sub

5.4.1.1.4 BeforeStop
BeforeStop()

Occurs when the driver is about to finish the communication. Use the BeforeStop event to
perform any necessary actions before finishing communication, such as writing to or reading
values from the equipment or device, before communication is no longer available.

Server Objec ts 337

5.4.1.1.5 OnCommError
OnCommError(EvtType, Size, Element, N1, N2, N3, N4)

Occurs when an I/O Driver detects any writing or reading error. Use an OnCommError event to
check when a writing or reading failure occurred in the I/O Driver. Event variables receive
information about this error. With these values, it is possible to track back which Tags have I/O
problems.

OnCommError event variables

NAME DESCRIPTION
EvtType Informs which type of operation the Driver
was performing when the error occurred,
according to the following options:

· 0: Single Element reading error (Size = 1).

Param1 is N1, Param2 is N2, Param3 is N3,
and Param4 is N4

· 1: Single Element writing error (Size = 1).

Param1 is N1, Param2 is N2, Param3 is N3,
and Param4 is N4

· 2: Block reading error (I/O Block). Size is

determined by the number of Block
Elements. Param1 is N1, Param2 is N2,
Param3 is N3, and Param4 is N4.

· 3: Block writing error (I/O Block). Size is

determined by the number of Block
Elements. Param1 is N1, Param2 is N2,
Param3 is N3, and Param4 is N4.

Size Number of values being read or written.

Element Index of the element being read or written

inside a Block.

N1 First parameter of a reading or writing

operation that generated the error.

N2 Second parameter of a reading or writing

operation that generated the error.

N3 Third parameter of a reading or writing

operation that generated the error.

N4 Fourth parameter of a reading or writing

operation that generated the error.

338 Server Objec ts

Example:
Sub Driver1_OnCommError(Type, Size, Element, N1, N2, N3, N4)
Application.GetObject("Data.InternalTag1").Value = _
Application.GetObject("Data.InternalTag1").Value + 1
Application.GetObject("Data.EvtType").Value = EvtType
Application.GetObject("Data.Size").Value = Size
Application.GetObject("Data.Element").Value = Element
Application.GetObject("Data.N1").Value = N1
Application.GetObject("Data.N2").Value = N2
Application.GetObject("Data.N3").Value = N3
Application.GetObject("Data.N4").Value = N4
End Sub

5.4.1.1.6 OnCommErrorEx
OnCommErrorEx(ErrorInfo)

Occurs soon after the execution of the OnCommError event.

ErrorInfo parameter information

NAME DESCRIPTION
ErrorInfo.EvtType Indicates the type of operation that caused
the error:

· 0: tag reading

· 1: tag writing

· 2: block reading

· 3: block writing

ErrorInfo.Size Size of the block that caused the error (if it is

a tag, Size is equal to 1).

ErrorInfo.Element Index of the block element that caused the

error.

ErrorInfo.Nx Nx or Bx parameters (x = 1, 2, 3, 4) of the

operation that caused the error.

ErrorInfo.ParamDevice ParamDevice parameter (String) of the

operation that caused the error.

ErrorInfo.ParamItem ParamItem parameter (String) of the

operation that caused the error.

Server Objec ts 339

5.4.1.1.7 OnTagRead
OnTagRead(Tag)

Occurs on tag reading, whenever the I/O Driver returns a new value or an error. This means
that if tag value or tag quality do not change, the event will not be triggered. For this event to
work, EnableDriverEvent property must necessarily be enabled. Besides, PercentDeadband
property can also influence the event, if EnableDeadband property is enabled. Example:
Sub Tags_OnTagRead(Tag)
Set Obj = Application.GetObject("Data1.TagName")
Obj.Value = Tag.Name
Set Obj = Application.GetObject("Data1.TagRead")
Obj.Value = True
Set Obj = Application.GetObject("Data1.TagType")
Obj.Value = TypeName(Tag)
End Sub

5.4.1.1.8 OnTagWrite
OnTagWrite(Tag, Succeeded, User)

Occurs when a writing operation is triggered at any Driver Tag.

OnTagWrite event variables

NAME DESCRIPTION
Tag A reference to the Tag object which is being
written. For example, you can access the Tag
property using a syntax like Tag.DocString.

Succeeded A Boolean value which indicates whether a

writing operation was successful or not.

User Parameter which receives the name of the

user performing the writing operation. The
default value of this parameter is "System". If
there is no user logged on the Viewer which
generated the event, this parameter
contains the value "Anonymous".

5.4.1.2 Methods
This section contains information about the methods of the I/O Driver object.

340 Server Objec ts

5.4.1.2.1 Write
Write(N1, N2, N3, N4, Value[, WriteSyncMode])

Writes data in the equipment synchronously. This method returns a Boolean indicating
whether the operation has been successful or not. N1 to N4 parameters correspond to
driver's [N] parameters. Value parameter defines the value to be written in the driver.
WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: write mode configured in the driver

· 1: synchronous write mode

· 2: asynchronous write mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
For further information on these parameters, see the driver's documentation. Example:
Sub Button1_Click()
Dim val
' When clicking the button, write into the driver
Set driver = Application.GetObject("Driver1")
' Writes 55.5 on the driver
driver.Write 4, 5, 1, 0, 55.5
End Sub

5.4.1.2.2 WriteEx
WriteEx(N1, N2, N3, N4, Value, Timestamp, Quality[, WriteStatus][, WriteSyncMode])

Writes data in the equipment. This method returns a Boolean indicating whether the
operation has been successful or not. N1 to N4 parameters correspond to driver's [N]
parameters. Value parameter defines the value to be written in the driver. For further
information on these parameters, see the driver's documentation.

Timestamp, Quality, and WriteStatus parameters are optional. When omitted, method's
behavior is similar to Write. Timestamp specifies the timestamp to be written in the tag (if
supported by the equipment). If omitted, the timestamp from the moment of the writing
operation is assumed. Quality indicates quality (from 0 to 255). If omitted, a Good (192) quality
is assumed. WriteStatus receives a value returned by the driver, indicating the writing status
(if supported by the driver, according to its own documentation).

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: write mode configured in the driver

· 1: synchronous write mode

· 2: asynchronous write mode (no confirmation)

Server Objec ts 341

When this parameter is omitted, the writing mode configured in the driver will also be used.
Example:
Dim status
If tag001.WriteEx(0, 0, 0, 0, 100, , , status) Then
MsgBox "Successful writing, status = " & status
Else
MsgBox "Writing failed, status = " & status
End If

5.4.1.3 Properties
This section contains information about the properties of the I/O Driver object.

5.4.1.3.1 DriverLocation

Defines which driver will be used by the I/O Driver object to communicate with a device.
This property accepts a String with the complete driver's path, in case it is not in the same
Domain's directory, or the relative driver's path if it is in the same Domain's directory. In case
there is no open Domain on Studio, a relative path is considered as starting from the folder
where the project or library containing the Driver object is. After that, the DriverName
property will change to the driver's description. This property cannot be modified once
communication has started. Default value is an empty String.

NOTE: It is always advisable to use option Browse DLL, on I/O Driver object's contextual menu,
to set this property correctly.

5.4.1.3.2 DriverName

Contains a String describing the Driver associated to the I/O Driver object. For this, you
must first set the DriverLocation property. This is a read-only property, and it is not available
at run time.

5.4.1.3.3 EnableReadGrouping

Enables reading optimization (automatic tag grouping). This property cannot be altered at
run time. Default value is True. The reading optimization only happens if the Driver supports
this feature.

5.4.1.3.4 P1

Use the P1 property to configure the driver. Check the driver documentation to correctly set
its parameters. This property cannot be modified after communication has started. Example:
Sub Driver1_BeforeStart()
' Driver1 is an object of type I/O Driver
DriverLocation = "c:\driver\plc.dll"
P1 = 2
P2 = 1
P3 = 9600
End Sub

342 Server Objec ts

5.4.1.3.5 P2

Use the P2 property to configure the driver. Check the driver documentation to correctly set
its parameters. This property cannot be modified after communication has started. Example:
Sub Driver1_BeforeStart()
' Driver1 is an object of type I/O Driver
DriverLocation = "c:\driver\plc.dll"
P1 = 2
P2 = 1
P3 = 9600
End Sub

5.4.1.3.6 P3

Use the P3 property to configure the driver. Check the driver documentation to correctly set
its parameters. This property cannot be modified after communication has started. Example:
Sub Driver1_BeforeStart()
' Driver1 is an object of type I/O Driver
DriverLocation = "c:\driver\plc.dll"
P1 = 2
P2 = 1
P3 = 9600
End Sub

5.4.1.3.7 P4

Use the P4 property to configure the driver. Check the driver documentation to correctly set
its parameters. This property cannot be modified after communication has started. Example:
Sub Driver1_BeforeStart()
' Driver1 is an object of type I/O Driver
DriverLocation = "c:\driver\plc.dll"
P1 = 2
P2 = 1
P3 = 9600
P4 = 500
End Sub

5.4.1.3.8 ParamDevice

Defines the address of the device accessed by the driver. This property is inherited by the
driver's blocks and tags, which can override this value, if necessary.

5.4.1.3.9 ReadRetries

Indicates the number of reading retries by the driver in case of error. If it is set to 2, for
example, it means the driver will retry failed communications twice, apart from the original
try.

Server Objec ts 343

5.4.1.3.10 ShareMaximum

Defines the maximum number of I/O Drivers that will be grouped into a shared I/O Server.
This property is only used when the ShareServer property is enabled. Example:
' This driver will not be shared
ShareServer = False
ShareMaximum = <any value>
' All drivers are grouped into the same IOServer
' Does not define a limit
ShareServer = True
ShareMaximum = 0
' Groups every 5 drivers into an IOServer
ShareServer = True
ShareMaximum = 5

5.4.1.3.11 ShareServer

If True, this driver will share its execution among all other I/O drivers that have the same
string in DriverLocation. It means that only the first I/O driver that is set will execute the
communication initialization. All other shared communication drivers will ignore all setting
parameters from P1 to P4, as well as other settings. Otherwise, if the ShareServer property is
False, the driver will not share any kind of communication with other I/O drivers. This property
cannot be modified once communication has started. Default value is False.

5.4.1.3.12 WriteFeedbackMode

Allows controlling writing feedback confirmation in tags. It applies only to readable tags,
that is, tags which AllowRead property is set to True. Through this property, reading tags which
receive writings is quickier. This property has the following setting options:

Available options for WriteFeedbackMode

OPTION DESCRIPTION
0 - wfWaitNextRead Tag reading is done normally on the next
scan.

1 - wfImmediateReadAfterWrite After each writing, a confirmation reading

will be performed as soon as possible.

2 - wfTrustWriteSuccess If the driver indicates a successfully writing,

the written value is directly assumed by the
tag, without reading it from the PLC.

The default value is 1 - wfImmediateReadAfterWrite. Applications from earlier versions, before

this property existed, assume 0 when loaded. Example:

344 Server Objec ts

 Sub CommandButton1_Click()
Dim mode
mode = Application.GetObject("Driver1").WriteFeedbackMode
MsgBox mode
Select case mode
Case 0
MsgBox "Tag reading will be done in the next scan."
Case 1
MsgBox "After each writing, a confirmation _
reading will be done as soon as possible."
Case 2
MsgBox "If the driver indicates writing success, _
the written value is assumed directly by the tag, _
without reading it from the PLC."
End Select
End Sub

NOTE: When a value of 2 is used, timestamp and quality may be damaged, since in a
successful writing the value is assumed by the tag without searching for timestamp and
quality in the PLC. Besides, the assumed value itself may present a little deviation due to any
kind of simplification in numbers that may occur in the driver or in the PLC. Also note that
some drivers or protocols may indicate success, even when the writing has failed. So, the
other values (0 - wfWaitNextRead or 1 - wfImmediateReadAfterWrite) should be preferred
when possible.

5.4.1.3.13 WriteRetries

Indicates the number of writing retries by the driver in case of error. If it is set to 2, for
example, it means the driver will retry a failed communication twice, apart from the original
try.

5.4.1.3.14 WriteSyncMode

Determines how writings will be sent to the IOServer (synchronous or asynchronous

mode). This property has the following configuration options:

Available options for WriteSyncMode

OPTION DESCRIPTION
0 - wsmDefault Synchronous mode (default).

1 - wsmSync Synchronous mode. Every time a value is

written on some tag, E3Run sends the writing
to the IOServer and waits for the return of the
writing.

Server Objec ts 345

 2 - wsmAsyncUnconfirmed Asynchronous mode without confirmation.
All writings are sent to the IOServer without
waiting the return, and it is always assumed
that the writing was successful. When in
asynchronous mode, the writing methods of
the tags (Write, WriteEx) always return True
immediately, and the writing status (on
methods which return this status) remains
always empty. The OnTagWrite event of the
driver is executed as soon as the writing is
sent to the IOServer, and the Succeeded
parameter always remain in True.

Asynchronous writings will be executed by the IOServer as soon as the driver is available
(when current reading is over). If several asynchronous writings are sent to the IOServer, the
driver will only return the readings after all asynchronous writings are executed.

5.4.1.4 I/O Block

This section contains information about events, methods, and properties of the I/O Block
object.

5.4.1.4.1 Events

This section contains information about the events of the I/O Block object.

5.4.1.4.1.1 OnRead
OnRead()

Occurs when the driver performs a communication block reading. Use the OnRead event when
it is necessary to perform some operation soon after some data has been modified in the
communication block object, such as the Quality, TimeStamp or even the Value property of
some of the block's element. Example:
Sub IOBlock1_OnRead()
' When reading a block, assign to the InternalTag1 tag
' the value of the block element elm1.
Set obj=Application.GetObject("DataServer1.InternalTag1")
Set elm = Application.GetObject("Driver1.IOBlock1.elm1")
obj.Value = elm.Value
End Sub

5.4.1.4.2 Methods

This section contains information about the methods of the I/O Block object.

346 Server Objec ts

5.4.1.4.2.1 Write
Write([WriteSyncMode])

Writes the I/O Block's current value in the equipment. Usually, this script command is used
only when the object's AllowWrite property is False.

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: writing mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
For further information, see the driver's documentation. This method returns a Boolean
indicating whether the operation has been successful or not.

5.4.1.4.2.2 WriteEx
WriteEx(Value, Timestamp, Quality[, WriteStatus][, WriteSyncMode])

Writes values in the equipment. All its parameters are optional; if omitted, method's behavior
is the same as Write. This method returns a Boolean indicating whether the operation has
been successful or not.

Value parameter defines the value to be written in the driver. Datatype depends on the driver;
if omitted, tag's current value is assumed. Timestamp specifies the timestamp to be written in
the tag (if supported by the equipment). If omitted, the timestamp from the moment of the
writing operation is assumed. Quality indicates quality (from 0 to 255). If omitted, a Good (192)
quality is assumed. WriteStatus receives a value returned by the driver, indicating writing
status (if supported by the driver, according to its own documentation).

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: writing mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
Example:

Server Objec ts 347

 Sub Tag1_OnRead()
' Use WriteEx to transfer values from one driver to another
Application.GetObject("Driver2.Tag")._
WriteEx Value, TimeStamp, Quality
End Sub

5.4.1.4.3 Properties

This section contains information about the properties of the I/O Block object.

5.4.1.4.3.1 AdviseType

Controls Advise mode. The available options are:

Available options for AdviseType

OPTION DESCRIPTION
0 - AlwaysInAdvise The tag is updated if AllowRead property is
True.

1 - AdviseWhenLinked The tag is updated only if AllowRead is True

and the tag is associated to an active object
(that is, one Display in an open Screen, an
enabled Alarm, etc.). A tag link for this
purpose can be assigned to these
properties: Value, RawValue, Quality and
from Bit00 to Bit31 for Block Elements, and
Quality and TimeStamp for I/O Blocks.

5.4.1.4.3.2 AllowRead

Defines whether the block will be read by the I/O driver. If True, the driver automatically
updates the I/O elements inserted in the block, in time spans defined by Scan property.
Otherwise, the communication block will neither be read nor updated. This property can be
modified at run time. Default value is True. Example:
Sub Button1_Click()
'Stops block reading
Set obj = Application.GetObject("Driver1.block1")
obj.AllowRead = False
End Sub

5.4.1.4.3.3 AllowWrite

Defines whether the block will be written automatically when the Value property from its I/
O Block Elements is modified. If True, the modifications will be sent to the device associated to
the I/O Driver. Otherwise, the modifications will be ignored. Communication elements will not
accept values if this property is set to False, unless AllowRead property is also set to False.
Example:
Sub Button1_Click()
'Disables block writing
Set obj = Application.GetObject("Driver1.block1")
obj.AllowWrite = False
End Sub

348 Server Objec ts

5.4.1.4.3.4 B1

Specifies which data cluster in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Example:
Sub Block1_BeforeStart()
B1 = 2
B2 = 1
B3 = 9600
End Sub

5.4.1.4.3.5 B2

Specifies which data cluster in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Example:
Sub Block1_BeforeStart()
B1 = 2
B2 = 1
B3 = 9600
End Sub

5.4.1.4.3.6 B3

Specifies which data cluster in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Example:
Sub Block1_BeforeStart()
B1 = 2
B2 = 1
B3 = 9600
End Sub

5.4.1.4.3.7 B4

Specifies which data cluster in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Example:
Sub Block1_BeforeStart()
B1 = 2
B2 = 1
B3 = 9600
B4 = 524
End Sub

5.4.1.4.3.8 EnableDeadBand

Enables or disables the PercentDeadBand property of the Block Elements. If True, the Block
value is only updated when it changes, and its new value exceeds the limit defined by the
PercentDeadBand property of any Element of the Block. Otherwise, the Block is always
updated, and the dead band limit is not checked. Whenever possible, you should keep the
dead band enabled, because it enhances data acquisition and the processing performance.
Usually, dead band is disabled only for Tags that return values representing events which
need to be handled in the OnRead event. The default value of this property is True.

Server Objec ts 349

NOTES:
· In case there are more than one Block Element mapped to the same index, the dead band
configuration used is the one which results in the smallest absolute dead band value
· If any Block index has an Element not mapped, the dead band in this index is equal to 0,
that is, any variation in the value of the Element violates the dead band
· If the EnableDeadBand property is enabled, the last value sent to the Block is compared to
the current value read, Element by Element. If any Block Element violates its dead band,
the whole Block is updated

5.4.1.4.3.9 EnableDriverEvent

Controls the way OnTagRead events are generated, which occur in the I/O driver that
contains the block. If True, OnTagRead event generation is enabled by this tag. Otherwise, it is
disabled. The three kinds of I/O elements (I/O Tags, I/O Blocks, and Block Elements) can
generate this event. The event occurs in the driver, not in the block.

5.4.1.4.3.10 ParamDevice

Defines the address of the device accessed by the block. This property is inherited from the
driver, but its value can be overridden, if necessary.

5.4.1.4.3.11 ParamItem

Identifies data accessed by the block from inside the device.

5.4.1.4.3.12 Quality

Informs the quality of the value contained in the Value property. Each time the Driver sets a
new value to the Block it also sets data quality. This is a read-only property. Default value is 0
(Bad Quality).

NOTE: For further information about quality, see the topic Quality on User's Manual.

5.4.1.4.3.13 Scan

Specifies the duration of the scan used by the server to update the block. This property is
represented in milliseconds, and can be modified after communication has started. It is used
only when AllowRead property is set to True. When you set this property in several blocks in
the application, you should increase the value of this property to those blocks that do not vary
very much in the device, enabling other blocks with higher priority to be read more frequently,
thus enhancing general system performance. Default value is 1,000 (1 second). Scan value
must be greater than zero. Example:

350 Server Objec ts

 Sub IOBlock1_BeforeStart()
Scan = 152
End Sub

5.4.1.4.3.14 Size

Defines the size of the value clusters in this block. See the driver documentation for this
property's limits, according to B1 to B4 parameters. By creating elements for the block, you
can access reading and writing values for the device. This property cannot be modified once
communication has been started. Default value is 0. Example:
Sub IOBlock1_BeforeStart()
Size = 10
End Sub

5.4.1.4.3.15 TimeStamp

Updated whenever there is a change in value or status in either the Value or the Quality
properties. Informs timestamp associated to both value and quality in an I/O block. This is a
read-only property. Default value is 00:00:00.

5.4.1.4.4 I/O Block Element

This section contains information about events, methods and properties of the I/O Block
Element object. This object does not have events associated to it.

5.4.1.4.4.1 Methods

This section contains information about the methods of the I/O Block Element object.

Write
Write([WriteSyncMode])

Writes I/O Block Element's current value in the equipment. Usually, this script command is
used only when the object's AllowWrite property is False.

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: write mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
For further information, see the driver's documentation. This method returns a Boolean
indicating whether the operation has been successful or not.

Server Objec ts 351

WriteEx
WriteEx(Value, Timestamp, Quality[, WriteStatus][, WriteSyncMode])

Writes values in the equipment. All its parameters are optional; if omitted, method's behavior
is the same as Write. This method returns a Boolean indicating whether the operation has
been successful or not.

Value parameter defines the value to be written in the driver. Datatype depends on the driver;
if omitted, tag's current value is assumed. Timestamp specifies the timestamp to be written in
the tag (if supported by the equipment). If omitted, the timestamp from the moment of the
writing operation is assumed. Quality indicates quality (from 0 to 255). If omitted, a Good (192)
quality is assumed. WriteStatus receives a value returned by the driver, indicating writing
status (if supported by the driver, according to its own documentation).

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: writing mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
Example:
Sub Tag1_OnRead()
' Use WriteEx to transfer values from one driver to another
Application.GetObject("Driver2.Tag")._
WriteEx Value, TimeStamp, Quality
End Sub

5.4.1.4.4.2 Properties

This section contains information about the properties of the I/O Block Element object.

Bit00 to Bit31
These properties represent the 32 bits in I/O Tag Value property, ranging from Bit00 (the
least significant bit) to Bit31 (the most significant bit). By modifying each one of these bits you
will modify tag's Value property, and vice-versa, but this only happens when UseBitFields
property is True. Default value is False.

NOTE: Bit values (from Bit00 to Bit31 properties) are not affected by the adjustment in scale.
That is, they represent the bits from the value read by the equipment before the conversion.

DeviceHigh
Defines the highest value reached by the Block Element in the device. This property is used
in the calculation of the value of the PercentDeadBand property, and also to adjust the scale
value of the device before setting it to the Value property. Likewise, the inverse operation is

352 Server Objec ts

done before sending the value to the Driver, when writing. This conversion happens only when
the EnableScaling property is set to True. Default value is 1000.

NOTE: Bit values (the Bit00 to Bit31 properties) are not affected by the scale adjustment, that
is, they represent bits from the value read by the equipment before conversion.

DeviceLow
Defines the lowest value reached by the Block Element in the device. This property is used in
the calculation of the value of the PercentDeadBand property, and also to adjust the scale
value of the device before setting it to the Value property. Likewise, the inverse operation is
done before sending the value to the Driver, when writing. This conversion happens only when
the EnableScaling property is set to True. Default value is 0.

NOTE: Bit values (the Bit00 to Bit31 properties) are not affected by the scale adjustment, that
is, they represent bits from the value read by the equipment before conversion.

EnableDriverEvent
Controls how the OnTagRead event is generated, which occurs in the I/O driver that contains
the block. If the EnableDriverEvent property of this tag is configured to True, generating the
OnTagRead event is enabled by this tag. Otherwise, it is disabled. The three kinds of I/O
elements (I/O Tag, I/O Block, and Block Element) can generate this event. The event occurs in
the driver, and not in the block.

EnableScaling
If True, all values from the device will receive scale adjustments according to DeviceHigh,
DeviceLow, EUHigh and EULow properties before they are attributed to Value property.
Otherwise, no adjustment in scale will be made. Default value is False. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

EU
Identifies the engineering unit represented by the value, such as degrees, meters, etc.
Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

Server Objec ts 353

EUHigh
Defines the highest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

EULow
Defines the lowest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 0. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

Index
Specifies this element's position among the other elements configured by Size property of
the I/O block where it is inserted. This property's value range from 0 to the value defined by
Size minus 1. (For example: If Size is 20, Index ranges from 0 to 19). This property can be
modified once communication has started. Default value is 0, but when mapping the elements
from a block, E3 Studio automatically adjusts Index parameter to the specified value. Example:
Sub Element_OnStartRunning()
Index = 15
End Sub

PercentDeadBand
The PercentDeadBand property determines the minimum variation (dead band) of a Block
Element, so that this value can be updated in E3. This value is specified as a percentage of the
difference between the DeviceHigh and the DeviceLow properties. This property is only used if
the EnableDeadBand property of the Block is set to True. If the PercentDeadBand property is

354 Server Objec ts

equal to 0, the Block Element does not have a dead band, and any variation in its value is
passed to E3. Otherwise, E3 receives a new value only if its difference, relative to the current
value, is larger than the dead band. Default value is 0.

Quality
Informs the quality of the value contained in Value property. Each time the Driver attributes
a new value to the Tag it also sets data quality. This property is read-only. Default value is 0
(Bad Quality).

NOTE: For further information on quality, see the topic Quality on User's Manual.

RawValue
It is the element's original value, before EnableScaling property has acted upon it. So, if
EnableScaling is False, Value and RawValue properties will behave identically.

UseBitFields
If True, every time the value from Value property is modified, the bits referring from Bit00 to
Bit31 properties will be updated. Also, every time the value from Bit00 to Bit31 properties are
modified, the value from Value property is updated and sent to the device, if AllowWrite
property is True. Otherwise, bits will not undergo any modification. This property can be
updated once communication has started. Default value is False.

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

Value
Updated whenever a new valid reading of a device is done, using N1 to N4 parameters.
Datatype (Integer, Floating Point, String) depends on the driver to which the element is
associated and its parameters.

This property is updated this way if AllowRead property is True, and when there are no
communication errors (in this case, Quality and TimeStamp properties are updated), according
to a scan time defined in Scan property. Another way to use this property is to write values in
the device; for this, just set a new value to Value property or to some of the bits from Bit00 to
Bit31. In this case, AllowWrite property must be True.

This is also I/O Tag's default property. So, it is not mandatory for a value reference to a I/O Tag
to make Value property explicit in order to access its value. Default value is empty (no value).
Example:
Sub Button1_Click()
' Accesses a tag and shows current value
' tag1 is an I/O tag
Set obj = Application.GetObject("IODriver1.tag1")
MsgBox "Tag1's current value: " & obj.Value
'This can also be done in a different way,
'with no need to show Value property, which is default
MsgBox " Tag1's current value: " & obj
End Sub

Server Objec ts 355

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

5.4.1.5 I/O Folder

This section contains information about properties of the I/O Folder object of the I/O Driver.
This object does not have events nor methods associated to it.

5.4.1.5.1 Properties

This section contains information about the properties of the I/O Folder object of the I/O
Driver.

5.4.1.5.1.1 ParamDevice

Defines the address of the device accessed by the I/O Folder. This property is inherited from
the I/O Driver, and its value can be overwritten, if needed.

5.4.1.6 I/O Tag

This section contains information about events, methods and properties of the I/O Tag object.

5.4.1.6.1 Events

This section contains information about the events of the I/O Tag object.

5.4.1.6.1.1 OnRead
OnRead()

Occurs when a tag reading is performed by the driver. Use the OnRead event when it is
necessary to perform some operation soon after some data has been modified in the tag, such
as the Value, Quality or TimeStamp properties. This event is generated by a background
reading. Example:
Sub CommTag1_OnRead()
' When reading the tag, assign its value
' to the InternalTag1 tag.
Set obj = Application.GetObject("DataServer1.InternalTag1")
obj = Value ' CommTag1 Value
End Sub

5.4.1.6.2 Methods

This section contains information about the methods of the I/O Tag object.

356 Server Objec ts

5.4.1.6.2.1 Write
Write([WriteSyncMode])

Writes I/O Tag current value in the equipment. Usually, this script command is used only when
the object's AllowWrite property is False.

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: write mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
For further information, see the driver's documentation. This method returns a Boolean
indicating whether the operation has been successful or not.

5.4.1.6.2.2 WriteEx
WriteEx(Value, Timestamp, Quality[, WriteStatus][, WriteSyncMode])

Writes values in the equipment. All its parameters are optional; if omitted, method's behavior
is the same as Write. This method returns a Boolean indicating whether the operation has
been successful or not.

Value parameter defines the value to be written in the driver. Datatype depends on the driver;
if omitted, tag's current value is assumed. Timestamp specifies the timestamp to be written in
the tag (if supported by the equipment). If omitted, the timestamp from the moment of the
writing operation is assumed. Quality indicates quality (from 0 to 255). If omitted, a Good (192)
quality is assumed. WriteStatus receives a value returned by the driver, indicating writing
status (if supported by the driver, according to its own documentation).

WriteSyncMode parameter allows you to use a writing mode that may be different from the
one used in the driver. The available options for this parameter are:

· 0: writing mode configured in the driver

· 1: synchronous writing mode

· 2: asynchronous writing mode (no confirmation)

When this parameter is omitted, the writing mode configured in the driver will also be used.
Example:

Server Objec ts 357

 Sub Tag1_OnRead()
' Use WriteEx to transfer values from one driver to another
Application.GetObject("Driver2.Tag")._
WriteEx Value, TimeStamp, Quality
End Sub

5.4.1.6.3 Properties

This section contains information about the properties of the I/O Tag object.

5.4.1.6.3.1 AdviseType

Controls the Advise mode. The available options are:

Available options for AdviseType

OPTION DESCRIPTION
0 - AlwaysInAdvise The tag is kept updated if AllowRead property
is equal to True.

1 - AdviseWhenLinked The tag is only updated if AllowRead is equal

to True and it is linked to any active object,
for example, a Display on an open Screen, an
enabled alarm, among others. The tag link for
this purpose can be done on the following
properties: Value, RawValue, TimeStamp,
Quality, and from Bit00 to Bit31 of the I/O Tag.

Example:
Sub CommandButton3_Click()
MsgBox Application._
Application.GetObject("Driver1.Tag1").AdviseType
End Sub

5.4.1.6.3.2 AllowRead

Defines whether the tag will be read by the I/O driver. If True, the driver automatically
updates Value and Bits (from Bit00 to Bit31) properties, in time spans defined by the Scan
property. Otherwise, the I/O tag will neither be read nor updated. This property can be
modified at run time. Default value is True. Example:
Sub Button1_Click()
' Stops tag reading
Set obj = Application.GetObject("Driver1.tag")
obj.AllowRead = False
End Sub

358 Server Objec ts

5.4.1.6.3.3 AllowWrite

Defines whether the tag will be written automatically when Value or Bits (from Bit00 to
Bit31) properties are modified. If True, the modifications will be sent to the device associated
to the I/O Driver. Otherwise, the modifications will be ignored. Default value is True. Example:
Sub Button1_Click()
' Disables tag writing
Set obj = Application.GetObject("Driver1.tag")
obj.AllowWrite = False
End Sub

5.4.1.6.3.4 Bit00 to Bit31

These properties represent the 32 bits in I/O Tag Value property, ranging from Bit00 (the
least significant bit) to Bit31 (the most significant bit). By modifying each one of these bits you
will modify tag's Value property, and vice-versa, but this only happens when UseBitFields
property is True. Default value is False.

NOTE: Bit values (from Bit00 to Bit31 properties) are not affected by the adjustment in scale.
That is, they represent the bits from the value read by the equipment before the conversion.

5.4.1.6.3.5 DeviceHigh

Defines the highest value achieved by this tag in the device. Adjusts the value scale from the
device before being attributed to Value property. Likewise, the inverse operation is done
before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

5.4.1.6.3.6 DeviceLow

Defines the lowest value achieved by this tag in the device. Adjusts the value scale from the
device before being attributed to Value property. Likewise, the inverse operation is done
before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 0. Example:

Server Objec ts 359

 Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

5.4.1.6.3.7 EnableDeadBand

Enables or disables the PercentDeadBand property. If True, tag value is only updated when
it changes, and its new value exceeds the limit defined by the PercentDeadBand property.
Otherwise, the tag is always updated, and the deadband limit is not checked. Whenever it is
possible, you should keep deadband enabled, because it enhances data acquisition and
processing performance. Usually, you should disable deadband only for tags that return
values which represent digital or analogical events, and it is necessary to process these
events via script on OnRead tag event. Default value is True.

5.4.1.6.3.8 EnableDriverEvent

Controls how the OnTagRead event is generated, which occurs in the I/O driver that contains
the block. If the EnableDriverEvent property of this tag is configured to True, generating the
OnTagRead event is enabled by this tag. Otherwise, it is disabled. The three kinds of I/O
elements (I/O Tag, I/O Block, and Block Element) can generate this event. The event occurs in
the driver, and not in the block.

5.4.1.6.3.9 EnableScaling

If True, all values from the device will receive scale adjustments according to DeviceHigh,
DeviceLow, EUHigh and EULow properties before they are attributed to Value property.
Otherwise, no adjustment in scale will be made. Default value is False. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

360 Server Objec ts

5.4.1.6.3.10 EU

Identifies the engineering unit represented by the value, such as degrees, meters, etc.
Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

5.4.1.6.3.11 EUHigh

Defines the highest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

5.4.1.6.3.12 EULow

Defines the lowest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 0. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

Server Objec ts 361

5.4.1.6.3.13 N1

Specifies which variable in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Default value is 0. Example:
Sub Tag_OnStartRunning()
N1 = 10
End Sub

5.4.1.6.3.14 N2

Specifies which variable in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Default value is 0. Example:
Sub Tag_OnStartRunning()
N2 = 3
End Sub

5.4.1.6.3.15 N3

Specifies which variable in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Default value is 0. Example:
Sub Tag_OnStartRunning()
N1 = 10
N3 = 5
N4 = 20
End Sub

5.4.1.6.3.16 N4

Specifies which variable in the device this tag is associated to. See the driver
documentation for appropriate parameters. This property can be modified once
communication has started. Default value is 0. Example:
Sub Tag_OnStartRunning()
N1 = 10
N4 = 20
End Sub

5.4.1.6.3.17 ParamDevice

Defines the address of the device accessed by the tag. This property is inherited from the
driver, but its value can be overridden, if necessary.

5.4.1.6.3.18 ParamItem

Identifies data this tag accesses from inside the device.

362 Server Objec ts

5.4.1.6.3.19 PercentDeadBand

Determines deadband for a tag, so that this value can be updated on E3. This value is the
variation percentage between the DeviceHigh and DeviceLow property values. This property is
only used if the tag's EnableDeadBand property is set to True. If PercentDeadBand value is 0,
the tag will not have deadband, and any variation in value will be passed to E3. Otherwise, E3
will receive a new value only if its difference is larger than deadband. Default value is 0.

5.4.1.6.3.20 Quality

Informs the quality of the value contained in Value property. Each time the Driver attributes
a new value to the Tag it also sets data quality. This is a read-only property. Default value is 0
(Bad Quality).

NOTE: For further information on quality, see the topic Quality on User's Manual.

5.4.1.6.3.21 RawValue

It is the element's original value, before EnableScaling property has acted upon it. So, if this
property is False, Value and RawValue properties will behave identically.

5.4.1.6.3.22 Scan

Specifies the duration of the scan used by the server to update the Value property. This
property is represented in milliseconds, and can be modified after communication has
started. It is used only when AllowRead property is set to True. When you set this property in
the several tags in the application, you should increase the value of the property to those tags
that do not vary very much in the device, enabling other tags with higher priority to be read
more frequently, and enhancing general performance in the system. Default value is 1,000 (1
second). Scan value should be above zero. Example:
Sub Tag_OnStartRunning()
Scan = 1500
End Sub

5.4.1.6.3.23 TimeStamp

Updated whenever there is a change in value or status in either Value or Quality

properties. Informs timestamp associated to both value and quality in I/O tag. This is a read-
only property. Default value is 00:00:00.

Server Objec ts 363

5.4.1.6.3.24 UseBitFields

If True, every time the value from Value property is modified, the bits referring from Bit00 to
Bit31 properties will be updated. Also, every time the value from Bit00 to Bit31 properties are
modified, the value from Value property is updated and sent to the device, if AllowWrite
property is True. Otherwise, bits will not undergo any modification. This property can be
updated once communication has started. Default value is False.

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by adjusting the scale. That is,
they represent the bits from the value read by the equipment before conversion.

5.4.1.6.3.25 Value

Updated whenever a new valid reading of a device is done, using N1 to N4 parameters.

Datatype (Integer, Floating Point, String) depends on the driver to which the element is
associated and its parameters.

This property is updated this way if the AllowRead property is True, and when there are no
communication errors (in this case, the Quality and TimeStamp properties are updated),
according to a scan time defined in the Scan property. Another way to use this property is to
write values in the device. For this, just set a new value to the Value property or to some of the
bits from the Bit00 to Bit31 properties. In this case, the AllowWrite property must be True.

This is also I/O Tag's default property. So, it is not mandatory for a value reference to a I/O Tag
to make the Value property explicit in order to access its value. Default value is empty (no
value). Example:
Sub Button1_Click()
' Accesses a tag and shows current value
' tag1 is an I/O tag
Set obj = Application.GetObject("IODriver1.tag1")
MsgBox "Tag1's current value: " & obj.Value
'This can also be done in a different way,
'with no need to show Value property, which is default
MsgBox " Tag1's current value: " & obj
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by adjusting in scale. That is, they
represent the bits from the value read by the equipment before conversion.

5.4.2 OPC Driver

This section contains information about events and properties of the OPC Driver object. This
object does not contain methods associated to it.

364 Server Objec ts

5.4.2.1 Events
This section contains information about the events of the OPC Driver object.

5.4.2.1.1 OnTagRead
OnTagRead(Tag)

Occurs on tag reading, always when a new value or error is returned by the OPC Server. That is,
if tag value or quality do not change, this event is not triggered. For this event to occur, the
EnableDriverEvent property of the tag must be enabled.

5.4.2.1.2 OnTagWrite
OnTagWrite(Tag, Succeeded, User)

Occurs when a writing is triggered on any Tag of the Driver. For this event to occur, the
EnableDriverEvent property of the Tag must be enabled. If the writing is asynchronous, the
OnTagWrite event is triggered only when the server sends an answer indicating whether the
writing is successful or not.

Variables of the OnTagWrite event

NAME DESCRIPTION
Tag A reference to the Tag object which is being
written. For example, you may access a Tag
property using a Tag.DocString syntax.

Succeeded A Boolean value indicating writing success or

failure.

User Parameter which receives the user

performing the writing operation. The default
value of this parameter is "System". If there is
no user logged on the Viewer which
generated the event, this parameter
contains the value "Anonymous". If the
writing is asynchronous, or if there is a failure
reported in an asynchronous way, this
parameter always has the value "System".

5.4.2.2 Properties
This section contains information about the properties of the OPC Driver object.

Server Objec ts 365

5.4.2.2.1 Compatibility

Controls the use of OPC default interfaces by E3's OPC client. The available options are:

· 0 - AnyVersion: normal operation (recommended). OPC driver communicates with both DA

2.0x and 1.0a servers (preference is given to 2.0x interfaces)

· 1 - Version10A: forces communication with DA 1.0a pattern for servers that support both DA
2.0x and 1.0a

· 2 - Version20: forces communication only with OPC DA 2.0x pattern

This property cannot be modified when OPC client communication is enabled (both in Studio
and at run time).

NOTE: only as a last resource the driver should be configured with a value different from 0 -
AnyVersion (default). This property is for advanced use only, and applies strictly to overcome
a possible incompatibility situation with some specific OPC servers.

5.4.2.2.2 ReconnectPeriod

Controls the connection period to the OPC Server. If connection is lost, the driver stops and
restarts until this action becomes successful. The period is set to milliseconds, and when the
value is set to 0, reconnection is disabled. Because OPC Driver is stopped and started,
BeforeStart and AfterStop events are generated. When connection is lost, all related tags will
be disconnected from their current state (bad/quality/null value). Example:
Sub OPCDriver1_AfterStart()
Application.GetObject("OPCDriver1.OPCGroup1")._
ReconnectPeriod = 0
End Sub

5.4.2.2.3 ServerId

Determines the server that OPC Driver connects to. This property can be modified only
when OPC Driver is not connected. If the property's field is blank, OPC object will not connect.
Default value is empty. Example:
Sub OPCDriver1_AfterStart()
MsgBox _
Application.GetObject("OPCDriver1.OPCGroup1").ServerID
End Sub

5.4.2.2.4 ServerMachine

Determines the address of the station where the OPC server is running. For applications
running locally, this property may remain blank. Otherwise, it is necessary to specify the path.
This property can only be modified when OPC driver is disconnected. Default value is empty.
Example:

366 Server Objec ts

 Sub OPCDriver1_AfterStart()
MsgBox Application._
GetObject("OPCDriver1.OPCGroup1").ServerMachine
End Sub

5.4.2.2.5 ServerName

Returns the OPC server name and description. This property is different from ServerID,
which is a code. Example:
Sub OPCDriver1_AfterStart()
MsgBox _
Application.GetObject("OPCDriver1.OPCGroup1").ServerName
End Sub

5.4.2.2.6 ServerStatus

Determines the status of the connection to the OPC server. The available options are the
following:

Available options for ServerStatus

OPTION DESCRIPTION
-1 - ServerStatus_Unknown OPC Driver is connected to the server but
either status is not informed or OPC client
has ReconnectPeriod property set to 0.

0 - ServerStatus_NoConnected OPC Driver is not connected to an OPC Server.

This happens when, for example, OPC driver
is not active, or connection has not been
established yet for any reason.

The following values are only informed when ReconnectPeriod property is different from 0. At
each non-specified period of time, the status is fetched from the server. In case it is not
correctly informed, the property can maintain this value equal to -1, or the disconnection can
be detected, which brings the status to 0. Values are based on the five default status types
defined for OPC servers.

Available options for ReconnectPeriod different from zero

OPTION DESCRIPTION
1 - ServerStatus_Running The server is running normally.

2 - ServerStatus_Failed The server is not running. A unspecified error

occurred on the server.

3 - ServerStatus_NoConfig The server is running, but without

configuration information.

4 - ServerStatus_Suspended The server was temporarily suspended.

Server Objec ts 367

 OPTION DESCRIPTION
5 - ServerStatus_Test The server is in Test Mode.

Example:
Sub CommandButton1_Click()
Dim status
status = Application.GetObject("DriverOPC1").ServerStatus
MsgBox "Driver status is " & status
Select Case status
Case -1
MsgBox "OPC Driver is connected to the OPC Server_
but its status was not informed."
Case 0
MsgBox "OPC Driver is not connected to an OPC Server."
Case 1
MsgBox "The OPC Server is running normally."
Case 2
MsgBox "The OPC Server is not running."
Case 3
MsgBox "The OPC Server is running with no configuration_
information."
Case 4
MsgBox "The OPC Server has been temporarily suspended."
Case 5
MsgBox "The OPC Server is running in Test Mode."
End Select
End Sub

NOTE: If you want this property to behave as if it were a Boolean, use ServerStatus different
from 0. This causes the property to differentiate only between the existence or not of a
connection, not considering more specific status from the server. Besides, the expression
will not depend on ReconnectPeriod different from 0.

5.4.2.2.7 WriteFeedbackMode

This property allows controlling feedback from tag writings. The configuration options of
this property are described in the following table.

Available options for the WriteFeedbackMode property

OPTION DESCRIPTION
0 - wfWaitNextRead After the writing, waits normally for the next
reading.

1 - wfImmediateReadAfterWrite Forces an asynchronous device reading right

after each writing.

2 - wfTrustWriteSuccess The written value is assumed by the tag

immediately, if the writing succeeded.

368 Server Objec ts

The default value of this property is 0 - wfWaitNextRead for applications created before the
implementation of this property, and 1 - wfImmediateReadAfterWrite for applications created
after its implementation.

NOTES:
· The WriteFeedbackMode property of the OPC Driver cannot be changed when the object is
active
· In the 2 - wfTrustWriteSuccess option, in case of asynchronous writings, the value is
assumed in the tag right after scheduling the writing, if the operation succeeded.
However, if the writing fails after, the value in the tag may be incorrect. In case of
synchronous writings, this value is assumed right after the writing finishes, if succeeded
· See also the WriteFeedbackMode property of the I/O Driver, which has a similar behavior

5.4.2.3 OPC Group

This section contains information about methods and properties of the OPC Group object. This
object does not contain methods associated to it.

5.4.2.3.1 Methods

This section contains information about the methods of the OPC Group object.

5.4.2.3.1.1 Refresh
Refresh(Source)

Forces the server to resend values from all Group Tags which have reading enabled, whether
they have changed their values or not. The Source parameter determines the driver data
source argument. If the informed value is 1 (RefreshFromCache), sent values are the server
cache values. Otherwise, if the informed value is 2 (RefreshFromDevice), values are updated in
the server cache before sending. To make sure this method works, The Enable property of the
Group, as well as at least one Group Tag reading, must be enabled. For further information on
this enabling mechanism (Advise mode), see the AllowRead and AdviseType properties.

5.4.2.3.2 Properties

This section contains information about the properties of the OPC Group object.

Server Objec ts 369

5.4.2.3.2.1 BlockMode

Determines the activating or deactivating behavior of the OPC Group. If True, OPC Tags
communication in the Group starts at once, right after activating all Tags in the Group. This
improves performance, because it minimizes the number of callings to the OPC Driver.
Otherwise, OPC Tags communication starts individually, according to the normal activation
sequence of the objects. So the first Tag in the Group (as seen in the Organizer) communicates
before the last one. Although slower, this block mode activation can be useful when you need
to perform an operation in the OnStartRunning event of the Tag. The deactivation occurs in an
analog way. When the value of the property is True, the deactivation of the Group Tag
communication occurs at once, when finishing the deactivation of the whole OPC Group. In
case the property is configured to False, deactivation occurs individually for each Tag
(according to the normal activation sequence of the objects).

5.4.2.3.2.2 DeadBand

Allows adjusting the minimum variation level of an OPC Tag, so it can be updated. This
property only applies to Group Tags which are considered of type analog by the OPC Server to
which the OPC Driver is connected. The valid interval for this property is from 0 to 100 percent.
When the DeadBand property is 0, it means that any variation in the value of a Group Tag
implies in updating this Group. This percentage applies to each Tag according to their
engineering limits (defined in the OPC Server). To update a tag, the following expression must
be True (according to OPC Server):
Abs(Previously_saved_value – Current_value) > (DeadBand / 100) * Abs(Upper_limit –
Lower_limit)

The default value of this property is 0.

5.4.2.3.2.3 Enable

Enables Tag updating inside an OPC Group. If this property is False, no Tag inside the OPC
Group is updated. Otherwise, Tags with the AllowRead property set to True, and in Advise
mode (for more information, see the AdviseType property), are kept updated according to the
updating time (the Scan property) and dead band (the DeadBand property) of the Group. If this
property is False, it is not possible to use the Refresh method of the Group.

5.4.2.3.2.4 RealScan

Scan time effectively used by the OPC server.

5.4.2.3.2.5 Scan

Specifies the duration of the scan used by the server to update Group Tags used by the
server. This property is represented in milliseconds, and can be modified after communication
has started. It is used only when the Enable property is set to True.

When you set this property in several Tags in the application, you should increase the value of

370 Server Objec ts

the property to those Group Tags that do not vary very much in the device, enabling other Tags
with higher priority to be read more frequently, thus enhancing general system performance.
The default value of this property is 1000.

5.4.2.3.3 OPC Block

This section contains information about the OPC Block object. This object does not contain
events nor methods associated to it.

5.4.2.3.3.1 Methods

This section contains information about the methods of the OPC Block object.

Write
Write()

Writes the current value of the OPC Block in the device. For further information, see the Driver
documentation. This method returns a Boolean indicating whether the operation has been
successful or not.

WriteEx
WriteEx([Value, ][SyncWrite])

Writes a value in the device. All parameters are optional. If omitted, the behavior of this
method is the same as the Write method. This method returns a Boolean indicating if the
operation was successful or not. The Value parameter defines the value to be written on the
Driver. The datatype depends on the Driver. If omitted, assumes the current Block value. The
SyncWrite parameter is a Boolean specifying if this operation must be synchronous (True) or
asynchronous (False). If omitted, uses the value specified in the SyncWrite property of the
Block.

NOTE: Just like the Write method, the writing is performed independent of the value being
different from the current Block value, as well as independent of the AllowWrite property of
the Block being True or False. Besides, if the writing works but the Block is not in scan (if its
AllowRead property is False, or because it is using the AdviseWhenLinked option when it is
not linked), the written value immediately assumes a good quality and the timestamp of the
moment of writing.

5.4.2.3.3.2 Properties

This section contains information about the properties of the OPC Block object.

Server Objec ts 371

AdviseType
Controls the Advise mode. The available options are:

Available options for AdviseType

OPTION DESCRIPTION
0 - AlwaysInAdvise The tag is updated if the AllowRead property
of the OPC Block is True and the Enable
property of the OPC Group is also True.

1 - AdviseWhenLinked The tag is updated only if the AllowRead

property is True and the tag is associated to
an active object (that is, one Display in an
open Screen, an enabled Alarm, etc.). A tag
link for this purpose can be assigned to these
properties: Value, RawValue, Quality and
from Bit00 to Bit31 for OPC Block Elements,
and Quality and TimeStamp for OPC Blocks.

Example:
Sub CommandButton3_Click()
MsgBox Application._
GetObject("OPCDriver.OPCGroup.SCRIPT1").AdviseType
End Sub

AllowRead
Defines whether the block will be read by the OPC driver. If True, the driver automatically
updates Value and Bits (from Bit00 to Bit31) properties from OPC Block Element, in time spans.
Otherwise, the OPC block will not be read if the AllowRead property is set to False. This
property can be modified at run time. Default value is True. Example:
Sub Button1_Click()
' Stops tag reading
Set obj = Application.GetObject("Driver1.tag")
obj.AllowRead = False
End Sub

AllowWrite
Configure this property to define whether this tag must be automatically written when the
Value property or any bit property (from Bit00 to Bit31) is modified. If the property is True, the
changes will be sent to the device or equipment linked to the OPC Driver, otherwise the
changes will be ignored. If this property is configured to True, the driver will automatically
update Value and bits (from Bit00 to Bit31) properties of this object, in time spans. Otherwise,
this OPC Block will not be read. The default value of this property is True. Example:
Sub Button1_Click()
Set obj = Application.GetObject("Driver1.tag")
obj.AllowWrite = False
End Sub

372 Server Objec ts

DataType
Read-only property. Determines datatype associated to this OPC Block (see the next
table).

Available options for DataType

OPTION DESCRIPTION
0 - _Undefined Undefined value (Empty).

1 - _Null Null value.

2 - _Integer 16-bit signed integer value.

3 - _Long 32-bit signed integer value.

4 - _Single 32-bit floating point value.

5 - _Double 64-bit floating point value.

6 - _Currency Currency value with four decimal places.

7 - _Date Date/time value.

8 - _String Literal value (String).

9 - _Object Generic object value.

10 - _Error Error code value.

11 - _Boolean Boolean value (true or false).

12 - _Variant Data of any type used for objects and other

values to which the datatype is unknown.

13 - _UnkObject Object reference value.

14 - _Decimal 96-bit floating point value.

36 - _Record Recording value.

16 - _Char 8-bit integer value.

17 - _Byte Used to create DLLs and OLE. Uses one byte

in memory.

18 - _Word 16-bit integer value.

19 - _Dword 32-bit integer value.

20 - _LongLong 64-bit signed integer value.

Server Objec ts 373

 OPTION DESCRIPTION
21 - _DDWord 64-bit integer value.

22 - _Integer_ Integer number, ranges from -32.768 to

32.767. Uses two bytes.

23 - _Uinteger Unsigned integer value (equivalent to a

DWORD), ranges from 0 to 4294967295 (2 32 -
1).

8194 - _ArrInteger Array of integer values.

8195 - _ArrLong Array of 32-bit signed integer values.

8196 - _ArrSingle Array of 32-bit floating point values.

8197 - _ArrDouble Array of 64-bit floating point values.

8198 - _ArrCurrency Array of currency values with four decimal

places.

8199 - _ArrDate Array of date/time values.

8200 - _ArrString Array of literal values (strings).

8201 - _ArrObject Array of reference object values.

8202 - _ArrError Array of error code values.

8203 - _ArrBoolean Array of boolean values (true or false).

8204 - _ArrVariant Array of any datatypes used for objects and

other values to which the datatype is
unknown.

8205 - _ArrUnkObject Array of reference object values.

8206 - _ArrDecimal Array of 96-bit floating point values.

8228 - _ArrRecord Array of record values.

8208 - _ArrChar Array of char values.

8209 - _ArrByte Array of byte values, which are values used to

create DLLs and OLE. Uses one byte in
memory.

8210 - _ArrWord Array of 32-bit integer values.

8211 - _ArrDWord Array of 32-bit integer values.

374 Server Objec ts

 OPTION DESCRIPTION
8212 - _ArrLongLong Array of 16-bit integer values.

8213 - _ArrDDWord Array of 32-bit signed integer values.

8214 - _ArrInteger_ Arrayof 16-bit signed integer values.

8215 - _ArrUInteger Array of unsigned integer values (equivalent

to a DWORD), ranges from 0 to 4294967295
(2 32 - 1).

EnableDriverEvent
This property is used to control generation of the OnTagRead event, which occurs in the OPC
Driver that contains the block. If the EnableDriverEvent property of the tag is set to True, on
each reading that comes from the OPC server, with error or not, the OnTagRead event is
generated on the OPC Driver which contains this block. Otherwise, the event does not occur.
Also, when the EnableDriverEvent property is True, on each writing sent to the OPC server, an
OnTagWrite event is generated in the OPC Driver which contains the tag. If this writing is
asynchronous, the OnTagWrite event is generated only when the server sends an answer
indicating whether the writing is successful or not. In this case, the event is only generated if
the EnableDriverEvent property is true at that moment, and not at the moment of sending the
writing. The default value of this property is False.

ItemID
Determines the path identifying the OPC block on the server to which the OPC Driver is
connected to. Path definition is flexible, and depends on the specific server. Usually, servers
specify an ID space with hierarchical items, such as ParentItem.ChildItem.Tag1. ItemID works
as a unique key for data, considering the location or the method which allows the OPC server
to connect to the data source. Although the default value is empty, it is necessary to specify
some value for the OPC block to be valid. Example:
Sub OPCBlock1_OnStartRunning()
MsgBox ItemID
End Sub

Quality
Informs the quality of the value contained in the Value property. Each time the Driver
attributes a new value to the Block it also sets its data quality. This property is read-only.
Default value is 0 (Bad Quality).

NOTE: For further information on quality, see the topic Quality on User's Manual.

Size
Defines the size of the value cluster in this block. See the driver documentation for this
property's limits according to B1 to B4 parameters. By creating elements for the block, it
allows both accessing reading values and writing values for the device. This property cannot
be modified once communication has started. Default value is 0. Example:
Sub OPCBlock1_OnStartRunning()
Size = 12
End Sub

Server Objec ts 375

SyncWrite
Determines the type of writing used by an OPC Block. If True, writing is synchronous, that is,
the OPC Driver waits for the writing result from the server. Otherwise, writing is asynchronous,
that is, OPC Tag value will be sent and OPC Driver processing will continue immediately.
Default value is False.

NOTE: In asynchronous mode (False), the quality of communication performance tends to be

higher. However, in synchronous mode (True), writing operation success is verified and
informed.

TimeStamp

Updated whenever there is a change in value or status in either Value or Quality

properties. Informs timestamp associated to both value and quality in an OPC Block. This is a
read-only property. Default value is 00:00:00.

5.4.2.3.3.3 OPC Block Element

This section contains information about the OPC Block Element object. This object does not
contain events nor methods associated to it.

Properties
This section contains information about the properties of the OPC Block Element object.

Bit00 to Bit31
These properties represent the 32 bits in OPC Block Element Value property, ranging from
Bit00 (the least significant bit) to Bit31 (the most significant bit). By modifying each one of
these bits you will modify tag's Value property, and vice-versa, but this only happens when
UseBitFields property is True. Default value is False.

NOTE: Bit values (from Bit00 to Bit31 properties) are not affected by the adjustment in scale.
That is, they represent the bits from the value read by the equipment before the conversion.

DeviceHigh
Defines the highest value achieved by this element in the device. Adjusts the value scale
from the device before being attributed to Value property. Likewise, the inverse operation is
done before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

376 Server Objec ts

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

DeviceLow
Defines the lowest value achieved by this element in the device. Adjusts the value scale
from the device before being attributed to Value property. Likewise, the inverse operation is
done before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 0. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

EnableScaling
If True, all values from the device will receive scale adjustments according to DeviceHigh,
DeviceLow, EUHigh, and EULow properties before they are attributed to Value property.
Otherwise, no adjustment in scale will be made. Default value is False. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

EU
Identifies the engineering unit represented by the value, such as degrees, meters, etc.
Example:
Sub Element_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

EUHigh
Defines the highest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is

Server Objec ts 377

True. The default value of this property is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

EULow
Defines the lowest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 0. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

Index
Specifies this element's position among the other elements configured by Size property of
the OPC block where it is inserted. This property's value range from 0 to the value defined by
Size minus 1. (For example: If Size is 20, Index ranges from 0 to 19). This property can be
modified once communication has started. Default value is 0, but when mapping the elements
from a block, E3 Studio automatically adjusts Index parameter to the specified value. Example:
Sub Element1_OnRead()
MsgBox Index
End Sub

Quality
Represents value quality status. E3 uses OPC pattern to inform this property. The field is
formed by a 16-bit word, and the 8 first bits are defined in three bit fields: Quality, Substatus,
and Limit, arranged like this: QQSSSSLL. Quality can be: bad, uncertain, or good (see the
following table). Substatus contains additional information about Quality. Limit indicates
diagnosis information. Servers that cannot support these types of information return 0 in the
corresponding bits.

The other 8 bits (of a higher order) are available for use from each manufacturer. If those bits

378 Server Objec ts

are used, default quality bits are still used to indicate which deductions can be made over the
returned data. So, it is the client's responsibility to interpret the specific quality information
field to make sure the server providing this information uses the same rules as the client.

OPC drivers or servers that do not support quality information always return 192 value (good
quality). It is also acceptable for a server to simply return bad (0) or good (192) quality, and not
to pass out any substatus or limit information in bits.

A list with possible values for Quality, as well as their meaning, can be seen in the following
tables.

Value ranges for Quality

RANGE QUALITY DESCRIPTION

0 - 63 BAD Value cannot be used for the
reasons indicated in
substatus.

64 - 127 UNCERTAIN Value quality is uncertain for

the reasons indicated in
substatus.

128 - 191 (Reserved) Not used in OPC standard.

192 - 255 GOOD Value quality is good.

Possible options for Limit

LIMIT DESCRIPTION
No Limit The value is free to move up or down.

Low The value is limited in some lower value.

High The value is limited in some higher value.

Constant The value is a constant and cannot move.

Server Objec ts 379

 Substatus for Bad Quality (0 - 63)

SUBSTATUS DESCRIPTION LIMITS

NOT
LIMITE LOW HIGH CONSTANT
D
Not specific The value is bad, but 000 001 002 003
no specific reason is
known.

Configuration error There is some server 004 005 006 007

specific problem with
the configuration. For
example, the item is
question has been
deleted from the
configuration.

Not connected The input is required 008 009 010 011

to be logically
connected to
something but it is
not. This quality may
reflect that no value
is available at this
time, for reasons like
the value may have
not been provided by
the data source.

Device failure A device failure has 012 013 014 015

been detected.

Sensor failure A sensor failure has 016 017 018 019

been detected (Limit
field may provide
additional
information).

Last known value Communication have 020 021 022 023

failed. However, the
last known value is
available. Note that
the age of the value
may be determined
by the TIMESTAMP in
the OPCITEMSTATE.

380 Server Objec ts

 SUBSTATUS DESCRIPTION LIMITS
NOT
LIMITE LOW HIGH CONSTANT
D
Communication Communication have 024 025 026 027
failure failed. There is no last
known value
available.

Out of service The block is off scan 028 029 030 031
or otherwise locked.
This quality is also
used when the active
state of the item or
the group containing
the item is inactive.

Not available Not used by OPC. 032 - 063

Substatus for Uncertain Quality (64 - 127)

SUBSTATUS DESCRIPTION LIMITS

NOT
LOW HIGH CONSTANT
LIMITED
Not specific There is no specific reason 064 065 066 067
why the value is uncertain.

Last used value Whatever was writing this 068 069 070 071
value has stopped doing so.
The returned value should
be regarded as stale. Note
that this differs from a BAD
value with Substatus 5 (Last
Known Value). That status is
associated specifically with
a detectable
communications error on a
fetched value. This error is
associated with a failure of
some external source to put
something into the value
within an acceptable period
of time. Note that the age of
the value can be determined
by the TIMESTAMP in
OPCITEMSTATE.

Not available Not used by OPC. 072 - 079

Server Objec ts 381

 SUBSTATUS DESCRIPTION LIMITS
NOT
LOW HIGH CONSTANT
LIMITED
Sensor not Either the value is limited at 080 081 082 083
accurate one of the sensor limits (in
which case the limit field
should be set to 1 or 2) or the
sensor is otherwise known
to be out of calibration via
some form of internal
diagnostics (in which case
the Limit field should be 0).

Engineering The returned value is 084 085 086 087

unit exceeded outside the limits defined for
this parameter. Note that in
this case the Limits field
indicates which limit has
been exceeded but does NOT
necessarily imply that the
value cannot move farther
out of range.

Sub-normal The value is derived from 088 089 090 091

multiple sources and has
less than the required
number of Good sources.

Not available Not used by OPC. 092 - 127

Substatus for Good Quality (192 - 255)

SUBSTATUS DESCRIPTION LIMIT

C
O
HN
IS
NOT LIMITED LOW
GT
HA
N
T
Not specific The value is good. There are no special 192 193 1
conditions. 9
45

Not used Not used by OPC. 196 - 215

382 Server Objec ts

 SUBSTATUS DESCRIPTION LIMIT
C
O
HN
IS
NOT LIMITED LOW
GT
HA
N
T
Local override The value has been overridden. Typically 216 217 2
this means the input has been 1
disconnected and a manually entered 89
value has been forced.

Not available Not used by OPC. 220 - 255

RawValue
It is the element's original value, before EnableScaling property has acted upon it. So, if
EnableScaling is False, Value and RawValue property will behave identically.

UseBitFields
If True, every time the value from Value property is modified, the bits referring from Bit00 to
Bit31 properties will be updated. Also, every time the value from Bit00 to Bit31 properties are
modified, the value from Value property is updated and sent to the device, if AllowWrite
property is True. Otherwise, bits will not undergo any modification. This property can be
updated once communication has started. Default value is False.

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

Value
Updated whenever a new value is read at OPC Server, according to the specifications of the
ItemID property of the OPC block where this element is inserted, and taking into consideration
the Index property (which specifies element position in OPC Server). Property's datatype
(integer, floating point, string, etc.) depends on the driver to which the element is associated
and its parameters.

This property is updated like this if OPC Block's AllowRead property is True, and according to
scan time defined in the Scan property of the OPC Block that contains the element. If OPC
Block's AllowWrite property is True, you can write values in the device simply by attributing a
new value to Value property.

This is also OPC Block Element's default property. So, it is not mandatory for a value reference
to an OPC Block Element to make Value property explicit in order to access its value. In case
the property is not updated, check if Index property is correctly set (its value must be zero up
to OPC block's size minus one). Example:

Server Objec ts 383

 Sub Button1_Click()
' Accesses an element and shows current value
' elm1 is an OPC Block Element object
Set obj = Application.GetObject("OPCDriver1.Group1.OPCBlock1.elm1")
MsgBox "Elm1's current value: " & obj.Value
'This can also be done in a different way,
'with no need to show Value property, which is default
MsgBox "Elm1's current value: " & obj
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before the conversion.

5.4.2.3.4 OPC Tag

This section contains information about events and properties of the OPC Tag object. This
object does not contain methods associated to it.

5.4.2.3.4.1 Methods

This section contains information about the methods of the OPC Tag object.

Write
Write()

Writes the current value of the OPC Tag in the device. For further information, see the Driver
documentation. This method returns a Boolean indicating whether the operation has been
successful or not.

WriteEx
WriteEx([Value, ][SyncWrite])

Writes a value in the device. All parameters are optional. If omitted, the behavior of this
method is the same as the Write method. This method returns a Boolean indicating if the
operation was successful or not. The Value parameter defines the value to be written on the
Driver. The datatype depends on the Driver. If omitted, assumes the current Tag value. The
SyncWrite parameter is a Boolean specifying if this operation must be synchronous (True) or
asynchronous (False). If omitted, uses the value specified in the Tag's SyncWrite property.

NOTE: Just like the Write method, the writing is performed independent of the value being
different from the current Tag value, as well as independent of the AllowWrite property of
the Tag being True or False. Besides, if the writing works but the Tag is not in scan (if its
AllowRead property is False, or because it is using the AdviseWhenLinked option when it is
not linked), the written value immediately assumes a good quality and the timestamp of the
moment of writing.

384 Server Objec ts

5.4.2.3.4.2 Properties

This section contains information about the properties of the OPC Tag object.

AdviseType
Controls the Advise mode. The available options are:

Available options for AdviseType

OPTION DESCRIPTION
0 - AlwaysInAdvise The tag is kept updated if AllowRead property
is equal to True and the Enable property of
the OPC Group is also set to True.

1 - AdviseWhenLinked The tag is updated only if AllowRead is True,

the Enabled property of the OPC Group is set
to True and the tag is associated to an active
object (that is, one Display in an open Screen,
an enabled Alarm, etc.). A tag link for this
purpose can be done on the following
properties: Value, RawValue, TimeStamp,
Quality and from Bit00 to Bit31 of OPC Tags.

Example:
Sub CommandButton3_Click()
MsgBox Application._
GetObject("OPCDriver.OPCGroup.OPCTag1").AdviseType
End Sub

AllowRead
Defines whether the Tag will be read by the OPC driver. If True, the driver automatically
updates Value and Bits (from Bit00 to Bit31) properties from this object, in time spans.
Otherwise, this Tag will neither be read nor updated. This property can be modified at run
time. Default value is True. Example:
Sub CommandButton1_Click()
' Stops tag reading
Set obj = Application.GetObject("Driver1.tag")
obj.AllowRead = False
End Sub

AllowWrite
Defines whether the tag will be written automatically when Value or Bits (from Bit00 to
Bit31) properties are modified. If True, the modifications will be sent to the device associated
to the OPC driver. Otherwise, these modifications will be ignored. Default value is True.
Example:
Sub Button1_Click()
' Disables tag writing
Set obj = Application.GetObject("Driver1.tag")
obj.AllowWrite = False
End Sub

Server Objec ts 385

Bit00 to Bit31
These properties represent the 32 bits in OPC Tag Value property, ranging from Bit00 (the
least significant bit) to Bit31 (the most significant bit). By modifying each one of these bits you
will modify Tag's Value property, and vice-versa, but this only happens when UseBitFields
property is True. Default value is False.

NOTE: Bit values (from Bit00 to Bit31 properties) are not affected by the adjustment in scale.
That is, they represent the bits from the value read by the equipment before conversion.

DataType
Read-only property. Determines datatype associated to this OPC Tag (see the next table).

Available options for DataType

OPTION DESCRIPTION
0 - _Undefined Undefined value (Empty).

1 - _Null Null value.

2 - _Integer 16-bit signed integer value.

3 - _Long 32-bit signed integer value.

4 - _Single 32-bit floating point value.

5 - _Double 64-bit floating point value.

6 - _Currency Currency value with four decimal places.

7 - _Date Date and time value.

8 - _String Literal value (String).

9 - _Object Generic object value.

10 - _Error Error code value.

11 - _Boolean Boolean value (True or False).

12 - _Variant Data of any type used for objects and other

values to which the datatype is unknown.

13 - _UnkObject Object reference value.

14 - _Decimal 96-bit floating point value.

36 - _Record Recording value.

386 Server Objec ts

 OPTION DESCRIPTION
16 - _Char 8-bit integer value.

17 - _Byte Used to create DLLs and OLE. Uses one byte

in memory.

18 - _Word 16-bit integer value.

19 - _Dword 32-bit integer value.

20 - _LongLong 64-bit signed integer value.

21 - _DDWord 64-bit integer value.

22 - _Integer_ Integer number, ranges from -32.768 to

32.767. Uses two bytes.

23 - _Uinteger Unsigned integer value (equivalent to a

DWord), ranges from 0 to 4294967295 (2 32 -
1).

8194 - _ArrInteger Array of integer values.

8195 - _ArrLong Array of 32-bit signed integer values.

8196 - _ArrSingle Array of 32-bit floating point values.

8197 - _ArrDouble Array of 64-bit floating point values.

8198 - _ArrCurrency Array of currency values with four decimal

places.

8199 - _ArrDate Array of date/time values.

8200 - _ArrString Array of literal values (strings).

8201 - _ArrObject Array of reference object values.

8202 - _ArrError Array of error code values.

8203 - _ArrBoolean Array of boolean values (True or False).

8204 - _ArrVariant Array of any datatypes used for objects and

other values to which the datatype is
unknown.

8205 - _ArrUnkObject Array of reference object values.

8206 - _ArrDecimal Array of 96-bit floating point values.

Server Objec ts 387

 OPTION DESCRIPTION
8228 - _ArrRecord Array of record values.

8208 - _ArrChar Array of char values.

8209 - _ArrByte Array of byte values, which are values used to

create DLLs and OLE. Uses one byte in
memory.

8210 - _ArrWord Array of 32-bit integer values.

8211 - _ArrDWord Array of 32-bit integer values.

8212 - _ArrLongLong Array of 16-bit integer values.

8213 - _ArrDDWord Array of 32-bit signed integer values.

8214 - _ArrInteger_ Arrayof 16-bit signed integer values.

8215 - _ArrUInteger Array of unsigned integer values (equivalent

to a DWord), ranges from 0 to 4294967295 (2
32
- 1).

DeviceHigh
Defines the highest value achieved by this tag in the device. Adjusts the value scale from the
device before being attributed to Value property. Likewise, the inverse operation is done
before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before conversion.

DeviceLow
Defines the lowest value achieved by this tag in the device. Adjusts the value scale from
the device before being attributed to Value property. Likewise, the inverse operation is done
before sending the value to the driver, when writing. This conversion happens only when
EnableScaling property is True. Default value is 0. Example:

388 Server Objec ts

 Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before conversion.

EnableDriverEvent
This property is used to control generation of the OnTagRead event, which occurs in the OPC
Driver that contains the tag. If the EnableDriverEvent property of the tag is set to True, on each
reading that comes from the OPC server, with error or not, the OnTagRead event is generated
on the OPC Driver which contains this tag. Otherwise, the event does not occur. Also, when
the EnableDriverEvent property is True, on each writing sent to the OPC server, an OnTagWrite
event is generated in the OPC Driver which contains the tag. If this writing is asynchronous,
the OnTagWrite event is generated only when the server sends an answer indicating whether
the writing is successful or not. In this case, the event is only generated if the
EnableDriverEvent property is true at that moment, and not at the moment of sending the
writing. The default value of this property is False.

EnableScaling
If True, all values from the device will receive scale adjustments according to EUHigh and
EULow properties before they are attributed to Value property. Otherwise, no adjustment in
scale will be made. Default value is False. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

EU
Identifies the engineering unit represented by the value, such as degrees, meters, etc.
Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

Server Objec ts 389

EUHigh
Defines the highest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 1,000. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before conversion.

EULow
Defines the lowest value to be attributed to Value property, adjusting the scale to the value
from the device before it is done. Likewise, the inverse operation is done before sending the
value to the driver, when writing. This conversion happens only when EnableScaling property is
True. The default value of this property is 0. Example:
Sub Tag_OnStartRunning()
' Adjusts the scale of temperature
' ranging from 0 to 255 at PLC, but it actually means
' 0 to 100 Celsius degrees
EU = "Celsius degrees"
EnableScaling = True
DeviceHigh = 255
DeviceLow = 0
EUHigh = 100
EULow = 0
End Sub

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before conversion.

ItemID
Determines the path identifying OPC tag on the server, which the OPC Driver connects to.
Path definition is flexible, and depends on the specific server. Usually, servers specify an ID
space with hierarchical items, such as ParentItem.ChildItem.Tag1. ItemID works as a unique
key for data, considering the location or the method which allows the OPC server to connect to
the data source. Although default value is empty, it is necessary to specify some value for an
OPC block to be valid. Example:
Sub OPCTag1_Click()
MsgBox ItemID
End Sub

Quality
Informs the quality of the value contained in the Value property. Each time the Driver
attributes a new value to the Tag it also sets data quality. This property is read-only. Default
value is 0 (Bad Quality).

390 Server Objec ts

NOTE: For further information on quality, see the topic Quality on User's Manual.

RawValue
It is the element's original value, before EnableScaling property has acted upon it. So, if
EnableScaling is False, Value and RawValue properties will behave identically.

SyncWrite
Determines the type of writing used by an OPC tag. If True, writing is synchronous, that is,
OPC Driver waits for the writing result from the server. Otherwise, writing is asynchronous,
that is, OPCTag value will be sent and OPC Driver processing will continue immediately.
Default value is False.

NOTE: In asynchronous mode (False), the quality of communication performance tends to be

higher. However, in synchronous mode (True), writing operation success is verified and
informed.

TimeStamp

Updated whenever there is a change in value or status in either Value or Quality

properties. Informs timestamp associated to both value and quality in OPC tag. This is a read-
only property. Default value is 00:00:00.

UseBitFields
If True, every time the value from Value property is modified, the bits referring from Bit00 to
Bit31 properties will be updated. Also, every time the value from Bit00 to Bit31 properties are
modified, the value from Value property is updated and sent to the device, if AllowWrite
property is True. Otherwise, bits will not undergo any modification. This property can be
updated once communication has started. Default value is False.

NOTE: Bit values (Bit00 to Bit31 properties) are not affected by the adjustment in scale. That
is, they represent the bits from the value read by the equipment before conversion.

Value
This property is updated when a new valid reading of a value from the equipment or device
is done using its parameters. However, the type of this variable (integer, floating point, etc.)
depends on the OPC driver to which it is linked and its parameters. This property will only be
updated this way if the AllowRead property is set to True and there is no communication
errors (in this case only the Quality and TimeStamp properties are updated), but according to
the scan time defined on the group to which it belongs. Another way to use this property is to
write values on the device or equipment. It is enough to set a new value to the Value property
or some of the Bit00 to Bit31 bits, as long as the AllowWrite property is set to True. This
property is also the standard property of the OPC Tag object. Thus, a reference by value of an
OPC Tag object does not need to explicit the Value property in order to access its value. The
default value of this property is empty. Example:

Server Objec ts 391

 Sub Button1_Click()
' Accesses a tag and shows its current value
' tag1 is an OPCTag
Set obj = Application._
GetObject("CommDriver1.tag1")
MsgBox "Tag1's current value: " & obj.Value
' Does not show Value property, since it is default
MsgBox "Tag1's current value: " & obj
End Sub

5.5 Data Server

This section contains information about events, methods, and properties of the following
objects: Data Folder, Counter Tag, Demo Tag, Internal Tag, and Timer Tag.

5.5.1 Queries
This section contains information about the properties, events and methods of the Query
object.

5.5.1.1 Events
This section contains information about the events of the Query object.

5.5.1.1.1 OnAsyncQueryFinish
OnAsyncQueryFinish(Recordset, Error)

Occurs when the GetAsyncADORecordset method returns. The Recordset parameter is the ADO
recordset generated by the query, and the Error parameter is a Boolean that, when True,
indicates that the object could not be generated. Example:
Sub query1_OnAsyncQueryFinish(Recordset, Error)
MsgBox "Returned " + CStr(Recordset.RecordCount) + " records"
End Sub

5.5.1.2 Methods
This section contains information about the methods of the Query object.

5.5.1.2.1 AddField
AddField(Name[, Table])

The AddField method adds a new field to the table in the Query. The Name parameter
determines the name of the new field to be added to the Query. The Table parameter
represents the name of the table to which the field belongs. This method was developed just
to keep compatibility to E3Chart's old Query object. Example:
Sub Button1_Click()
Screen.Item("E3Browser").Item("Query").AddField "Field1"
End Sub

392 Server Objec ts

5.5.1.2.2 AddStorageTag
AddStorageTag(Name, FieldType)

Adds a Tag from the Storage to the Query. The Name parameter gets the name of the Tag to be
added. The FieldType parameter indicates the Tag type (0: Double, 1: Bit, 2: String, 3: Integer).
Returns a Boolean indicating whether the operation has been successful or not.

5.5.1.2.3 AddTable
AddTable(Name)

Adds a table from the database to the Query. The Name parameter determines the name of
the table to be added.

5.5.1.2.4 Execute
Execute(ImmediateExecute)

The Execute method executes a SQL command that does not have a return (such as DELETE,
UPDATE, or INSERT), configured in SQLQuery. The ImmediateExecute parameter indicates
whether the operation passes through database operation queues (e3i and e3o files) before it
reaches the database (if False), or it is sent directly to the database (if True). The advantage of
using a Query to execute commands is using variables, such as in a simple query.

Example of SQL commands:

DELETE FROM test WHERE cod > 10
UPDATE test SET cod = 10 WHERE cod > 10
INSERT INTO test (cod) VALUES(10)

Example:
Sub CommandButton1_Click()
Screen.Item("Query1").Execute
End Sub

5.5.1.2.5 GetADORecordSet
GetADORecordSet()

The GetADORecordSet method returns a Recordset of ADO (ActiveX Data Object) type as the
result of executing the configured query. Example:
Sub Button1_Click()
Set rec = Screen.Item("Query1").GetADORecordset()
strDates = " "
i = 0
' Displays a message with the first 10 records
' of the E3TimeStamp column
While (NOT rec.EOF AND i < 10)
strDates = strDates & CStr(rec("E3TimeStamp")) & _
Chr(10) & Chr(13)
i = i + 1
rec.MoveNext()
Wend
MsgBox strDates
End Sub

Server Objec ts 393

NOTE: For more information about the ADORecordset object returned by this method, please
check Microsoft documentation on http://msdn.microsoft.com/en-us/library/ms675841
(VS.85).aspx.

5.5.1.2.6 GetAsyncADORecordSet
GetAsyncADORecordSet()

Creates a Query and, when it finishes, generates the object's OnAsyncQueryFinish event,
passing the recordset generated by the Query to this event.

5.5.1.2.7 GetE3QueryFields
GetE3QueryFields()

GetE3QueryFields method returns a collection of the Query fields. The fields have properties
that can be modified, as follows:

Query fields properties

Name Type Description

ColumnName Text Column name. This name
must exist in the tables
added to the Query.

TableName Text Associated table name. The

table should be added in the
Query settings.

Alias Text Alias of the column in the

Query.

Criteria Text Query criteria on the column.

OrderBy Text Column sorting. The valid

values are "ASC" (ascending
sort order),
"DESC" (descending sort
order) and "" (none). Any
other value indicates that the
column has no sorting order.

394 Server Objec ts

 Name Type Description
OrderNumber Number Column order number in the
query order. Values must be
greater than 0 (zero) if the
column has a sorting order.
The value is equal or less
than the total of query sorting
order fields.

Function Text Function to which the column

can be passed as a
parameter.

GroupBy Boolean If True, the column is an

element of a group.

Visible Boolean If True, the column is visible.

NOTE: To use this method, the Query must be previously created at design time.

5.5.1.2.8 RemoveField
RemoveField(FieldName[, Table])

The RemoveField method removes a field previously included in a Query. The FieldName
parameter determines the name of the field to be removed from Query. The Table parameter
represents the name of the table to which the field belongs. This method was developed just
to keep compatibility to E3Chart's old Query object. Example:
Sub CommandButton1_Click()
Screen.Item("E3Browser").Item("Query").RemoveField "Field1"
End Sub

5.5.1.2.9 RemoveStorageTag
RemoveStorageTag(Name)

Removes a tag previously configured in the Query. The Name parameter indicates the tag
name. Returns a Boolean indicating whether the operation has been successful or not.

5.5.1.2.10 RemoveTable
RemoveStorageTag(Name)

Removes a tag previously configured in the Query. The Name parameter indicates the tag
name. Returns a Boolean indicating whether the operation has been successful or not.

Server Objec ts 395

5.5.1.2.11 SetVariableValue
SetVariableValue(VarName, Value)

The SetVariableValue method adjusts the value of a variable setup in the Query, so that this
value can be informed as a filter or parameter before being performed. It must be defined the
variable name (VarName) and the value (Value), which can be a number, a text or a date/time.
Example:
Sub CommandButton_Click()
Set cons = Screen.Item("E3Browser1").Item("Query1")
InitialDate = now - 1
FinalDate = now
cons.SetVariableValue "IniDate", InitialDate
cons.SetVariableValue "EndDate", FinalDate
End Sub

5.5.1.3 Properties
This section contains information about the properties of the Query object.

NOTE: It is not advisable accessing these properties directly via scripts. You should access
the Query object, passing parameters through SetVariableValue method and modifying filters
or fields through the collection returned by the GetE3QueryFields method.

5.5.1.3.1 CursorLocation

Defines where the Query is generated and handled, from a DBMS (Database Management
System) point of view. The available options are:

· 0 - clServer: the Query is generated on the DBMS (server).

· 1 - clClient: the Query is generated on E3 Server (client).

The default value of this property is 1 - clClient. See also the CursorType property.

NOTE: This property has no effect for Databases where the SourceType property is equal to 0 -
stAccess, because in this case E3 Server always generates and handles the Query. However,
for SourceType equal to 1 - stOracle or 2 - stSqlServer, it is advisable to use the option 1 -
clClient. For more information, check the documentation of the CursorLocation property and
the CursorLocationEnum enumeration of the ADO (ActiveX Data Object) object.

396 Server Objec ts

5.5.1.3.2 CursorType

Defines the type of Query according to data view. The available options are:

Available options for CursorType

OPTION DESCRIPTION
0 - ctKeyset Any change in records initially returned by
the Query is viewed (Default).

1 - ctStatic No change in records initially returned by the

Query is viewed.

2 - ctDynamic All new records added to the Query are

viewed, besides the changes in records
initially returned by the Query.

5.5.1.3.3 DataSource

Indicates the Database or Storage object that is used in the Query. This is a read-only
property, but it can be modified at run time.

5.5.1.3.4 Fields

Text with the fields to be viewed in the Query, separated by commas. It corresponds to the
argument of the SELECT clause in Query's SQL code. When blank, it determines that the Query
must display all table fields. This is a read-only property, but it can be modified at run time.

5.5.1.3.5 FunctionSubType

Specifies the subtype of the function indicated in the FunctionType property. Only the
options 1 - ftArchivedValue, 2 - ftTagAttribute, and 6 - ftCalculatedData have subtype. For the
other functions, FunctionSubType assumes -1 - fsNoSubType. The following table shows the
possible property values according to the chosen function in the FunctionType property:

Subtypes for ArchivedValue function (FunctionType = 1)

SUBTYPE DESCRIPTION
0 - fsPreviousArchivedValue Value right before the informed TimeStamp.

1 - fsInterpolatedArchivedValue Calculated value based of previous and next

values.

2 - fsNextArchivedValue Value right after the informed TimeStamp.

Server Objec ts 397

 SUBTYPE DESCRIPTION
3 - fsExactArchivedValue If a value is found at the exact informed
TimeStamp.

Subtypes for TagAttribute function (FunctionType = 2)

SUBTYPE DESCRIPTION
0 - fsTagAttributeDescription Tag meaning or description.

1 - fsTagAttributeSource Tag path.

2 - fsTagAttributeType Datatype: Double, Boolean, String.

3 - fsTagAttributeEU Engineering units.

4 - fsTagAttributeLowEng Lower limit.

5 - fsTagAttributeHighEng Upper limit.

6 - fsTagAttributeDeadBand Recording Dead Band.

7 - fsTagAttributeDeadBandUnit Dead Band unit (absolute or percentage).

8 - fsTagAttributeMinRecTime Minimum recording time (variations in

smaller intervals are not recorded).

9 - fsTagAttributeMaxRecTime Maximum recording time (the absence of

values at this interval forces a recording).

Subtypes for CalculatedData function (FunctionType = 6)

SUBTYPE DESCRIPTION
0 - fsTotalCalculatedData Total of values.

1 - fsMinimumCalculatedData Minimum value.

2 - fsMaximumCalculatedData Maximum value.

3 - fsStandardCalculatedData Standard deviation.

4 - fsRangeCalculatedData Range of values.

5 - fsMeanCalculatedData Mean of values.

398 Server Objec ts

 SUBTYPE DESCRIPTION
6 - fsMedianCalculatedData Median of values.

5.5.1.3.6 FunctionType

Specifies the function that defines Query data. Some functions have subfunctions that may
be indicated in FunctionSubType property. The FunctionType property is valid if a Storage
object is the source of the Query (it is indicated in the DataSource property). This property can
assume the following values:

Available options for FunctionType

OPTION DESCRIPTION
-1 - ftNoFunction There is no function defined.

0 - ftLastValue Returns the last value stored in Database.

1 - ftArchivedValue Returns a stored value relative to a

predefined time instant defined at the
TimeStamp variable. The relationship is
specified in the FunctionSubType property.

2 - ftTagAttribute Returns a Tag attribute, defined in the

FunctionSubType property.

3 - ftCompressedDataNValues Returns, for a single Tag, N values defined in

the variable NumVals, from an initial time,
defined in the variable StartTime.

4 - ftCompressedDataStartEndTime Returns, for a single Tag, the values at the

interval between the variables StartTime and
EndTime.

5 - ftSampledData Returns, for one or more tags, the

interpolated values (that is, estimated) at
the interval between the variables StartTime
and EndTime, in fixed intervals defined by the
variable TimeInterval.

6 - ftCalculatedData Returns, for one or more tags, the result of

the math operation (specified in the
FunctionSubType property) applied to data at
the interval between variables StartTime and
EndTime, in fixed intervals defined by the
variable TimeInterval.

Server Objec ts 399

NOTE: Variables can also be defined at run time through Query's SetVariableValue method.

5.5.1.3.7 GroupBy

Text corresponding to the argument of the GROUP BY clause in Query's SQL code. This is a
read-only property, but it can be modified at run time.

5.5.1.3.8 Having

Text corresponding to the argument of the HAVING clause in Query's SQL code. This property
is usually used with the GroupBy property. This is a read-only property, but it can be modified
at run time.

5.5.1.3.9 OrderBy

Text corresponding to the argument of the ORDER BY clause in Query's SQL code. This is a
read-only property, but it can be modified at run time.

5.5.1.3.10 SQL

Contains the SQL code specified for the Query. This is a read-only property, but it can be
modified at run time.

5.5.1.3.11 Table

Contains the tables to be queried (for example, Alarms is the alarms or events table). It
corresponds to the argument of the FROM clause in Query's SQL code. This is a read-only
property, but it can be modified at run time.

5.5.1.3.12 Where

Determines the Query condition that filters the table records to be viewed, that is, only the
records that meet this conditions are viewed. It corresponds to the WHERE argument in the
Query's SQL code. This is a read-only property, but it can be modified at run time.

5.5.2 Data Folder

The Data Folder object does not have specific events, methods, or properties, only general
ones. These can be viewed on section General Events, Methods, and Properties of Objects.

400 Server Objec ts

5.5.3 Counter Tag
This section contains information about events, methods, and properties of the Counter Tag
object. This object does not have methods associated to it.

5.5.3.1 Events
This section contains information about the events of the Counter Tag object.

5.5.3.1.1 OnPreset
OnPreset()

It occurs every time the Preset property value is reached.

5.5.3.2 Properties
This section contains information about the properties of the Counter Tag object.

5.5.3.2.1 AutoRestart

Indicates that the counting must restart from zero after it reaches the value established in
the Preset property. This property is only valid when the CounterType property is set to 0 -
Preset.

5.5.3.2.2 CounterType

Defines the behavior of the counter. The available values for this property are:

· 0 - Preset: the counting is stopped when the value set on the Preset property is reached

· 1 - Infinite: the counting goes on indefinitely

5.5.3.2.3 Enabled

Starts or stops the counter. If True, the counting is started, otherwise it is stopped.

5.5.3.2.4 Increment

Defines the update interval of the Value property. In case the value of this property is
modified while the counting is on, this modification will only be effective when the counter is
stopped and restarted.

Server Objec ts 401

5.5.3.2.5 Preset

Limit to be reached by the counter, in seconds. In case the Preset value is not a multiple of
Increment, the tag reaches this value before the next increment.

5.5.3.2.6 ResetCounterWhenEnabled

Enables restarting the counting (from zero) each time the value of the Enabled property
returns to True. When disabled the counter restarts counting from the point it was previously
interrupted.

5.5.3.2.7 Value

Displays the counting of the counter, in seconds. This is a read-only property. This property
gets values multiples of Increment, except when the Enabled property is set to False. In this
case, the value is the one when the tag is disabled. When restarting the counting, the property
value is the next multiple of Increment. The maximum value of this property is 2147483647
(0x7FFFFFFF).

5.5.4 Demo Tag

This section contains information about methods and properties of the Demo Tag object. This
object does not have events associated to it.

5.5.4.1 Methods
This section contains information about the methods of the Demo Tag object.

5.5.4.1.1 Reset
Reset()

Resets the phase (movement in time) of the tag wave format. This phase must not be reset
unless the tag is enabled. This method, when the tag is enabled, has no effect on CurrentTime
and Random type tags, which are not periodic. When the tag is disabled, its value is simply
reset, regardless of tag type. Example:
Sub CommandButton1_Click()
Application.GetObject("Data.Sine").Reset()
End Sub

5.5.4.2 Properties
This section contains information about the properties of the Demo Tag object.

402 Server Objec ts

5.5.4.2.1 Enabled

Defines whether Demo tag variation is activated. If True, Demo tag will update the Value
property according to the settings in the Period and the Scan properties. Otherwise, variation
is disabled. Default value is True. Example:
Sub CommandButton1_Click()
Application.GetObject("Data.DemoTag1").Enabled = True
End Sub

5.5.4.2.2 Maximum

Determines the maximum tag value. Default value is 100. Example:

Sub CommandButton2_Click()
' When clicking the button, a message box is opened,
' indicating DemoTag6 Maximum property value
MsgBox Application.GetObject("Data.DemoTag6").Maximum
End Sub

5.5.4.2.3 Minimum

Determines the minimum tag value. Default value is 0. Example:

Sub CommandButton2_Click()
' When clicking the button, a message box is opened,
' indicating DemoTag6 Minimum property value
MsgBox Application.GetObject("Data.DemoTag6").Minimum
End Sub

5.5.4.2.4 Period

Defines the wave shape length, in milliseconds. Does not apply when the Type property is
set to either 0 - Random or 3 - CurrentTime. Default value is 10,000 ms. Example:
Sub DemoTag1_OnStartRunning()
Period = 1000
End Sub

5.5.4.2.5 Scan

Defines the time interval between two variations of the Value property, in milliseconds. Use
this property to have a greater or smaller amount of data generated by the Demo tag. Default
value is 1,000. Scan value should be greater than 0. Example:
Sub Line1_Click()
Application.GetObject("Data.DemoTag2").Scan = 200
End Sub

5.5.4.2.6 TimeStamp

The TimeStamp property is updated whenever a value or state change occurs on Value or
Quality properties. It informs what is the date/time associated to the Demo Tag value, as well
as to its quality. This is a read-only property. Default value is 00:00:00.

Server Objec ts 403

5.5.4.2.7 Type

Determines the wave type of the tag. Change this property according to the next table.
When the Type property is set to 3 (CurrentTime), the Value property will contain the current
server date/time.

Available options for Type

VALUE WAVEFORM
0 Random

1 Sine

2 Square

3 CurrentTime

4 RampUp

5 RampDown

6 RampUpDown

Example:
Sub Line1_Click()
Application.GetObject("Data.DemoTag2").Type = 2
End Sub

5.5.4.2.8 Value

The Value property varies according to the waveform type, established in the Type property.
This is a read-only property. Default value is 0. Example:
Sub CommandButton1_Click()
MsgBox Application.GetObject("Data.DemoTag2").Value = 10
End Sub

5.5.5 Internal Tag

This section contains information about methods and properties of the Internal Tag object.
This object does not have events associated to it.

404 Server Objec ts

5.5.5.1 Methods
This section contains information about the methods of the Internal Tag object.

5.5.5.1.1 WriteEx
WriteEx(NewValue, NewTimestamp, NewQuality)

Allows modifications to an Internal Tag value, timestamp, and quality in a single operation.
This method returns a Boolean indicating whether the operation has been successful or not.

The NewValue parameter specifies the tag's new value; if omitted, tag value does not change.
The NewTimestamp parameter specifies the tag's new timestamp; if omitted, the timestamp
from the moment of method call is used. The NewQuality parameter specifies tag's new
quality; if omitted, a Good quality (192) is assumed. All these parameters can be omitted.
Example:
Sub CommandButton12_Click()
Dim Ret
Ret = Application.GetObject("Data.InternalTag1")._
WriteEx(123.456, "1/1/2001", 193)
If Ret Then
MsgBox "It works!"
Else
MsgBox "Failed!"
End If
End Sub

5.5.5.2 Properties
This section contains information about the properties of the Internal Tag object.

5.5.5.2.1 Quality

Informs the value quality in the Value property. This is a read-write property, but whenever
the Internal Tag value is modified, by script or by a link, it will be updated as well. Example:
Sub CommandButton1_Click()
MsgBox Application.GetObject("Data.InternalTag1").Quality
End Sub

NOTE: For more information on quality, see the Quality topic on the User's Manual.

5.5.5.2.2 Retentive

If True, the internal tag value will be stored automatically, in case the active domain stops.
This guarantees that the tag value will be synchronized with a standby server. Then, when the
server starts running, tag value will be the same as the server that has stopped. Otherwise,
tag value will be adjusted to the initial value whenever the domain has been executed, or the
active server switches. This property has no effect if altered at run time. Example:

Server Objec ts 405

 Sub CommandButton1_Click()
Dim status
status = Application.GetObject("Data.InternalTag1").Retentive
MsgBox status
Select Case status
Case True
MsgBox "The internal tag value will be _
stored automatically."
Case False
MsgBox "The tag value will be adjusted to the initial _
value whenever the Domain is executed or _
when an active server switch occurs."
End Select
End Sub

NOTE: This property is only valid for internal tags contained on the Server. Internal tags
contained on the Viewer cannot be retentive.

5.5.5.2.3 TimeStamp

The TimeStamp property informs the date/time associated to the value in the Value
property. This is a read-write property, but whenever an Internal Tag value is modified, by
script or by a link, it will be updated as well.

5.5.5.2.4 Value

This is a Variant type property, which allows storing values of any type, from an Integer to an
object pointer (see the next example). Use it to store values in the Viewer or in the Server and
to exchange data among several points in the application. Default value is empty. This is a
read-write property. Example:
Sub Months_OnStartRunning()
' Months is an Internal tag.
' The event is used to initialize the array.
Value = Array("January", "February", "March", _
"April", "May", "June", "July", "August", _
"September", "October", "November", "December")
End Sub

5.5.6 Timer Tag

This section contains information about events and properties of the Timer Tag object. This
object does not have methods associated to it.

5.5.6.1 Events
This section contains information about the events of the Timer Tag object.

5.5.6.1.1 OnPreset
OnPreset()

It occurs every time the value of NextExecTime property is reached.

406 Server Objec ts

5.5.6.2 Properties
This section contains information about the properties of the Timer Tag object.

5.5.6.2.1 Enabled

Enables or disables the Timer. The default value of this property is True.

5.5.6.2.2 NextExecTime

Displays the next triggering time. This is a read-only property.

5.5.6.2.3 RepeatInterval

This is used whenever the tag type is set to continuous. The default value of this property is
00:00:01.

5.5.6.2.4 StartTime

Initial date and time of the Timer. For the Single type it is the triggering date/time itself. For
other types is the moment when the Timer triggers. The default value is the local date and
time.

5.5.6.2.5 TriggerType

This is the type of the Timer trigger. The available options are:

Available options for TriggerType

OPTION DESCRIPTION
0 - ttSingle Single trigger.

1 - ttContinuous Continuous trigger.

2 - ttDaily Daily based trigger.

3 - ttMonthly Monthly based trigger.

Server Objec ts 407

5.6 Database
This section contains information about methods and properties of the Database object. This
object does not have events associated to it.

5.6.1 Methods
This section contains information about the methods of the Database object.

5.6.1.1 SetDBParameters
SetDBParameters(ServerName, UserName, Password, DBName)

Connection String with the DB in the properties of the Database object. The ServerName
parameter determines the server name. The UserName parameter determines the name of
the user. The Password parameter determines the login password to connect to the database.
The DBName parameter is the name of the database used in SQL Server. For other databases
this parameter is not used.

5.6.2 Properties
This section contains information about the properties of the Database object.

5.6.2.1 ConnectionActive
Displays the status of the main database connection. If the connection is active, this
property is True. Otherwise, its value is False.

5.6.2.2 EnableLocalCreation
Defines if the Viewer creates a local database connection or not. The local connection is
used only to create queries. If the property is enabled (True), Viewer tries to create the
connection locally, and if this is not possible, fetches the query on the server. The default
value of this property is False.

5.6.2.3 EnableSynchronization
Indicates to E3, if enabled (True), that it must also perform data recording on a second
database simultaneously, to ensure security. If this property is enabled and there is a Standby
server, E3 performs a synchronization between databases from both servers. The default
value of this property is False, that is, synchronization is disabled.

408 Server Objec ts

5.6.2.4 NetLibrary

Configures the type of database network library. The available options are:

Available options for NetLibrary

OPTION DESCRIPTION
0 - Default Default database type.

1 - NamedPipes Named Pipes database type.

2 - TcpIp Winsock TCP/IP database type.

3 - SpxIpx SPX/IPX database type.

4 - BanyanVines Banyan Vines database type.

5 - MultiProtocol Multi-protocolo (RPC) database type.

NOTE: the NetLibrary option is only available on SQL Server databases.

5.6.2.5 nRetries

This property specifies the number of times E3 tries to perform a database operation,
besides the first one. The default value of this property is 5. If the value of this property is
equal to 0 (zero), only one try is performed by operation. In case there is a database
connection loss during any of the tries, the operation is aborted and the remaining attempts
are dismissed.

5.6.2.6 ReconnectDelay

The ReconnectDelay property determines the delay time (in milliseconds) for the system to
try to restore a lost database connection. The default value of this property is 2000 (two
seconds).

5.6.2.7 SourceDatabase

In case the database is Access, this is the name of the .mdb file. In case the database is SQL
Server, this is the name of the SQL server concatenated with the chosen database, as Server/
Database. In case the database is Oracle, this is the name of the connection. This is a read-
only property.

Server Objec ts 409

5.6.2.8 SourceType

Indicates the database used by the object. The available options are:

· 0 - stAccess: Access database

· 1 - stOracle: Oracle database

· 2 - stSqlServer: SQL Server database

5.6.2.9 TimeOutCommand

Contains the delay time for any database operation, before the system generates a timeout
error. The default value is 180 (three minutes).

5.6.2.10 TimeOutConnection

Contains the delay time to perform a database connection, before the system generates a
timeout error. The default value is 15 seconds.

5.6.2.11 TotalFailedWrites

Contains the total number of operation errors in the database up to the current moment.

5.6.2.12 UserName

Login used to connect to the Database. This is a read-only property.

5.6.2.13 UseTransaction
Defines if the DBServer uses database transactions or not. If True, each block of database
operations (200 operations), like Historic, Storage, Formula, and Alarm operations are
executed at once, that is, as a single transaction.

5.7 Historic
This section contains information about methods and properties of the Historic object. This
object does not have events associated to it.

410 Server Objec ts

5.7.1 Methods
This section contains information about the methods of the Historic object.

5.7.1.1 StartAcquisition
StartAcquisition()

Enables Historic to record its field values periodically, from a rate specified in the ScanTime
property. This method can be called at any time after calling the StopAcquisition method. The
default behavior of this method is to start the application enabled, that is, this method is
always executed internally when starting the Historic. Example:
Sub Button1_Click()
' When clicking the button, enables the historic.
Application.GetObject("Hist1").StartAcquisition()
End Sub

5.7.1.2 StopAcquisition
StopAcquisition()

Disables acquiring records by period in Historic, no matter what value is set in the ScanTime
property. The recording by period is disabled until the StartAcquisition method is called. The
default behavior of the Historic object is starting the application with recording disabled.
Example:
Sub Hist1_OnStartRunning()
' Disables Historic as soon as it starts.
StopAcquisition()
End Sub

5.7.1.3 WriteRecord
WriteRecord()

Inserts a new record in the Database. The values are obtained from current values of each
variable specified as field data sources of the Historic. This method is used in two situations:

· To write a new data record before the time set for the next recording when Historic is
enabled by time

· To write a new data set when Historic is disabled

Example:
Sub Tag1_OnValueChange()
' Writes a new record in the Historic
' when a tag changes its value.
Application.GetObject("Hist1").WriteRecord()
End Sub

Server Objec ts 411

5.7.2 Properties
This section contains information about the properties of the Historic object.

5.7.2.1 BackupDiscardInterval

Indicates the amount of time units in which backup data is kept in the main table and in the
backup table, until it is discarded (for example, to keep data for 24 months on the main table,
and more six months in the backup table, the property value must be 30 months). This
property works together with the BackupDiscardTimeUnit property. The default value of this
property is 12 (twelve time units indicated in the BackupDiscardTimeUnit property).

NOTE: The total time indicated by combining the BackupDiscardInterval an

BackupDiscardTimeUnit properties must be greater than the time indicated by the
DiscardInterval and DiscardTimeUnit properties.

5.7.2.2 BackupDiscardTimeUnit

The BackupDiscardTimeUnit property indicates the time unit in which backup data remains
until it is discarded. The available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

This property works together with the BackupDiscardInterval property.

5.7.2.3 CacheSize

Defines the block size of the records which must be read by the Historic before sending them
to the database. For example, if CacheSize is equal to 4, blocks with four records each are sent
to the associated Database Server. The valid values for this property must be in a range
between 1 and 4. The default value of this property is 1.

NOTE: The record block is sent every second, even when it does not reach the size configured
in the CacheSize property.

412 Server Objec ts

5.7.2.4 CompressedTable

Enables using dead band for data recording. The default value of this property is False.

5.7.2.5 DBServer

Indicates the Database used by the Historic to create tables and record data. The default
value of this property is empty.

5.7.2.6 DeadBand

This property works together with the CompressedTable property. Indicates the calculated
value over the last recorded value (a percentage) which defines if this new value is recorded. If
the recorded value is not numeric, changing it makes all values to be recorded.

5.7.2.7 DiscardInterval

This property works together with the DiscardTimeUnit property. The DiscardInterval
property indicates the time interval during which Historic data is stored in the database table,
until it is discarded. The default value of this property is 1 (one time unit indicated in the
DiscardTimeUnit property). If this property is set to a value less than the value of the
BackupDiscardInterval property, E3 automatically set the value of the BackupDiscardInterval
property as double the value of DiscardInterval. This property can be modified at run time.

5.7.2.8 DiscardTimeUnit

This property works together with the DiscardInterval property. The DiscardTimeUnit
property indicates the time unit in which data table is stored until it is discarded. The
available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

5.7.2.9 EnableBackupTable
Creates a backup table where discarded data remains for security reasons. If set to True,
the table is created. Otherwise, there is no backup table. The default value of this property is
False.

Server Objec ts 413

5.7.2.10 EnableDiscard

Indicates Historic data discarding after a certain period of time. If set to False, data is
stored indefinitely on the table. Otherwise, it is discarded after a certain period of time. The
default value of this property is False.

5.7.2.11 EnableQualityLogs

When in True, the Historic starts and E3 generates a record equal to the first collected
record but with bad quality (0) and timestamp of minus one second.

5.7.2.12 ScanTime

Defines the time interval variation, in milliseconds, that the Historic waits to perform
acquisition and recording of a new table record. Use this property if there is a need for more or
less amount of data generated per second. The default value of this property is 1000.

5.7.2.13 TableName

Defines the name of the table used in the Historic.

5.7.2.14 UserTable
When this property is set to True, identifies a user historic, that is, table data was imported
from the database. Otherwise, it is an E3 regular Historic. This is a read-only property.

5.7.2.15 UseTagQuality
If True, Historic uses the tag source quality value. Otherwise, the old evaluation method is
used (0 = uncertain value; 1 = good value).

5.7.2.16 VerificationInterval

This property works together with the VerificationUnit property to control the time interval
that E3 checks for older data, and then discard them. The default value of this property is 1
(one time unit indicated by VerificationUnit).

5.7.2.17 VerificationUnit
This property works together with the VerificationInterval property. The VerificationUnit
property indicates the time unit in which the data discard verification is performed. The
available options are:

· 0 - dtHour: hours

414 Server Objec ts

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

5.8 Storage
This section contains information about methods and properties of the Storage object. This
object does not have events associated to it.

5.8.1 Methods
This section contains information about the methods of the Storage object.

5.8.1.1 CreateNewSession
CreateNewSession([DefaultType, ][DefaultMinRecTime, ][DefaultMaxRecTime, ][
DefaultDeadBand, ][DefaultDeadBandUnit, ][DefaultScanTime])

Generates a session capable of including data from a Storage, independent of normal

acquisition. The optional parameters are used to configure session Tags, in case they are not
informed during creation. They are, respectively:

· DefaultType: Data type (0: Double, 1: Bit, 2: String, 3: Integer)

· DefaultMinRecTime: Minimum time interval between recordings

· DefaultMaxRecTime: Maximum time interval without recording

· DefaultDeadBand: Dead band

· DefaultDeadBandUnit: Tag's dead band unit

· DefaultScanTime: Scan time

This methods works even if there are no fields configured in the Storage object.

5.8.1.2 StartAcquisition
StartAcquisition()

Starts or resumes data generation to the Database. The Storage receives notifications about
what Tags were modified, and when this happens, it checks whether records were stored or
not. When this method is called, the change notification and the recording generation are
started or resumed. Example:

Server Objec ts 415

 Sub Button1_Click()
' When clicking this button, enables the Storage
Application.GetObject("Storage1").StartAcquisition()
End Sub

5.8.1.3 StopAcquisition
StopAcquisition()

Stops data generation to the Database. The Storage receives notifications about what Tags
were modified, and when this happens, it checks whether records were recorded or not. When
this method is called, the change notification and the recording generation are stalled.
Example:
Sub Storage1_OnStartRunning()
' Disables the Storage as soon as it starts
StopAcquisition()
End Sub

5.8.2 Properties
This section contains information about the properties of the Storage object.

5.8.2.1 BackupDiscardInterval

Indicates the amount of time units during which backup data is kept on the main table and
on the backup table, until it is discarded (for example, to keep data for 24 months on the main
table, and six more months on the backup table, the value of this property must be 30
months). This property works together with the BackupDiscardTimeUnit property. The default
value of this property is 12 (twelve time units indicated by BackupDiscardTimeUnit).

NOTE: The total time indicated by the combination of BackupDiscardInterval and

BackupDiscardTimeUnit properties must be greater than the time indicated by
DiscardInterval and DiscardTimeUnit properties.

5.8.2.2 BackupDiscardTimeUnit

The BackupDiscardTimeUnit property indicates the time unit in which backup data remains
stored, until it is discarded. The available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

This property works together with the BackupDiscardInterval property.

416 Server Objec ts

5.8.2.3 CacheSize

Defines the block size of records which must be read by the Storage before sending them to
the database. For example, if CacheSize is equal to 4, blocks with four records each are sent to
the associated Database object. The default value of this property is 10.

NOTE: A record block is sent every 1 second, even if it does not reach the size configured in the
CacheSize property.

5.8.2.4 CompressionRate

Displays the data compression rate obtained up until now.

5.8.2.5 DBServer

Indicates the Database object used by the Storage to create tables and data records. The
default value of this property is an empty String.

5.8.2.6 DiscardInterval

This property works together with the DiscardTimeUnit property. The DiscardInterval
property indicates the time interval into which Historic data remains stored on the database
table, until it is discarded. The default value of this property is 1 (one time unit indicated by
the DiscardTimeUnit property). If this property is set to a value less or equal to the value of
BackupDiscardInterval property, E3 automatically adjusts the value of the
BackupDiscardInterval property as double the value of the DiscardInterval property. This
property can be modified at run time.

5.8.2.7 DiscardTimeUnit

This property works together with the DiscardInterval property. The DiscardTimeUnit
property indicates the time unit into which data remains stored until it is discarded. The
available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

Server Objec ts 417

5.8.2.8 EnableBackupTable

Creates a backup table where discarded data remains for security reasons. If set to True,
the Storage creates this table. Otherwise, there is no backup table. The default value of this
property is False.

5.8.2.9 EnableDiscard

Enables data discarding after a certain amount of time. If set to False, data is indefinitely
stored on the table. Otherwise, data is discarded after a certain amount of time. The default
value of this property is False.

5.8.2.10 Fields
Collection which points to Fields created in the Storage. For each Field, it is possible to
view Name and Link properties, and modify Type, MinRecTime, MaxRecTime, DeadBand,
ScanTime, and DeadBandUnit properties.

5.8.2.11 StringFieldSize

This property specifies the maximum size that Storage's String-type fields may have (this is
the size used when creating a Value field of the Strings table).

5.8.2.12 TableName

Defines the name of the table to be used in the Storage.

5.8.2.13 VerificationInterval

This property works together with the VerificationUnit property to control the time interval
into which E3 checks how old data is, to discard it later. The default value of this property is 1
(one time unit indicated by VerificationUnit).

5.8.2.14 VerificationUnit

This property works together with the VerificationInternal property. The VerificationUnit
property indicates the time unit into which data discard checking is performed. The available
options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

418 Server Objec ts

· 3 - dtMinute: minutes

5.8.3 Storage Fields

This section contains information about properties of the Storage Field object. This object
does not have events nor methods associated to it.

5.8.3.1 Properties
This section contains information about the properties of the Storage Field object.

5.8.3.1.1 DeadBand

Dead band used to calculate Storage algorithm. Indicates the precision that users are
willing to lose on every Field being stored. The higher the value of DeadBand property, the
more compact the database (less data is recorded). This value can be specified in absolute
units, or as a percentage of Tag's current value, according to DeadBandUnit property.

5.8.3.1.2 DeadBandUnit

Unit of DeadBand property. It can be specified in absolute units, or as a percentage of Tag's

current value.

5.8.3.1.3 Link

Determines the data source associated to this Field. This is a read-only property.

5.8.3.1.4 MaxRecTime

Maximum difference, in seconds, between timestamps of two consecutive records stored on

a database, that is, the maximum time with any data being recorded. For example, if a Tag
value is not varying, yet its current value must be written to the database when the number of
seconds configured in MaxRecTime is reached. This behavior can be disabled by setting
property value to 0 (zero).

5.8.3.1.5 MinRecTime

Minimum difference, in milliseconds, between timestamps of any two records with the
same quality stored on a database, that is, the minimum time for a new data to be recorded.
This parameter is used to limit the number of records written to a database, in case of a Tag
undergoing sudden variations on its value. This behavior can be disabled by setting property
value to 0 (zero).

Server Objec ts 419

5.8.3.1.6 Name

Property returning the name configured for this Field in the Storage object. By using this
name, it is possible to search for items in the collection.

5.8.3.1.7 ScanTime

Returns or sets Field's scan time (in milliseconds), that is, how often a Tag value is sent to
the compression algorithm, in case it is not varying. If this property's value is equal to 0 (zero),
the value of MaxRecTime property is used for the same purpose.

5.8.3.1.8 Type

Returns the object type in the Storage format (0: Double, 1: Bit, 2: String, 3: Integer). This is
a read-write property, but it only accepts changes while data collecting for this Field has not
started yet.

NOTE: Bit, String, and Integer datatypes are not submitted to Storage's compression
algorithm. Therefore, when there is a variation on Field's quality or value, the value is
recorded on the database. DeadBand, DeadBandUnit, MaxRecTime, and MinRecTime
properties do not affect these datatypes, because they are exclusive to the compression
algorithm.

5.9 Formulas
This section contains information about methods and properties of the Formula object. This
object does not have events associated to it.

5.9.1 Methods
This section contains information about the methods of the Formula object.

5.9.1.1 CreateUnit
CreateUnit(UnitName)

Creates a unit on the Formula table. This method has the UnitName parameter which
determines the name of the unit to be created. Returns True if the operation is successful.
Otherwise, returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button, creates a new Unit
Application.GetObject("Formula1").CreateUnit("Unit2")
End Sub

420 Server Objec ts

5.9.1.2 CreateValue
CreateValue(ValueName)

Creates a value set on the Formula table. This method has the ValueName parameter, which
determines the name of the set to be created. Returns True if the operation is successful.
Otherwise, returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button, creates a new Value
Application.GetObject("Formula1").CreateValue("Template5")
End Sub

5.9.1.3 DeleteUnit
DeleteUnit(UnitName)

Deletes a unit on the Formula table. This method has the UnitName parameter, which informs
the name of the unit to be deleted. Returns True if the operation is successful. Otherwise,
returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button, deletes the unit
Application.GetObject("Formula1").DeleteUnit("Unit2")
End Sub

5.9.1.4 DeleteValue
DeleteValue(ValueName)

Deletes a value set on the Formula table. This method has the ValueName parameter, which
informs the value set to be deleted. Returns True if the operation is successful. Otherwise,
returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button, deletes a value set
Application.GetObject("Formula1").DeleteValue("Template5")
End Sub

5.9.1.5 FindUnit
FindUnit(UnitName)

Checks if a certain unit exists on the Formula database. This method has the UnitName
parameter, which determines the name of the unit to be found. This method returns True if the
operation is successful. Otherwise, returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button, displays a message box
' with the result
MsgBox(Application.GetObject("Formula1")._
FindUnit("Unit2"))
End Sub

Server Objec ts 421

5.9.1.6 FindValue
FindValue(ValueName)

Checks if a certain value set exists on Formula database. This method has the ValueName
parameter, which informs the name of the set to be checked. Returns True if the operation is
successful. Otherwise returns False. Example:
Sub Button1_Click()
Dim val
' When clicking the button displays a message box
' with the result
MsgBox CStr(Application.GetObject("Formula1")._
FindValue("Template5"))
End Sub

5.9.1.7 GetUnitData
GetUnitData(UnitName, TemplateName, Val)

Places on the variable indicated by Val the tag associated to the UnitName unit of the
TemplateName template. Returns True if the operation is successful. Otherwise, returns False.
Example:
Sub Button1_Click()
Dim whatTag, whatFormula
Application.GetObject("Formula1").GetUnitData _
"Unit1", "Template2", var1
End Sub

5.9.1.8 GetValueData
GetValueData(ValueName, TemplateName, Val)

Places on the Val variable the value of the ValueName value set which is associated to the
TemplateName template. Returns True if the operation is successful. Otherwise, returns False.
Example:
Sub Button1_Click()
Dim Value, whatFormula
Application.GetObject("Formula1").GetValueData _
"Value4", "Template2", var1
End Sub

5.9.1.9 LoadFormulaValuesQuiet
LoadFormulaValuesQuiet(UnitName, ValueName)

Loads a value set to a destination unit, without displaying a message. This method has the
UnitName parameter, which determines the name of the unit and the ValueName parameter,
which determines the name of the value set. Returns True if the operation is successful, and
False on failure (which does not necessarily mean a script error). Example:
Sub Button1_Click()
Application.GetObject("Formula1").LoadFormulaValuesQuiet _
"Unit3", "Value1"
End Sub

NOTE: This method is also acessible through the Viewer object.

422 Server Objec ts

5.9.1.10 RenameUnit
RenameUnit(UnitName, NewUnitName)

Renames a certain existing unit on the Formula table. Returns True if the operation is
successful, or False otherwise. This method has the UnitName parameter, which determines
the name of the unit to be found, and the NewUnitName parameter, which informs the new
unit name. Example:
Sub Button1_Click()
Dim val
' When clicking the button, renames the unit
Application._
GetObject("Formula1").RenameUnit "Unit2", "Unit3"
End Sub

5.9.1.11 RenameValue
RenameValue(ValueName, NewValueName)

Renames a certain set of values which exists in the Formula table. Returns True if the
operation is successful or False, otherwise. This method has the ValueName parameter, which
is the name of the set of values and the NewValueName parameter, which is the new name of
the set of values. Example:
Sub CommandButton1_Click()
Application.GetObject("Formula1").RenameValue "Template5", "TemplateABC"
End Sub

5.9.1.12 SaveFormulaValues
SaveFormulaValues(UnitName, ValueName[, IgnoreErrors])

This method saves the current values of the Tags from an origin unit into a set of values in the
Formula table. This method does not check limits, in case the template has a restriction of
absolute type. The UnitName parameter is the name of the origin unit and the ValueName
parameter is the set of values which is saved. Returns True if the operation is successful.
Otherwise, returns False. The IgnoreErrors parameter, when in True, forces all values to be
saved, even if there are errors in the Formula links. However, its default value is False.
Example:
Sub CommandButton1_Click()
Application.GetObject("Formula1") SaveFormulaValues "Unit1", "Value1"
End Sub

5.9.1.13 SetUnitData
SetUnitData(UnitName, TemplateName, Data)

Loads the identified Tag to a certain template, on a certain unit, in the Formula table. Returns
True if the operation is successful or False, otherwise. This method has the UnitName
parameter, which is the name of the unit, the TemplateName parameter, which is the name of
the Tag template, and the Data parameter, which is the name of the variable that contains the
Tag name. Example:
Sub CommandButton1_Click()
Application.GetObject("Formula1").SetUnitData "Unit2", "Template5", 50
End Sub

Server Objec ts 423

5.9.1.14 SetValueData
SetValueData(ValueName, TemplateName, Data)

Changes the value referring to a template defined for a certain set of values. This method
checks for limit values, returning True if the operation is successful or False, otherwise. This
method has the ValueName parameter, which is the name of the set of values, the
TemplateName parameter, which determines the template name, and the Data parameter,
which is the name of the variable that holds the value. Example:
Sub CommandButton1_Click()
Application.GetObject("Formula1").SetValueData "Unit2", "Template1", 100
End Sub

NOTE: For more information about the SetValueData method, please check the articles KB
112 and KB 1246 from the Elipse Knowledgebase website.

5.9.2 Properties
This section contains information about the properties of the Formula object.

5.9.2.1 DBServer

Indicates the name of the database where Formula information is stored, that is, units and
value sets. The default value of this property is empty.

5.9.2.2 ImmediateExecute
When enabled, the Formula object writes its records directly into the Database, without
passing through operation queues (.e3i and .e3o files). This makes database operations to be
viewed faster.

5.9.2.3 TableName

Indicates the name of the tables where Formula information is stored. The default value of
this property is empty.

5.10 Alarms
This section contains information about events, methods, and properties of the Alarm
Configuration, Alarm Area, Alarm Source, and Alarm Server objects.

424 Server Objec ts

5.10.1 Alarm Configuration
The Alarm Configuration object does not contain specific events, methods, or properties, only
general ones. These can be viewed on section General Events, Methods, and Properties of
Objects.

5.10.2 Alarm Area

This section contains information about properties of the Alarm Area object. This object does
not have events nor methods associated to it.

5.10.2.1 Properties
This section contains information about the properties of the Alarm Area object.

5.10.2.1.1 ActiveAlarms

Determines the number of active alarms in the Area. If this property is set to 0 (zero),
inactive alarms are listed via property ActiveNACKAlarms. This is a read-only property. Default
value is 0 (zero).

5.10.2.1.2 ActiveHighAlarms

Indicates the number of active alarms with high severity. This is a read-only property.

5.10.2.1.3 ActiveHighNACKAlarms

Indicates the number of non-acknowledged alarms with high severity. This is a read-only
property.

5.10.2.1.4 ActiveLowAlarms

Indicates the number of active alarms with low severity. This is a read-only property.

5.10.2.1.5 ActiveLowNACKAlarms

Indicates the number of non-acknowledged alarms with low severity. This is a read-only
property.

Server Objec ts 425

5.10.2.1.6 ActiveMedAlarms

Indicates the number of active alarms with medium severity. This is a read-only property.

5.10.2.1.7 ActiveMedNACKAlarms

Indicates the number of non-acknowledged alarms with medium severity. This is a read-only
property.

5.10.2.1.8 ActiveNACKAlarms

Indicates the number of non-acknowledged alarms inside an object. This is a read-only

property.

5.10.2.1.9 Alarm

Indicates that there are active alarms inside the Area. If this option is set to True, there is
at least one active alarm inside the Area, and the property ActiveAlarms performs a reading
from server, then indicating the amount of active alarms. Otherwise, property
ActiveNACKAlarms performs a reading of non-acknowledged alarms. This is a read-only
property.

5.10.2.1.10 AlarmVerify

Enables a check on all alarms inside the object. After enabling that check (True), if the value
of property ActiveAlarms is greater than 0 (zero), server then checks active alarms, as well as
non-acknowledged ones, listing these last ones in the property ActiveNACKAlarms. This
property is useful to avoid a cascade effect on some systems, where the occurrence of an
event triggers a large amount of related alarms.

426 Server Objec ts

5.10.3 Alarm Source
This section contains information about common methods and properties of the Alarm Source
object. This object does not have common events associated to it.

NOTE: When an Alarm Source object is disabled or deactivated, the ActiveNACKAlarm, Alarm,
CurrentSeverity, CurrentSubConditionName, FormattedValue, RawAlarm, and Value
properties assume their default values, indicating that the Alarm Source is not linked to an
active alarm message. In this case, the values of the Alarm and ActiveNACKAlarm are
propagated to the counters of upper areas.
To have these properties receive a value other than the default, it is necessary that the
following conditions are present:
· The Alarm Source must be enabled and active
· The Alarm Area (and all the hierarchically superior objects) must be enabled and active
· The Alarm Server must be active

5.10.3.1 Common Methods

This section contains information about the common methods of the Alarm Source objects.

5.10.3.1.1 Ack
Ack([ActorID])

Acknowledges an alarm configured in the Alarm Source object. This method returns a Boolean
indicating whether the operation has been successful or not. The ActorID parameter informs
the name of the user responsible for alarm acknowledgement. This is an optional parameter
and, if omitted, assumes the user logon of the Viewer, "Anonymous" if there is no user logged
on, or "System" if the method call started at the server.

5.10.3.1.2 GetAlarm
GetAlarm()

Returns an object that grants access to each type of alarm specific settings. This allows
checking or modifying any alarm properties at run time. Depending on the type of alarm, this
method returns the following properties:

· Analog Alarm: Responsible for digital alarm settings

Digital Alarm Properties

ITEM DESCRIPTION
DigitalReturnMessageText Digital alarm returning message.

Server Objec ts 427

 ITEM DESCRIPTION
Digital Enables or disables digital alarm checking.

DigitalLimit Digital alarm limit.

DigitalMessageText Digital alarm message text.

DigitalSeverity Digital alarm severity. Set of values:

· 0: High

· 1: Medium

· 2: Low

DigitalAckRequired Acknowledgement required for this type of

alarm (digital).

· Analog Alarm: Responsible for the definition of the alarm level. Properties of this object (it
has four alarm levels):

Analog Alarm properties

ITEM DESCRIPTION
LevelDeadBand Dead band for alarm level.

LevelReturnMessageText Returns alarm's message.

LoLo Alarm properties

ITEM DESCRIPTION
LoLo Enables or disables LoLo alarm checking.

LoLoLimit LoLo alarm limit.

LoLoMessageText LoLo alarm message text.

LoLoSeverity LoLo alarm severity. Set of values:

· 0: High

428 Server Objec ts

 ITEM DESCRIPTION
· 1: Medium

· 2: Low

LoLoAckRequired Acknowledgement required for this alarm

level (LoLo).

Lo Alarm properties

ITEM DESCRIPTION
Lo Enables or disables the Lo alarm checking.

LoLimit Lo alarm limit.

LoMessageText Lo alarm message text.

LoSeverity Lo alarm severity. Set of values:

· 0: High

· 1: Medium

· 2: Low

LoAckRequired Acknowledgement required for this alarm

level (Lo).

Hi Alarm properties

ITEM DESCRIPTION
Hi Enables or disables the High alarm checking.

HiLimit Hi alarm limit.

HiMessageText Hi alarm message text.

HiSeverity Hi alarm severity. Set of values:

· 0: High

Server Objec ts 429

 ITEM DESCRIPTION
· 1: Medium

· 2: Low

HiAckRequired Acknowledgement required for this alarm

level (Hi).

HiHi Alarm properties

ITEM DESCRIPTION
HiHi Enables or disables the HiHi alarm checking.

HiHiLimit HiHi alarm limit.

HiHiMessageText HiHi alarm message text.

HiHiSeverity HiHi alarm severity. Set of values:

· 0: High

· 1: Medium

· 2: Low

HiHiAckRequired Acknowledgement required for this alarm

level (HiHi).

· Rate of Change Alarm: Responsible for the settings of a Rate Of Change-type alarm

Rate of Change Alarm properties

ITEM DESCRIPTION
ROCReturnMessageText Rate of Change return message.

ROC Enables or disables Rate of Change checking.

ROCLimit Rate of Change alarm limit. For this alarm to

occur, it is enough that the value of the
associated Tag exceeds this value in one
second.

ROCMessageText Rate of Change alarm message text.

430 Server Objec ts

 ITEM DESCRIPTION
ROCSeverity Rate of Change alarm severity. Set of values:

· 0: High

· 1: Medium

· 2: Low

ROCAckRequired Acknowledgement required for this type of

alarm (rate of change).

· Dead Band Alarm: Responsible for dead band alarm settings

Dead Band Alarm Properties

ITEM DESCRIPTION
DeadBandSetPoint Dead Band alarm limit. Every time the value
of the associated Tag exceeds the value of
this property up or down the DeadBandLimit
value, this alarm occurs.

DeadBandReturnMessageText Dead band alarm return message.

DeadBand Enables or disables dead band alarm

checking.

DeadBandLimit Dead band alarm limit.

DeadBandMessageText Dead band alarm message text.

DeadBandSeverity Severity of dead band alarm. Set of values:

· 0: High

· 1: Medium

· 2: Low

DeadBandAckRequired Acknowledgement required for this type of

alarm (dead band).

Example:

Server Objec ts 431

 Sub Button1_Click()
Dim val
' When clicking the button, AlarmSource BatteryLevel
' Lo alarm level is changed
Application.GetObject("ConfigAlarms1.Area1.BatteryLevel")_
.GetAlarm().LoLimit = 10.2
End Sub

NOTE: specific properties for each alarm source type can be accessed directly via scripts or
links, as well as visualized in the object's Property List, making their editing via GetAlarm
method no longer mandatory.

5.10.3.2 Common Properties

This section contains information about the common properties of the Alarm Source objects.

5.10.3.2.1 ActiveNACKAlarm

If set to True, indicates that the Source was not acknowledged since last activation. This is a
read-only property. The default value of this property is False.

5.10.3.2.2 Alarm

If set to True, indicates the active condition of the alarm. The default value of this property
is False.

5.10.3.2.3 AlarmVerify

If set to True, enables alarm source checking (that is, generating the alarm).

5.10.3.2.4 AreaNameOverride

Determines an alternative name for the Area which contains the Alarm Source. The default
value of this property is an empty String.

NOTES:
· When this property is empty, the name of the Alarm Source is composed by the names of
the Area objects hierarchically above it
· This property, even when filled in, does not influence the Alarm Area counters
hierarchically above it, which keep counting the alarms of this Alarm Source
· If this property is changed at run time, the new value is only effective when the next alarm
on this Alarm Source occurs

432 Server Objec ts

5.10.3.2.5 CurrentSeverity

Indicates the last severity of the active alarm, that is:

· 0: High

· 1: Medium

· 2: Low

The default value of this property is -1, indicating that the Alarm Source is not active.

5.10.3.2.6 CurrentSubConditionName

Determines the name of the last active alarm condition. The available options for this
property are:

Available options for CurrentSubConditionName

OPTION DESCRIPTION
LOLO Analog Alarm on LOLO range.

LO Analog Alarm on LO range.

HI Analog Alarm on HI range.

HIHI Analog Alarm on HIHI range.

DB Dead Band alarm.

ROC Rate Of Change alarm.

DIG Digital alarm.

The default value of this property is an empty String.

5.10.3.2.7 Delay

Specifies a delay time for the alarm (in ms), when entering as well as leaving the condition.
When this property is in 0 (which will always be the default value), no delay is applied. When
different from 0, the alarm is only activated or deactivated if it remains on the same condition
for a time greater than or equal to the one specified.

Server Objec ts 433

5.10.3.2.8 DoubleAckRequired

When configured as True, indicates that the alarm can be acknowledged when active as
well as when it is inactive, that is, can be doubly acknowledged. When configured as False,
indicates that the alarm can only be acknowledged once and, when acknowledged, it leaves
the alarm list. Alarms that do not need acknowledgement (using the AckRequired property)
does not allow that type of customization. Applications prior to version 2.5 have this property
set to False.

5.10.3.2.9 Event

When configured as True, indicates that this is an Event-type alarm. An Event-type alarm,
when activated, is acknowledged by the "System" user. Therefore, when it is acknowledged
nothing happens (it has no effect), as well as it does not increment the number of active
alarms nor the number of unacknowledged alarms. It cannot be modified at run time.

5.10.3.2.10 Format

The Format property specifies what type of format is applied to the object. It allows
changing the way data is displayed without changing data behind it. This property can be
manually edited or configured using the Format window. Its use is similar to the formatters
used on spreadsheets, following the same basic sintax. The following data types are
supported:

Data types supported by Format

DATA DESCRIPTION
Numerical Decimal, scientific, hexadecimal, binary, and
octal output.

Text General text.

Boolean Boolean values.

Date/Time Gregorian calendar.

5.10.3.2.11 FormattedValue

Contains the value of the alarm in the Value property, according to the Format property.
This is a read-only property. The default value of this property is Null.

434 Server Objec ts

5.10.3.2.12 RawAlarm

Indicates if the alarm must be active, independent of the waiting time. When the waiting
time is equal to 0 (zero), the value of RawAlarm is the same as the Alarm property. This is a
read-only property. The default value of this property is False.

5.10.3.2.13 Source

Contains the expression that must be evaluated in order to determine whether the alarm
must occur.

5.10.3.2.14 Value

Contains the value that was evaluated to determine whether the alarm occurs. The default
value of this property is Null.

5.10.3.3 Analog Alarm Source

This section contains information about the properties of the Analog Alarm Source object. This
object does not have events nor methods associated to it.

When the value of the Event property (common to all Alarm Sources) is set to True, the
HiEvent, HiHiEvent, LoEvent, and LoLoEvent properties cannot be modified (all alarm
subconditions behave as events).

5.10.3.3.1 Properties

This section contains information about the properties of the Analog Alarm Source object.

5.10.3.3.1.1 Hi

Enables or disables checking of Hi type alarms.

5.10.3.3.1.2 HiAckRequired

Indicates that the Hi type alarm requires acknowledgment.

5.10.3.3.1.3 HiEvent

Defines whether the Alarm's Hi subcondition should be treated as an event. If the Event
property, common to all Alarm Sources, is set to True, this property cannot be modified, and
its value always remains in True. In addition, this property cannot be modified at run time.

Server Objec ts 435

5.10.3.3.1.4 HiHi

Enables or disables checking of HiHi type alarms.

5.10.3.3.1.5 HiHiAckRequired

Indicates that the HiHi type alarm requires acknowledgement.

5.10.3.3.1.6 HiHiEvent

Defines whether the Alarm's HiHi subcondition should be treated as an event. If the Event
property, common to all Alarm Sources, is set to True, this property cannot be modified, and
its value always remains in True. In addition, this property cannot be modified at run time.

5.10.3.3.1.7 HiHiLimit

Sets the limit value of the HiHi type alarm.

5.10.3.3.1.8 HiHiMessageText

Sets the text message of the HiHi type alarm limit.

5.10.3.3.1.9 HiHiSeverity

Indicates the level of importance of the HiHi type alarm. The options are:

· 0: High

· 1: Medium

· 2: Low

5.10.3.3.1.10 HiLimit

Indicates the level in which the Hi type alarm is activated.

5.10.3.3.1.11 HiMessageText

Sets the text message of the Hi type alarm limit.

436 Server Objec ts

5.10.3.3.1.12 HiSeverity

Indicates the level of importance of the Hi type alarm. The options are:

· 0: High

· 1: Medium

· 2: Low

5.10.3.3.1.13 LevelDeadBand

Dead band for the alarm level limits.

5.10.3.3.1.14 LevelReturnMessageText

Sets the return message of the alarm level.

5.10.3.3.1.15 Lo

Enables or disables checking of Lo type alarms.

5.10.3.3.1.16 LoAckRequired

Indicates that the Lo type alarm requires acknowledgment.

5.10.3.3.1.17 LoEvent

Defines whether the Alarm's Lo subcondition should be treated as an event. If the Event
property, common to all Alarm Sources, is set to True, this property cannot be modified, and
its value always remains in True. In addition, this property cannot be modified at run time.

5.10.3.3.1.18 LoLimit

Indicates the level in which the Lo type alarm is activated.

5.10.3.3.1.19 LoLo

Enables or disables checking LoLo type alarms.

Server Objec ts 437

5.10.3.3.1.20 LoLoAckRequired

Indicates that the LoLo type alarm requires acknowledgement.

5.10.3.3.1.21 LoLoEvent

Defines whether the Alarm's LoLo subcondition should be treated as an event. If the Event
property, common to all Alarm Sources, is set to True, this property cannot be modified, and
its value always remains in True. In addition, this property cannot be modified at run time.

5.10.3.3.1.22 LoLoLimit

Indicates the level in which the LoLo type alarm is activated.

5.10.3.3.1.23 LoLoMessageText

Sets the text message of the LoLo type alarm limit.

5.10.3.3.1.24 LoLoSeverity

Indicates the level of importance of the LoLo type alarm. The options are:

· 0: High

· 1: Medium

· 2: Low

5.10.3.3.1.25 LoMessageText

Sets the text message of the Lo type alarm limit.

5.10.3.3.1.26 LoSeverity

Indicates the level of importance of the Lo type alarm. The options are:

· 0: High

· 1: Medium

· 2: Low

438 Server Objec ts

5.10.3.4 Digital Alarm Source
This section contains information about the properties of the Digital Alarm Source object. This
object does not have events nor methods associated to it.

5.10.3.4.1 Properties

This section contains information about the properties of the Digital Alarm Source object.

5.10.3.4.1.1 Digital

Enables or disables checking of Digital alarms.

5.10.3.4.1.2 DigitalAckRequired

Need of acknowledgement for the Digital alarm.

5.10.3.4.1.3 DigitalLimit

Limit for the Digital alarm.

5.10.3.4.1.4 DigitalMessageText

Message text of the Digital alarm.

5.10.3.4.1.5 DigitalReturnMessageText

Return message of the Digital alarm.

5.10.3.4.1.6 DigitalSeverity

Severity of the Digital alarm. Set of values:

· 0: High

· 1: Medium

· 2: Low

Server Objec ts 439

5.10.3.5 Dead Band Alarm Source
This section contains information about the properties of the Dead Band Alarm Source object.
This object does not have events nor methods associated to it.

5.10.3.5.1 Properties

This section contains information about the properties of the Dead Band Alarm Source object.

5.10.3.5.1.1 DeadBand

Enables or disables checking of Dead Band alarms.

5.10.3.5.1.2 DeadBandAckRequired

Need of acknowledgement for the Dead Band alarm.

5.10.3.5.1.3 DeadBandLimit

Limit for Dead Band alarm.

5.10.3.5.1.4 DeadBandMessageText

Text of Dead Band alarm message.

5.10.3.5.1.5 DeadBandReturnMessageText

Return message of Dead Band alarm.

5.10.3.5.1.6 DeadBandSetpoint

Alarm dead band limit. Each time the associated tag value surpasses this property value
more or less the DeadBandLimit value, the alarm occurs.

5.10.3.5.1.7 DeadBandSeverity

Importance of the Dead Band alarm. Set of values are:

· 0: High

· 1: Medium

· 2: Low

440 Server Objec ts

5.10.3.6 Rate Of Change Alarm Source
This section contains information about the properties of the Rate Of Change Alarm Source
object. This object does not have events nor methods associated to it.

5.10.3.6.1 Properties

This section contains information about the properties of the Rate Of Change Alarm Source
object.

5.10.3.6.1.1 ROC

Enables or disables checking of Rate Of Change alarms.

5.10.3.6.1.2 ROCAckRequired

Need of acknowledgement for the Rate Of Change alarm.

5.10.3.6.1.3 ROCLimit

Limit for the Rate Of Change alarm. For the alarm to occur, it is enough that the associated
tag value surpasses this value in one second.

5.10.3.6.1.4 ROCMessageText

Message text of the Rate Of Change alarm.

5.10.3.6.1.5 ROCReturnMessageText

Return message of the Rate Of Change alarm.

5.10.3.6.1.6 ROCSeverity

Importance of the Rate Of Change alarm. Set of values are:

· 0: High

· 1: Medium

· 2: Low

Server Objec ts 441

5.10.3.7 Discrete Alarm Source
This section contains information about the properties of the Discrete Alarm Source object.
This object does not have events nor methods associated to it.

When the value of the Event property (common to all Alarm Sources) is set to True, the Kind
property of objects belonging to the collection of Subconditions of a Discrete Alarm Source
cannot be modified (all alarm subconditions behave as events).

5.10.3.7.1 Properties

This section contains information about the properties of the Discrete Alarm Source object.

5.10.3.7.1.1 DiscreteReturnMessageText

Returns or modifies the return message of the Discrete Alarm Source. If any object in the
collection of Subconditions has its Kind property set to 2 (Return), the Message property of that
object is used, instead of the value defined in DiscreteReturnMessageText.

5.10.3.7.1.2 SubConditions

Returns an object that is a collection of Subconditions of the Discrete Alarm Source. See
items Common Methods and Common Properties for methods and properties, respectively,
applicable to this collection.

Common Methods
This section contains information about the methods of the collection of Subconditions of the
Discrete Alarm Source.

AddSubCondition
AddSubCondition([Name, Caption, Message, Kind, AckRequired, Severity, Value])

Adds a Subcondition object to the collection of Subconditions. This method has the following
optional parameters:

Parameters of AddSubCondition method

PARAMETER DESCRIPTION
Name The object's name. Corresponds to the
Subcondition object's Name property. If it is
omitted, the Subcondition is then created
with the name "Subcondition". If the value
passed on this parameter already exists in
the collection, it is automatically
incremented.

442 Server Objec ts

 PARAMETER DESCRIPTION
Caption The object's description. Corresponds to the
Subcondition object's Caption property.

Message The Subcondition's message text.

Corresponds to the Subcondition object's
Message property.

Kind The type of behavior of this Subcondition.

Possible values for this parameter are: 0 -
Alarm (default); 1 - Event; 2 - Return.
Corresponds to the Subcondition object's
Kind property.

AckRequired Indicates whether this Subcondition requires

acknowledgement. Corresponds to the
Subcondition object's AckRequired property.
The default value of this property is True.

Severity The type of severity of this Subcondition.

Possible values for this parameter are: 0 -
High; 1 - Medium (default); 2 - Low.
Corresponds to the Subcondition object's
Severity property.

Value Parameter containing a value that will be

evaluated to determine whether the alarm
occurs. Corresponds to the Value property,
common to all Alarm Sources.

Item
Item(Index)

Returns a reference to a Subcondition object, indicated by Index. This parameter can be an

index in the collection (starting at 1), or the object's name (the Name property).

RemoveSubCondition
RemoveSubCondition(Index)
Removes the Subcondition object indicated by Index. This parameter can be an index in the
collection (starting at 1), or the object's name (the Name property).

Common Properties
This section contains information about the properties of the collection of Subconditions of
the Discrete Alarm Source.

Count
Returns the number of children objects (items) of a collection of Subconditions. This
property works together with the Item method. If the collection has no children objects,
returned value is 0 (zero).

Server Objec ts 443

SubCondition
This section contains information about the properties of the Subcondition object. This object
does not have events nor methods associated to it.

Properties
This section contains information about the properties of the Subcondition object.

AckRequired
Indicates whether this Subcondition object requires acknowledgement.

Caption
Subcondition's description.

Enabled
Enables or disables the Subcondition.

Kind
Indicates Subcondition's behavior. Possible values for this property are the following:

· 0: Alarm

· 1: Event

· 2: Return

If the Event property, common to all Alarm Sources, is set to True, this property cannot be
modified, and its value always remains in 1 (Event). In addition, this property cannot be
modified at run time.

Limit
Defines Alarm Source's value to generate the Subcondition.

Message
The event message when the Subcondition is active. If the Kind property is set to 2 (Return),
this property is considered as the alarm's return message.

Name
Subcondition object's name. This value is case-insensitive.

Severity
The type of severity of this Subcondition. Possible values for this property are:

· 0: High

444 Server Objec ts

· 1: Medium

· 2: Low

5.10.4 Alarm Server

This section contains information about the properties and methods of the Alarm Server
object. This object does not events associated to it.

5.10.4.1 Methods
This section contains information about the methods of the Alarm Server object.

5.10.4.1.1 AckAllAlarms
AckAllAlarms([ActorID])

Acknowledges all alarms in the server, regardless of their area. This method returns a Boolean
indicating whether the operation has been successful or not. The ActorID parameter informs
the name of the user responsible for alarm acknowledgement. This is an optional parameter
and, if omitted, assumes the user logon of the Viewer, "Anonymous" if there is no user logged
on, or "System" if the method call started at the server. Example:
Sub Button1_Click()
' When clicking the button, it acknowledges all alarms
Application.GetObject("AlarmServer1")._
AckAllAlarms (Application.User)
End Sub

5.10.4.1.2 AckArea
AckArea(Area[, ActorID])

Acknowledges the alarms in a given area. This method returns a Boolean indicating whether
the operation has been successful or not. The Area parameter specifies the name of the area
(s) which alarms are acknowledged, by matching the beginning of their names. For example,
AckArea("ANA") acknowledges alarms in areas named "ANALOG", "ANA.AREA2", etc. If this
parameter is empty, the method behaves like AckAllAlarms. The ActorID parameter informs
the name of the user responsible for alarm acknowledgement. This is an optional parameter
and, if omitted, assumes the user logon of the Viewer, "Anonymous" if there is no user logged
on, or "System" if the method call started at the server. Example:
Sub Button1_Click()
'When clicking the button, it acknowledges Area1 alarms
Application.GetObject("AlarmServer1")._
AckArea "Area1", Application.User
End Sub

Server Objec ts 445

5.10.4.1.3 LogTrackingEvent
LogTrackingEvent(Message[, ActorID], Area, Severity, EventTime, Source, EventCategory,
EventType, UserFields, AlarmSourceName, FullAlarmSourceName)

Simulates an event or an alarm and sends it straight to Alarm Server's database, without
passing througn an E3Alarm. This is why this event cannot be seen at E3Alarm, nor can the
alarm be acknowledged.

Each method parameter allows specifying the value of the field with the same name in the
event. Event fields are fulfilled according to method parameters.

LogTrackingEvent method parameters

NAME DESCRIPTION
Message Parameter with the content of the text
configured on the alarm source. If omitted, it
assumes an empty String.

ActorID Optional text parameter which specifies the

operator that accepted the alarm. If omitted,
it assumes the user logon of the Viewer,
"Anonymous" if there is no user logged on, or
"System" if the method call started at the
server.

Area Text parameter with the name of the area

where the alarm source belongs to. If
omitted, it assumes an empty value.

Severity Numeric parameter informing event severity.

If omitted, it assumes 0 (high severity).

EventTime DateTime parameter informing when the

event occurred. If omitted, it assumes the
timestamp of the moment of method call.

Source Text parameter that specifies the link used to

evaluate alarm conditions. If omitted, it
assumes an empty String.

EventCategory Text parameter with values for categories of

events. If omitted, it assumes an empty
String.

EventType Text parameter that specifies the type of the

event. For alarms, it assumes the value
"Condition". If omitted, it assumes "Tracking".

446 Server Objec ts

 NAME DESCRIPTION
UserFields Four (or more) position array parameters
where each position specifies an user-
customized field value.

AlarmSourceName Text parameter with the name of the alarm

source. If omitted, it assumes an empty
String.

FullAlarmSourceName Text parameter with the alarm source full

path, including area, alarm configuration and
possible folders where the alarm is inserted.
If omitted, it assumes an empty String.

The other event fields cannot be specified and always assume the following values:

· CurrentValue: 0.0

· Quality: ""

· ConditionActive: 0 (False)

· ConditionName: ""

· SubConditionName: ""

· Acked: 1 (True)

· AckRequired: 0 (False)

· Enabled: 1 (True)

· EventTimeUTC: *Always equal to EventTime (just like in alarm events)

· ChangeMask: 0

· Cookie: 0

NOTE: This method fails if the Alarm Server option Store alarm event in the database is False,
or when a database error occurs.

Example:

Server Objec ts 447

 Sub CommandButton1_Click()
' In parameter UserFields, the element value will be shown
' for each element
Application.GetObject("AlarmServer1").LogTrackingEvent_
"Button clicking", Application.User, "Operation", 2, ,_
"Button1", , , array(1, 2, "a", "b")
End Sub

5.10.4.2 Properties
This section contains information about the properties of the Alarm Server object.

5.10.4.2.1 ActiveAlarms

Determines the total amount of active alarms in the system. This is a read-only property.

5.10.4.2.2 ActiveHighAlarms

Indicates the number of high severity active alarms. This is a read-only property.

5.10.4.2.3 ActiveHighNACKAlarms

Indicates the number of high severity unacknowledged alarms. This is a read-only property.

5.10.4.2.4 ActiveLowAlarms

Indicates the number of low severity active alarms. This is a read-only property.

5.10.4.2.5 ActiveLowNACKAlarms

Indicates the number of low severity unacknowledged alarms. This is a read-only property.

5.10.4.2.6 ActiveMedAlarms

Indicates the number of medium severity active alarms. This is a read-only property.

5.10.4.2.7 ActiveMedNACKAlarms

Indicates the number of medium severity unacknowledged alarms. This is a read-only

property.

448 Server Objec ts

5.10.4.2.8 ActiveNACKAlarms

Indicates the total amount of unacknowledged alarms in the system (active or not). This is a
read-only property.

5.10.4.2.9 BackupDiscardInterval

Indicates the time interval during which backup data is kept until it is discarded. This
property works along with BackupDiscardTimeUnit property. Default value is 12 (twelve time
units indicated by BackupDiscardTimeUnit).

NOTE: The total amount of time indicated by the combination of the BackupDiscardInterval
and BackupDiscardTimeUnit properties must be longer than the time indicated by the
DiscardInterval e DiscardTimeUnit properties.

5.10.4.2.10 BackupDiscardTimeUnit

This property indicates the time unit to keep backup data until it is discarded. The
available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

This property works along with the BackupDiscardInterval property.

5.10.4.2.11 DataSource

Defines the Database to be used to record alarm data. Default value is empty, that is, there
is no Database to store data.

5.10.4.2.12 DiscardInterval

This property works along with the DiscardTimeUnit property. The DiscardInterval property
indicates the time interval during which alarm data is stored in the database table, until it is
discarded. Default value is 1 (one time unit indicated by the DiscardTimeUnit property). This
property can be changed at run time.

Server Objec ts 449

5.10.4.2.13 DiscardTimeUnit

This property works along with the DiscardInterval property. The DiscardTimeUnit property
indicates the time unit to store data on table until it is discarded. The available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

5.10.4.2.14 EnableBackupTable

Creates a backup table where discarded data is stored, for security reasons. If True, the
table is created. Otherwise, it is not. Default value is True.

5.10.4.2.15 EnableDiscard

Indicates alarm data discard after a certain time. If False, data is stored indefinitely on the
table. Otherwise, it is not. Default value is False.

5.10.4.2.16 Logging

Creates an alarm information record in the Database specified by the DataSource property.
If False, record is not created. Otherwise, it is. Default value is False.

5.10.4.2.17 TableName

Defines a name for the alarms table. Default value is "Alarms". It can be changed at run
time, and its effect is immediate.

5.10.4.2.18 VerificationInterval

This property works along with the VerificationUnit property to control the time interval E3
checks if data is old, and then discard it. Default value is 1 (one time unit indicated by the
VerificationUnit property).

450 Server Objec ts

5.10.4.2.19 VerificationUnit

This property works along with the VerificationInterval property. The VerificationUnit property
indicates the time unit to check for data discard. The available options are:

· 0 - dtHour: hours

· 1 - dtDay: days

· 2 - dtMonth: months (default)

· 3 - dtMinute: minutes

Server Objec ts 451

 CHAPTER

6
Frequently Asked Questions

How to make a windowed Screen display a title bar with Minimize, Maximize, and Close
buttons?

For this, you must use Splitter's SetFrameOptions method. The Flags parameter specifies
window features. A value of 127 defines a window with visible Minimize, Maximize, and Close
buttons.

How to open a modal Screen?

To open a modal Screen, use Viewer's DoModal method. For example, Application.DoModal
"Screen1", "Title1", 0, 0, 400, 200, 0, 1 opens a Screen named Screen1, with title "Title1", at
position 0, 0, with 400 pixels width and 200 pixels height, passes 0 as a Screen parameter, and
enables a window title bar.

How can I copy values from an E3Browser's row to a Tag?

First, select the row (or record) in E3Browser. Then, use E3Browser's GetColumnValue method.
The Index parameter is the column's index to be copied (starting at 0).

How to prevent users from typing a String into a SetPoint?

Check if typed value is a number on SetPoint's Validate event. For example:

Sub Text1_Validate(Cancel, NewValue)
If NOT IsNumeric(newValue) Then
MsgBox "The value must be a number."
Cancel = True
End If
End Sub

How to open a date picker to select a date and time when clicking a SetPoint?

Using the ShowDatePicker method on SetPoint's Click event. For example:

Sub Text1_Click()
Dim datevalue
If Application.ShowDatePicker(datevalue) Then
Value = datevalue
End If
End Sub

How to acknowledge all alarms from an area?

To acknowledge all alarms from an area by script, you can use the Application.GetObject
("AlarmServer1").AckArea(area, user) method, where:

452 Frequently Asked Questions

· Area is the name of the alarm area which the alarm should be acknowledged

· User is the name of the logged in user, which may be the Application.User item

To acknowledge all active alarms, you can also use the Application.GetObject
("AlarmsServer1").AckAllAlarms(user) method.

How to execute an action when clicking a specific mouse button or key?

Using Screen's KeyDown or KeyUp events. These events are triggered when a key is pressed or
released and return two parameters. One is the ASCII code of the pressed key, and the other
one is the SHIFT and CTRL key state when key is pressed. The idea is to compare event's return
parameters with the ASCII code of the expected character.

How to create a WhileRunning script?

By creating an event associated to a property which always has the same value. For example,
Screen's Visible property. While the object is visible (Visible is equal to True), the script is
executed. However, it is recommended that WhileRunning scripts should be avoided, because
they may affect application performance. In most cases, they can be replaced by Links.

How to create an OnValueChanged script?

Creating an event linked to Tag's Value property, which is executed when a property changes
its value.

NOTE: Be careful to not use Viewer methods on Server, for example MsgBox. If this is the case,
the event must be created on the Screen or on the Viewer object itself, instead of on the Tag.

How to create Tags and Screen objects at run time?

Using the AddObject method. For example, the following script creates I/O Tags on Driver1.
Set obj = Application.GetObject("Driver1")
For i = 1 To 100
Set tag = obj.AddObject("IOTag", false)
tag.Name = "IOTag" & CStr(i)
tag.Activate
Next

How to display a message on Screen when changing a Tag value?

By creating an event on the Screen associated to Tag's Value property, which is executed when
the property changes its value. In this event, use the MsgBox method to display that message.

How to perform a date-filtered query before creating a Report?

To perform this, you need to configure the Query object (see Queries chapter), which

Frequently Asked Questions 453

accompanies the Report, and create the necessary variables on Filter column. In the event
that calls the Report, use a script like the following:
Set report = Application.LoadReport("[Report1]")
Set query = report.Query()
query.SetVariableValue "Variable1", Value1
query.SetVariableValue "Variable2", Value2
report.PrintPreview()

Where:

· [Report1] is the name of the Report to be called

· Variable1, Variable2 are the variables created on E3TimeStamp field's filter

· Value1, Value2 are the dates to be queried

To check other filter types, see the Query chapter or the available documentation at Elipse
Knowledgebase website.

How to debug Server and Viewer script errors?

If the event is executing on Viewer, use the MsgBox method. If the event is executing on Server,
use the Trace method.

454 Frequently Asked Questions

Headquarter Branch MG
Rua 24 de Outubro, 353 - 10º andar Rua Antônio de Albuquerque, 156
90510-002 Porto Alegre RS 7º andar Sala 705
Phone: +55 (51) 3346-4699 30112-010 Belo Horizonte - MG
Fax: +55 (51) 3222-6226 Phone: +55 (31) 2511-2121
E-mail: [email protected] E-mail: [email protected]

Branch SP Branch PR
Rua dos Pinheiros, 870 - Conj. 141/142 Av. Sete de Setembro, 4698/1705
05422-001 São Paulo - SP 80240-000 Curitiba - PR
Phone: +55 (11) 3061-2828 Phone: +55 (41) 3342-0120
Fax: +55 (11) 3061-2828 Fax: +55 (41) 3342-0120
E-mail: [email protected] E-mail: [email protected]

Branch RJ USA
Praia de Botafogo, 300/525 40190 Jarvis Gray Lane
22250-044 Rio de Janeiro - RJ Avon - NC - USA 27915
Phone: +55 (21) 2158-1015 Phone: +1 (252) 995-6885
Fax: +55 (21) 2158-1099 Fax: +1 (252) 995-5686
E-mail: [email protected] E-mail: [email protected]

Germany Taiwan
D-67714 Waldfischbach Deutschland 9F., N.12, Beiping 2nd St., Sanmin Dist.
Phone: +49 (0) 6333-4439 807 Kaohsiung City - Taiwan
Fax: +49 (0) 6333-2790045 Phone: +886 (7) 323-8468
E-mail: [email protected] Fax: +886 (7) 323-9656
E-mail: [email protected]

Check our website for information about a representative in your city or country.

w w w .elipse.c om.br
[email protected] om.br