Task Automation Guide
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Release: AT332_TAG_E0 (November 2016) © Copyright 1997-2016 Forsk. All Rights Reserved. Published by:
Forsk
7 rue des Briquetiers 31700 Blagnac, France Tel: +33 562 747 210 Fax: +33 562 747 211
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.
Table of Contents
1
Getting Started. . . .17
1.1 Supported Extensions . . . 17
1.2 Script Tutorial. . . 17
1.2.1 Writing a VBScript File . . . 17
1.2.2 Testing the Script . . . 18
1.2.3 Scheduling the Script . . . 18
1.2.4 Debugging the Script . . . 21
1.2.5 Error Management. . . 21
1.3 Macro Tutorial . . . 23
1.3.1 Adding Macros to Atoll . . . 24
1.3.2 Running a Macro . . . 25
1.3.3 Saving a List of Macros . . . 25
1.4 Windows Script Host, 32-bit vs 64-bit . . . 25
2
Object Model . . . .29
2.1 Interfaces Implemented by Objects. . . 29
2.2 Properties and Methods Provided by Objects . . . 30
2.2.1 Parameters . . . 30
2.2.2 Error Information . . . 30
3
Application Object . . . .33
3.1 How to Access the Application Object. . . 34
3.2 get_Application . . . 35 3.3 get_Parent . . . 35 3.4 get_Active . . . 35 3.5 put_Active . . . 35 3.6 get_Documents . . . 36 3.7 get_Name. . . 36 3.8 get_FullName. . . 36 3.9 get_Path . . . 36 3.10 get_ActiveDocument. . . 37 3.11 get_WindowStatus . . . 37 3.12 put_WindowStatus . . . 37 3.13 put_StatusBar . . . 38 3.14 get_Visible . . . 38 3.15 put_Visible . . . 38 3.16 get_Version . . . 38 3.17 Quit . . . 39 3.18 LogMessage . . . 39
Atoll 3.3.2 Task Automation Guide
Table of Contents © 2016 Forsk. All Rights Reserved.
3.20 get_IniFileFullPath . . . .40 3.21 put_IniFileFullPath . . . .40 3.22 GetOption . . . .40 3.23 SetOption . . . .41 3.24 Sleep . . . .41 3.25 SetAddinInfoEx . . . .41 3.26 put_OLENotRespondingDialog . . . .42 3.27 put_OLEBusyDialog . . . .42 3.28 put_OLEMessagePendingDelay . . . .42 3.29 get_PID . . . .42 3.30 Application Events . . . .42 3.30.1 WillQuitApp. . . .43 3.30.2 DocumentOpenComplete . . . .43 3.30.3 WillCloseDocument . . . .43 3.30.4 WillSaveDocument . . . .43 3.30.5 DocumentSaveComplete . . . .43 3.30.6 DocumentNewComplete . . . .44 3.30.7 WillRefreshDocument . . . .44 3.30.8 RefreshDocumentComplete . . . .44 3.30.9 WillArchiveDocument. . . .44 3.30.10 ArchiveDocumentComplete. . . .44 3.30.11 WillRun . . . .45 3.30.12 RunComplete. . . .45 3.30.13 LicenceAcquireComplete . . . .45 3.30.14 LicenceReleaseComplete . . . .46 3.30.15 WillNewDocumentFromDatabase. . . .47 3.30.16 WillRunMicrowave . . . .47
4
Documents Object . . . 51
4.1 How to Access a Documents Object. . . .51
4.2 get_Count . . . .52 4.3 get_Item . . . .52 4.4 get_Application . . . .52 4.5 get_Parent . . . .52 4.6 Open . . . .52 4.7 Add . . . .53 4.8 OpenFromDatabase. . . .53 4.9 CloseAll . . . .54 4.10 SaveAll. . . .55
5
Document Object. . . 59
5.1 How to Access a Document Object. . . .61
5.2 get_Application . . . .61
5.3 get_Parent . . . .61
5.4 get_FullName . . . .61
5.5 get_Name . . . .62
5.7 get_ReadOnly . . . 62 5.8 get_Saved. . . 62 5.9 get_CoordSystemProjection. . . 62 5.10 putref_CoordSystemProjection . . . 63 5.11 get_CoordSystemDisplay . . . 63 5.12 putref_CoordSystemDisplay . . . 63 5.13 get_CoordSystemInternal . . . 63 5.14 get_TransmissionUnit . . . 64 5.15 put_TransmissionUnit . . . 64 5.16 get_ReceptionUnit . . . 64 5.17 put_ReceptionUnit . . . 64 5.18 get_DistanceUnit . . . 64 5.19 put_DistanceUnit. . . 64 5.20 Close . . . 65 5.21 FilePrint . . . 65 5.22 Save. . . 65 5.23 Refresh . . . 65 5.24 Archive . . . 66 5.25 Run . . . 66 5.26 SetConfig . . . 66 5.27 Import. . . 67 5.28 GetRecords. . . 67 5.29 Redraw . . . 68 5.30 CenterMapOn . . . 68 5.31 GetRootFolder . . . 68 5.32 RunPathloss . . . 69 5.33 GetService . . . 69 5.34 ExportConfig . . . 70 5.35 GetCommandDefaults. . . 70 5.36 InvokeCommand . . . 71 5.37 get_RadiatedPowerUnit . . . 71 5.38 put_RadiatedPowerUnit . . . 71 5.39 get_AntennaGainUnit . . . 71 5.40 put_AntennaGainUnit . . . 72 5.41 get_HeightOffsetUnit . . . 72 5.42 put_HeightOffsetUnit . . . 72 5.43 get_DatabaseConnectionString . . . 72 5.44 HasRunningTask. . . 72 5.45 RunEx . . . 73
Atoll 3.3.2 Task Automation Guide
Table of Contents © 2016 Forsk. All Rights Reserved.
5.47 get_DisplayApplicationDialogues . . . .73 5.48 put_DisplayApplicationDialogues . . . .74 5.49 PutDatabaseSchemaString . . . .74 5.50 PutDatabaseConnectionString . . . .74 5.51 ChangeDatabaseConnection . . . .74 5.52 get_TemperatureUnit . . . .75 5.53 put_TemperatureUnit . . . .75 5.54 GetDocumentProperties . . . .75 5.55 SetDocumentProperties . . . .75 5.56 get_RadioTableNames. . . .77 5.57 LogMessage . . . .77
6
TabularData Object . . . 81
6.1 How to Access a TabularData Object . . . .82
6.2 get_ColumnCount . . . .83 6.3 get_RowCount . . . .83 6.4 Edit . . . .83 6.5 AddNew . . . .84 6.6 Update . . . .84 6.7 Delete . . . .84 6.8 GetValue . . . .84 6.9 SetValue . . . .85 6.10 GetPrimaryKey . . . .87 6.11 FindPrimaryKey . . . .87 6.12 Find . . . .87 6.13 GetFormattedValue . . . .88 6.14 CancelUpdate . . . .89 6.15 get_ColumnNumber . . . .89 6.16 get_CanEdit . . . .89 6.17 get_CanAddNew . . . .90 6.18 get_CanFilterSort . . . .90 6.19 get_Filter. . . .90 6.20 put_Filter . . . .90 6.21 get_Sort . . . .91 6.22 put_Sort . . . .92 6.23 GetOriginalValue . . . .92 6.24 get_RowStatus . . . .92 6.25 get_Columns. . . .93 6.26 GetValues . . . .93 6.27 GetFormattedValues . . . .95
6.28 SetValues . . . 95
6.29 Hidden Columns In Radio Tabular Data Objects . . . 96
6.29.1 Table MWLINKS . . . 96
6.29.2 Table MWOTLINKS . . . 96
6.29.3 Transmitters Tables, All Technologies . . . 96
7
Zones and Predictions Tabular Data Objects. . . .99
7.1 Zones Tabular Data Object . . . 99
7.2 Predictions Tabular Data Object . . . 100
8
CoordSystem Object . . . .105
8.1 How to Access a CoordSystem Object . . . 105
8.2 Code . . . 105 8.3 ConvertCoordsTo. . . 106 8.4 Datum . . . 107 8.5 DatumName. . . 107 8.6 Description . . . 107 8.7 Ellipsoid . . . 107 8.8 EllipsoidName . . . 107 8.9 Name . . . 108 8.10 Pick . . . 108 8.11 ProjMethod . . . 108 8.12 ProjParameter . . . 109 8.13 SetDatum . . . 109 8.14 SetProjection . . . 109 8.15 Unit . . . 109
9
ChildFolder Object . . . .113
9.1 How to Access a ChildFolder Object . . . 114
9.2 get_Application . . . 114 9.3 get_Parent . . . 115 9.4 get_Name. . . 115 9.5 put_Name . . . 115 9.6 get_Count. . . 116 9.7 get_Item . . . 116 9.8 get__NewEnum . . . 116 9.9 get_Visible . . . 116 9.10 put_Visible . . . 117 9.11 get_Selected . . . 117 9.12 put_Selected . . . 118 9.13 Export . . . 118 9.14 CentreOnMap . . . 120
Atoll 3.3.2 Task Automation Guide
Table of Contents © 2016 Forsk. All Rights Reserved.
9.16 AddChild . . . 120 9.17 Remove . . . 121 9.18 get_position . . . 121 9.19 put_position . . . 121 9.20 get_Object . . . 122 9.21 get_dispatch . . . 122 9.22 get_ObjectKind. . . 122 9.23 GetProperty . . . 124 9.24 SetProperty. . . 124 9.25 GetPropertiesInfo. . . 124 9.26 PropertyIsPropertyContainer . . . 125 9.27 PropertyIsTabularData. . . 125 9.28 LoadProperties . . . 125 9.29 SaveProperties . . . 125 9.30 RemoveItem . . . 125 9.31 SetCustomIcon . . . 126 9.32 OpenPropertySheet . . . 126
10
PropertyContainer Object . . . 129
10.1 Get. . . 129 10.2 Set . . . 130 10.3 GetInfo . . . 130 10.4 IsPropertyContainer. . . 130 10.5 IsTabularData . . . 130 10.6 Load. . . 130 10.7 Save . . . 131 10.8 RemoveAll. . . 131 10.9 Remove . . . 13111
ChildFolder Object Properties. . . 135
11.1 How to Access ChildFolder Object Properties . . . 135
11.2 Common ChildFolder Object Properties . . . 136
11.3 Predictions Folder Properties . . . 137
11.4 Coverage Prediction Properties . . . 137
11.4.1 General Properties . . . 140
11.4.2 Group, Filter, and Sort Properties . . . 141
11.4.3 Non-Simulation-based Coverage Conditions . . . 141
11.4.4 Simulation-based Coverage Conditions . . . 143
11.4.5 Shadowing and Indoor Coverage Conditions . . . 144
11.4.6 Display Properties. . . 144
11.5 GSM Simulation Group Properties . . . 146
11.6 UMTS Simulation Group Properties . . . 147
11.8 3GPP Multi-RAT Simulation Group Properties . . . 149
11.9 Standard Propagation Model Properties. . . 150
11.10 CW Measurement Properties. . . 152
11.11 Drive Test Data Properties . . . 153
11.12 Custom ChildFolder Object Properties . . . 153
11.13 Master Link Properties . . . 154
11.14 Link Properties . . . 154
11.15 Vector Layer Properties . . . 154
11.15.1 Display Properties . . . 154
11.16 Aster Propagation Model Properties . . . 156
11.17 KPI Item Properties. . . 157
12
ChildFolder Feature Objects . . . .161
12.1 Clutter Feature Object . . . 161
12.1.1 How to Access the Clutter Feature Object. . . 161
12.1.2 get_Source . . . 161
12.1.3 get_ClassAttributes . . . 162
12.1.4 get_DefaultAttributes . . . 162
12.1.5 Accessing Clutter Class Attributes . . . 162
12.2 Traffic Feature Object . . . 164
12.2.1 How to Access the Traffic Feature Object . . . 164
12.2.2 get_Source . . . 164
12.2.3 get_ScenarioProvider. . . 164
12.2.4 ExportCumulatedTraffic. . . 165
12.2.5 HasTrafficForService . . . 166
12.3 UMTS Traffic Scenario Provider Object . . . 167
12.3.1 GetMeanSize. . . 167
12.3.2 Create . . . 167
12.4 Environment Based Traffic Map Feature Object. . . 169
12.4.1 How to Access Environment Based Traffic Map Feature Objects . . . 169
12.4.2 get_Source . . . 169
12.4.3 get_ClassAttributes . . . 169
12.4.4 get_DefaultAttributes . . . 169
12.4.5 Accessing Environment Based Traffic Maps Attributes . . . 170
12.5 Simulation Feature Object . . . 171
12.5.1 How to Access Simulation Feature Objects . . . 172
12.5.2 get_Source . . . 172 12.5.3 get_Statistics . . . 172 12.5.4 get_Cells . . . 173 12.5.5 get_Sites . . . 173 12.5.6 get_Mobiles . . . 173 12.5.7 get_Results . . . 173
12.6 Simulation Group Feature Object . . . 174
12.6.1 How to Access Simulation Group Feature Objects . . . 174
12.6.2 get_Source . . . 176
12.6.3 get_Statistics . . . 176
12.6.4 get_MeanSimulation . . . 176
12.6.5 get_StdDevSimulation . . . 176
12.6.6 Accessing Mobiles, Cells, Sites, for Simulations and Simulation Groups. . . 177
12.7 3GPP Multi-RAT Simulation Group Feature Object . . . 181
12.7.1 get_Source . . . 181
12.7.2 get_Statistics . . . 182
12.7.3 get_MeanSimulation . . . 182
Atoll 3.3.2 Task Automation Guide
Table of Contents © 2016 Forsk. All Rights Reserved.
12.8.1 How to Access GSM Interference Matrix Feature Objects . . . 184
12.8.2 get_Source. . . 184 12.8.3 Load . . . 184 12.8.4 CompleteScopeInfo . . . 184 12.8.5 get_Scope . . . 184 12.8.6 put_Active . . . 185 12.8.7 get_Active . . . 185 12.8.8 get_Type . . . 185 12.8.9 put_Type . . . 186 12.8.10 get_BasedOnTraffic . . . 186 12.8.11 put_BasedOnTraffic . . . 187 12.8.12 get_Resolution . . . 187 12.8.13 put_Resolution . . . 187 12.8.14 get_StdDev . . . 187 12.8.15 put_StdDev . . . 188 12.8.16 get_InfoQuantityIndicator . . . 188 12.8.17 put_InfoQuantityIndicator . . . 188 12.8.18 get_CdfTab . . . 188
13
Document Commands . . . 193
13.1 How to Invoke a Document Command . . . 194
13.2 IMPORTXML . . . 194 13.3 EXPORTXML . . . 195 13.4 APPENDTABLECOLUMN. . . 195 13.5 CALCULATEPOINTS. . . 196 13.6 IMPORTTESTMOBILEDATA . . . 197 13.7 RUNNEIGHBOURALLOCATION . . . 198 13.8 RUNINTERTECHNOLOGYNEIGHBOURALLOCATION. . . 199 13.9 RUNINTRACARRIERNEIGHBOURALLOCATION . . . 200 13.10 RUNINTERCARRIERNEIGHBOURALLOCATION . . . 201 13.11 CLONESTUDY . . . 201 13.12 DUPLICATESTUDY. . . 202 13.13 COMPARESTUDY . . . 202 13.14 CALCULATEEQUIPMENTLOSSES . . . 203 13.15 CALCULATEREPEATERS . . . 203 13.16 CALCULATEREMOTEANTENNAS . . . 204 13.17 EXPORTACTIVESETANALYSIS . . . 205 13.18 CALCULATEPOINTSECI0 . . . 208 13.19 RUNALLCARRIERSALLOCATION . . . 209 13.20 RUNMASTERCARRIERALLOCATION. . . 210 13.21 MWRun . . . 210 13.22 EXPORTMAPWINDOW. . . 220 13.23 IMPORTPLANETDATAFILE . . . 221 13.24 EXPORTMWLINKANALYSISPROFILEPICTURE . . . 221 13.25 GETPOWERMODE . . . 222 13.26 SETPOWERMODE . . . 222 13.27 APPENDVECTORDATACOLUMN . . . 223
13.28 LOADSAVEPRINTSETUP . . . 224 13.29 CALCULATEPATHLOSS . . . 225 13.30 MWLinksCustomExport. . . 225 13.31 ARCHIVETODATABASE . . . 226 13.32 MWCalculateProfiles. . . 226 13.33 PURGEPATHLOSSFOLDERS . . . 227
14
Enumerations. . . .231
14.1 Enumerations. . . 23114.1.1 Atoll Type Library Enumerations. . . 231
14.1.1.1 AtoSaveStatus . . . 231 14.1.1.2 AtoSaveChanges . . . 231 14.1.1.3 AtoRefreshPriority . . . 231 14.1.1.4 AtoArchiveStatus . . . 231 14.1.1.5 AtoWindowStatus . . . 231 14.1.1.6 AtoLogType . . . 232 14.1.1.7 AtoCompareOp . . . 232 14.1.1.8 AtoTransmissionUnit . . . 232 14.1.1.9 AtoReceptionUnit . . . 232 14.1.1.10 AtoDistanceUnit . . . 232 14.1.1.11 AtoRadiatedPowerUnit. . . 233 14.1.1.12 AtoAntennaGainUnit . . . 233 14.1.1.13 AtoHeightOffsetUnit. . . 233 14.1.1.14 AtoRootType . . . 233 14.1.1.15 AtoRowFilter . . . 233 14.1.1.16 AtoRowStatus . . . 233 14.1.1.17 AtoTemperatureUnit . . . 234
14.1.2 FSKGISLib Type Library Enumerations . . . 234
14.1.2.1 GeographicUnit . . . 234
14.1.2.2 ProjectionMethod. . . 234
Atoll 3.3.2 Task Automation Guide
Atoll 3.3.2 Task Automation Guide
This Task Automation Guide is aimed at advanced administrators who plan to write scripts or macros to enhance the function-alities that are available in Atoll.
This manual assumes that the reader has an advanced knowledge of Atoll and radio network planning and is familiar with Microsoft script technologies and the VBScript language in particular.
About Atoll
Atoll is a 64-bit multi-technology wireless network design and optimisation platform. Atoll is open, scalable, flexible, and
supports wireless operators throughout the network life cycle, from initial design to densification and optimisation.
Atoll includes integrated single RAN – multiple RAT network design capabilities for both 3GPP (GSM/UMTS/LTE) and 3GPP2
(CDMA/LTE) technology streams. It provides operators and vendors with a powerful native 64-bit framework for designing and optimising current and future integrated multi-technology networks. Atoll supports multi-technology HetNets, small cell planning, and Wi-Fi offloading.
Atoll Microwave is a complete backhaul and microwave link planning solution based on the leading Atoll platform, which
includes a high performance GIS and advanced data and user management features. Atoll Microwave can share its site data-base with Atoll radio planning and optimisation modules, thus allowing easy data consistency management across the oper-ator organisation.
Atoll’s integration and automation features help operators smoothly automate planning and optimisation processes through
flexible scripting and SOA-based mechanisms. Atoll supports a wide range of implementation scenarios, from standalone to enterprise-wide server-based configurations.
If you are interested in learning more about Atoll, please contact your Forsk representative to inquire about our training solu-tions.
About Forsk
Forsk is an independent company providing radio planning and optimisation software solutions to the wireless industry since 1987.
In 1997, Forsk released the first version of Atoll, its flagship radio planning software. Since then, Atoll has evolved to become a comprehensive radio planning and optimisation platform and, with more than 7000 installed licenses worldwide, has reached the leading position on the global market. Atoll combines engineering and automation functions that enable opera-tors to smoothly and gradually implement SON processes within their organisation.
Today, Forsk is a global supplier with over 450 customers in 120 countries and strategic partnerships with major players in the industry. Forsk distributes and supports Atoll directly from offices and technical support centres in France, USA, and China as well as through a worldwide network of distributors and partners.
Since the first release of Atoll, Forsk has been known for its capability to deliver tailored and turn-key radio planning and opti-misation environments based on Atoll.
To help operators streamline their radio planning and optimisation processes, Forsk provides a complete range of implemen-tation services, including integration with existing IT infrastructure, automation, as well as data migration, installation, and training services.
Getting Help
The online help system that is installed with Atoll is designed to give you quick access to the information you need to use the product effectively. It contains the same material as the Atoll 3.3.2 User Manual.
You can browse the online help from the Contents view, the Index view, or you can use the built-in Search feature. You can also download manuals from the Forsk web site at:
http://www.forsk.com/MyForskAccount/
Printing Help Topics
Atoll 3.3.2 Task Automation Guide
Introduction © Forsk 2016. All Rights Reserved.
To print help topics or chapters:
1. In Atoll, click Help > Help Topics.
2. In the Contents tab, expand the table of contents.
3. Right-click the section or topic that you want to print and click Print. The Print Topics dialog box appears. 4. In the Print Topics dialog box, select what you want to print:
• If you want to print a single topic, select Print the selected topic.
• If you want to print an entire section, including all topics and sections in that section, select Print the selected
heading and all subtopics. 5. Click OK.
About Atoll Documentation
The following PDF manuals are available for Atoll and Atoll Microwave and can be downloaded from the Forsk web site at: http://www.forsk.com/MyForskAccount/
• Atoll User Manual
• Atoll Administrator Manual
• Atoll Data Structure Reference Guide • Atoll Technical Reference Guide • Atoll Task Automation Guide • Atoll Model Calibration Guide
To read PDF manuals, download Adobe Reader from the Adobe web site at: http://get.adobe.com/reader/
Hardcopy manuals are also available. For more information, contact to your Forsk representative.
Contacting Technical Support
Forsk provides global technical support for its products and services. To contact the Forsk support team, visit the My Forsk web site at:
http://www.forsk.com/MyForskAccount/
Alternatively, depending on your geographic location, contact one of the following support teams:
• Forsk Head Office
For regions other than North and Central America and China, contact the Forsk Head Office support team: • Tel.: +33 562 747 225
• Fax: +33 562 747 211 • Email: [email protected]
Opening Hours: Monday to Friday 9.00 am to 6.00 pm (GMT +1:00)
• Forsk US
For North and Central America, contact the Forsk US support team: • Tel.: 1-888-GO-ATOLL (1-888-462-8655)
• Fax: 1-312-674-4822
• Email: [email protected]
Opening Hours: Monday to Friday 8.00 am to 8.00 pm (Eastern Standard Time)
• Forsk China
For China, contact the Forsk China support team: • Tel: +86 20 8557 0016
• Fax: +86 20 8553 8285
• Email: [email protected]
Chapter 1
Atoll 3.3.2 Task Automation Guide
1 Getting Started
Atoll provides an application programming interface that enables you to extend and customise Atoll.
If you plan to write scripts or macros, you must be familiar with Microsoft Windows Script Technologies, especially with the VBScript language.
You can start by:
• Going through the section "Supported Extensions" on page 17 to learn which types of extensions can be developed. • Reading the following tutorials before starting your own development:
• "Script Tutorial" on page 17, • "Macro Tutorial" on page 23,
1.1 Supported Extensions
The following types of extensions are available. • Scripts
A script is a sequence of VBScript statements in a text file, executable from outside Atoll (Windows Script Host). Scripts allow task automation in Atoll when no interaction with the user is needed. Scripts do not require any setup and are specially useful for scheduling tasks in batch mode. Scripts use COM inter-process communication for communicating with Atoll.
Sample code:
Several scripts are available for download at www.forsk.com.
• Macros
A macro is a sequence of VBScript statements in a text file, executable from within Atoll. Macros allow task automa-tion in Atoll. Macros may interact with the user, but the interacautoma-tion is limited by VBScript. Macros must be added to Atoll in order to be available for execution. They can be saved in Atoll user configuration files. Macro commands can be added to toolbars. Macros use COM in-process communication for communicating with Atoll.
Sample code:
Several macros are available for download at www.forsk.com.
1.2 Script Tutorial
Through this tutorial, you will learn to automate some simple tasks, such as archiving data to databases, running calculations, and executing scripts on a scheduled time.
1.2.1 Writing a VBScript File
Open a text editor, and type in the following code: Option Explicit
Dim var Dim myapp Dim doc
Sub Atoll_RunComplete(arg1, arg2) var = 1
End Sub
Atoll 3.3.2 Task Automation Guide
Chapter 1: Getting Started © 2016 Forsk. All Rights Reserved.
You must replace all the parameters beginning with "my" with your own values in the above connection string. This script:
1. Starts an invisible session.
2. Opens a new document from an existing database. 3. Runs all the calculations in this document. 4. Waits for the end of calculations.
Event RunComplete is thrown when calculations are done. The syntax for catching any event is to concatenate the name of the event to the string "Atoll_". As these parameters have not been used in the above example, they have been named "arg1" and "arg2". Moreover, we connect and disconnect the script using the appropriate method of WScript.
5. Saves the document. 6. Exits the Atoll session.
Save your script file as a VBScript file, for example “C:\Atollmacros\tutorial.vbs”.
1.2.2 Testing the Script
To test the script:
1. Double-click the C:\Atollmacros\tutorial.vbs file in Windows Explorer.
2. Check a few minutes later whether “C:\TEMP\mydoc.atl” has been created or not.
1.2.3 Scheduling the Script
You can schedule scripts using the Windows Task Scheduler. This tutorial describes the steps for Windows 2000. For other operating systems, where the procedure might differ slightly, please refer to Windows Help.
WScript.ConnectObject myapp, "Atoll_" myapp.Visible = False
Set doc = myapp.Documents.OpenFromDatabase(
"Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=myAtollDb-Name;Data Source=myServer", "dbo;<ALL>;")
doc.Run True var = 0 Do While var = 0 WScript.Sleep 1000 Loop doc.Save("C:\mydoc.atl") WScript.DisconnectObject myapp doc = Null Const atoSaveNo = 0 myapp.Documents.CloseAll atoSaveNo myapp.Quit atoSaveNo myapp = Null WScript.Quit 0
To open the Windows Task Scheduler:
1. Select Start > Settings > Control Panel. The Control Panel opens. 2. Double-click the Scheduled Tasks icon.
3. Double-click the Add Scheduled Task icon. The Scheduled Taks Wizard opens. 4. Click Next.
5. Click the Browse button. 6. Select cscript.exe. 7. Click Next.
8. Change the name of the task, for example "Atoll tutorial". 9. Choose your preferred periodicity.
10. Click Next.
The following wizard pages enable you to define more precisely when your task should run and which user starts it.
11. In the last page, select the Open advanced properties for this task when I click Finish check box. 12. Click Finish. The advanced properties Atoll Tutorial dialogue opens.
Figure 1.1: Scheduled Tasks Wizard
Atoll 3.3.2 Task Automation Guide
Chapter 1: Getting Started © 2016 Forsk. All Rights Reserved.
13. In the Atoll Tutorial dialogue, add your VBScript file name in the Run field and append "\\B" option to specify batch
mode. This suppresses dialogue boxes such as alerts and script errors.
14. Set account information if needed.
15. Click OK. Your task will be displayed in the Scheduled Tasks window:
To modify the task properties:
1. Right-click the Atoll Tutorial task. The context menu opens. 2. Select Properties from the context menu.
Figure 1.3: Scheduled Tasks Wizard
Figure 1.4: Atoll Tutorial
To control the current status of the task: • Select View > Details.
To open the log file:
• Select Advanced > View Log. To test the new task:
1. Right-click the Atoll Tutorial task. The context menu opens. 2. Select Run from the context menu.
1.2.4 Debugging the Script
To debug the script, use a command prompt console and the wscript "//X" command line option:
You will be prompted for the debugger you want to use. Microsoft provides a specialised script debugger to debug VBScript code, which is available in the free downloads section of Microsoft’s website. You can set breakpoints and inspect the contents of variables using this debugger.
While debugging, you can temporarily make Atoll visible on the desktop using:
1.2.5 Error Management
It is important to check for any error that might occur during the execution of the script. Microsoft Visual Basic scripting language provides "On Error Resume Next" along with the "Err" object to manage errors. Here is our sample script with error management: wscript tutorial.vbs //X Myapp.Visible = True Option Explicit Dim var Dim myapp Dim doc
On Error Resume Next Sub CatchError If Err Then
myapp.LogMessage Err.Description, 1 WScript.Echo Err.Description
End If
WScript.Echo "Script failed."
myapp.LogMessage "Script failed.", 1 Const atoSaveNo = 0
If IsObject(doc) Then doc.Close atoSaveNo doc = Null
Atoll 3.3.2 Task Automation Guide
Chapter 1: Getting Started © 2016 Forsk. All Rights Reserved.
End If If IsObject(myapp) Then myapp.Documents.CloseAll atoSaveNo myapp.Quit 0 myapp = Null End If WScript.Quit -1 End Sub
Sub Atoll_RunComplete(arg1, arg2) var = 1
End Sub
Set myapp = CreateObject("Atoll.Application") If Err Then
WScript.Echo "Can't create 'Atoll.Application' object." Err.Clear
Call CatchError End If
WScript.ConnectObject myapp, "Atoll_" myapp.Visible = False
Set doc = myapp.Documents.OpenFromDatabase(
"Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=myAtollDb-Name;Data Source=myServer", "dbo;<ALL>;")
If Err Then Call CatchError End If doc.Run True
If Err Then Call CatchError End If var = 0
Do While var = 0 WScript.Sleep 1000 Loop
doc.Save("C:\mydoc.atl")
If Err Then Call CatchError End If WScript.DisconnectObject myapp doc = Null
Error checking is activated with "On Error Resume Next". When an error occurs, the script continues execution from the next line and the "Err" object is set accordingly. You can check for Err.Number, or for Err (because Number is its default property) to catch any error.
1.3 Macro Tutorial
Macros are run by Atoll upon being invoked by the user. Macros are written in VBScript, like scripts. The difference between scripts and macros is the execution context.
When a macro is launched from Atoll, an instance of anAtoll Application object is automatically added as a script-level variable available to the macro code. Therefore, CreateObject or GetObject to access an Application object must not be called. The first line of your macro can be directly:
The script-level variable name for the Atoll Application object is "Atoll" and it is optional. So, the above line is equivalent to:
Macros can also be invoked in response to application events.
Example myapp.Quit atoSaveNo myapp = Null WScript.Quit 0 mydoc = Atoll.ActiveDocument mydoc = ActiveDocument Sub Atoll_DocumentSaveComplete(doc)
LogMessage "Archive on save running ..." Dim status
On Error Resume Next status = doc.Archive Const atoError = 1
Const atoArchiveCanceled = 1 If Err.Number <> 0 Then
LogMessage "Archive on save failed. " & Err.Description & ".", atoError Else
If status = atoArchiveCanceled Then
LogMessage "Archive on save failed.", atoError
LogMessage "You must resolve the conflicts manually.", atoError
MsgBox "Archive on save failed. You must resolve the conflicts manual-ly."
Else
Atoll 3.3.2 Task Automation Guide
Chapter 1: Getting Started © 2016 Forsk. All Rights Reserved.
The above example shows a macro used to automatically archive a document once it has been saved.
1.3.1 Adding Macros to Atoll
You can add a macro to your Atoll session as follows:
1. Select Tools > Add-ins and Macros. The Add-ins and Macros dialogue opens. 2. Under Macros, click the Add button.
Browse for your script file. You can create a new macro file by typing a name for the new (empty) macro file in the file selection box. Atoll will initialize this new file with minimal VBScript script. Atoll interprets your file and lists all public macros found in the file in an explorer.
If you create an empty macro file, it is initialised with the following code:
You can then edit the file and add any command in the sub Main, or add another sub and execute it..
3. Expand the explorer entry, select a macro and click the Run button to start the macro.
To edit a macro file:
1. Under Macros, select the macro in the list of macros.
2. Click the Edit button. The macro file is opened in the default editor. 3. Modify the code.
4. Save the file. 5. Close the file editor
6. In the Add-ins and Macros dialogue, click the Refresh button. Atoll will update the macro.
To associate an icon file to a macro:
1. Under Macros, select the macro in the list of macros. 2. Click the Icon button.
End If End If End Sub
Public Sub Main End Sub
3. Select the icon file to be used for the macro.
A toolbar button is added for the macro in Atoll, which you can click to run the macro.
For macros returning values, only functions, and not subroutines, may be defined. This is the case, for example, of all "OnWill…" calls as the returned value, the status value, allows the user to bypass the standard behaviour.
For functions, the name of the returned value is the same as the name of the function:
1.3.2 Running a Macro
To run a macro:
• Select a macro in the Add-ins and Macros dialogue and click Run, or • Select a macro in the Add-ins and Macros dialogue and double-click it, or • Click the macro’s button in the toolbar.
If a problem occurs during the macro execution, an error message is displayed in a dialogue box with the line number indi-cated. The same message is also logged in the Atoll Event Viewer.
1.3.3 Saving a List of Macros
Once macros have been added to an Atoll session, they can be saved in a configuration file. If no document is open in Atoll, you can still use the Tools > User Configurations > Save command for saving the macros in the configuration file.
Similar to all other configuration file contents, if the configuration file is named Atoll.cfg and is stored at the same location as Atoll.exe, Atoll will always be started with the list of macros saved in this configuration file. Macros will be available even if no Atoll document is open. For more information on configuration files, please refer to the Administrator Manual.
1.4 Windows Script Host, 32-bit vs 64-bit
Microsoft Windows Script Host is used to run scripts.
On a 64-bit OS, there is a 32-bit and a 64-bit version of Windows Script Host available. Both can be used to script Atoll. The
Atoll version used by a script depends on the Atoll versions installed (32/64 bit) and on the Windows Script Host version used
to run the script.
The following table shows the Atoll version launched by Windows Script Host:
You need to explicitly use 32-bit or 64-bit Windows Script Host on machines where both 32-bit Atoll and 64-bit Atoll are installed.
Function Atoll_WillRun(doc, success) doc.Save
Atoll_WillRun = False ‘ Intercepts the run order and cancels ‘ it by returning False
End Function
Only 32-bit Atoll installed Only 64-bit Atoll installed Both 32-bit and 64-bit Atoll installed 32-bit WSH used to run
the script 32-bit Atoll is launched 64-bit Atoll is launched 32-bit Atoll is launched
64-bit WSH used to run
Atoll 3.3.2 Task Automation Guide
Chapter 2
Atoll 3.3.2 Task Automation Guide
2 Object Model
This chapter describes the Atoll object model. Figure 2.1 on page 29 provides an overview of the Atoll object model.
Atoll exposes a number of objects of various types. These objects provide access to Atoll components through properties and
methods. Properties and methods usually have input and output parameters. The objects exposed by Atoll are:
2.1 Interfaces Implemented by Objects
Atoll objects provide access to Atoll components through properties and methods.
Figure 2.1: Atoll Object Model
Name Description
Application Object The Application object provides an entry point for clients to retrieve and navigate through the Atoll object model.
Documents Object The Documents object is used to create a new document or to iterate through open documents in an Atoll session.
Document Object The Document object provides access to ATL documents and database
connections. TabularData Object
The TabularData object provides access to Atoll tables whether an Atoll document is connected to a database or not. It also provides access to other
tables which are not database tables, such as PREDICTIONS and ZONES. CoordSystem Object This object contains the entire definition of a coordinate system.
ChildFolder Object A ChildFolder object represents an item in the Atoll Explorer window. PropertyContainer Object The PropertyContainer object is a generic container containing a set of
named properties of arbitrary types
Transmitter Object The Transmitter object provides read-only access to antenna patterns, antenna losses, and some transmitter properties.
Application Documents
Document 1 Document 2 PropertyContainer 1
PropertyContainer 2 TabularData 1 TabularData 2 ChildFolder 1 ChildFolder 2 CoordSystem TabularData 1 TabularData 2 ChildFolder 1 ChildFolder 2 CoordSystem
Atoll 3.3.2 Task Automation Guide
Chapter 2: Object Model © 2016 Forsk. All Rights Reserved.
2.2 Properties and Methods Provided by Objects
Access to Atoll components is available through properties and methods. Properties and methods usually have input and output parameters.
For reading and writing a property, you write:
For calling a method, you write:
2.2.1 Parameters
Properties and methods may have parameters.
Input Parameters
Input parameters are marked with [in]. Input parameters are not mutated by methods or property setters implementation. Input parameters are specified by value.
Output Parameters
Output parameters are marked with [out]. Output parameters are specified by reference. Upon successful completion of methods or property getters, the referenced value is changed.
Input/Output Data Types
• BSTR
BSTR may be used as a method parameter data type. It is used to specify a character string. In VBScript, it corresponds to the String data type.
• VARIANT
VARIANT may be used as a method parameter data type. It is used to specify values of many different types, especially arrays. It can be used by VBScript.
2.2.2 Error Information
When an error is returned by a property or method, an error information context is created and an exception is thrown. If the script or macro does not use the On Error Resume Next statement, it will be terminated due to the error.
If the script or macro uses the On Error Resume Next statement, the error information is available as properties of the script-level Err object. For example, Err.Description which provides the error description:
In
Please refer to the VBScript Language Reference for more information about VBScript, error handling, and the Err script-level variable.
value = object.property ’for reading a property object.property = value ’for writing a property
object.method
Dim strDescription If Err Then
strDescription = Err.Description End If
Chapter 3
Application
Object
Atoll 3.3.2 Task Automation Guide
3 Application Object
The Application object provides an entry point for clients to retrieve and navigate through the Atoll object model. • IApplication7
The Application object provides the following properties and methods:
Name Description Attributes
get_Application Returns the Atoll Application object. Type: Application object
Access: Read
get_Parent Returns the Atoll Application object. Type: Application object
Access: Read
get_Active Returns whether the Atoll window is active
or not.
Type: Boolean Access: Read/Write
put_Active Sets the Atoll window active. Type: Boolean
Access: Read/Write
get_Documents Returns the Documents object. Type: Documents object
Access: Read
get_Name Returns the application name. The
application name is always "Atoll".
Type: String Access: Read
get_FullName Returns the full path of the executable. Type: String
Access: Read
get_Path Returns the path of the executable. Type: String
Access: Read
get_ActiveDocument Returns the active document. Type: Document object
Access: Read
get_WindowStatus Returns the window status of the Atoll
application.
Type: Integer Access: Read/Write
put_WindowStatus Sets the window status of the Atoll
application.
Type: Integer Access: Read/Write
put_StatusBar Sets the status bar text of the Atoll
application.
Type: String Access: Write
get_Visible Returns the application visible state. Type: Boolean
Access: Read/Write
put_Visible Sets the application visible state. Type: Boolean
Access: Read/Write
get_Version Returns the application version. Type: String
Access: Read
Quit Quits the application.
LogMessage Displays a message in the Atoll event
observer window.
CreatePropertyContainer Returns an empty PropertyContainer object.
get_IniFileFullPath Returns the full path to the Atoll initialisation file.
Type: String Access: Read/Write put_IniFileFullPath Sets the full path to the Atoll initialisation
file.
Type: String Access: Read/Write
GetOption Returns an option read from the Atoll
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
The Application object fires the following events:
3.1 How to Access the Application Object
The application object is the top-level object. Sub-objects are obtained through properties of the application. To get an appli-cation object in VBScript, use one of the following:
Because Atoll registers itself in the Running Objects Table when an Atoll session is running, you can use:
In the context of macros, an instance of the main object Application is automatically added as a global variable of the macro code. Therefore, it must not call CreateObject or GetObject to get an Application object.
The global variable of type Application object available to macros is named "Atoll".
SetOption Sets an option in the Atoll initialisation file.
Sleep Suspends the application apartment
execution.
Name Description
WillQuitApp Event fired when the user wants to exit an Atoll session.
DocumentOpenComplete Event fired when a document has been opened.
WillCloseDocument Event fired when the user wants to close a document.
WillSaveDocument Event fired when the user wants to save a document.
DocumentSaveComplete Event fired just after a document has been saved.
DocumentNewComplete Event fired when a new document has been created.
WillRefreshDocument Event fired when the user wants to refresh a document from database.
RefreshDocumentComplete Event fired when a document has been refreshed from database.
WillArchiveDocument Event fired when the user wants to archive a document to the database.
ArchiveDocumentComplete Event fired when the document has been archived in database.
WillRun Event fired when the user wants to start a calculation.
RunComplete Event fired when the calculation has finished.
LicenceAcquireComplete This feature enables the user to log Atoll licence token usage from an add-in. LicenceReleaseComplete This feature enables the user to log Atoll licence token usage from an add-in.
Name Description Attributes
Set app = CreateObject("Atoll.Application")
Set app = GetObject(, "Atoll.Application")
Using GetObject("", "Atoll.Application") (note the difference in the first parameter) will automatically start a new instance of Atoll if no session is already running and attach the macro to this new instance.
Each call to GetObject("", "Atoll.Application") will start a new Atoll instance. If this is not intended, use GetObject(, “Atoll.Application”), which attaches the script to the first Atoll session started when several sessions are running.
3.2 get_Application
Returns the Atoll Application object.
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll Application object.
3.3 get_Parent
Returns the Atoll Application object.
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll Application object.
3.4 get_Active
Returns whether the Atoll window is active or not.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether the Atoll windows application is active or not.
Example
3.5 put_Active
Sets the main application window active.
Parameters
[in] aNewVal:
• VARIANT_TRUE: Activates the main window application.
Example
See "get_Active" on page 35.
HRESULT get_Application(IApplication **ppVal);
HRESULT get_Parent(IApplication **ppVal);
HRESULT get_Active(VARIANT_BOOL *pVal);
Dim app Dim act
Set app = CreateObject("Atoll.Application") act = app.Active
app.Active = True
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
3.6 get_Documents
Returns the Documents object.
Parameters
[out] ppDocVal: Address of the IDocuments interface pointer used to return the Documents object.
Example
3.7 get_Name
Returns the application name. The application name is always "Atoll".
Parameters
[out] pVal: Address of the BSTR used to return the application name.
3.8 get_FullName
Returns the full path of the executable.
Parameters
[out] pVal: Address of the BSTR used to return the application full path.
Remarks
The path name returned is the full path, for example, "C:\Program Files\Forsk\Atoll\Atoll.exe".
3.9 get_Path
Returns the path of the executable.
Parameters
[out] pVal: Address of the BSTR used to return the application path.
Remarks
The path returned is provided as an absolute path, for example, "C:\Program Files\Forsk". HRESULT get_Documents(IDocuments **ppDocVal);
Dim app Dim docs
Set app = CreateObject("Atoll.Application") Set docs = app.Documents
HRESULT get_Name(BSTR *pVal);
HRESULT get_FullName(BSTR *pVal);
3.10 get_ActiveDocument
Returns the active document.
Parameters
[out] ppDocVal: Address of the IDocument interface pointer used to return the Document object.
Example
3.11 get_WindowStatus
Returns the window status of the Atoll application.
Parameters
[out] pVal: Address of the AtoWindowStatus enumeration used to return the window status.
Example
3.12 put_WindowStatus
Sets the window status of the Atoll application.
Parameters
[in] newVal: The window status.
Example
See "get_WindowStatus" on page 37.
HRESULT get_ActiveDocument(IDocument **ppDocVal);
Dim app Dim doc
Set app = CreateObject("Atoll.Application") Set doc = app.ActiveDocument
HRESULT get_WindowStatus(enum AtoWindowStatus *pVal);
Dim app Dim status
Set app = CreateObject("Atoll.Application") status = app.WindowStatus
Const atoMinimized = 2
app.WindowStatus = atoMinimized
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
3.13 put_StatusBar
Sets the status bar text of the Atoll application.
Parameters
[in] bstrNewVal: The text to display in the status bar.
Example
3.14 get_Visible
Returns the application visible state.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return the application visible state.
Remarks
When Atoll is not visible, a dialogue that would normally require user input is automatically closed as if the user has clicked its default button without changing any of the dialogue controls.
3.15 put_Visible
Sets the application visible state.
Parameters
[in] aNewVal:
• VARIANT_TRUE: Makes Atoll visible. • VARIANT_FALSE: Hides Atoll.
Remarks
When Atoll is not visible, a dialogue that would normally require user input is automatically closed as if the user has clicked its default button without changing any of the dialogue controls.
3.16 get_Version
Returns the application version.
HRESULT put_StatusBar(const BSTR bstrNewVal);
Dim app
Set app = CreateObject("Atoll.Application") app.StatusBar = “This is my message”
HRESULT get_Visible(VARIANT_BOOL *pVal);
HRESULT put_Visible(VARIANT_BOOL aNewVal);
Parameters
[out] pVal: Address of the BSTR used to return the version.
Remarks
The string is formatted like in the Atoll about dialogue, for example, "2.6.1".
Atoll 3.1.0 and above:
The application build number is included in the string, for example, "3.1.0 (Build 3730)"
3.17 Quit
Quits the application.
Parameters
[in] aSaveChanges:
• atoSaveNo: Discards document changes, then closes the application. • atoSaveYes: Saves document changes, then closes the application.
• atoSavePrompt: The user is prompted to save document changes, then the application is closed.
[out] pStatus: The AtoSaveStatus enumeration pointer used to return whether changes were successfully saved or not. • Returns atoSaveCanceled when the user was prompted and has chosen not to save the changes, otherwise returns
atoSaveSucceeded.
Remarks
Once this method has returned the Atoll Application object has been destroyed and invoking any method on it will result in undefined behaviour.
3.18 LogMessage
Displays a message in the Atoll event observer window.
Parameters
[in] bstrMsg: The text to display. [in] aLogType:
• atoInfo: An information message is displayed. • atoError: An error message is displayed. • atoWarning: A warning message is displayed.
3.19 CreatePropertyContainer
Returns an empty PropertyContainer object.
Parameters
[out] pProperties: Address of the VARIANT used to return the empty PropertyContainer object.
HRESULT Quit(enum AtoSaveChanges aSaveChanges, enum AtoSaveStatus *pStatus);
HRESULT LogMessage(const BSTR bstrMsg, enum AtoLogType aLogtype = atoInfo);
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Remarks
The VARIANT returned if of type VT_DISPATCH, and it implements the IPropertyContainer interface. The empty container returned can be used to hold default parameters specific to an Atoll document command or to hold an Atoll ChildFolder Object properties.
3.20 get_IniFileFullPath
Returns the full path to the Atoll Initialisation File.
Parameters
[out] pVal: Address of the BSTR used to return the full path to the Atoll Initialisation File.
Remarks
The Atoll Initialisation File is usually named "Atoll.ini" and it is located in the directory where Atoll was installed.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. After the path to the Initialisation File has been changed, and in order for some options to be used, it is necessary to quit Atoll and start it again. Therefore, it is recommended to change the full path to the Initialisation File as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available options.
3.21 put_IniFileFullPath
Sets the full path to the Atoll Initialisation File.
Parameters
[in] bstrFile: A BSTR used to specify the full path to the Atoll Initialisation File.
Remarks
The Atoll Initialisation File is usually named "Atoll.ini" and it is located in the directory where Atoll was installed.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. After the path to the Initialisation File has been changed, and in order for some options to be used, it is necessary to quit Atoll and start it again. Therefore, it is recommended to change the full path to the Initialisation File as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available options.
3.22 GetOption
Returns an option read from the Atoll Initialisation File.
Parameters
[in] bstrSection: A BSTR used to specify the name of an Atoll Initialisation File section. [in] bstrOption: A BSTR used to specify the name of an Atoll Initialisation File option.
[out] pVal : Address of the VARIANT used to return the option value. The type of the VARIANT returned is VT_NULL when the option bstrOption is not found under the section bstrSection in the Initialisation File. The type of the returned VARIANT is VT_I4 when the option bstrOption is an integer, otherwise the type of the VARIANT returned is VT_BSTR. If bstrOption is left empty, pVal will be used to return the entire section whose name is specified in bstrSection.
HRESULT get_IniFileFullPath(BSTR *pVal);
HRESULT put_IniFileFullPath(BSTR bstrFile);
Remarks
Please refer to the Atoll Administrator Manual for the list of available sections and options.
3.23 SetOption
Sets an option in the Atoll Initialisation File.
Parameters
[in] bstrSection: A BSTR used to specify the name of an Atoll Initialisation File section. [in] bstrOption: A BSTR used to specify the name of an Atoll Initialisation File option. [in] varValue: A VARIANT used to specify the option value to write to the Initialisation File.
Remarks
The caller must have write access permission to the Initialisation File.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. Therefore, it is recommended to set options as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available sections and options.
3.24 Sleep
Suspends the application apartment execution.
Parameters
[in] lMilliseconds : A long integer used to specify the time, in milliseconds, to sleep.
Example
Remarks
Application events can still be processed while the application apartment execution is suspended.
Application Version
2.8.1
3.25 SetAddinInfoEx
Reserved for future use.
HRESULT SetOption(BSTR bstrSection, BSTR bstrOption, VARIANT varValue);
HRESULT Sleep(long lMilliseconds);
’Sleep 5 seconds Atoll.Sleep 5000 HRESULT SetAddinInfoEx( LONGLONG hInstance, LPDISPATCH dispatch, long idr, long cookie );
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
3.26 put_OLENotRespondingDialog
Enables or disables OLE not responding dialog.
Parameters
[in] newVal: A VARIANT_BOOL used to specify whether the OLE not responding dialog is enabled (VARIANT_TRUE), or disabled (VARIANT_FALSE).
3.27 put_OLEBusyDialog
Enables or disables OLE busy dialog.
Parameters
[in] newVal: A VARIANT_BOOL used to specify whether the OLE busy dialog is enabled (VARIANT_TRUE), or disabled (VARIANT_FALSE).
3.28 put_OLEMessagePendingDelay
Sets the OLE message pending delay.
Parameters
[in] newVal: A LONG integer used to specify the OLE message pending delay.
3.29 get_PID
Returns the Windows Process ID of the Atoll session.
Parameters
[out] pVal: Address of the long integer used to return the process ID of the Atoll session.
3.30 Application Events
Events related to the application are fired: • Before the application shuts down, • When a document has just been opened, • Before a document is closed,
• Before a document is saved, • When a document has been saved,
• When a new document has just been created, • Before a document is refreshed from database, • When a document has been refreshed from database, • Before a document is archived in database,
HRESULT put_OLENotRespondingDialog(VARIANT_BOOL newVal);
HRESULT put_OLEBusyDialog(VARIANT_BOOL newVal);
HRESULT put_OLEMessagePendingDelay(LONG newVal);
• When a document has been archived in database, • When a calculation is requested,
• When a Microwave calculation is requested, • After a calculation has completed, • When a licence is acquired, • When a licence is released,
• Before a new document is created from an existing database.
3.30.1 WillQuitApp
Event fired when the user wants to exit an Atoll session. It occurs just before all add-ins are disconnected and after all docu-ments have been closed.
Parameters
[out] evtStatus: A VARIANT_BOOL pointer used to return whether Atoll is allowed to quit (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.2 DocumentOpenComplete
Event fired when a document has been opened.
Parameters
[in] document: The IDocument interface pointer of the document object which has been opened.
3.30.3 WillCloseDocument
Event fired when the user wants to close a document. It occurs just before the document closes, i.e., after all confirmations requested by Atoll have been answered (stop running tasks, save changes, etc...).
Parameters
[in] document: The IDocument interface pointer of the document object being closed.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be closed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.4 WillSaveDocument
Event fired when the user wants to save a document. It occurs just before the document file is saved but after a valid file name is set.
Parameters
[in] document: The IDocument interface pointer of the document object being saved.
[out] evtStatus: A VARIANT_BOOL pointer used to return when the document is allowed to be saved (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.5 DocumentSaveComplete
HRESULT WillQuitApp(VARIANT_BOOL* evtStatus);
HRESULT DocumentOpenComplete(IDocument* document);
HRESULT WillCloseDocument(IDocument* document, VARIANT_BOOL* evtStatus);
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] document: The IDocument interface pointer of the document which has been successfully saved.
3.30.6 DocumentNewComplete
Event fired when a new document has been created.
Parameters
[in] document: The IDocument interface pointer of the document which has been created.
3.30.7 WillRefreshDocument
Event fired when the user wants to refresh a document from database. It occurs just before the connection with the database is checked.
Parameters
[in] document: The IDocument interface pointer of the document being refreshed.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be refreshed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.8 RefreshDocumentComplete
Event fired when a document has been refreshed from database.
Parameters
[in] document: The IDocument interface pointer of the document which has been refreshed.
3.30.9 WillArchiveDocument
Event fired when the user wants to archive a document to the database. It occurs just after the connection with the database is set up and after Atoll has checked if any changes have to be archived. If nothing requires archiving, this event is not fired.
Parameters
[in] document: The IDocument interface pointer of the document being archived.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be archived (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.10 ArchiveDocumentComplete
Event fired when the document has been archived in database. It occurs just before the connection with the database is broken.
HRESULT DocumentSaveComplete (IDocument* document);
HRESULT DocumentNewComplete(IDocument* document);
HRESULT WillRefreshDocument(IDocument* document, VARIANT_BOOL* evtStatus);
HRESULT RefreshDocumentComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been archived.
3.30.11 WillRun
Event fired when the user wants to start a calculation. If all is set to VARIANT_TRUE, this event occurs after the user has confirmed that all previous calculations must be deleted.
Parameters
[in] document: The IDocument interface pointer of the document on which calculation is requested.
[in] all: A VARIANT_BOOL value used to specify whether the user has requested "Calculate All (Ctrl+F7)" (VARIANT_TRUE) or "Calculate (F7)" (VARIANT_FALSE).
[out] evtStatus: A VARIANT_BOOL pointer used to return whether calculation is allowed to run against the document (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.12 RunComplete
Event fired when the calculation has finished. It occurs after all tasks have completed.
Parameters
[in] document: The IDocument interface pointer of the document.
[in] succeeded: The VARIANT_BOOL used to specify whether calculation has succeeded (VARIANT_TRUE) or not (VARIANT_FALSE).
Remarks
For documents based on the 3GPP Multi-RAT template, there may be several RunComplete events in response to one calcu-lation task. For instance, the path loss matrices calcucalcu-lation might result in 3 RunComplete events, one for LTE, one for UMTS, and one for GSM matrices.
3.30.13 LicenceAcquireComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measurements module (Measures) is available for auto-connected add-ins only.
Fired when one licence token is acquired.
HRESULT ArchiveDocumentComplete(IDocument* document);
HRESULT WillRun(
IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus );
HRESULT RunComplete(IDocument* document, VARIANT_BOOL succeeded);
HRESULT LicenceAcquireComplete( IDocument *pDocument,
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] pDocument: The IDocument interface pointer of the document that needed one licence token. [in] lModuleID: The long integer used to specify the ID of the licence token that has just been acquired.
Remarks
lModuleID will be one of these constant values:
• LICENCE_GSMTDMA • LICENCE_MW • LICENCE_MEASURES • LICENCE_AFP • LICENCE_PACK3G • LICENCE_UMTS • LICENCE_CDMA • LICENCE_TDSCDMA • LICENCE_WIMAX • LICENCE_LTE
• For LICENCE_MEASURES token, pDocument will be NULL. Module identifiers used when licence application events are fired:
3.30.14 LicenceReleaseComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measurements (Measures) module will be avail-able for autoconnected add-ins only.
Fired when one licence token is released. long lModuleID
);
const long LICENCE_GSMTDMA = 2; const long LICENCE_MW = 4; const long LICENCE_MEASURES = 8; const long LICENCE_AFP = 16; const long LICENCE_PACK3G = 32; const long LICENCE_UMTS = 64; const long LICENCE_CDMA = 128; const long LICENCE_TDSCDMA = 256; const long LICENCE_WIMAX = 512; const long LICENCE_LTE = 2048;
HRESULT LicenceReleaseComplete( IDocument *pDocument,
long lModuleID );
Parameters
[in] pDocument: The IDocument interface pointer of the document that just released the licence token. [in] lModuleID: The long integer used to specify the ID of the licence token that has just been released.
Remarks
lModuleID will be one of these constant values:
• LICENCE_GSMTDMA • LICENCE_MW • LICENCE_PACK3G • LICENCE_UMTS • LICENCE_CDMA • LICENCE_TDSCDMA • LICENCE_WIMAX • LICENCE_LTE
3.30.15 WillNewDocumentFromDatabase
3.2.0Fired just before a new document is created from an existing database.
Parameters
[in] connexion: The database connexion string. [in] schema: The database schema.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the creation of the new document from the database iden-tified by the connexion and schema parameters is allowed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.16 WillRunMicrowave
Event fired when the user wants to start a Microwave calculation.
Parameters
[in] document: The IDocument interface pointer of the document on which Microwave calculation is requested.
[in] all: A VARIANT_BOOL value used to specify whether the user has requested "Calculate All (Ctrl+F7)" (VARIANT_TRUE) or "Calculate (F7)" (VARIANT_FALSE).
[out] evtStatus: A VARIANT_BOOL pointer used to return whether Microwave calculation is allowed to run against the docu-ment (VARIANT_TRUE) or not (VARIANT_FALSE).
HRESULT WillNewDocumentFromDatabase( BSTR connexion, BSTR schema, VARIANT_BOOL *pEvtStatus ); HRESULT WillRunMicrowave( IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus );
Atoll 3.3.2 Task Automation Guide
Chapter 4
Documents
Object
Atoll 3.3.2 Task Automation Guide
4 Documents Object
The Documents object is used to create a new document or to iterate through open documents in an Atoll session. The Documents object provides the following properties and methods:
4.1 How to Access a Documents Object
To access a Documents object:
The "For Each" VBScript statement can be used with the Documents collection object:
Name Description Attributes
get_Count Returns the number of currently open documents ina
session.
Type: Integer Access: Read
get_Item Returns one document currently open in a session.
Type: Documents object Access: Read
get_Application Returns the Atoll application object.
Type: Application object Access: Read
get_Parent Returns the Atoll application object.
Type: Application object Access: Read
Open Opens an existing document and adds it to the collection of
open documents.
Add Creates a new document and adds it to the collection of
open documents.
OpenFromDatabase Creates a new document from a database and adds it to
the collection of open documents.
CloseAll Closes all open documents.
SaveAll Saves all open documents.
Dim allDocs
Set allDocs = Atoll.Documents
Dim allDocs Dim doc
Set allDocs = Atoll.Documents For Each doc In allDocs ‘ do some work with doc ‘...
