Atoll

Wireless Network Engineering Software

Atoll Scripting Tutorial

Technical Note

TN045
Atoll Scripting Tutorial
Release: TN045 (November 2019)
© Copyright 1997-2019 Forsk. All Rights Reserved.
Published by:
Forsk
7 rue des Briquetiers
31700 Blagnac, France
Tel: +33 562 747 210
Fax: +33 562 747 211
www.forsk.com
The software described in this document is provided under a licence agreement. The software may only be used or copied under the terms and
conditions of the licence agreement. No part of the contents of this document may be reproduced or transmitted in any form or by any means
without written permission from the publisher.
The product or brand names mentioned in this document are trademarks or registered trademarks of their respective registering parties.
Third party services that are not part of Atoll are governed by the terms and conditions of their respective providers, which are subject to change
without notice.
The publisher has taken care in the preparation of this document, but makes no expressed or implied warranty of any kind and assumes no
responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the
use of the information contained herein.
TN045 Atoll Scripting Tutorial

1 Introduction
This document describes the functions and properties used in the Atoll Scripting Tutorial. The Atoll Scripting
Tutorial uses the standard Atoll API interfaces to demonstrate some of the operations that can be done with it.
This tutorial is compatible with Atoll version 3.4.0 (build 16278) or later.
You cannot use these files with an earlier version of Atoll.

2 Installing the Atoll Scripting Tutorial

The Atoll Scripting Tutorial contains .VBS scripts, .MDB database files, and .ATL Atoll documents organised in the
following chapters:

Tutorial

1 - Starting Atoll This tutorial contains a script that starts Atoll and displays the Atoll Events viewer.

2 - Working with documents This tutorial contains a script that opens an existing .ATL document, a script that cre-
ates an .ATL document from a database, and a script that creates an .ATL document
from a template.

3 - Working with databases This tutorial contains a script that creates an .ATL document from a database and
performs an Archive operation and a script that opens an .ATL document from a data-
base and performs an Refresh operation.

4 - Working with tabular data This tutorial contains a script that creates sites and transmitters in an existing .ATL
document and a script that identifies and displays in the Events viewer the available
antenna in an existing .ATL document.

5 - Working with configuration files This tutorial contains a script that exports a computation zone and a focus zone into
a configuration file and a script that imports transmitter properties in an existing .ATL
document from a configuration file.

6 - Working with zones This tutorial contains a script that performs some operations (such as visualizing,
creating, or deleting) on a focus zone.

7 - Working with predictions This tutorial contains a script that creates and calculates coverage predictions.
8 - Exporting predictions This tutorial contains a script that exports coverage predictions into external files.

9 - Working with events This tutorial contains a script that manages Atoll events.

To work with the Atoll Scripting Tutorial:

1. Extract files from the archive.
2. To execute a script, double-click the .VBS file.
3. To see the details of a script, open the script (.VBS file) with a text editor such as Notepad.

+ The .ATL and .MDB files required for Tutorials 2, 3, and 4 were created with Atoll
version 3.4.0 (build 16278).
To use them with a later version:
1. Open the .ATL document from the database with Atoll version 3.4.0 (build
16278).
2. Save the document.
3. Open the document with the later version of Atoll.
4. Select Document > Database > Export to create a database with the upper
Atoll version.

© 2019 Forsk. All Rights Reserved. 3

Atoll Scripting Tutorial

3 Objects and Methods

3.1 Application Object

The objAtoll object used in the script corresponds to the Application object described in the Task Automation Guide.
It is the Atoll application as a whole. Among many others, the following methods are used:

Methods Description Parameters

LogMessage Displays a message and an icon in the Atoll Message (type: string).
Events viewer. iconType (type: integer):
"0" for an information icon
"1" for an error icon
"2" for a warning icon
Sleep Suspends the Atoll execution for a specified timeToSleep (type: integer)
period of time expressed in milliseconds, and
then continues the execution.

CreatePropertyContainer Creates a PropertyContainer object (see "Prop-

ertyContainer Object" on page 4).

Documents Returns a Documents object (see "Documents

Object" on page 4).

CoordSystemProjection Creates a CoordSystem object that is the coor-

dinate system used in the Atoll document.

3.2 PropertyContainer Object

The objAtoll.CreatePropertyContainer method used in the script creates an object of the PropertyContainer type
(for more information, see the Task Automation Guide). The following method is used:

Methods Description Parameters

Set Defines a value for a property. propertyName (type: string)

propertyValue (type: string or integer)

3.3 Documents Object

The objAtoll.Documents method used in the script returns a Documents object that is a collection of all the
documents available in Atoll (for more information, see the Task Automation Guide). Among many others, the
following methods are used:

4 © 2019 Forsk. All Rights Reserved.

TN045 Atoll Scripting Tutorial

Methods Description Parameters

Open Opens an existing Atoll file (.ATL) by using the filePath (type: string)
absolute path of the file. asReadOnly (type: boolean):
"True" to open the file in read only mode.
"False" to open the file in read and write mode.

Add Creates an Atoll file (.ATL) based on a template. technologyTemplateName (type: string):
 GSM GPRS EDGE
 UMTS HSPA
 TD-SCDMA
 CDMA2000 1xRTT 1xEV-DO
 LTE NB-IoT
 WiMAX 802.16e
 Wi-Fi
 3GPP Multi-RAT
 3GPP2 Multi-RAT
 5G Multi-RAT
 Microwave Radio Links
 Backhaul
For more information on the templates, see the Atoll
User Manual.

OpenFromDatabase Creates an Atoll document (.ATL) from the data- connectionToDatabase (type: string)
base with or without a specific schema. databaseSchema (type: string)

3.4 Document Object

The objDocument object used in the script corresponds to a Document object that is a document in Atoll (for more
information, see the Task Automation Guide). Among many others, the following methods are used:

Methods Description Parameters

Save Saves the Atoll document in a specified direc- filePath (type: string)
tory by using an absolute path.

Archive Saves the document modifications into the

database.

Refresh Updates the active document with modifica- refreshMethod (type: integer):
tions from the database.  "0" to cancel any changes you have made and
update the document with modifications from the
database.
 "1" to update the document with modifications
from the database while keeping any changes you
have made.

SetConfig Loads a user configuration file (.cfg or .geo) into filePath (type: string)
the Atoll document.

ExportConfig Saves some document properties into a config- filePath (type: string):
uration file.  GEO
 ZONES
 STUDIES

RunEx Starts calculations. recalculatePathloss (type: boolean):

 "True" to recalculate all pathloss matrices before
starting calculations.
 "False" to recalculate only the invalidated pathloss
matrices before starting calculations.
 atollShouldWait (type: boolean):
 "True" to make Atoll waits until the calculation is
finished.
 "False" to run calculations in background.

© 2019 Forsk. All Rights Reserved. 5

Atoll Scripting Tutorial

Methods Description Parameters

GetRecords Returns a TabularData object (see "TabularData tabularDataName (type: string)

Object" on page 6). allContent (type: boolean):
 "True" to return all the records of the table.
 "False" to filter the records to return according to
the filter used on the document folder associated
with the table. If no folder is associated with the
table, this parameter is ignored.

GetRootFolder Returns a ChildFolder object (see "ChildFolder whichTab (type: integer):

Object" on page 6).  "0" for the Network explorer
 "1" for the Geo explorer
 "2" for the Parameters explorer

3.5 TabularData Object

The objDocument.GetRecords method used in the script returns a TabularData object giving access to all the data
that can be represented as a table in an Atoll document (for more information, see the Task Automation Guide).
Among many others, the following methods are used:

Methods Description Parameters

Find Searches for a value in a column. startingRow (type: integer) that indicates the row num-
ber from which the search starts.
columnIdentifier (type: string or integer) that indicates
the name of the column within which the search is per-
formed or the column position in the table. Note that the
column position starts at zero (0).
searchCriteria (type: integer) that indicates the search
operator to use:
 "0" for equal (=)
 "1" for less than (<)
 "2" for less than or equal to (<=)
 "3" for greater than or equal to (>=)
 "4" for greater than (>)
 "5" for different (<>)
searchedValue (type: integer or string)

AddNew Creates an empty row inside the table and ena-

bles the edition mode for this new row.

Edit Enables the edition mode for a row. rowNumber (type: integer)

GetValue Retrieves the value depending on a row and a rowNumber (type: integer)
column. columnIdentifier (type: string or integer) that indicates
the name of the column within which the search is per-
formed or the column position in the table. Note that the
column position starts at zero (0).

SetValue Sets a value of a column for a row in edition columnIdentifier (type: string or integer) that indicates
mode. the name of the column within which the search is per-
formed or the column position in the table. Note that the
column position starts at zero (0).
theValue (type: integer or string)

Update Disables the edition mode after updating the

modification made in the table.

3.6 ChildFolder Object

The objDocument.GetRootFolder method used in the script returns a ChildFolder object giving access to the folders
of the explorer windows in an Atoll document (for more information, see the Task Automation Guide).

6 © 2019 Forsk. All Rights Reserved.

TN045 Atoll Scripting Tutorial

Among many others, the following functions are used:

Methods Description Parameters

Item Gives access to a particular folder. folderNameOrObjectKind (type: string) that indicates
the folder as shown in Atoll or the unique identifier of the
folder.

AddChild Adds a new item inside a folder. objectKind (type: string) that specifies the type of the
item to create.
position (type: integer) that specifies the position of the
item in the explorer.

Export Exports an item

4 Properties
The following properties are used for the Application object:

Properties Description Type Possible Values

visible Specifies whether Atoll is visible. boolean True

False

The following properties are used for the Document object:

Properties Description Type Possible Values

name Specifies the name of the document without the string

file extension.

fullName Specifies the absolute path of the document string

including the extension.

The following properties are used for the TabularData object:

Properties Description Type Possible Values

rowCount Specifies the number of rows inside a table. integer

The following properties are used for the ChildFolder object:

Properties Description Type Possible Values

name Specifies the name of the prediction contained string

in the Network explorer.

visible Specifies whether the prediction is visible. boolean True

False
selected Specifies whether the check box associated boolean True
with the prediction is selected in the Network False
explorer.

addtolegend Specifies whether the prediction legend must boolean True

be added to the Legend window. False

description Indicates the description of the prediction as it string

appears in the prediction Properties dialog box.

© 2019 Forsk. All Rights Reserved. 7

 Head Office US Office China Office
7 rue des Briquetiers 200 South Wacker Drive – Suite 3100 Suite 302, 3/F, West Tower, Jiadu Commercial Building,
31700 Blagnac, France Chicago, IL 60606, USA No. 66 Jianzhong Road, Tianhe Hi-Tech Industrial Zone,
Tel: +33 562 747 210 Tel: +1 312 674 4800 Guangzhou, 510665, P. R. of China
Fax: +33 562 747 211 Fax: +1 312 674 4847 Tel: +86 20 8553 8938 Fax: +86 20 8553 8285

TN045 www.forsk.com November 2019