At oll

RF Planning & Optimisation Software

Atoll Scripting Tutorial:

Used Functions and Properties

API_AST_E0

Atoll Scripting Tutorial

Table of Contents
1

Introduction ............................................................................................................................................ 4

Installation of the tutorial ...................................................................................................................... 4

3
3.1
3.2

Used Functions and Properties ............................................................................................................ 4

Used Functions ..................................................................................................................................... 4
Used Properties .................................................................................................................................... 7

Forsk 2010

Atoll Scripting Tutorial

Introduction
This document describes the functions and properties used in the Atoll Scripting Tutorial. Atoll Scripting
Tutorial is developed by Forsk using the standard Atoll API interfaces to demonstrate some of the
operations that could be done with it. This tutorial has been tested with Atoll version 2.8.3 (build 3451).

Installation of the tutorial

To install the tutorial, just download the archive of the studied chapter. There are nine chapters and
one folder containing the necessary files per chapter:

Chapter 1: Starting Atoll

Chapter 2: Working with Atoll document (Opening, Creating)

Chapter 3: Working with a database (Archive,Refresh)

Chapter 4: Working with tabular data (Reading, Writing)

Chapter 5: Working with configuration file (Importing,Exporting)

Chapter 6: Working with zones

Chapter 7: Working with predictions (Creating, Running)

Chapter 8 Working with predictions (Exporting)

Chapter 9: Working with events

To use the scripts, just double-click on the file(s) with vbs extension. Then dont hesitate to open these files with
Notepad to see how the things work.

Used Functions and Properties

3.1

Used Functions

The objAtoll used in the script corresponds to the Application object used in the SDK
Developer Reference Guide. It is the Atoll application as a whole. Among many others, the
following functions have been used:

LogMessage displays a message in the Atoll event viewer window with aside a specific
icon type. It takes two parameters in the following order: message and iconType.

Message is a string

iconType is an integer that can take one of the three values:

0 for an information icon to be shown (

1 for an error icon to be shown (

2 for a warning icon to be shown (

)
)

Sleep suspends Atoll execution for a specified length of time expressed in

milliseconds, and then continues execution. It takes one parameter: timeToSleep.

timeToSleep is an integer

objAtoll.CreatePropertyContainer used in the script corresponds to the

PropertyContainer object used in the SDK Developer Reference Guide . It creates an
object that contains properties. It does not take any parameter.

Set defines a value for a property. It takes two parameters in the following order:
propertyName, propertyValue.

Forsk 2010

Atoll Scripting Tutorial

propertyName is a string

propertyValue is a string or an integer

The objAtoll.Documents used in the script corresponds to the Documents object used in
the SDK Developer Reference Guide. It is a collection of all the documents available in
Atoll. Among many others, the following functions have been used:

Open opens and existing atl file, as read only or not, by using its full path (i.e.
absolute path). It takes two parameters in the following order: filePath and
asReadOnly.

filePath is a string

asReadOnly is a boolean that can take one of the two values:

True for an opening as read only

False for an opening as read and write

Add
creates
an
atl
file,
by
using
a
It takes one parameter: technologyTemplateName.

technology

template.

technologyTemplateName is a string that can take (by default) one of the

following value:

LTE

GSM GPRS EGPRS

UMTS HSPA

TD-SCDMA

Microwave Radio Links

CDMA2000 1xRTT 1xEV-DO

WiMAX 802.16e

WiMAX 802.16d

OpenFromDatabase creates an atl file, by using data coming from a database

with or without a particular schema. It takes two parameters in the following order:
connectionToDatabase and databaseSchema.

connectionToDatabase is a string

databaseSchema is a string

The objDocument used in the script corresponds to the Document object used in the SDK
Developer Reference Guide. It is a document in Atoll. Among many others, the following functions
have been used:

Save saves a document into an atl file full path (i.e. absolute path). It takes one parameter:

filePath

filePath is a string

Archive saves to documents modifications into the database the document is connected to. It

does not take any parameter.

Refresh updates the active document with modifications coming from the database the
document is connected to. It takes one parameter: refreshMethod.

Forsk 2010

refreshMethod is an integer that can take one of the following value:

5

Atoll Scripting Tutorial

0 for updating the document after clearing all the documents modifications not saved
to the database

1 for updating the document while keeping all the documents modifications not yet
saved into the database

SetConfig loads a configuration file (cfg or geo) into the document. It takes one parameter:
filePath.

ExportConfig saves some documents properties into a configuration file. It takes one
parameter: filePath.

filePath is a string

filePath is a string that can take one of the following value:

GEO

ZONES

STUDIES

RunEx starts the calculations and can make Atoll wait for them to be finished. It takes two
parameters in the following order: recalculatePathloss and atollShouldWait.

recalculatePathloss is a boolean that can take one of the two values:

True for recalculating all the path loss matrices before starting the calculations

False for recalculating only invalidated path loss matrices before starting the
calculations

atollShouldWait is a boolean that can take one of the two values:

True for asking Atoll to wait for the calculations to be finished

False for asking Atoll to do the calculations in the background

objDocument.CoordSystemProjection used in the script corresponds to the CoordSystem

object used in the SDK Developer Reference Guide. It is the used coordinate system inside the

document.

objDocument.GetRecords used in the script corresponds to the TabularData object used in the
SDK Developer Reference Guide. It is the object that gives access to all the data that could
be represented as a table in a document. Among many others, the following functions have
been used:

Find searches a value within a particular column. It takes four parameters in the following

order: startingRow, columnIdentifier, searchCriteria and searchedValue.

startingRow is an integer indicating the row number from which the search will
start from

columnIdentifier is a string indicating the name of the column within which the
search is performed. It could also be an integer, indicating the columns position
inside the Tabulardata. It is important to keep in mind that the columns position
starts at zero.

searchCriteria is an integer indicating the search operator that can take one of the
six values:

Forsk 2010

0 for = (i.e; Equal)

1 for < (i.e; Strictly lower)

2 for <= (i.e; Lower or equal)

Atoll Scripting Tutorial

3 for >= (i.e; LGreater or equal)

4 for > (i.e; Strictly greater)

5 for <> (i.e; Different)

searchedValue is a string or an integer

AddNew creates a new empty row inside the Tabulardata and put it into the edition mode. It

does not take any parameter.

Edit puts a row into the edition mode. It takes one parameter: rowNumber.

rowNumber is an integer

GetValue retrieves the value depending on a row and a column. It takes two parameters in the

following order: rowNumber and columnNumber.

rowNumber is an integer

columnNumber is a string indicating the name of the column within which the
search is performed. It could also be an integer, indicating the columns position
inside the Tabulardata. It is important to keep in mind that the columns position
starts at zero.

SetValue sets a value of a column for a row being in the edition mode. It takes two parameters

in the following order: columnNumber and theValue.

columnNumber is a string indicating the name of the column within which the
search is performed. It could also be an integer, indicating the columns position
inside the Tabulardata. It is important to keep in mind that the columns position
starts at zero.

theValue is a string or an integer

Update stops the edition mode after updating the modification made into the Tabulardata. It

does not take any parameter.

objDocument.GetRootFolder used in the script corresponds to the ChildFolder object used in the
SDK Developer Reference Guide. It is the object that gives access the folders inside the

explorer window of a document. It takes one parameter: whichTab. whichTab can take
one of the three values: 0 for the Data tab, 1 for the Geo tab and 2 for the Module Tab. Among
many others, the following functions have been used:

Item gives access to a particular folder. It takes one parameter: folderNameOrObjecKind.

folderNameOrObjecKind is a string that could be the name of the folder as it is

seen in Atoll or the unique identifier of the folder.

AddChild adds a new item inside a folder. It takes two parameters in the following order:

objectKind and position.

3.2

objectKind is a string that indicates the type item to create

position is an integer that indicates the position of item as it can be seen in Atoll.

Used Properties

The following properties were used for the Application object:

visible indicates whether Atoll should be visible. It is a boolean that can take one of the
two values:

Forsk 2010

True

Atoll Scripting Tutorial

The following properties were used for the Document object:

name indicates the name of the document without the extension file. It is a string.

fullName indicates the full path name (i.e. the absolute path) of the document with the
extension file. It is a string.

The following properties were used for the TabularData object:

rowCount indicates the number of row inside a TabularData. It is an integer.

The following properties were used for the ChildFolder object and more particularly on the
predictions folder:

name indicates the name of the prediction as it seen in the explorer window. It is a string.

visible indicates whether the prediction should be visible. It is a boolean that can take one
of the two values:

Forsk 2010

False

True

False

selected indicates whether the prediction should be selected in the explorer window. It is a
boolean that can take one of the two values:

True

False

addtolegend indicates whether the predictions legend should be included in the legend
window. It is a boolean that can take one of the two values:

True

False

description indicates the description of the prediction as it seen in the predictions

properties. It is a string.

Atoll Scripting
Tutorial:
Used Functions
and Properties

October 10

Head Office
7, rue des Briquetiers
31700 Blagnac - France
Tel: +33 562 747 210
Fax: +33 562 747 211

US Office
200 South Wacker Drive - Suite
3100
Chicago, IL 60606 - USA
Tel: +1 312 674 4846
Fax: +1 312 674 4847

China Office
Suite 302, 3/F, West Tower,
Jiadu Commercial Building,
No. 66 Jianzhong Road,
Tianhe Hi-Tech Industrial Zone,
Guangzhou, 510665, P. R. of China
Tel: +86 20 8553 8938
Fax: +86 20 8553 8285